콘텐츠로 이동

교재 저장소와 실습 코드 저장소 구분

이 과정의 실행 기준은 교재 저장소와 실습 코드 저장소를 분리해서 이해해야 합니다. ttamlops-2607은 문서와 슬라이드, JupyterLite 안내를 관리하고, 실제 수강생이 로컬에서 실행할 코드와 notebook 원본은 tta-aiqa 저장소에서 관리합니다.

이 구분은 단순한 저장 위치 문제가 아닙니다. 교재 저장소에 실행 코드가 섞이면 문서의 설명과 실제 실습 코드가 서로 다른 속도로 바뀌면서, 수강생은 어떤 명령을 믿어야 하는지 알 수 없게 됩니다. 따라서 강의 중 실행 명령을 안내할 때는 항상 tta-aiqa 루트를 기준으로 말하고, ttamlops-2607의 경로는 문서, 슬라이드, 브라우저 실습 mirror, prepared evidence 확인 경로로만 사용합니다.

저장소 역할 관리 대상 수강생에게 안내할 때의 기준
ttamlops-2607 교재와 슬라이드 docs/, slide/, storyboards/, JupyterLite 안내, 내부 시나리오 메타데이터 문서를 읽고 판단 기준과 실습 흐름을 확인
tta-aiqa 실제 실습 코드 labs/, demos/, packages/ai-quality, compose.yaml, configs/, artifacts/ 로컬에서 notebook, Python script, Docker Compose, Kubernetes/GitOps 실습 실행
JupyterLite site 브라우저 보조 실습 소형 CSV, prepared artifact, Lite용 notebook 설치 없이 출력과 판단 흐름을 빠르게 확인

교재의 파일 경로는 별도 표기가 없으면 tta-aiqa 루트 기준으로 읽습니다. 예를 들어 labs/ch03_serving/fastapi_serving_lab.ipynb는 ../tta-aiqa/labs/ch03_serving/fastapi_serving_lab.ipynb를 뜻합니다. 교재 사이트 안의 JupyterLite 링크만 ttamlops-2607에서 빌드되는 브라우저 경로를 가리킵니다.

1. 실행 명령 기준

로컬 실행 명령은 tta-aiqa 루트에서 수행해야 합니다. ttamlops-2607에서 같은 명령을 실행하면 문서 빌드, 슬라이드 빌드, JupyterLite mirror 확인처럼 교재 관리 작업으로 해석합니다.

교육장 VM을 사용하는 실습에서는 먼저 VM에 접속한 뒤 tta-aiqa에서 명령을 실행합니다. VM 접속은 3장 Argo CD/KServe와 4장 Grafana Cloud 확인 전에 끝나 있어야 합니다.

ssh -o PreferredAuthentications=password \
  -o PubkeyAuthentication=no \
  -J mrml-bastion@146.56.41.109 \
  tta@10.99.0.20

이 명령은 bastion host를 거쳐 내부 실습 VM에 접속합니다. 비밀번호 인증을 사용하므로 비밀번호는 문서나 notebook에 기록하지 않습니다. 접속이 끝난 뒤에는 VM 안에서 tta-aiqa repository 위치로 이동해 실습 명령을 실행합니다.

VS Code로 접속할 때도 같은 VM을 사용합니다. VS Code에는 Remote - SSH 확장을 설치하고, 개인 PC의 ~/.ssh/config에 아래 host alias를 추가합니다.

Host tta-aiqa-vm
  HostName 10.99.0.20
  User tta
  ProxyJump mrml-bastion@146.56.41.109
  PreferredAuthentications password
  PubkeyAuthentication no

설정 후 VS Code에서 Remote-SSH: Connect to Host...를 실행하고 tta-aiqa-vm을 선택합니다. 접속 창이 열리면 비밀번호를 입력하고, VM 안의 tta-aiqa repository 폴더를 열어 실습을 진행합니다.

작업 이동할 위치 예시
notebook 원본 실행 ../tta-aiqa uv run jupyter lab labs/ch03_serving/fastapi_serving_lab.ipynb
전체 산출물 재생성 ../tta-aiqa uv run python scripts/course.py labs
FastAPI 계약 확인 ../tta-aiqa uv run python labs/ch03_serving/check_serving_contract.py
Docker Compose serving 확인 ../tta-aiqa docker compose --profile serving up --build serving-api
교재 사이트 빌드 ttamlops-2607 uv run --group docs mkdocs build --strict

이 기준을 지키면 보고서에서도 증거 범위를 정확히 쓸 수 있습니다. tta-aiqa에서 실행한 결과는 로컬 재생성 또는 live smoke 결과로 쓸 수 있고, JupyterLite에서 확인한 결과는 브라우저 sample 또는 prepared evidence 확인값으로 제한해서 씁니다.

2. 3장 이후 실습 코드 배치 기준

3장 이후의 실습은 컨테이너, MLflow, FastAPI, Kubernetes, Argo CD, KServe, Grafana Cloud가 이어지므로 코드 위치가 더 중요합니다. 교재는 “무엇을 확인해야 하는가”를 설명하고, 실제 manifest와 script는 tta-aiqa에서 실행 가능해야 합니다.

흐름 tta-aiqa에 있어야 하는 실행 자산 교재에서 설명할 판단
Dockerfile로 container 만들기 demos/ch03_docker_kubernetes/Dockerfile, compose.yaml 모델과 설정이 이미지에 들어갔는가
MLflow를 container로 실행 compose.yaml의 mlflow service, MLflow tracking script 또는 notebook 모델 평가 기록과 candidate URI가 남는가
FastAPI serving 확인 labs/ch03_serving/fastapi_serving_lab.ipynb, check_serving_contract.py 요청 schema, 정상 응답, 오류 응답, 추적 필드가 맞는가
Kubernetes에 MLflow 배포 Kubernetes manifest 또는 Helm/Kustomize 경로 MLflow tracking server가 cluster에서 접근 가능한가
KServe로 후보 모델 배포 Argo CD Application, KServe InferenceService, ServingRuntime manifest 어떤 runtime이 실제 추론을 수행하는가
Grafana Cloud dashboard telemetry 전송 script, dashboard JSON, query 안내 score/prediction distribution과 오류, 지연 시간이 관측되는가

실행 자산이 아직 tta-aiqa에 없으면 교재에서 해당 명령을 성공 경로처럼 쓰면 안 됩니다. 그 경우 문서는 “필요 실행 자산”으로 남기고, 실제 Lab으로 전환하기 전에 tta-aiqa에 파일을 추가한 뒤 검증해야 합니다.