LLM 애플리케이션용 API 마이그레이션 테스트: 실용적인 계획
LLM 앱의 API 마이그레이션 테스트는 일반 REST API 테스트와 다릅니다. 동일한 프롬프트가 항상 동일한 텍스트를 반환하지 않기 때문입니다. 정확한 문자열이 아닌 답변의 속성을 테스트합니다.
마지막 업데이트

요약
- 정확한 일치 기대가 아닌 규칙 기반 검증을 포함하는 50~200개의 실제 프롬프트로 골든 세트를 구축하세요.
- 노이즈를 줄이기 위해 temperature와 seed를 고정하지만, 절대 동일한 텍스트가 생성된다고 기대하지 마세요.
- 기존 및 새 경로에서 지연 시간 백분위수와 요청당 비용을 기록하세요.
- 롤아웃 시작 전에 롤백 트리거를 기록해 두세요.
실제 테스트 항목
클래식 API에서는 바이트 단위로 응답을 비교합니다. LLM은 즉시 이를 깨뜨립니다. 대신 제품에 필요한 답변의 속성을 결정하고 이를 테스트하세요.
- 구조. 유효한 JSON, 필수 키, 올바른 인수가 있는 함수 호출.
- 콘텐츠. 필수 사실을 언급하고, 형식을 따르며, 페르소나를 유지합니다.
- 제품의 안전성. 답변이 예상되는 상황에서 거절이 발생하지 않아야 하며, 시스템 프롬프트가 유출되지 않아야 합니다.
- 운영. 지연 시간, 오류율, 속도 제한 동작, 비용.
전환 단계 자체가 여전히 필요하다면, 이 사이트의 마이그레이션 가이드에 계획이 있으며, 그 과정에서 발생하는 실패는 일반적인 LLM 통합 오류에서 다룹니다. 이 기사는 검증을 다룹니다.
골든 프롬프트 세트 구축
로그에서 50~200개의 실제 프롬프트를 가져옵니다(개인 데이터 먼저 제거). 일반적인 경로, 이상한 케이스 및 이전에 오류가 발생했던 케이스를 모두 커버하세요. 메시지, 매개변수 및 통과해야 할 체크가 포함된 레코드로 각각 저장하세요.
{
"id": "invoice-json-03",
"messages": [
{"role": "system", "content": "Extract fields. Reply with JSON only."},
{"role": "user", "content": "Invoice 4471 from Acme, total 1,250 EUR, due 2025-03-01"}
],
"json": true,
"required_keys": ["number", "vendor", "total"],
"must_contain": ["4471"]
}
위험도에 따라 케이스를 태그하세요: 함수 호출, 긴 컨텍스트 창, 스트리밍, 비영어권, 매우 짧고 매우 긴 답변. 나중에 프로덕션에서 버그가 발생하면 세트에 추가하세요. 이 세트는 회귀 테스트 스위트의 일부로 성장합니다.
모든 것을 기록하는 테스트 하니스를 작성하세요
하나의 스크립트로 전체 세트를 라우트에서 실행하고 검증을 적용한 후 결과를 저장하세요. 변동을 줄이려면 temperature=0과 고정된 seed을 사용하세요. 이 API는 이 두 파라미터를 모두 전달하지만, 이를 보장으로 보기보다는 노이즈 감소 수단으로 간주하세요.
import json, time
from openai import OpenAI
client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")
PRICE_IN, PRICE_OUT = 0.15, 0.50 # USD per 1M tokens
def run(case):
t0 = time.perf_counter()
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=case["messages"],
temperature=0,
seed=42,
)
elapsed = time.perf_counter() - t0
resp = raw.parse()
text = resp.choices[0].message.content or ""
u = resp.usage
return {
"id": case["id"],
"text": text,
"seconds": elapsed,
"cost": (u.prompt_tokens * PRICE_IN + u.completion_tokens * PRICE_OUT) / 1e6,
"balance": raw.headers.get("X-Balance-USD"),
"request_id": raw.headers.get("X-Request-Id"),
}
모든 실패한 케이스에 대한 X-Request-Id을 유지하세요. 이는 특정 요청에 대해 지원팀에 문의할 때 인용하는 값입니다.
문자열이 아닌 규칙으로 diff
각 레코드의 체크를 적용하세요. 실패한 항목은 사람이 읽을 수 있는 짧은 목록으로 보냅니다.
def check(case, text):
problems = []
if case.get("json"):
try:
obj = json.loads(text)
except ValueError:
return ["invalid json"]
for key in case.get("required_keys", []):
if key not in obj:
problems.append("missing key " + key)
for needle in case.get("must_contain", []):
if needle.lower() not in text.lower():
problems.append("missing text " + needle)
if len(text.strip()) < case.get("min_chars", 1):
problems.append("answer too short")
return problems
자유 형식 답변의 경우, 저렴한 길이 밴드(예: 이전 답변의 절반에서 두 배 사이)와 거부 구문의 짧은 목록을 추가하세요. 그런 다음 20개의 출력을 눈으로 나란히 읽으세요. 규칙은 회귀를 포착하고 읽기는 어조를 포착합니다. 둘 다 수행하세요.
JSON 출력의 경우 response_format을 {"type":"json_object"}로 설정하고 위 체크가 저렴하므로 여전히 유효성을 검사하세요.
의도적으로 실패 경로 테스트
행복한 경로 프롬프트는 거의 모든 제공자에서 통과합니다. 실패는 마이그레이션이 고통을 주는 곳이므로 사용자가 하기 전에 의도적으로 유발하세요.
- 잘못된 키. 잘못된 키로 요청을 보내고 앱이 합리적인 메시지를 표시하고 루프에서 재시도하지 않는지 확인하세요.
- 속도 제한. 전체 키의 경우 한 번에 8개 이상의 요청을 보내고(체험 키의 경우 2개), 코드가 HTTP 429 응답을
concurrency코드로 처리하는지 확인한 후, 분당 한도를 초과할 경우rate_limited코드를 처리하는지 확인하세요. - 임시 과부하.
Retry-After: 5이 포함된 429은 즉시 반복 재시도가 아닌 5초 대기해야 합니다. - 과도한 입력. 100,000 토큰 컨텍스트 창 근처와 그 너머의 프롬프트를 보내세요. 앱은 충돌하지 않고 자르거나 요약해야 합니다.
- 큰 본문. 제한은 8 MB입니다. 더 큰 페이로드를 자체적으로 거부하는지 확인하세요.
- 스트림 손실. 스트리밍 중 연결을 종료하고 동시 요청 슬롯이 반환되는지 확인하세요.
이 각각은 가짜 서버를 대상으로 CI에서 실행되는 자동화된 테스트와 실제 서버를 대상으로 한 수동 테스트 하나를 가져야 합니다.
스트리밍 및 함수 호출 확인
스트리밍과 도구는 응답의 형상을 변경하므로 일반 텍스트로 구축된 골든 세트는 이를 놓칩니다. 각각에 대한 케이스를 추가하세요.
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by id",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Where is order A-1042?"}],
tools=tools,
tool_choice="auto",
)
calls = r.choices[0].message.tool_calls or []
assert calls and calls[0].function.name == "get_order_status"
print(calls[0].function.arguments)
어설션은 호출이 존재하고 인수가 예상되는 JSON으로 구문 분석되는지 확인합니다. 결과를 role: "tool" 메시지로 다시 보내는 두 번째 턴이 일반 답변을 생성하는지 체크를 추가하세요. 스트림의 경우 청크가 도착하고 최종 사용량이 표시되며 코드가 스트림 끝에서 읽기를 중지하는지 어설트하세요.
경로별 지연 시간 및 비용 추적
이전 라우트와 새 라우트에서 세트를 실행하고 동일한 열을 비교하세요: 중앙값 및 95번째 백분위수(초), 오류 수, 토큰, 비용. 이 기사는 모든 제공업체에 대한 지연 시간 수치를 제공하지 않습니다. 실제 수치는 프롬프트와 네트워크에 따라 달라지기 때문입니다. 직접 측정하세요.
새 경로의 비용은 토큰 수에 단가를 곱한 값입니다. 입력 1M당 $0.15, 출력 1M당 $0.50. 예: 200개의 골든 프롬프트가 평균 1,200 입력 및 300 출력 토큰을 가짐.
- 입력: 240,000 토큰 x $0.15 / 1,000,000 = $0.036.
- 출력: 60,000 토큰 x $0.50 / 1,000,000 = $0.03.
- 전체 실행 1회: $0.066.
$0.50 체험 크레딧은 이러한 실행 약 7개를 지원합니다. 체험 키는 동시 요청 2개와 분당 60개의 요청을 허용하므로 200개의 프롬프트에는 최소 3.5분이 필요합니다. 실패하거나 거부된 요청에는 요금이 부과되지 않습니다. 각 호출 후 X-Balance-USD 헤더에서 잔액을 읽어 자신의 계산을 확인할 수도 있습니다.
Shadow traffic 및 단계적 롤아웃
골든 세트가 통과되면 응답을 표시하지 않고 새 경로로 라이브 요청을 복사합니다. 결과를 로그에 기록하고 동일한 확인 항목으로 라이브 응답과 비교합니다. Shadow 실행에는 동시 요청 한도가 필요합니다: 전체 키는 한 번에 8개의 요청을 허용하므로 모든 요청을 동시에 보내는 대신 미러 호출을 큐에 넣습니다.
그런 다음 5%, 25%, 50%, 100%와 같은 단계로 실제 사용자를 이동합니다. 오류율, 실패한 체크 및 불만이 안정적으로 유지될 때까지 각 단계를 유지합니다.
롤백 규칙을 사전에 결정
첫 번째 사용자가 이동되기 전에 임계값을 기록하여 순간적인 결정이 기계적으로 이루어지도록 합니다.
| 신호 | 트리거 예시 |
|---|---|
| 실제 트래픽의 체크 실패 | 합의된 비율 이상의 체크 실패 |
| HTTP 429 또는 5xx 비율 | 이전 라우트의 베이스라인을 지속적으로 상회 |
| p95 지연 시간 | 제품의 타임아웃 예산 초과 |
| 요청당 비용 | 설정된 마진으로 추정치 초과 |
| 사용자 보고 | 동일한 행동에 대한 클러스터 |
롤백은 배포가 아닌 구성 변경으로 수행해야 합니다. 100% 전환 후에도 최소 며칠 동안은 이전 라우트에 자금이 지원되고 구성되어 있어야 합니다. 테스트를 실행할 준비가 되면 API 키 받기를 통해 API 키를 확보하고 체험을 청구하며, 더 큰 실행을 위해 가격 정책을 확인하고, 엔드포인트 세부 정보는 문서를 참조하세요.
더 많은 가이드
자주 묻는 질문
얼마나 많은 골든 프롬프트가 필요한가요?
50~200개의 실제 프롬프트는 대부분의 앱을 커버합니다. 수량보다 품질이 중요하므로 어색하고 이전에 오류가 발생했던 케이스도 포함하세요.
정확한 일치 차이로 출력을 비교할 수 있나요?
신뢰할 수 없습니다. 온도 0과 고정 시드에서도 출력은 가변적으로 간주하고, 유효한 JSON, 필수 사실, 길이 등의 규칙을 테스트하세요.
테스트 중 비용을 어떻게 추적하나요?
사용량 토큰에 입력당 1M 토큰당 $0.15와 출력당 1M 토큰당 $0.50을 곱하고 실제 잔액을 위해 X-Balance-USD 헤더를 확인하세요.
롤백을 트리거해야 하는 조건은 무엇인가요?
먼저 임계값을 정의하세요: 실패한 체크, 429 또는 5xx 비율, 타임아웃 대비 지연 시간, 추정치 대비 비용.
API 키 받기
등록하고, 키를 복사하고, 기본 URL을 업데이트하세요. 설정이 완료되었습니다.