03. AI 서비스와 모델 서빙 구조¶
서빙 품질은 2장에서 평가한 모델 기준이 API와 배포 환경에서도 유지되는지 확인하는 문제입니다. 실습 API 응답에는 request_id, model_version, score, threshold, prediction이 남습니다. 이 값이 있어야 high_risk 예측 비율 증가 운영 시나리오에서 점수와 예측 분포 변화를 운영 로그로 추적할 수 있습니다.
수강생은 서빙 인수 확인 담당자 역할로 API 응답과 배포 설정을 검토합니다. 목표는 모델 지표를 다시 계산하는 것이 아니라, 평가 때 사용한 기준선(baseline) 모델과 운영 API가 같은 조건으로 동작하는지 확인하는 것입니다.
앞 장에서는 현재 운영 입력 실패 양상을 재현한 품질 저하 평가 데이터셋에서 정밀도 하락, FP 증가, PR-AUC 하락을 확인했습니다. 그러나 그 평가 기준이 실제 /predict 응답에서도 같은 모델, 같은 특성, 같은 임계값으로 적용되는지는 별도의 증거가 필요합니다. 3장은 API 호출 성공 이후의 서빙 기준 일치 여부를 확인합니다.
| 기준 | 내용 |
|---|---|
| 맡는 일 | 평가 기준이 API 응답과 배포 설정에서 유지되는지 확인 |
| 이번 장의 상황 | /predict는 200 OK를 반환하고 추적 필드를 남기지만, 평가 기준과 서빙 기준의 일치 여부를 확인해야 함 |
| 확인 증거 | 입력 스키마, score, threshold, prediction, model_version, request_id, Docker/Kubernetes 설정 |
| 판단 산출물 | 서빙/API 품질 확인 리포트와 서빙 일치성 체크 |
1. 공통 운영 시나리오 적용¶
공통 운영 시나리오 high_risk_prediction_shift는 3장에서 추적 가능성 확인으로 적용됩니다. 이 장은 운영 이상 원인을 판단하지 않고, 이후 4장에서 같은 요청과 같은 설정을 로그로 따라갈 수 있는지 확인합니다.
| 항목 | 3장에서의 적용 |
|---|---|
| 이번 장의 역할 | API 정상 응답이 운영 추적에 필요한 필드를 남기는지 확인 |
| 새로 확인하는 증거 | /predict 응답의 request_id, model_version, score, threshold, prediction |
| 후보 상태 변화 | 추적 필드 부재 후보는 약화하고, 운영 입력 변화와 로그 기반 후보는 남김 |
| 보고서 문장 | API는 정상 응답을 반환했고 model_version, threshold, request_id가 남아 운영 로그와 연결할 수 있습니다 |
| 다음 질문 | 운영 로그와 메트릭에서도 같은 필드로 점수와 예측 변화를 추적할 수 있는가 |
2. 이번 장에서 다룰 서빙 확인 상황¶
서빙 확인 사건은 평가 기준이 API 응답으로 이동하는 과정에서 발생할 수 있는 불일치를 찾는 상황입니다. 2장에서 기준선 모델과 threshold를 확인했더라도, FastAPI 앱과 컨테이너 실행 환경이 같은 모델 파일과 같은 설정을 사용하는지는 API 응답과 설정값으로 다시 확인해야 합니다.
2장 기준 모델과 threshold 확인
→ FastAPI 예측 API 호출
→ 예측 API 응답 필드 확인
→ 응답 필드: request_id, model_version, score, threshold, prediction
→ QA 판단: 운영 로그에서 같은 요청과 설정을 추적할 수 있음
이 사건에서 줄여야 할 원인 후보는 세 가지입니다. 첫째, API가 다른 모델 파일을 사용했을 가능성입니다. 둘째, 입력 스키마나 특성 순서가 평가 기준과 달라졌을 가능성입니다. 셋째, threshold나 model_version 같은 설정값이 응답과 로그에 남지 않아 추적이 어려운 상태입니다.
3. 모델 서빙 품질의 역할¶
모델 서빙 품질의 핵심은 오프라인 평가(offline evaluation) 조건과 서빙(serving) 조건을 연결하는 것입니다. 오프라인 평가는 API로 제공하기 전에 평가 데이터셋에서 지표를 계산하는 단계입니다. 서빙은 그 모델을 API로 실행해 실제 요청에 응답하는 단계입니다.
API가 200 응답을 반환해도 품질 판단은 끝나지 않습니다. 입력 스키마, 특성 순서, 전처리, 예측 클래스(class) 기준, 임계값, 모델 버전이 평가 기준과 맞아야 2장의 지표를 운영 응답과 비교할 수 있습니다.
Docker, Kubernetes, FastAPI는 도구 사용법 자체가 목적이 아닙니다. 학습 초점은 같은 모델과 설정을 반복 실행하고, API 응답과 배포 설정에서 품질 추적 정보를 확인하는 데 있습니다.
4. 핵심 질문¶
핵심 질문은 “API가 동작하는가”보다 “평가한 조건으로 동작하는가”에 가깝습니다. 다음 질문은 장애 분석뿐 아니라 배포 전 인수 확인에도 사용합니다.
| 확인 관점 | 핵심 질문 |
|---|---|
| 실행 환경 | 모델 API가 같은 실행 조건에서 재현되는가 |
| API 계약 | 입력 스키마, 정상 응답, 오류 응답이 명확한가 |
| 추적 정보 | request_id, model_version, score, threshold, prediction이 응답에 남는가 |
| 서빙 일치성 | 특성, 전처리, 예측 클래스 기준, 임계값이 평가 기준과 같은가 |
| 배포 설정 | Docker/Kubernetes 설정이 의도한 모델과 임계값을 사용하게 하는가 |
이 질문들이 모두 확인되어야 API 응답을 모델 품질 판단의 근거로 사용할 수 있습니다. 하나라도 빠지면 4장의 로그 분석과 5장의 이상 징후 판단에서 원인을 좁히기 어렵습니다.
5. 학습 흐름¶
학습 흐름은 실행 단위에서 시작해 API 계약, 서빙 일치성, 배포 설정으로 넓어집니다. 각 단계는 도구를 하나 더 배우기 위한 순서가 아니라, 평가 기준이 운영 환경으로 이동할 때 흔들릴 수 있는 지점을 하나씩 확인하는 순서입니다.
컨테이너 실행 단위 이해
→ 모델 서빙 구조 확인
→ FastAPI 예측 API 확인
→ 요청/응답 흐름 확인
→ Docker 실행 흐름 확인
→ 학습-서빙 불일치 점검
→ Kubernetes 배포 흐름 확인
이 흐름을 따라가면 모델 평가 결과가 API 응답과 배포 설정으로 어떻게 연결되는지 볼 수 있습니다. 이 장의 판단은 “평가한 모델과 기준이 운영 응답에서도 추적 가능한가”입니다.
6. 산출물과 확인 기준¶
서빙/API 품질 확인 리포트는 3장의 핵심 산출물입니다. 이 리포트는 “API가 호출된다”는 사실보다 “평가 기준과 운영 응답이 연결된다”는 근거를 남깁니다. 3장의 Demo와 Lab은 도구 학습이 아니라 서빙 불일치 원인 후보를 줄이기 위한 증거 확인입니다.
| 산출물 | 실행 또는 확인 경로 | 보고서에 남길 필드 | 약화되는 원인 후보 |
|---|---|---|---|
| API 계약 확인 결과 | labs/ch03_serving/fastapi_serving_lab.ipynb |
입력 스키마, 정상 응답 필드, 422 오류 응답 구조 | API 계약이 모호해서 분석이 불가능하다는 후보 |
| 예측 API 응답 | labs/ch03_serving/fastapi_serving_lab.ipynb와 artifacts/logs/prediction_events.jsonl |
score, threshold, prediction, model_version, request_id |
응답에서 평가 기준을 추적할 수 없다는 후보 |
| 학습-서빙 불일치 점검 결과 | labs/ch03_serving/check_serving_contract.py |
특성 목록, 순서, threshold 일치 여부 | 특성 순서나 threshold가 평가와 다르다는 후보 |
| Docker 실행 확인 | 3-5 문서와 packages/ai-quality 실행 자산 |
이미지, 컨테이너, 환경 변수, 모델 산출물 경로 | 로컬 실행 조건이 매번 달라진다는 후보 |
| 배포 흐름 확인 | 3-7, 3-8 문서의 매니페스트와 ConfigMap 예시 | 매니페스트, ConfigMap, 실행 중 설정값 | 배포 설정이 의도한 모델과 threshold를 보장하지 않는다는 후보 |
산출물의 공통 기준은 추적 가능성입니다. 어떤 모델이 어떤 입력과 임계값으로 어떤 예측을 만들었는지 설명할 수 있어야 운영 이상 징후를 분석할 수 있습니다. 따라서 3장 보고서에는 “API는 정상 응답을 반환했고 model_version, threshold, request_id가 남으므로 4장에서 운영 로그와 같은 요청을 연결해 확인할 수 있습니다”처럼 다음 조사 단계에 필요한 추적 조건을 명시합니다.
7. 문서 목록¶
문서 목록은 서빙 기준을 확인하는 순서입니다.
| 순서 | 문서 | 확인할 내용 |
|---|---|---|
| 1 | 컨테이너 기본 개념 | 컨테이너, 이미지, 동일 실행 환경 재현 |
| 2 | 모델 서빙 구조와 실행 단위 | 예측 API, 모델 로더, 전처리 코드, 설정값의 위치 |
| 3 | FastAPI 기반 예측 API 확인 | 입력 스키마, API 계약, 오류 응답 확인 |
| 4 | 요청과 응답 흐름 이해 | 요청(request), 응답(response), JSON, request_id 기반 추적 |
| 5 | Docker 기반 모델 컨테이너 실행 | Dockerfile, 실행 흐름, 환경 변수, 상태 확인 |
| 6 | Train-Serving Skew와 서빙 일치성 검증 | 특성, 전처리, 예측 클래스, 임계값 일치성 |
| 7 | Kubernetes 실행 구조 이해 | Pod, Deployment, 매니페스트 구조 |
| 8 | 모델 배포 흐름 확인 | 배포 후 API 응답과 설정값 확인 |
| 9 | 3장 마무리 | 서빙 구조를 QA 체크로 바꾸는 기준 |
| 10 | 전체 참고문헌 | 출처와 추가 학습 자료 |
이 장이 끝나면 수강생은 Kaggle 기반 모델이 어떤 API 응답과 배포 설정으로 실행되는지 설명할 수 있어야 합니다. 남은 질문은 운영 중 같은 요청과 예측 변화를 로그와 메트릭으로 추적할 수 있는가입니다.