실행 모델 확인¶

이 페이지의 역할은, 앞 교시에서 확인한 요청 처리 성공을 실행 모델 승인으로 바꾸지 않고 /v1/model, 입력 계약, 파일 지문, 배포 설정을 같은 식별값으로 대조하는 것입니다. 2장에서 Candidate B는 평가 기준을 통과했지만, 그 결과는 지금 프로세스가 같은 모델 패키지(model package)를 실행한다는 증거가 아닙니다. 로컬 Compose에서 기준 모델 정보를 읽었더라도 대상 환경까지 같은 상태라고 단정하지 않습니다.

지금 쓸 수 있는 근거는 로컬 API가 입력 검사를 통과한 요청을 처리한다는 사실, 기준 모델의 profile, version, threshold, Candidate B의 평가 승인입니다. 아직 닫히지 않은 질문은 확인한 URL의 실행 모델이 그 승인 기록과 같은지, 로컬에서 맞춘 값이 대상 환경에도 있는지로 남습니다. 이 페이지가 남기는 판단은 확인한 범위의 모델 정보와 파일 지문이며, 다음 확인은 대상 환경이 그 실행을 어떻게 배치하는지를 보는 단계입니다. 실행과 기록 칸은 서빙 실습의 실행 모델 확인을 따릅니다.

실행 모델을 판정하는 세 단서

API 응답은 지금 확인한 URL이 내보낸 모델 선언입니다.
파일 지문은 모델 파일, 설명 파일, 입력 계약을 각각 가리킵니다.
환경 이름과 확인 시간은 그 사실을 어디까지 보고할 수 있는지 정합니다.

실행 모델을 알려 주는 API¶

/v1/model은 예측을 다시 계산하지 않고, 지금 프로세스가 어떤 모델이라고 말하는지만 돌려줍니다. 이 경로의 본문에는 score나 prediction이 없으며, 한 건의 입력을 다시 넣어 본 결과가 아닙니다. 확인할 값은 backend, profile, version, threshold, feature_count, education_only입니다.

로컬 Compose의 기준 모델 응답은 아래 형식입니다. backend=local은 이 프로세스가 로컬 모델 파일을 읽는다는 선언이고, feature_count=133은 입력 항목 수, education_only=true는 교육용 분류 경계입니다. 공개 대상 URL에서는 같은 필드 집합을 읽되 backend=kserve를 기대해 로컬 응답과 한 환경의 근거로 합치지 않습니다.

{
  "backend": "local",
  "profile": "baseline",
  "version": "baseline-f2576f12512a",
  "threshold": 0.5,
  "feature_count": 133,
  "education_only": true
}

위 JSON은 로컬 기준 모델의 기대 예시입니다. 확인하지 않은 값을 관측값으로 복사하지 않습니다.

필드마다 확인하는 사실의 범위가 다릅니다. 아래 표는 로컬 기준 모델 응답을 읽을 때 보고서에 남길 값과, 그 값만으로 닫히지 않는 질문을 나눕니다.

필드	로컬 기준 모델에서 기대하는 값	이 값이 보여주는 것	이 값만으로 닫히지 않는 것
`backend`	`local`	지금 프로세스가 점수를 계산하는 경로	대상 환경의 점수 계산 경로
`profile`	`baseline`	프로세스가 말하는 모델 종류	디스크의 모델 파일이 같은지
`version`	`baseline-f2576f12512a`	종류와 모델 파일 지문 앞자리를 묶은 식별값	설명 파일과 입력 계약까지 같은지
`threshold`	`0.5`	점수를 `high_risk`/`low_risk`로 나누는 기준값	평가 때 쓴 기준값이 파일에 그대로인지
`feature_count`	`133`	프로세스가 기대하는 입력 항목 수	이름, 순서, 자료형이 같은지
`education_only`	`true`	교육용 분류이며 의료 판단이 아님	대상 배포가 성공했는지

