AI API停止前にmigration auditを完了する方法

Model名やBase URLの変更だけではmigrationは完了しません。streaming、tool calls、errors、limits、usageが変わり得るため、一次sourceのshutdown date、全dependency、contract比較、reversible cutoverが必要です。2026-08-25時点でOpenAIはDeprecationsに日付とreplacementを掲載し、一般policyはgenerally availableに6か月、specializedに3か月、previewにはより短い期間を示します。予定は特定entryから決めます。

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、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、終了signal、usageの位置、first token前/partial output後の切断、retryによる外部action重複を記録します。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またはexplicit acceptanceが必要です。

BetterToken transportはhttps://www.bettertoken.ai/v1/chat/completions、user Bearer Key、current Model IDを使います。test Keyを作成し、current Chat Completions contractに従ってcontrol requestを実行し、HTTP statusと検証可能なresponse fieldを記録します。これはformatだけを確認し、model equivalenceは確認しません。

cutover前にcontrol-request fieldsをcurrent contractと比較します。 Chat Completionsガイドを開く

6. reversible cutover

feature flag/versioned config、owner/window、metrics、正確なrollback condition、secretsを含まないold configを準備します。両contractをdeployしcontrolled trafficから開始、比較後criteria通過時のみ拡大し、written invariant違反でrollbackします。shutdown前に観測後のみold pathを削除し、修正と再runの時間を残します。rollbackは停止済みAPIを復元できません。

readiness evidence

official link/date、owner付きinventory、versioned fixtures/results、各material differenceのdecision、測定可能なrunbookが必要です。一つでもなければ200でもmigration_in_progressです。

Sources: https://developers.openai.com/api/docs/deprecations、https://docs.bettertoken.ai/api-reference/chat-completions。