실행 환경과 운영 기록¶

배포 설정이 Candidate B를 가리키고, 확인한 API가 HTTP 200을 반환해도 두 자료가 같은 실행 환경을 가리킨다는 보장은 없습니다. 따라서 대상 환경에서 Candidate B가 실행 중이라고 곧바로 단정할 수는 없습니다.

배포 설정은 실행하려는 상태를 보여 주고, API 응답과 대시보드는 직접 확인한 환경의 상태를 보여 줍니다. 모델 승인은 미리 확정한 공식 평가 결과를 바탕으로 내린 별도 결론입니다. 이 절에서는 실행 환경과 운영 기록(telemetry)을 어디까지 근거로 사용할 수 있는지 설명합니다.

이 문서에서 먼저 나눌 것

선언 파일은 실행하려는 상태를, API와 운영 기록은 직접 확인한 상태를 보여 줍니다.
API의 HTTP 200은 한 요청의 규약 처리를 뜻하며, 대상 환경 전체의 배포 완료를 뜻하지 않습니다.
지표·로그·추적 기록은 서로 같은 정보를 반복하는 자료가 아니라, 조사 범위를 좁히는 서로 다른 도구입니다.

모델 파일에서 API까지 이어지는 실행 구조¶

승인된 모델 파일은 혼자서 요청을 처리하지 못합니다. FastAPI 같은 웹 애플리케이션이 입력 형식을 검사하고 모델을 호출한 뒤, 점수와 예측을 응답으로 돌려줍니다. 이 과정에서는 FastAPI를 처음부터 구현하지 않고 제공된 코드에서 입력 스키마, 모델 호출, 오류 응답과 모델 정보가 어디에서 정해지는지 확인합니다.

컨테이너(container)는 애플리케이션 코드, 라이브러리와 실행 설정을 같은 환경에서 실행할 수 있도록 묶는 단위입니다. Docker 이미지는 컨테이너를 만들기 위한 읽기 전용 설계도이고, 컨테이너는 그 이미지를 실제로 실행한 상태입니다. 같은 이미지를 사용하면 환경 차이를 줄일 수 있지만, 어떤 모델 파일과 설정을 연결했는지는 별도로 확인해야 합니다.

Kubernetes는 여러 컨테이너의 실행 상태를 선언한 설정과 맞추는 플랫폼입니다. Pod는 하나 이상의 컨테이너가 함께 실행되는 기본 단위이고, Deployment는 필요한 Pod 수와 갱신 방법을 관리합니다. 이 과정의 모델 서빙에는 KServe의 InferenceService가 포함되므로 일반 Deployment와 모델 추론용 리소스의 역할을 구분해서 봅니다.

모델 패키지, API, 컨테이너, Kubernetes/KServe, GitOps는 서로 다른 실행 층의 상태를 보여 줍니다. 한 층의 확인 결과로 다음 층의 성공까지 주장할 수 없습니다.

실행 층	맡는 역할	확인할 근거	아직 모르는 것
모델 패키지	모델 파일과 프로필, 버전, 임계값을 묶음	모델 해시값과 메타데이터	어떤 API가 실제로 이 파일을 읽는지
FastAPI 애플리케이션	입력 검사, 모델 호출, 응답과 오류 처리	입력 스키마, `/v1/model`, `/v1/predict` 응답	대상 환경 전체가 안정적인지
Docker 이미지와 컨테이너	코드와 라이브러리를 같은 실행 환경으로 제공	이미지 설정, 환경 변수, 실행 로그	올바른 모델 패키지가 연결됐는지
Kubernetes와 KServe	선언한 수량과 모델 서빙 상태를 관리	Pod, Deployment, `InferenceService`, 준비 상태	Git 선언과 실제 요청 결과가 모두 일치하는지
GitOps	Git의 배포 선언을 대상 환경에 반영	개정본, 동기화 상태, 렌더링 결과	API 모델 정보와 운영 기록이 정상인지

각 층이 정상이어도 다음 층의 상태까지 자동으로 증명되지는 않습니다. 모델 패키지를 게시한 사실, 컨테이너가 실행 중인 사실, Pod가 준비 상태인 사실, API가 한 번 응답한 사실을 구분해 기록해야 실행 모델 불일치를 놓치지 않습니다.

배포 선언과 실행 모델의 비교¶

