3-5. Docker 기반 모델 컨테이너 실행¶

Docker Demo는 모델 API를 같은 실행 조건으로 묶고, 실행 후에도 3-3에서 확인한 API 계약(contract)이 유지되는지 보는 과정입니다. 명령어 암기보다 이미지(image)에 포함된 모델 산출물(model artifact), 컨테이너(container)의 실행 설정, /health와 /predict 응답을 확인하는 데 집중합니다.

이 문서를 읽을 때는 다음 기준을 중심으로 확인합니다.

Dockerfile 포함물: 코드, 설정 파일, 모델 산출물이 의도한 경로에 들어가는지 확인
실행 설정: MODEL_VERSION, MODEL_THRESHOLD, 포트(port)가 실제 컨테이너에 적용되는지 확인
응답 확인: /health와 /predict에서 모델 버전(model_version), 점수(score), 임계값(threshold), 예측(prediction)을 확인
Demo 범위: Docker 운영 심화가 아니라 배포 산출물(artifact)과 실행 결과 확인에 집중

3-5-1. 제공된 Dockerfile 구조 확인¶

Docker Demo는 demos/ch03_docker_kubernetes에 있습니다. Dockerfile은 앞에서 확인한 FastAPI 애플리케이션 코드, 설정 파일, 2장에서 만든 모델 산출물을 이미지에 포함합니다. 즉 Docker는 API 계약 자체를 새로 만드는 단계가 아니라, 이미 확인한 API를 같은 실행 환경으로 묶어 재현하는 단계입니다.

Dockerfile에서 가장 먼저 볼 부분은 코드, 설정, 모델 산출물이 이미지에 함께 들어가는지입니다. 이 세 가지가 분리되어 있으면 컨테이너는 실행되더라도 평가 때 확인한 모델과 다른 조건으로 API가 실행될 수 있습니다.

COPY packages ./packages
COPY configs ./configs
COPY artifacts/models/chapter_02_baseline.pkl ./artifacts/models/chapter_02_baseline.pkl

이 구조에서 QA가 확인할 것은 “어떤 모델이 이미지에 들어갔는가”와 “실행 시 어떤 임계값이 적용되는가”입니다. Dockerfile을 읽을 때는 명령어를 외우기보다 모델 산출물과 설정이 어디에서 들어오는지 확인해야 합니다.

Dockerfile 요소	QA 질문
`COPY packages`	앞에서 확인한 FastAPI 코드와 공통 패키지 포함 여부
`COPY configs`	서빙 설정과 특성(feature) 설정 포함 여부
`COPY artifacts/models`	의도한 기준선(baseline) 모델 포함 여부
`CMD` 또는 실행 명령	FastAPI 서빙 앱 실행 여부

Dockerfile에 모델 산출물을 직접 포함하는 방식은 교육용으로 단순합니다. 실무에서는 모델 레지스트리(model registry)나 외부 저장소에서 산출물을 가져오는 구조도 많습니다. 어떤 방식이든 QA가 확인해야 할 핵심은 동일합니다. 서빙 시점에 어떤 모델이 사용되는지 추적 가능해야 합니다.

이 Demo에서 Dockerfile의 기본 설정은 다음과 같습니다.

설정	값	QA 해석
`MODEL_PATH`	`artifacts/models/chapter_02_baseline.pkl`	2장 기준선 모델 사용
`MODEL_VERSION`	`v1`	응답과 로그에서 확인할 모델 버전
`MODEL_THRESHOLD`	`0.5`	2장 평가 기준과 연결되는 임계값
`EVENT_LOG_PATH`	`artifacts/logs/prediction_events.jsonl`	요청 로그 추적 가능

QA는 Dockerfile의 값만 보고 끝내지 않습니다. 이미지에 적힌 기본값이 실행 시 환경 변수(env)로 덮어써질 수 있기 때문에, 컨테이너 실행 후 API 응답에서 실제 model_version과 threshold를 다시 확인해야 합니다.

3-5-2. 모델 컨테이너 실행 흐름¶

모델 컨테이너 실행은 빌드(build), 실행(run), 확인(check) 순서로 이해하면 됩니다. 빌드는 이미지를 만드는 단계이고, 실행은 이미지를 컨테이너로 실행하는 단계이며, 확인은 실행된 API가 앞에서 확인한 요청/응답 계약(contract)을 유지하는지 확인하는 단계입니다.

bash demos/ch03_docker_kubernetes/scripts/build_image.sh
bash demos/ch03_docker_kubernetes/scripts/run_container.sh

build_image.sh는 모델 산출물이 없으면 먼저 2장 기준선 학습을 실행하라고 안내합니다. 이 확인이 없으면 잘못된 이미지를 만들거나 빌드 중간에 실패할 수 있습니다.

실행 흐름은 다음처럼 QA 확인 항목으로 읽습니다.

단계	스크립트	확인 내용
build	`build_image.sh`	Dockerfile이 성공적으로 이미지를 만들고 모델 산출물이 포함되는지
run	`run_container.sh`	컨테이너가 올바른 포트와 환경 변수로 실행되는지
상태 확인(health check)	`check_container.sh`	모델 로딩과 API 실행 상태가 정상인지
예측 API 간단 확인(smoke test)	`check_container.sh`	`/predict` 응답에 필수 필드(field)가 있는지

이 Demo는 수강생이 Docker 운영자가 되기 위한 실습이 아닙니다. QA가 배포 산출물과 실행 결과를 어떻게 확인하는지 보는 Demo입니다. 따라서 Docker 명령어 세부 옵션보다 상태 확인과 예측 응답(prediction response)을 더 중요하게 봅니다.

