3-8. 모델 배포 흐름 확인¶
3-8 Demo는 Docker와 Kubernetes에서 모델 API가 실행된 뒤에도 2장에서 평가한 기준선(baseline) 모델과 임계값(threshold)이 유지되는지 확인하는 과정입니다. 배포 명령 자체보다 배포 후 응답과 설정값이 품질 판단 근거로 남는지를 봅니다.
이 문서를 읽을 때는 다음 기준을 중심으로 확인합니다.
- Docker 실행 결과:
/health와/predict응답에서 모델 버전(model_version), 점수(score), 임계값, 예측(prediction) 확인 - Kubernetes 적용 결과: ConfigMap, Deployment, Pod, Service의 설정 흐름 확인
- 오류 요청 확인: 잘못된 입력이 검증 오류(validation error)로 처리되는지 확인
- 운영 관측 연결: 응답 필드(field)가 로그와 지표로 이어질 수 있는지 확인
3-8-1. Docker 기반 모델 컨테이너 실행¶
Docker Demo는 이미지 빌드(image build), 컨테이너 실행(container run), 상태 확인(health check), 예측 API 간단 확인(smoke test) 순서로 확인합니다. run_container.sh는 컨테이너를 포그라운드로 실행하므로, 상태 확인 스크립트는 다른 터미널에서 실행합니다.
Docker daemon 권한이 없거나 로컬 포트 사용이 제한된 환경에서는 아래 명령이 실패할 수 있습니다. 이 경우 실패를 수강생의 실습 실패로 보지 않고, 실행 blocker로 기록합니다. 대신 demos/ch03_docker_kubernetes/Dockerfile과 scripts 파일을 inspection해서 어떤 모델 artifact와 환경 변수가 배포 증거가 되어야 하는지 정리합니다.
bash demos/ch03_docker_kubernetes/scripts/build_image.sh
bash demos/ch03_docker_kubernetes/scripts/run_container.sh
컨테이너가 실행된 상태에서 다른 터미널에서 다음 명령을 실행합니다.
bash demos/ch03_docker_kubernetes/scripts/check_container.sh
확인할 것은 빌드 로그(build log) 전체가 아닙니다. 어떤 모델 산출물(model artifact)이 이미지(image)에 들어갔고, 컨테이너 실행 후 어떤 응답이 나오는지입니다. 수강생은 /health와 /predict 결과에서 모델 버전, 임계값, 예측이 보이는지 확인합니다.
Docker 기반 확인은 다음처럼 정리합니다.
| 확인 단계 | 관측할 값 | QA 판단 |
|---|---|---|
| 이미지 빌드(image build) | chapter_02_baseline.pkl 포함 여부 |
2장 기준선 모델 사용 |
| 컨테이너 실행(container run) | MODEL_VERSION, MODEL_THRESHOLD |
평가 기준과 운영 설정 연결 |
/health |
status, model_version |
API 실행과 모델 로딩 확인 |
/predict |
request_id, score, threshold, prediction |
요청 추적과 품질 관측 가능성 확인 |
Demo 실패 시에는 모델 산출물이 있는지, Docker가 실행 중인지, 권한이 있는지, 포트(port)가 충돌하지 않는지 확인합니다. Docker daemon 권한 문제처럼 교육장 환경에서 바로 해결하기 어려운 실패라면 blocked: Docker daemon unavailable로 남기고 artifact inspection 결과를 보고서 근거로 사용합니다. 그러나 핵심은 Docker 문제 해결이 아니라 배포 후 품질 관측에 필요한 정보가 응답과 로그에 노출되는지 확인하는 것입니다.
3-8-2. 제공된 매니페스트(manifest) 기반 배포 흐름 확인¶
Kubernetes 환경이 있고 실습용 namespace에 적용해도 되는 상황이라면 다음 순서로 매니페스트를 적용합니다. 이 명령은 클러스터 상태를 변경하므로, 권한이 없거나 공유 클러스터 정책이 불명확하면 실행하지 않습니다. 이 Demo의 핵심은 매니페스트를 새로 작성하는 것이 아니라 제공된 파일에서 설정 흐름과 실행 후 증거를 확인하는 것입니다.
kubectl apply -f demos/ch03_docker_kubernetes/k8s/namespace.yaml
kubectl apply -f demos/ch03_docker_kubernetes/k8s/configmap.yaml
kubectl apply -f demos/ch03_docker_kubernetes/k8s/deployment.yaml
kubectl apply -f demos/ch03_docker_kubernetes/k8s/service.yaml
QA 관점의 핵심은 apply 명령 자체가 아닙니다. 매니페스트에 적힌 이미지와 환경 변수(env)가 실제 Pod에 반영되었는지, 준비 상태(readiness)가 통과했는지, Service를 통해 API에 접근할 수 있는지입니다.
제공된 매니페스트는 설정이 어떤 경로로 API 실행에 들어가는지 보여줍니다.
| 확인 단계 | 수강생이 볼 것 | QA 판단 |
|---|---|---|
| ConfigMap 적용 | MODEL_VERSION, MODEL_THRESHOLD, API_PORT, EVENT_LOG_PATH |
운영 설정값의 출처 확인 |
| Deployment 적용 | 이미지, envFrom, readinessProbe |
설정 주입과 준비 상태 기준 확인 |
| Pod 상태 | Running, Ready | 트래픽을 받을 준비 여부 확인 |
| Service 확인 | port: 80, targetPort: 8000 |
외부 접근 포트와 컨테이너 포트 연결 확인 |
ConfigMap과 Deployment의 연결은 특히 중요합니다. ConfigMap에 있는 MODEL_THRESHOLD: "0.5"가 컨테이너 환경 변수로 들어가고, FastAPI 앱이 이 값을 읽어 /predict 응답의 threshold로 반환해야 평가 기준과 운영 기준을 연결할 수 있습니다.
반대로 MODEL_PATH는 이 Demo의 ConfigMap에 들어 있지 않습니다. 모델 파일은 Docker 이미지에 포함되고, Dockerfile의 기본 MODEL_PATH 설정을 사용합니다. 그래서 배포 확인은 ConfigMap만 보는 것으로 끝나지 않습니다. 이미지가 어떤 모델 산출물을 포함했는지, 그리고 실행 중 응답이 어떤 model_version과 threshold를 반환하는지 함께 확인해야 합니다.
Kubernetes 환경이 없거나 클러스터 변경 side effect가 허용되지 않으면 매니페스트를 읽고 확인 포인트만 검토합니다. 이 경우에도 학습 목표는 유지됩니다. 실제 명령 실행보다 배포 구조를 이해하고 QA 확인 항목을 정리하는 것이 목적입니다.
no-apply 검토에서는 클러스터 상태를 바꾸지 않고 다음 항목만 확인합니다. 이 표는 매니페스트 inspection으로 쓸 수 있는 근거와, 실제 배포 후에만 말할 수 있는 근거를 구분하기 위한 장치입니다.
| 파일 | inspection 확인값 | 아직 말하면 안 되는 결론 |
|---|---|---|
configmap.yaml |
MODEL_VERSION=v1, MODEL_THRESHOLD=0.5, API_PORT=8000, EVENT_LOG_PATH=artifacts/logs/prediction_events.jsonl |
실행 중 Pod가 실제로 이 값을 읽었다 |
deployment.yaml |
이미지 ai-quality-serving:chapter-03, envFrom ConfigMap, readinessProbe /health |
Pod가 Ready 상태로 트래픽을 받았다 |
service.yaml |
port: 80, targetPort: 8000 |
Service를 통해 API 호출이 성공했다 |
이 경우 보고서 문장은 다음처럼 씁니다.
Kubernetes apply는 실행하지 않았으므로 live response는 검증하지 못했습니다.
Manifest inspection 결과 ConfigMap은 `MODEL_VERSION=v1`, `MODEL_THRESHOLD=0.5`, `EVENT_LOG_PATH=artifacts/logs/prediction_events.jsonl`을 정의하고, Deployment는 `envFrom`과 `/health` readinessProbe를 사용합니다.
따라서 manifest 기준의 의도된 설정 흐름은 확인했지만, 실행 중 Pod 응답과 Service 접근성은 4장 또는 별도 배포 환경에서 재확인해야 합니다.
3-8-3. 배포 후 API 응답 확인¶
배포 후에는 API가 정상 응답을 반환하는지 확인합니다. 여기서 정상 응답은 200 상태 코드(status code)만 뜻하지 않습니다. 응답 안에 모델 버전, 점수, 임계값, 예측, request_id가 있어야 로그와 대시보드로 이어질 수 있습니다.
bash demos/ch03_docker_kubernetes/scripts/check_k8s_deployment.sh
실습 환경에 Kubernetes가 없거나 권한이 없으면 check_k8s_deployment.sh를 실행하지 않고 매니페스트와 스크립트를 읽어 확인 포인트만 검토합니다. 중요한 것은 배포 도구 사용법이 아니라, 배포 후에도 API 계약(contract)과 설정값이 유지되는지 확인하는 것입니다.
준비된 inspection 결과는 artifacts/reports/chapter_03_serving_inspection.md에 정리되어 있습니다. 이 파일은 Docker/Kubernetes 실행 권한이 없는 수강생이 보고서에 남길 수 있는 inspection 근거를 제공하지만, /health와 /predict live 호출 증거는 아닙니다.
배포 후 확인은 다음 순서로 진행합니다.
| 순서 | 확인 | 품질 판단으로 이어지는 질문 |
|---|---|---|
| 1 | /health 응답에서 상태와 model_version 확인 |
의도한 모델 버전이 실행 중인가 |
| 2 | /predict 정상 요청으로 점수, 임계값, 예측 확인 |
평가 기준과 같은 임계값이 적용되는가 |
| 3 | 잘못된 요청으로 검증 오류(validation error) 확인 | 입력 계약(contract)이 예측 로직 전에 동작하는가 |
| 4 | 로그에서 request_id가 남는지 확인 |
요청 단위 원인 추적이 가능한가 |
이 확인은 운영 관측(observability)의 준비 단계입니다. API가 응답에 필요한 정보를 포함하지 않으면 운영 대시보드에서도 품질 상태를 제대로 볼 수 없습니다.
3-8-4. 모델 버전과 임계값 설정 확인¶
배포 후 /health와 /predict 응답에서 model_version, threshold, prediction을 확인합니다. 이 정보가 빠지면 운영 품질을 관측할 때 모델 버전이나 임계값 변경의 영향을 추적하기 어렵습니다.
모델 버전은 어떤 모델이 응답했는지 알려 주고, 임계값은 점수를 클래스(class)로 바꾸는 기준을 알려 줍니다. 예측은 최종 클래스이고, 점수는 임계값 적용 이전의 모델 출력입니다. 이 네 가지가 함께 있어야 배포 후 품질 문제를 설명할 수 있습니다.
| 응답 값 | 품질 문제 분석에서의 역할 |
|---|---|
model_version |
배포 버전 확인 |
score |
점수 분포(score distribution) 변화 확인 |
threshold |
FP/FN 기준 변화 확인 |
prediction |
예측 분포(prediction distribution) 변화 확인 |
배포 후 QA 코멘트는 다음처럼 쓰는 것이 좋습니다.
배포된 API는 `/health`에서 `model_version=v1`을 반환하고, `/predict` 응답에 `request_id`, `score`, `threshold`, `prediction`을 포함합니다.
ConfigMap의 `MODEL_THRESHOLD=0.5`가 응답의 `threshold`와 일치하므로 평가 기준과 운영 기준이 연결됩니다.
다음 단계에서는 이 응답 필드가 구조화 로그와 메트릭으로 남는지 확인합니다.
모델 서빙 품질의 결론은 AI 서비스 품질이 모델 파일 하나만으로 결정되지 않는다는 점입니다. 컨테이너 실행 환경, API 계약, 특성 스키마(feature schema), 임계값, 모델 버전, 배포 설정이 모두 연결됩니다. QA는 API가 실행되는지만 확인하지 말고, 학습과 평가 기준이 서빙 기준과 일치하는지 확인해야 합니다.