3-4. 요청과 응답 흐름 이해¶

요청과 응답 흐름은 API가 입력을 받아 모델 판단 결과를 돌려주는 경로입니다. 3-3 Lab에서 정상 응답과 오류 응답을 확인했다면, 3-4에서는 그 응답이 어떤 단계를 거쳐 만들어지고 어느 단계에서 품질 문제가 드러나는지 나누어 봅니다.

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

요청 주체와 처리 주체: 클라이언트(client)가 무엇을 보내고 서버(server)가 무엇을 검증하는지 확인
요청(request)과 응답(response) 분리: 입력 특성(feature)과 모델 출력 정보를 구분
JSON 데이터 전달: 누락, 타입 오류, null 입력이 어디에서 차단되는지 확인
추적 흐름: request_id가 응답과 로그를 어떻게 연결하는지 확인

3-4-1. 클라이언트와 서버 구조¶

클라이언트는 JSON 페이로드(payload)를 보내고, 서버는 스키마(schema) 검증 후 모델 점수(score)를 계산합니다. 이 구조는 일반 API와 비슷하지만, AI 서비스에서는 점수, 임계값(threshold), 예측(prediction)이라는 모델 품질 관련 값이 응답과 로그에 포함된다는 차이가 있습니다.

3장의 상황에 적용하면, 클라이언트는 생체신호 특성을 보내고 서버는 2장에서 평가한 기준선 모델과 임계값을 사용해 응답을 만듭니다. 따라서 정상 응답을 볼 때도 “서버가 살아 있다”에서 멈추지 않고, 어떤 모델 버전(model_version)과 어떤 기준으로 응답했는지 확인해야 합니다.

클라이언트
→ FastAPI 스키마 검증
→ PredictionRequest 생성
→ PredictRisk 유스케이스 실행
→ PredictionResponse 생성
→ JSON 응답

각 단계의 책임을 나누면 문제 발생 시 추적이 쉬워집니다. 클라이언트가 잘못된 필드(field)를 보내면 스키마 검증(schema validation)에서 실패해야 합니다. 스키마는 통과했지만 모델 입력이 맞지 않으면 요청 변환이나 특성 이름 대응을 봐야 합니다. 점수는 계산되지만 예측이 기대와 다르면 임계값을 확인해야 합니다.

단계	실패 예시	확인 위치
클라이언트 페이로드	필수 필드 누락	요청 데이터
스키마 검증(schema validation)	타입 오류	FastAPI/Pydantic 스키마
유스케이스	특성 이름 대응 오류	application 계층
모델 점수 계산(model scoring)	모델 로딩 또는 특성 순서 오류	모델 로더(model loader), 특성 설정(feature config)
응답	추적 필드 누락	응답 스키마

QA는 이 흐름을 기준으로 테스트 케이스를 만들 수 있습니다. 정상 요청, 필수 필드 누락, 타입 오류, 임계값 변경, 모델 버전 변경을 각각 분리해서 확인하는 것이 좋습니다. 하나의 테스트에서 모든 문제를 한꺼번에 확인하면 API 계약(contract) 문제인지, 설정 문제인지, 모델 입력 문제인지 구분하기 어렵습니다.

3-4-2. 요청과 응답 이해¶

요청에는 모델 입력 특성이 들어갑니다. 응답에는 점수, 임계값, 예측, 모델 버전이 들어갑니다. QA는 입력 계약(contract)과 응답 계약(contract)을 함께 봐야 합니다.

요청과 응답은 나중에 같은 판단을 재현하기 위한 한 쌍의 증거입니다. 예를 들어 요청에는 heart_rate, oxygen_saturation처럼 모델이 판단에 사용할 값이 들어갑니다. 응답에는 그 입력을 모델이 어떻게 해석했는지 보여주는 score, threshold, prediction이 들어갑니다. 이 둘이 함께 남아야 나중에 같은 요청을 재현하고, 품질 문제가 입력 때문인지 설정 때문인지 추적할 수 있습니다.

요청과 응답은 다음처럼 서로 다른 정보를 담습니다.