이 응답은 API 표면의 실행 모델 선언입니다. 값이 기준 모델과 같아도 대상 환경의 연결, 준비, 실제 마운트까지 증명하지 않으므로, 확인한 URL과 시각을 함께 적습니다.

모델 입력값의 이름과 순서¶

입력 계약은 특성 이름만 맞추는 규칙이 아니라, 이름, 모델 내부 순서, 개수, 자료형, 결측 허용을 한 묶음으로 정한 약속입니다. 모델 파일 해시가 같아도 이 계약이 다르면 같은 예측을 보장할 수 없습니다. 요청 검사는 이 계약을 기준으로 입력을 거르고, 통과한 JSON 객체를 표준 계약 순서로 재배열한 뒤 모델에 전달합니다.

age와 age__missing은 나이 값과 그 값이 빠졌는지의 표시를 나눈 한 쌍입니다. age는 실수이고 결측을 허용하며, age__missing은 참 또는 거짓이고 결측을 허용하지 않습니다. 가공 표에서는 결측 표시를 0.0과 1.0으로 볼 수 있고, API 요청에서는 false와 true로 보냅니다. 뜻은 같고 표현만 다릅니다.

표준 입력 계약 configs/contracts/model-input.yaml은 133개 항목을 약속한 이름과 순서로 고정합니다. 아래 표는 계약 앞부분의 확인 단위입니다.

특성 이름	자료형	결측 허용	확인 포인트
`age`	실수	허용	나이 값이며 비어 있을 수 있습니다.
`age__missing`	참 또는 거짓	금지	나이 값이 빠졌는지를 표시하며 비워 둘 수 없습니다.
`gender`	범주	허용	허용된 범주와 결측 규칙을 확인합니다.

필수 항목이 빠지거나 알 수 없는 이름이 추가되고, 자료형 또는 결측 규칙이 다르면 모델 파일을 실행하기 전에 입력이 거절됩니다. JSON 객체의 키 나열 순서는 달라도 되며 API가 표준 계약 순서로 재배열하므로, 역순 요청도 나머지 규칙이 맞으면 정상 처리됩니다. 특성 수 133이 /v1/model과 같아도 모델 내부의 표준 순서와 이름, 자료형, 결측 규칙을 대조하지 않으면 같은 서비스라고 기록하지 않습니다.

API·모델 파일·배포 설정의 모델 정보¶

한 자료의 이름만으로 실행 모델을 확정할 수 없습니다. API 응답, 모델 설명 파일 metadata.json, 배포 설정 deployment.json 또는 선택한 배포 설정이 같은 모델 종류와 파일 지문을 가리키는지 나란히 봐야 합니다. API가 baseline이라고 말해도 파일과 배포 설정이 자동으로 같지는 않습니다.

세 자료에 모두 있는 값은 profile과 모델 파일 지문입니다. /v1/model의 version은 {profile}-{모델 SHA-256 앞 12자리} 형식이며, 로컬 기준 모델에서는 baseline-f2576f12512a입니다. threshold는 /v1/model과 metadata.json에서 대조하고, deployment.json에 이 필드가 없으면 값을 채워 넣지 않습니다. Candidate B를 확인할 때는 모델 지문 앞자리 c712a8e52344뿐 아니라, API와 metadata.json의 threshold가 0.35인지도 맞춰 봅니다.

세 자료를 같은 시각의 한 확인으로 읽습니다. 아래 표는 로컬 기준 모델에서 실제 있는 필드만 대조하는 위치입니다.

필드	`/v1/model`	`metadata.json`	`deployment.json` 또는 배포 설정
모델 종류	`profile`	`profile`	`profile`
버전	`version`	`profile`과 `model_sha256` 앞 12자리로 재구성	선택한 경로 이름과 같은 식별값
판정 기준값	`threshold`	`threshold`	필드 없음. 값을 채워 넣지 않음
파일 지문	`version`에 앞자리만 포함	`model_sha256`	`model_sha256` 또는 예상 모델 SHA-256