실행 환경은 모델이 요청을 처리하는 프로세스와 주변 설정입니다. API가 알려 주는 모델 정보에는 어떤 프로필, 버전, 임계값, 모델 패키지(model package)가 연결됐는지가 담깁니다. 모델 패키지는 함께 실행해야 하는 모델 파일과 메타데이터를 말합니다.

오프라인에서 승인한 모델이 실행 환경에서도 사용된다고 말하려면, 선언 파일과 실제 API, 운영 기록의 프로필과 해시값을 대조해야 합니다. 아래 흐름의 역할은 승인 근거에서 대상 환경 관측까지 이어지는 확인 경로를 보여 주는 것입니다. 앞의 파일은 “무엇을 실행해야 하는가”를, 뒤의 API와 운영 기록은 “무엇을 실제로 확인했는가”를 보여 줍니다.

flowchart LR
  accTitle: 공식 평가 결과에서 운영 기록까지 이어지는 확인 흐름
  accDescr: 2장 공식 평가 결과를 release manifest, Candidate B 오버레이, 고정 모델 패키지, 모델과 예측 API, 지표 로그 추적 기록 순서로 대조합니다.
  A[2장 공식 평가 결과] --> B[release-manifest]
  B --> C[Candidate B 오버레이]
  C --> D[고정 모델 패키지]
  D --> E[/v1/model 과 /v1/predict]
  E --> F[지표 로그 추적 기록]

흐름도의 텍스트 대체: 2장의 공식 평가 결과를 release-manifest, Candidate B 오버레이, 고정 모델 패키지, /v1/model·/v1/predict, 지표·로그·추적 기록 순서로 대조합니다.

Candidate B의 기준 결과는 release-manifest.json의 SHA-256 해시값과 연결됩니다. 후보 오버레이에는 같은 해시값과 고정된 PVC subPath가 들어 있습니다. 대상 /v1/model과 운영 기록의 시간대를 실제로 확인했을 때에만 대상 환경에서 확인한 결과라고 적습니다.

대조 순서

release manifest와 오버레이에서 선택하려는 프로필·해시값·경로를 확인합니다.
실제로 확인한 API에서 프로필·버전·임계값을 확인합니다.
같은 환경·시간대의 운영 기록을 확인합니다.
빠진 단계가 있으면 그 상태와 담당자를 기록하고, 대상 환경 성공을 쓰지 않습니다.

각 자료는 조사 순서에서 맡는 역할이 다릅니다. 역할을 바꾸어 쓰면 한 요청의 사건을 전체 시간대의 추세로 오해할 수 있습니다.

자료	확인한 사실	아직 모르는 것
`release-manifest.json`	어떤 후보 모델과 모델 해시값이 모델 평가를 통과했는지	대상 실행 작업이 그 모델 패키지를 읽고 있는지
후보 오버레이 렌더링 결과	대상 환경에 어떤 해시값과 경로를 적용하려 하는지	GitOps(선언 파일을 기준으로 배포 상태를 맞추는 방식) 동기화와 상태 확인이 끝났는지
`/v1/model`	확인한 API의 프로필, 버전, 임계값	전체 SHA-256이 실제로 연결된 파일과 같은지
유효한 `/v1/predict` 요청	한 요청이 API 규약에 맞게 처리됐는지	모든 시간대의 요청이 안정적인지
대시보드와 운영 기록	확인한 시간대에 어떤 신호가 있었는지	정답을 기준으로 한 모델 성능이나 단일 원인

/v1/model은 전체 해시값을 직접 돌려주지 않습니다. 따라서 API에서는 프로필, 버전, 임계값을 확인하고, 전체 해시값과 고정된 경로는 선언 파일과 오버레이에서 따로 확인합니다. 프로필 하나가 맞는다고 해서 대상 환경 전체를 확인한 것은 아닙니다.

이 교재에서 확인하는 환경

수업용 대상 Risk API는 강사가 안내한 공개 HTTPS 베이스에서 확인합니다. 로컬 Compose는 http://127.0.0.1:8000에서 기존 운영 모델의 공개 API 형식을 확인하는 연습 경로입니다. 로컬 API의 HTTP 200이나 422는 로컬에서 확인한 결과이며, Candidate B가 대상 환경에서 실행 중이라는 근거가 아닙니다. 공개 HTTPS와 로컬 루프백은 서로 다른 확인 범위입니다.