실습 환경에서 Docker 실행이 어렵다면 먼저 실패 원인을 구분합니다. Docker Desktop 또는 daemon이 실행되지 않았거나 권한이 없으면 이 Demo는 실행 blocker입니다. 이때는 스크립트를 실행한 것으로 간주하지 않고, Dockerfile, build_image.sh, run_container.sh, check_container.sh를 읽어 artifact inspection 결과로 남깁니다. 이 경우에도 확인할 질문은 같습니다. 어떤 모델 파일이 이미지에 들어가고, 어떤 환경 변수가 실행 중인 API 응답으로 드러나야 하는지 확인합니다.

Docker를 실행하지 못한 경우 보고서는 실행 결과와 inspection 결과를 분리해야 합니다. 다음 항목을 확인하면 Dockerfile 기준으로 의도된 배포 설정은 설명할 수 있지만, live response 검증을 했다고 쓰면 안 됩니다.

inspection 항목	확인값	보고서에서 쓸 수 있는 말
모델 산출물	`artifacts/models/chapter_02_baseline.pkl`	이미지가 2장 기준선 모델을 포함하도록 정의됨
모델 버전	`MODEL_VERSION=v1`	기본 실행 설정은 `v1`을 응답과 로그에 노출하도록 정의됨
임계값	`MODEL_THRESHOLD=0.5`	기본 실행 설정은 2장 평가 기준 임계값과 연결됨
이벤트 로그	`EVENT_LOG_PATH=artifacts/logs/prediction_events.jsonl`	예측 이벤트를 구조화 로그로 남기도록 정의됨

이때 사용할 수 있는 보고서 문장은 다음처럼 제한합니다.

Docker live smoke test는 실행하지 못했습니다. 다만 Dockerfile inspection 결과 이미지에는 `chapter_02_baseline.pkl`이 포함되고, 기본 `MODEL_VERSION=v1`, `MODEL_THRESHOLD=0.5`, `EVENT_LOG_PATH=artifacts/logs/prediction_events.jsonl` 설정이 정의되어 있습니다.
따라서 Dockerfile 기준의 의도된 서빙 설정은 2장 평가 기준과 연결되지만, 실행 중 `/predict` 응답값 검증은 미완료입니다.

3-5-3. 환경 변수와 설정값 확인¶

Docker 실행 시 MODEL_VERSION, MODEL_THRESHOLD를 환경 변수로 전달할 수 있습니다. 이 값들은 같은 이미지를 다른 설정으로 실행할 수 있게 합니다. 편리하지만, 동시에 품질 문제의 원인이 될 수 있습니다.

환경 변수	기본값	QA 확인
`MODEL_VERSION`	`v1`	응답의 `model_version`과 일치하는지 확인
`MODEL_THRESHOLD`	`0.5`	임계값 변경이 FP/FN 변화로 이어질 수 있음을 확인
`API_PORT`	`8000`	컨테이너 포트(container port)와 서비스 포트(service port)를 구분

환경 변수는 코드 리뷰만으로 확인하기 어렵습니다. 실행 중인 컨테이너가 어떤 환경 변수를 받았는지, API 응답에 어떤 값이 나타나는지 확인해야 합니다. 특히 임계값은 모델 품질 지표와 직접 연결됩니다.

QA는 환경 변수 변경을 배포 변경으로 취급해야 합니다. 모델 파일이 같아도 임계값이 바뀌면 정밀도(Precision)와 재현율(Recall)이 달라질 수 있기 때문입니다. 따라서 임계값 변경은 실험 기록, 평가 기준, 배포 기록에 함께 남아야 합니다.

3-5-4. 실행 상태 확인¶

컨테이너 실행 후 다음 스크립트(script)로 상태 확인과 예측 API를 확인합니다.

bash demos/ch03_docker_kubernetes/scripts/check_container.sh

check_container.sh는 /health를 호출한 뒤, docker-smoke-001 요청으로 /predict를 호출합니다. 이 출력은 모델 품질을 평가하기 위한 숫자가 아니라, 배포된 API가 품질 추적에 필요한 값을 반환하는지 확인하기 위한 간단 확인(smoke test)입니다.

확인	기대 결과	QA 해석
`/health`	`status=ok`, `model_version=v1`	모델 로딩과 실행 상태 확인
`/predict`	`request_id`, `score`, `threshold`, `prediction` 포함	4장 운영 로그와 5장 분포 분석으로 연결 가능

상태 확인은 API 프로세스가 살아 있는지, 모델 로딩이 성공했는지 확인하는 기본 신호입니다. 그러나 상태 확인이 성공했다고 해서 모델 품질이 보장되는 것은 아닙니다. /predict 간단 확인을 통해 실제 요청/응답 계약(contract)을 확인해야 합니다.

예상 응답은 다음과 같은 형태입니다. 점수는 모델과 입력에 따라 달라질 수 있으므로, 숫자 자체보다 필드 존재와 설정값 일치 여부를 봅니다.

{
  "request_id": "docker-smoke-001",
  "model_version": "v1",
  "score": 0.53,
  "threshold": 0.5,
  "prediction": "high_risk"
}

실행 상태 확인에서 QA가 봐야 할 것은 다음입니다.

확인 항목	이유
응답 상태 코드(status code)	API 호출이 성공했는지 확인
`model_version`	의도한 모델 버전인지 확인
`threshold`	평가 기준과 같은 임계값이 적용되었는지 확인
`prediction`	최종 클래스(class)가 반환되는지 확인
로그 생성	요청(request) 추적이 가능한지 확인

준비된 inspection 결과를 함께 확인하려면 artifacts/reports/chapter_03_serving_inspection.md를 읽습니다. 이 파일은 Dockerfile과 Kubernetes manifest의 설정값을 수강생 보고서에 옮기기 위한 근거 자료이며, live 실행 결과를 대체하지는 않습니다.