실제 있는 필드가 같으면 확인한 자료가 같은 모델 정보를 가리킨다는 뜻입니다. 없는 필드를 다른 자료의 값으로 메우지 않으며, 확인하지 않은 대상 환경까지 같다고 확장하지 않습니다.

모델 파일의 내용 지문 대조¶

SHA-256은 파일 내용에서 계산한 지문이며, 같은 이름의 다른 파일을 가릅니다. 파일명이 model.joblib로 같아도 내용이 바뀌면 지문이 바뀝니다. 지문 하나가 준비 상태나 대상 배포 성공을 보증하지도 않습니다.

선언 파일에 적힌 해시를 읽는 것과 파일 내용에서 지문을 계산하는 것은 다른 확인입니다. tta-aiqa 저장소 루트에서 아래 명령으로 model.joblib, metadata.json, 입력 계약 파일을 각각 계산한 뒤, deployment.json이나 릴리스 기록의 기대값과 비교합니다. 모델 파일 지문, 설명 파일 지문, 입력 계약 지문은 서로 대신하지 않습니다.

shasum -a 256 artifacts/models/revisions/v2/deployed/model.joblib
shasum -a 256 artifacts/models/revisions/v2/deployed/metadata.json
shasum -a 256 configs/contracts/model-input.yaml

로컬 기준 모델에서 기대하는 앞자리는 아래와 같습니다. Candidate B를 확인할 때는 모델 파일 지문 앞자리 c712a8e52344뿐 아니라, metadata.json과 /v1/model의 threshold가 0.35인지도 대조합니다.

파일	지문이 가리키는 내용	기준 모델 앞자리	이 지문이 증명하지 않는 것
`model.joblib`	모델 파일 내용	`f2576f12512a...`	설명 파일과 입력 계약이 같은지
`metadata.json`	모델 설명 파일 내용	`8bbb9b827cce...`	모델 파일 내용이 같은지
입력 계약 `model-input.yaml`	입력 항목의 이름, 순서, 자료형 약속	`fbd02c614968...`	지금 프로세스가 그 파일을 읽는지

위 표의 앞자리는 기대 예시입니다. 확인하지 않은 값을 관측값으로 복사하지 않습니다. 계산한 지문이 기대값과 같으면 확인한 파일이 릴리스 기록의 내용과 같다는 뜻이며, 실행 확인은 다음 절에서 환경을 나눠 기록합니다.

로컬 환경의 실행 모델 확인¶

로컬 실행 모델은 Compose 설정, 마운트한 모델 파일, http://127.0.0.1:8000/v1/model 응답이 같은 식별값을 가리킬 때만 확인한 것입니다. Compose는 AIQA_API_MODEL_BACKEND=local로 로컬 파일을 읽게 하고, 모델 디렉터리를 /runtime/model에, 설정과 입력 계약을 /runtime/configs에 읽기 전용으로 붙입니다. 이 세 곳이 같은 profile, version, 파일 지문을 가리킬 때만 로컬 실행 모델로 기록합니다.

로컬 확인의 범위는 지금 호출한 Compose API입니다. 응답의 backend가 local이고 profile=baseline, version=baseline-f2576f12512a, threshold=0.5, feature_count=133이면, 마운트 경로의 deployment.json과 metadata.json에서 같은 종류와 모델 SHA-256 앞자리를 찾습니다. 아래 표는 세 꼭짓점에서 같은 식별값을 확인하는 위치입니다.

꼭짓점	확인 위치	로컬 기준 모델에서 맞출 값
Compose 설정	`deploy/compose.yaml`	`backend=local`, 모델 경로 `/runtime/model/model.joblib`
마운트한 파일	`artifacts/models/revisions/v2/deployed`	`profile=baseline`, 모델 SHA-256 `f2576f12512a...`
localhost 응답	`http://127.0.0.1:8000/v1/model`	`profile`, `version`, `threshold`, `feature_count`가 위와 같음

