# LLM API를 바꾸기 전에 스트리밍과 도구 호출 호환성을 어떻게 테스트하나요? > LLM API 마이그레이션은 단일 채팅 데모가 아니라 기록 가능한 계약 fixture로 테스트해야 합니다. 텍스트 스트림, 강제 도구, 분할 인수, 다중 호출, 결과 왕복, 취소, 오류, usage를 검증하세요. 10분짜리 채팅 테스트는 중요한 실패를 놓칠 수 있습니다. retry 후 중복 호출, 마지막 스트림 이벤트 전 JSON 실행, 잘못된 역할의 도구 결과, 취소 후 계속되는 쓰기 작업이 대표적입니다. 유효한 마이그레이션 gate는 고정 요청을 실제 parser와 실행기에 통과시킨 뒤 구조적 불변 조건을 평가합니다. 첫 스위트는 자주 실행할 만큼 작고 모델 간 비교가 가능할 만큼 결정론적이어야 합니다. 목적은 지능을 평가하는 것이 아니라 새 API가 기존 에이전트 루프를 안전하게 구동함을 증명하는 것입니다. ## 클라이언트가 의존하는 계약을 정의하세요 공급자를 테스트하기 전에 클라이언트가 요구하는 동작을 작성하세요. “OpenAI 호환” 같은 모호한 표현만 사용하지 마세요. | 계약 영역 | 필수 불변 조건 | 보관할 증거 | |---|---|---| | 인증 | 예상 엔드포인트가 키를 수용 | 상태와 request ID | | 텍스트 스트림 | 델타가 하나의 최종 메시지로 조립 | 순서가 있는 원시 이벤트 | | 도구 스트림 | 실행 전에 호출이 완료 | 호출 buffer와 최종 이벤트 | | 상관관계 | 결과가 올바른 호출에 연결 | call ID 매핑 | | Retry | 호출은 최대 한 번 실행 | idempotency 로그 | | Usage | 카운터가 있거나 unavailable로 표시 | 최종 응답 메타데이터 | 프로토콜 지원은 모델별입니다. Atlas Cloud는 여러 요청 형식을 제공하므로 테스트 경로를 고르기 전에 최신 [`supported_apis` 가이드](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis)를 확인하세요. ## 결정론적 도구 네 개를 만드세요 서로 다른 실패 모드를 드러내는 fixture를 사용합니다. * `echo_json`: 검증된 인수를 그대로 반환합니다. * `read_fixture`: sandbox의 알려진 파일을 읽습니다. * `delayed_value`: 제어된 지연 뒤 완료됩니다. * `always_error`: 안정된 구조화 오류를 반환합니다. 각 도구에 `additionalProperties: false`를 포함한 엄격한 스키마와 고유 fixture ID를 부여해 중복 실행을 보이게 하세요. 날씨, 검색 결과, 변경되는 repository에 의존하면 안 됩니다. ## 단계별 호환성 행렬을 실행하세요 스트리밍 전에 비스트리밍을, 여러 호출 전에 한 호출을 테스트하세요. | 단계 | 프롬프트 동작 | 통과 조건 | |---|---|---| | A | 일반 텍스트 반환 | 최종 텍스트와 stop 상태 도착 | | B | `echo_json` 강제 | 이름과 유효한 인수 도착 | | C | `echo_json` 스트리밍 | 조각이 한 번만 조립 | | D | 읽기 도구 두 개 호출 | 두 결과가 올바르게 연결 | | E | 도구 오류 하나 수신 | 모델이 수정하거나 깨끗이 종료 | | F | 스트림 중간 취소 | 늦은 도구 실행 없음 | 모든 후보에 같은 스키마와 의미의 요청을 사용하세요. native 프로토콜이 다른 envelope을 요구하면 wire 표현만 조정합니다. ## SDK 아래에서 원시 이벤트를 캡처하세요 고수준 SDK 객체는 production에서 편리하지만 마이그레이션 차이를 숨길 수 있습니다. 단조 증가 순번, response ID, output index, call ID, 이벤트 유형, 민감정보를 제거한 payload 길이를 기록하는 debug transport를 추가하세요. 스트리밍 함수 인수는 점진적으로 도착합니다. 호출별로 조립하고 마지막 인수 이벤트를 기다리세요. ```text START -> CALL_OPEN -> ARGUMENT_DELTAS -> CALL_DONE -> VALIDATED -> EXECUTED | | +-> CANCELLED <---+ ``` 뒤로 가는 전환과 중복 실행을 거부하세요. 연결이 `EXECUTED` 뒤이지만 모델이 결과를 받기 전에 끊기면 쓰기를 맹목적으로 반복하지 말고 idempotency key를 사용합니다. ## 도구 결과의 전체 왕복을 테스트하세요 유효한 도구 호출은 계약의 절반입니다. 프로토콜이 요구하는 메시지 또는 item type으로 결과를 반환한 뒤, 결과의 알려진 필드를 사용하는 최종 답변을 요구하세요. 큰 결과, 빈 결과, Unicode, 구조화 오류를 테스트하고 context에 재진입하기 전에 크기를 제한하세요. 첫 대형 결과에서 어댑터 가정이 드러날 수 있습니다. ## 문구가 아니라 불변 조건을 비교하세요 두 모델의 최종 표현이 다르다고 실패시키지 마세요. 다음을 확인합니다. * 예상 도구 이름이 선택됐습니다. * 인수가 JSON Schema를 통과했습니다. * 모든 call ID가 고유하고 올바르게 연결됐습니다. * 각 도구가 의도대로 0회 또는 1회 실행됐습니다. * 루프가 허용된 호출 예산 안에서 끝났습니다. * 최종 답변이 fixture 결과를 사용했습니다. 후보별 snapshot은 디버깅에만 쓰고 통과 기준은 공급자 중립으로 유지하세요. ## 실패와 취소 사례를 추가하세요 첫 인수 조각 뒤, 호출 완료 뒤, 도구 실행 뒤에 각각 스트림을 끊으세요. 429, timeout, 잘못된 JSON, 알 수 없는 도구 이름을 주입하고 클라이언트가 안전하게 retry, 복구 또는 유용한 오류로 정지하는지 확인합니다. 가장 위험한 버그는 상태 변경 도구를 반복하는 모호한 retry입니다. 쓰기에는 명시적 idempotency를 요구하세요. ## 스위트를 릴리스 gate로 만드세요 설정 변경마다 빠른 smoke suite를, SDK나 gateway 업그레이드 때 전체 행렬을 실행합니다. 모델, 프로토콜, Base URL, 스키마 hash, 스트리밍 flag, 클라이언트 버전, timestamp를 결과와 함께 보관하세요. Atlas Cloud는 스트리밍과 비스트리밍 LLM 요청을 모두 지원하며 하나의 [모델 카탈로그](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis)에서 후보를 탐색할 수 있습니다. 공통 접근 방식이 동일한 기능을 뜻하지 않으므로 각 모델에 같은 gate를 실행하세요. ## 결론 LLM API 마이그레이션을 상태가 있는 프로토콜 변경으로 테스트하세요. 결정론적 도구로 시작하고 원시 이벤트를 기록하며 완료 이벤트 뒤에만 인수를 조립하고 결과 왕복을 검증한 뒤 retry와 취소를 주입하세요. 한 채팅 응답이 정상으로 보일 때가 아니라 계약 스위트가 통과할 때 새 모델을 배포해야 합니다. ## FAQ ### 첫 호환성 테스트는 무엇을 포함해야 하나요? 비스트리밍 텍스트 요청 하나와 강제 읽기 전용 도구 호출 하나로 시작해 엔드포인트, 인증, 스키마, 기본 응답 형식 문제를 분리하세요. ### 원시 스트리밍 이벤트를 왜 기록해야 하나요? SDK helper가 이벤트 순서와 필드 차이를 숨길 수 있습니다. 원시 이벤트는 call ID, 인수 조각, 완료 표시, 오류, usage가 실제로 도착하는 방식을 보여 줍니다. ### 정확히 같은 텍스트로 공급자를 비교해도 되나요? 대개 적절하지 않습니다. 유효한 호출, 필수 필드, 실행 횟수, 최종 상태, 작업 결과 같은 구조적 불변 조건을 비교하세요. ### 잘못된 도구 인수는 어떻게 테스트하나요? 구조화된 검증 오류를 모델에 돌려주고, 안전하지 않은 입력을 실행하지 않은 채 정해진 호출 예산 안에서 수정하거나 종료하는지 확인하세요. ### 테스트 스위트에 쓰기 도구를 포함해야 하나요? 결정론적 읽기 전용 도구로 시작하세요. 호출 조립, 검증, 중복 제거, 오류 복구가 통과한 뒤에만 sandbox 쓰기 fixture를 추가합니다. ### 호환성 테스트는 얼마나 자주 실행해야 하나요? 모델 또는 프로토콜 변경 전마다 빠른 smoke subset을, SDK·스키마·gateway·stream parser 변경 시 전체 스위트를 실행하세요.