{
  "request_id": "lab-03-request-001",
  "heart_rate": 92,
  "respiratory_rate": 18,
  "body_temperature": 37.2,
  "oxygen_saturation": 94,
  "systolic_blood_pressure": 128,
  "diastolic_blood_pressure": 82
}

{
  "request_id": "lab-03-request-001",
  "model_version": "v1",
  "score": 0.5389,
  "threshold": 0.5,
  "prediction": "high_risk"
}

첫 번째 JSON은 모델이 무엇을 보았는지를 보여주고, 두 번째 JSON은 그 입력을 어떤 모델과 기준으로 판단했는지를 보여줍니다. request_id가 같기 때문에 같은 요청의 로그와 지표를 이어서 찾을 수 있습니다.

구분	포함 값	QA 확인
요청	특성, `request_id`	모델 입력이 충분하고 재현 가능한지
응답	`request_id`, `model_version`, `score`, `threshold`, `prediction`	추적과 품질 관측이 가능한지

요청과 응답은 서로 다른 질문에 답합니다. 요청은 “모델이 무엇을 보고 판단했는가”를 보여주고, 응답은 “그 입력을 어떤 모델과 기준으로 어떻게 판단했는가”를 보여줍니다. 요청만 확인하면 운영 품질을 추적할 수 없고, 응답만 확인하면 어떤 입력으로 그런 결과가 나왔는지 재현하기 어렵습니다.

특히 request_id는 양쪽을 연결하는 키입니다. 운영 로그에서는 이 값을 검색해 특정 요청의 입력, 점수, 예측, 지연 시간(latency)을 추적합니다.

3-4-3. JSON 기반 데이터 전달¶

API 요청은 JSON 형식입니다. JSON은 사람이 읽기 쉽고 여러 시스템에서 사용하기 편하지만, 숫자와 문자열, null 값 처리에 주의해야 합니다. 숫자 특성이 문자열로 들어오거나 필수 필드가 누락되면 검증 오류(validation error)가 발생할 수 있습니다.

JSON 문제	API 반응	QA 확인
필수 필드 누락	422 오류	누락 필드가 명확히 표시되는지
숫자 대신 문자열	422 오류 또는 변환	타입 검증 기준이 명확한지
허용되지 않은 추가 필드	설정에 따라 다름	계약(contract)이 명확한지
`null` 입력	필드 설정에 따라 오류	결측치 처리 정책이 명확한지

AI 서비스에서는 JSON 오류가 단순 API 오류를 넘어 데이터 품질 문제로 이어질 수 있습니다. 운영에서 특정 필드 누락이 갑자기 증가하면 상위 시스템(upstream)의 데이터 수집 또는 전송 로직 변경을 의심해야 합니다. 이 신호는 4장의 검증 실패(validation failure) 지표와 연결됩니다.

3-4-4. request_id 기반 추적 흐름¶

request_id는 특정 요청의 입력, 응답, 로그를 연결하는 키입니다. 운영에서 품질 문제가 발생했을 때 request_id가 없으면 개별 요청을 추적하기 어렵습니다.

request_id는 예상과 다른 예측을 개별 요청 단위로 추적하기 위한 최소 증거입니다. 예를 들어 특정 요청에서 예상과 다른 high_risk 예측이 나왔다고 가정하겠습니다. request_id가 있으면 해당 요청의 입력 특성, 모델 버전, 점수, 임계값, 예측, 지연 시간을 로그에서 찾을 수 있습니다. request_id가 없다면 시간대와 페이로드를 추정해야 하므로 원인 분석이 어려워집니다.

request_id로 연결할 정보	확인 목적
입력 특성	데이터 품질 문제 확인
`model_version`	어떤 모델이 응답했는지 확인
점수	임계값 근처 샘플(sample)인지 확인
임계값	운영 기준이 맞았는지 확인
예측	최종 예측 확인
지연 시간	응답 지연 여부 확인

운영 관측(observability)에서는 request_id를 사용해 로그와 지표를 연결합니다. 모델 서빙 단계에서는 API가 이 값을 생성하거나 전달하고, 응답과 로그에 남길 준비가 되어 있는지 확인합니다.