AI API 종료 전 migration audit를 완료하는 방법

Model 이름이나 Base URL 변경만으로 migration은 끝나지 않습니다. streaming, tool calls, errors, limits, usage가 달라질 수 있으므로 shutdown date, 전체 dependency, contract 비교, 되돌릴 수 있는 cutover가 필요합니다. 2026-08-25 OpenAI는 Deprecations에 날짜와 replacement를 게시합니다. 일반 policy는 generally available 6개월, specialized 3개월, preview는 더 짧을 수 있으므로 특정 항목을 기준으로 잡습니다.

1. 이벤트 기록

코드 변경 전 official source, 확인일, 이전/대체 endpoint와 model, shutdown_date, owner를 기록합니다. provider notice에 없는 날짜는 unknown으로 두고 재확인 owner를 정하며 긴급성을 만들지 않습니다.

deprecation_source: https://developers.openai.com/api/docs/deprecations
checked_at: 2026-08-25
old_endpoint: /v1/chat/completions
old_model: OLD_MODEL_ID
replacement_endpoint: /v1/chat/completions
replacement_model: NEW_MODEL_ID
shutdown_date: YYYY-MM-DD
owner: team-name

2. dependency inventory

endpoint, Base URL, protocol, ID/fallback, payload/messages, tool schema/required fields/choice, SSE parser/usage, errors/retry, prompt, services, cron, workflows, SDK, CI, serverless, n8n/Dify, secret store, background jobs를 포함합니다. secret 값 대신 이름과 owner만 남깁니다.

3. control request 준비

개인정보를 제거한 factual text, required JSON, valid tool call, no-tool case, 완료된 stream, 4xx, transient error/test double을 씁니다. 문구가 아니라 schema, arguments, application result, required facts, stream end, retry를 비교하고 cost와 latency는 별도로 측정합니다.

4. streaming과 errors 분리 검사

event와 data, 종료 신호, usage 위치, 첫 token 전/부분 출력 후 끊김, retry의 외부 동작 중복을 기록합니다. HTTP status, machine-readable code, retry boundary를 보관합니다. 401, 403, schema validation error는 자동 retry하지 않고, 429/temporary 5xx에는 Retry-After, 시도 제한, idempotency를 적용합니다.

5. old/new dual run

test에서 old path를 baseline으로 두고 동일 fixtures를 new path에 보냅니다. 다음을 저장합니다.

case_id | old_result | new_result | contract_pass | difference | decision

tool arguments, fields, stream 종료, error 차이는 client fix 또는 명시적 acceptance가 필요합니다.

BetterToken transport는 https://www.bettertoken.ai/v1/chat/completions, 사용자 Bearer Key, 현재 Model ID를 사용합니다. test Key를 만들고 current Chat Completions contract에 따라 control request를 실행한 뒤 HTTP status와 검증 가능한 response field를 기록합니다. 이는 형식만 확인하며 model equivalence는 확인하지 않습니다.

cutover 전에 control-request fields를 현재 contract와 비교하세요. Chat Completions 가이드 열기

6. reversible cutover

feature flag/versioned config, owner/observation window, metrics, 정확한 rollback condition, secrets 없는 old config를 준비합니다. 두 contract를 deploy하고 controlled traffic부터 시작해 비교 후 기준 통과 시만 확대하며, 작성된 invariant 위반 시 rollback합니다. shutdown 전 관찰 후에만 old path를 제거하고, 수정·재실행 시간을 남깁니다. rollback은 종료된 API를 복구하지 못합니다.

준비 증거

official source/date, owner가 있는 inventory, versioned fixtures/dual-run results, 모든 material difference의 결정, 측정 가능한 runbook이 필요합니다. 하나라도 없으면 200이어도 migration_in_progress입니다.

출처: https://developers.openai.com/api/docs/deprecations, https://docs.bettertoken.ai/api-reference/chat-completions.