대상 환경이나 Grafana Cloud를 직접 확인하지 못했다면 API의 모델 정보, URL, 시간대, 대시보드 값을 추정하지 않습니다. 운영 환경 확인 상태를 target_pending으로 남기고, 확인하지 못한 이유와 다음 담당자의 조치를 기록합니다.

API 요청과 응답의 해석 범위¶

API 입출력 규약은 API가 받는 특성의 형식과 응답 필드를 정한 규칙입니다. 모델은 현재 데이터 규약(data contract)의 133개 특성을 사용합니다. 공개 요청도 약속한 특성을 모두 포함해야 하며 일부 키를 생략하면 입력 오류가 됩니다. 3장 노트북은 운영용 operational 자료에서 완전한 요청 값을 만들므로 133개 값을 손으로 입력할 필요가 없습니다.

유효한 요청은 HTTP 200과 request_id, model_profile, model_version, score, threshold, prediction을 돌려줍니다. 점수와 예측은 요청마다 달라지므로, 문서에 적힌 예시 값을 복사하지 말고 실제 응답에서 확인한 값만 배포 판단 기록에 적습니다.

잘못된 요청은 유효한 요청에 약속에 없는 특성 이름을 넣어 만듭니다. 이 요청은 HTTP 422, detail.code=MODEL_INPUT_INVALID, detail.validation_category=extra를 돌려줘야 합니다. 응답과 로그에는 민감한 원문 대신 missing|extra|type|other 중 하나의 제한된 분류가 남습니다.

API 확인 목록

준비 상태에서는 모델이 요청을 받을 준비가 됐는지 확인합니다.
/v1/model에서는 확인한 API의 모델 정보를 대조합니다.
유효한 요청에서는 200, 요청 ID, 응답 필드를 확인합니다.
의도적으로 잘못 만든 요청에서는 422와 명시적인 오류 코드를 확인합니다.

준비 상태, 모델 정보, 정상·오류 예측 응답, 지표는 각각 다른 확인 질문에 답합니다. 한 요청의 성공이나 오류 처리만으로 대상 환경 전체가 정상이라고 판단하지 않습니다.

요청 또는 응답	확인할 값	해석할 수 있는 내용
`GET /health/ready`	`status=ready`, `model_version`	점수 계산기가 준비됐는지
`GET /v1/model`	`backend`, `profile`, `version`, `threshold`, `feature_count`	확인한 API의 모델 정보를 오프라인 자료와 대조할 수 있는지
유효한 `POST /v1/predict`	HTTP 200, `X-Request-ID`, 모델 정보, 점수 관련 필드	유효한 특성으로 한 요청을 처리했는지
잘못된 `POST /v1/predict`	HTTP 422, `MODEL_INPUT_INVALID`, 제한된 `validation_category`, `X-Request-ID`	입력 형식 오류를 분명히 처리했는지
`GET /metrics`	`aiqa_risk_*` 시계열	집계한 운영 신호의 출처를 확인할 수 있는지

요청 ID(request ID)는 응답, 로그, 추적 기록에서 같은 요청을 찾는 연결 고리입니다. request_id를 Prometheus 지표 레이블에 넣으면 요청마다 새로운 시계열이 생겨 관리하기 어려워집니다. 지표에는 profile, version, scenario, prediction처럼 값의 종류가 제한된 레이블만 사용합니다.

지표, 로그, 추적 기록의 역할¶

운영 기록은 여러 요청의 흐름과 한 요청의 세부 과정을 함께 확인하게 합니다. 지표는 요청 수, 상태 코드, P95 지연 시간, 점수 또는 예측 분포처럼 시간대별 변화를 보여 줍니다. 로그는 입력 오류와 요청 ID를, 추적 기록은 한 요청이 거친 경로와 시간을 보여 줍니다.

95백분위수(P95)는 데이터의 95%가 이 값 이하에 놓이는 경계값입니다. 다시 말해 상위 5%가 시작되는 지점입니다. P95 지연 시간이 올랐다면 평균 요청은 괜찮아도 느린 요청이 늘었을 수 있습니다. 이 값 하나만으로 모델 품질이 떨어졌다고 판단할 수는 없습니다.

