Put a JSON Contract in Front of a Free Model Route Before Your CI Ever Calls It

개요

GitLab CI와 같은 시스템에서 무료 모델 API 엔드포인트의 응답 구조 변경으로 인해 발생하는 실패를 방지하기 위해, 모델과 호출자 사이에 JSON 계약을 강제하는 게이트웨이를 구현하는 방법에 대해 설명합니다.

주요 내용

* 무료 모델 API 엔드포인트의 불안정성: 무료 모델 API는 종종 필드 이름 변경, 열거형 값 변경, 응답 크기 변화 등의 형태로 응답 구조가 예고 없이 변경될 수 있습니다.
* 기존 실패 처리 방식의 한계: 파싱 실패 시 재시도, 기본값 설정, CI 내 검증 등의 방식은 근본적인 계약 불일치 문제를 해결하지 못하고, 실제 문제 발생 시점을 늦추거나 문제를 은폐할 수 있습니다.
* 계약 게이트웨이의 역할: 게이트웨이는 호출자(예: CI 잡)와 모델 엔드포인트 사이에 위치하여 다음을 수행합니다.
* CI 잡과 동일한 POST 페이로드를 수신합니다.
* 모델 엔드포인트로 페이로드를 전달하고 타임아웃을 설정합니다.
* 응답 크기를 제한하고 JSON 형식 및 필수 필드, 허용 필드, 타입, 열거형 값을 강제합니다.
* 응답 구조가 유효하면 200 OK를 반환하고, 불일치 시 502 Bad Gateway와 함께 문제 목록을 반환합니다.
* 불일치 발생 시 지연 시간, 문제 목록, 응답의 첫 200자 샘플을 기록합니다.
* 게이트웨이 구현:
* contract.mjs: 계약 내용을 JSON 형식으로 정의합니다 (필수 필드, 허용 필드, 각 필드의 타입 및 값 제약).
* check-payload.mjs: 입력 페이로드가 정의된 계약과 일치하는지 검증하는 함수를 제공합니다.
* gateway.mjs: Node.js http 모듈을 사용하여 실제 게이트웨이 서버를 구현합니다. upstream 모델 URL, 포트, 최대 지연 시간, 최대 응답 크기 등의 환경 변수를 설정할 수 있습니다. fetch API를 사용하여 upstream에 요청을 보내고, 응답을 받아 checkPayload 함수로 검증한 후 결과를 반환합니다.
* 테스트의 중요성: gateway.test.mjs와 같이 계약 불일치 시나리오를 테스트하는 것은 성공 경로만 테스트하는 것보다 중요하며, 이를 통해 계약 변경으로 인한 잠재적 실패를 미리 발견할 수 있습니다.
* 무료 서버 활용: 게이트웨이를 CI 파이프라인 내부가 아닌 작은 무료 서버에 배포함으로써, 항상 접근 가능하며 여러 리포지토리에서 공유되고 로컬 개발 환경에서도 호출될 수 있도록 합니다. CI 잡은 이제 게이트웨이를 호출하게 됩니다.
* 게이트웨이의 한계: 게이트웨이는 응답의 의미론적 정확성, 틀린 정보, 또는 문법적 오류를 검증하지는 않습니다. 이는 콘텐츠 자체의 검토는 인간 또는 다른 모델에게 맡기고, 구조적 불일치라는 특정 유형의 실패만 방지하기 위한 도구입니다.
* 사용 시점: 사용자 대면 또는 지연 시간에 민감한 애플리케이션, 민감 데이터 처리, 고가용성 요구 사항이 있는 경우, 동적으로 변경되는 출력 구조가 필요한 경우에는 적합하지 않습니다. 주로 CI 잡, 이슈 분류, 테스트 생성, 무료 티어 실험 등의 개발 시간 도구로 사용됩니다.
* 워크플로우: 계약을 먼저 정의하고, 행복 경로 및 실패 경로 테스트를 추가한 후, 게이트웨이를 무료 서버에 배포하고 CI 잡이 게이트웨이를 호출하도록 설정합니다. 502 오류 발생 시 문제 목록을 확인하고 필요한 경우 계약을 업데이트합니다.

시사점

이 패턴은 무료 모델 API 엔드포인트의 응답 구조 변경으로 인한 CI/CD 파이프라인의 예기치 않은 실패를 효과적으로 방지하며, 개발자는 코드 변경이 아닌 API 계약 변경을 빠르게 인지하고 대응할 수 있게 하여 디버깅 시간을 단축시키고 시스템의 안정성을 향상시킬 수 있습니다.