3-1. 컨테이너 기본 개념¶
컨테이너(container)는 모델 서빙 API를 같은 조건으로 실행하기 위한 배포 단위입니다. 3-1에서는 컨테이너를 운영 인프라 심화 주제로 다루지 않고, 평가 때 확인한 모델 파일, 패키지, 설정값이 서빙 환경에서도 재현되는지 확인하는 관점으로 설명합니다.
이 문서를 읽을 때는 다음 기준을 중심으로 확인합니다.
- 실행 조건 재현: Python 버전, 패키지, 모델 파일, 설정값이 함께 묶이는지 확인
- 이미지(image)와 컨테이너 구분: 배포 대상 산출물과 실제 실행 상태를 분리해서 확인
- 설정값 추적:
MODEL_VERSION,MODEL_THRESHOLD, 모델 경로가 의도한 값인지 확인 - 한계 인식: 컨테이너가 특성(feature), 전처리, 예측 클래스(class) 기준 일치를 자동 보장하지는 않음
3장의 상황으로 보면 컨테이너는 “API를 실행하는 포장”이 아니라, 2장에서 평가한 기준선 모델과 설정을 같은 조건으로 실행하기 위한 확인 단위입니다. chapter_02_baseline.pkl을 사용한다고 생각했는데 컨테이너 안에서는 다른 모델 경로나 다른 MODEL_THRESHOLD가 적용되면, API는 정상 응답해도 2장의 평가 결과와 연결하기 어렵습니다.
3-1-1. 컨테이너가 필요한 이유¶
AI 모델 평가는 노트북이나 로컬 스크립트에서 끝나지 않습니다. 실제 서비스에서는 모델 파일, Python 패키지, API 서버, 설정값, 로그 경로가 함께 실행되어야 합니다. 이 중 하나라도 개발 환경과 운영 환경에서 달라지면 같은 모델을 사용하더라도 다른 결과가 나올 수 있습니다.
컨테이너는 실행 환경을 하나의 배포 단위로 묶는 방법입니다. 모델 서빙 API를 실행할 때 필요한 코드, 패키지, 설정, 모델 산출물(model artifact)을 이미지에 포함하고, 그 이미지를 컨테이너로 실행합니다. QA 관점에서는 컨테이너가 “모델 품질을 높이는 도구”라기보다 “같은 조건으로 실행하고 검증할 수 있게 만드는 도구”입니다.
Docker 공식 문서는 컨테이너를 애플리케이션과 실행 의존성을 함께 패키징해 실행하는 방식으로 설명합니다. AI 서비스에서 이 설명은 특히 중요합니다. 모델 API는 Python 코드만으로 동작하지 않고, 모델 산출물, 라이브러리 버전, 설정값, 실행 명령, 로그 경로가 함께 맞아야 합니다. 따라서 컨테이너는 모델 품질을 직접 보장하지는 않지만, 품질 확인을 반복 가능한 조건으로 묶어 주는 장치입니다.
실행 환경 차이는 같은 모델 artifact의 예측 결과나 실행 안정성을 바꿀 수 있습니다. 예를 들어 로컬 스크립트에서는 특정 Python 버전과 scikit-learn 버전으로 모델이 정상 동작했는데, 서빙 서버에는 다른 버전의 패키지가 설치되어 있다면 예측 결과나 실행 오류가 달라질 수 있습니다. 컨테이너는 이런 차이를 줄이기 위해 사용됩니다. 이 저장소의 Dockerfile은 python:3.11-slim을 기준 이미지(base image)로 사용하고, uv sync --frozen으로 실행 의존성을 고정합니다.
| 확인 항목 | QA 관점 |
|---|---|
| Python 버전 | 학습 환경과 서빙 환경 차이로 인한 오류를 감소 |
| 패키지 버전 | scikit-learn, FastAPI 등 실행 의존성을 고정 |
| 모델 파일 위치 | API가 의도한 모델 artifact를 읽는지 확인 |
| 환경 변수 | MODEL_VERSION, MODEL_THRESHOLD가 의도와 같은지 확인 |
| 실행 포트 | 서비스가 노출되는 포트와 문서가 일치하는지 확인 |
컨테이너는 모델 품질을 직접 보장하지 않습니다. 결측값(missing value)이 많은 데이터가 들어오면 같은 컨테이너를 사용해도 점수(score)와 예측(prediction) 분포는 흔들릴 수 있습니다. 그러나 같은 모델과 같은 설정을 반복 실행할 수 있기 때문에, 품질 확인 결과를 재현하고 배포 후 문제를 추적하는 데 중요합니다.
2장에서 만든 기준선(baseline) 모델을 예로 들면, 컨테이너에서 확인해야 할 것은 지표(metric) 개선이 아닙니다. artifacts/models/chapter_02_baseline.pkl을 의도한 경로에서 읽고, threshold=0.5, model_version=v1 같은 설정을 API 응답과 로그에서 확인할 수 있는지입니다. 이 정보가 확인되지 않으면 API 응답의 prediction이 평가 때의 판단 기준에서 나온 것인지 설명하기 어렵습니다.
흔한 오해는 “컨테이너로 배포했으니 학습 환경과 서빙 환경이 완전히 같다”는 것입니다. 컨테이너는 실행 환경을 고정하는 데 도움을 주지만, 학습 때 사용한 특성 목록, 전처리 방식, 예측 클래스 기준, 임계값(threshold)이 서빙 코드와 일치하는지는 별도로 확인해야 합니다. 이 문제는 “학습 기준과 서빙 기준의 불일치”이며, 3-6에서 학습-서빙 불일치(Train-Serving Skew)라는 이름으로 다시 다룹니다.
3-1-2. 이미지와 컨테이너의 차이¶
이미지는 실행에 필요한 파일과 설정을 담은 정적인 산출물입니다. 컨테이너는 그 이미지를 실제로 실행한 인스턴스입니다. 같은 이미지를 여러 번 실행하면 여러 컨테이너가 생길 수 있습니다.
QA가 이 차이를 이해해야 하는 이유는 배포 대상과 실행 상태가 다르기 때문입니다. 이미지에는 어떤 코드와 모델이 포함되었는지 확인해야 하고, 컨테이너에서는 실제로 실행 중인 프로세스가 올바른 설정으로 동작하는지 확인해야 합니다.
| 구분 | 의미 | QA 확인 포인트 |
|---|---|---|
| 이미지 | 실행 파일, 패키지, 모델 파일을 담은 빌드 결과 | 어떤 모델 파일과 설정이 포함되었는지 확인 |
| 컨테이너 | 이미지가 실행된 프로세스 | 상태 확인(health check), API 응답, 로그를 확인 |
| 태그(tag) | 이미지 버전 식별자 | 배포 대상 이미지가 의도한 버전인지 확인 |
컨테이너 이미지는 태그뿐 아니라 포함된 모델 산출물과 설정값까지 확인해야 합니다. 예를 들어 ai-quality-serving:v1이라는 이미지를 만들었다고 하겠습니다. 이 이미지가 실제로 어떤 모델 산출물을 포함하는지, MODEL_VERSION이 어떤 값으로 설정되는지 확인해야 합니다. 그런 다음 컨테이너를 실행하고 /health와 /predict 응답에서 동일한 정보가 노출되는지 확인합니다.
이 차이를 모르면 “빌드한 이미지가 맞다”와 “현재 실행 중인 컨테이너가 맞다”를 혼동하기 쉽습니다. QA는 이미지의 포함물과 컨테이너의 실행 상태를 둘 다 확인해야 합니다.
이미지 태그(image tag)도 중요합니다. latest 태그만 사용하면 실제로 어떤 코드와 모델이 배포되었는지 추적하기 어렵습니다. 실습에서는 단순화를 위해 로컬 이미지(local image)를 사용하지만, 실무에서는 이미지 태그, 모델 버전(model_version), git commit, 데이터셋 버전(dataset version)을 함께 기록해야 배포 이력을 설명할 수 있습니다.
3-1-3. 동일 실행 환경 재현¶
같은 모델 평가 결과를 서비스에서 재현하려면 학습과 평가에 사용한 특성, 예측 클래스 기준, 임계값, 모델 버전이 서빙 환경과 맞아야 합니다. 컨테이너는 이 정보를 실행 환경에 묶는 수단이지만, 모든 항목의 일치 여부를 자동으로 검증해 주지는 않습니다.
동일 실행 환경 재현은 “API가 실행된다”보다 더 넓은 의미입니다. API가 정상 응답을 반환하더라도 임계값이 평가 때와 다르거나, 모델 산출물이 다른 버전이거나, 특성 순서가 달라지면 품질이 달라질 수 있습니다. QA는 실행 성공과 품질 조건 일치를 구분해야 합니다.
| 재현 대상 | 확인 방법 |
|---|---|
| 코드 버전 | 이미지 태그, git commit, 배포 기록 |
| 모델 산출물 | 모델 경로(model path), 해시(checksum), 모델 버전 |
| 특성 목록 | configs/validation/model_features.yaml, API 스키마(schema) |
| 임계값 | MODEL_THRESHOLD, 응답의 threshold |
| 예측 클래스 기준 | low_risk, high_risk 기준 |
컨테이너는 QA가 동일 조건을 확인할 수 있도록 정보를 한곳에 모아 줍니다. 그러나 검증 항목을 응답이나 로그에 남기지 않으면 실제 운영에서 확인하기 어렵습니다. 그래서 실습 예측 응답에는 model_version, score, threshold, prediction, request_id를 포함합니다.
같은 확인은 실행 전후로 나누어 볼 수 있습니다. 실행 전에는 이미지에 어떤 모델 파일과 설정이 들어갔는지 확인하고, 실행 후에는 실제 API 응답과 로그가 같은 값을 노출하는지 확인합니다.
| 시점 | 확인 대상 | 판단 |
|---|---|---|
| 실행 전 | 이미지, 설정 파일, 모델 경로 | 의도한 산출물이 배포 단위에 포함되었는지 확인 |
| 실행 후 | /health, /predict 응답, 예측 이벤트 로그 |
실행 중인 컨테이너가 의도한 모델과 임계값을 사용하는지 확인 |
3-1-4. AI 서비스에서 컨테이너가 담는 것¶
실습 Dockerfile은 demos/ch03_docker_kubernetes/Dockerfile에 있습니다. Dockerfile은 애플리케이션 코드, 설정 파일, 모델 산출물, 실행 명령을 이미지에 포함합니다.
Docker image 문서 관점에서 이미지는 실행에 필요한 파일과 설정을 담은 패키지입니다. QA는 이미지를 “배포 파일”로만 보지 말고, 어떤 모델과 설정이 함께 묶였는지 확인해야 합니다. 같은 코드라도 이미지에 포함된 모델 산출물이 다르면 API가 반환하는 점수와 예측은 달라질 수 있습니다.
| 구성 요소 | 예시 | QA 확인 |
|---|---|---|
| 애플리케이션 코드 | packages/ai-quality/src/ai_quality |
예측 API와 공통 로직이 포함되었는지 |
| 설정 파일 | configs/operations/serving.yaml, configs/validation/model_metadata.yaml |
임계값과 모델 경로 기준이 맞는지 |
| 모델 산출물 | artifacts/models/chapter_02_baseline.pkl |
2장에서 만든 기준선 모델인지 |
| 실행 명령 | python -m ai_quality.serving.infrastructure.fastapi_app |
의도한 API 서버가 실행되는지 |
컨테이너에 무엇이 들어가는지 확인하는 것은 배포 전 QA의 기본입니다. 모델 산출물이 누락되면 API가 실행되지 않을 수 있고, 잘못된 산출물이 들어가면 API는 정상 응답을 주지만 2장에서 평가한 모델과 다른 기준으로 예측할 수 있습니다.
실제 운영 기준은 설정 파일과 환경 변수의 우선순위까지 확인해야 알 수 있습니다. configs/operations/serving.yaml에 임계값이 있어도 Docker 또는 Kubernetes에서 환경 변수로 덮어쓰면 실제 운영 임계값은 달라질 수 있습니다. QA는 파일에 적힌 값이 아니라 실행 중인 응답과 로그에 남는 값을 확인해야 합니다.