조사는 지표에서 시작해 대표 요청으로 좁혀 가는 편이 안전합니다. 예를 들어 422 비율이 늘었다면 지표로 시간대와 시나리오를 확인하고, 같은 시간의 로그에서 MODEL_INPUT_INVALID와 요청 ID를 찾습니다. 그 뒤 추적 기록으로 API 경로와 지연 시간을 확인해 입력 형식이나 실행 환경을 더 살펴볼지 정합니다.

조사 순서

지표에서 변화한 시간대와 시나리오를 고릅니다.
로그에서 같은 시간대의 대표 요청, HTTP 상태, 오류 코드와 제한된 validation_category를 찾습니다.
추적 기록에서 그 요청이 거친 경로와 지연을 확인합니다.
확인한 사실, 남은 원인 후보, 담당자와 다음 확인 조건을 기록합니다.

지표는 조사할 시간대를, 로그는 대표 오류 범주를, 추적 기록은 지연·오류 위치를 좁혀 줍니다. 어느 하나도 정답 기반 모델 품질이나 원인을 단독으로 확정하지 못합니다.

확인 순서	확인할 내용	지금 내릴 수 있는 판단	아직 남는 한계
1. 지표	422/5xx 비율, P95 지연 시간, 점수, 예측 분포	더 살펴볼 시간대와 시나리오를 정합니다	한 요청에서 난 정확한 이유
2. 로그	요청 ID, HTTP 상태, 오류 코드, 제한된 검증 분류와 모델 정보	민감한 원문 없이 대표 오류의 범주를 확인합니다	원본 입력과 전체 추세의 비율
3. 추적 기록	같은 요청 ID의 서비스 경로와 처리 시간	지연이나 오류가 난 위치를 좁힙니다	정답이 필요한 모델 품질 지표
4. 배포 판단 기록	신호, 원인 후보(hypothesis), 담당자, 다음 확인 조건	무엇을 보류하거나 추가 확인할지 적습니다	원인의 확정

HTTP 422는 입력 형식 오류이고, 5xx는 서버 쪽 처리 오류입니다. 422가 요청 수 패널에는 보이지만 5xx만 보는 오류율 패널에는 보이지 않을 수 있습니다. 한 패널만 보고 “오류가 없었다” 또는 “모델 문제다”라고 단정하면 안 됩니다.

확인 범위에 따른 기록 방법¶

prepared, local_verified, target_verified, target_pending은 승인 후보 B의 서로 다른 확인 상태입니다. 가장 강해 보이는 상태를 고르는 것이 아니라, Candidate B에 대해 실제로 본 파일, URL, 시간대에 맞는 가장 정확한 상태를 고릅니다. 기존 baseline 자료의 출처를 나타내는 scope=static/local/target과는 다른 축입니다.

prepared: 파일과 선언을 확인했지만 API 또는 대상 환경을 직접 보지 못했습니다.
local_verified: Candidate B를 로컬 API에서 실제 서빙하고 모델 정보, 정상·비정상 요청과 같은 모델의 운영 자료를 직접 확인했습니다.
target_verified: 제공된 대상 환경의 모델 정보와 필요한 운영 자료를 직접 확인했습니다.
target_pending: 대상 환경 자료가 아직 없으므로 필요한 담당자와 자료를 기록합니다.

Candidate B의 모델 평가 APPROVE와 대상 환경 미확인을 같은 기록에 남겨야 범위를 과장하지 않습니다. 아래 문장은 기존 운영 모델의 로컬 API나 준비된 자료를 확인했을 때 쓸 수 있는 예시입니다.

Candidate B는 공식 평가 자료에서 APPROVE입니다. 이번에는 [준비된 파일 또는 로컬]에서 [선언 파일 또는 API의 모델 정보]를 확인했습니다. 대상 URL, 같은 모델 해시값, 운영 기록의 시간대는 아직 확인하지 못했습니다. 따라서 운영 환경 확인 상태는 target_pending으로 두고 서빙 또는 플랫폼 담당자가 필요한 자료를 확인합니다.

로컬 결과를 대상 환경 결과로 바꾸어 쓰지 않으려면, 먼저 자신의 환경에서 직접 확인할 수 있는 범위를 정해야 합니다. 실습 환경 준비를 읽은 뒤 데이터의 네 가지 역할로 이동해 실제 자료를 확인합니다.