로컬 삼각형이 맞아도 대상 클러스터가 같은 모델을 실행 중이라는 뜻은 아닙니다. Compose나 API가 실행되지 않으면 선언과 파일만 본 prepared 범위이며, 대상 실측이 없으면 target_pending으로 남깁니다. 기본 Compose는 기존 운영 모델의 공개 API 형식을 연습하는 경로이므로, 이 결과만으로 Candidate B를 확인했다고 올리지 않습니다. 명령과 기록 칸은 서빙 실습의 실행 모델 확인을 봅니다.

대상 환경의 실행 모델 확인¶

대상 환경은 선언 파일과 실제 확인을 나눕니다. 배포 설정에서는 기준 모델 경로 physionet-2012/v2/baseline-f2576f12512a 또는 Candidate B 경로 physionet-2012/v2/candidate-b-c712a8e52344와 예상 모델 SHA-256을 읽을 수 있습니다. Candidate B를 확인할 때는 모델 지문 앞자리뿐 아니라, API와 metadata.json의 threshold가 0.35인지도 대조합니다. YAML에 경로가 있다고 대상 API와 연결, 준비 상태가 이미 같은 모델로 준비된 것은 아닙니다.

실측은 대상 /v1/model 응답, 실제로 연결된 모델 파일, 같은 시각의 준비 자료입니다. 대상 응답을 봤다면 backend=kserve와 profile, version, threshold, feature_count, education_only를 선언값과 대조합니다. 이 자료가 없으면 대상 실행 모델은 미확인입니다. 아래 표는 선언과 실측을 나누어 보고하는 기준입니다.

확인 층	볼 수 있는 것	보고할 수 있는 문장	자료가 없을 때
선언	배포 설정의 모델 경로와 예상 SHA-256	“대상에 실행하려는 모델 정보가 이렇게 적혀 있다.”	선언 파일이 없으면 대상 계획도 미확인
실측	대상 `/v1/model`, 실제 연결 파일, 준비 자료	“이 URL과 시각에서 모델 정보를 확인했다.”	성공을 말하지 않고 미확인으로 남김

로컬 삼각형의 성공은 대상 배포 성공을 대신하지 않습니다. 대상 URL이 없거나 응답을 받지 못했다면 운영 환경 확인 상태는 target_pending입니다. Compose나 API를 실행하지 못하고 선언과 파일만 봤다면 prepared이며, 그 결과를 대상 실측으로 올리지 않습니다.

모델 정보 불일치의 해석¶

모델 종류, 버전, 기준값, 파일 지문 중 하나가 다르면 조사 시작입니다. 불일치 자체는 자동 복구, 되돌리기, 배포 실패, 성능 저하의 증명이 아닙니다. 다른 항목에 따라 다음에 볼 자료가 달라지므로, 한 필드로 원인을 확정하지 않습니다.

값이 다를 때는 설정, 파일, 설명 파일, 실행 응답을 다시 대조합니다. 아래 표는 다른 항목마다 다음에 볼 자료와, 아직 단정하지 않을 결론을 나눕니다.

다른 항목	먼저 볼 곳	아직 단정하지 않는 것
`profile` 또는 `version`	배포 설정과 모델 묶음 정보	대상 환경이 이미 복구됐다
`threshold`	`/v1/model`과 `metadata.json`. `deployment.json`에 없으면 채우지 않음	모델 파일이 바뀌었다
특성 수 또는 입력 계약	특성 이름과 순서, 요청 스키마	같은 모델 파일로 같은 서비스다
모델 SHA-256	마운트 경로와 파일 내용 지문	파일 이름만 같으면 같은 모델이다

확인한 범위에서 값이 같으면 “이 URL의 실행 모델 선언과 파일 지문을 대조했다”고 적습니다. 대상 실측이 없으면 미확인을 유지하고, 예측 비율 변화의 원인도 아직 닫지 않습니다. 다음 단계에서는 그 실행이 대상 환경에 어떻게 배치되는지를 선언과 실제 상태로 나눠 봅니다.