AI APIのベースURLを変更する前に実施すべき7つの移行テスト

AI APIのベースURL移行テストは、環境変数を変更する前に行うべきであり、本番トラフィックが失敗し始めてからではありません。単一のbaseURLまたはbase_urlを変更すると、認証、モデル選択、ストリーミング、ツール呼び出し、使用記録、クォータの動作、ロールバック制御が同時に新しいパスに移動する可能性があります。

Flatkeyは、1つのキー、1つのOpenAI互換ルーティングレイヤー、そしてモデルプロバイダー全体でより明確な請求と使用状況のレビューを求めるチーム向けに設計されています。2026年7月7日に確認されたFlatkeyの公開ホームページには、ルートの例としてhttps://router.flatkey.ai/v1/chat/completionsが示されていましたが、現在のモデルと価格のページでは、レビュー用にモデル、エンドポイント、プロバイダー、請求のコンテキストが公開されていました。これらのページを移行当日の証拠として扱い、トラフィックを移動する前に自身のアカウントでスモークテストを実行してください。

このガイドを、AI APIのベースURL移行テストの実践的な手順として使用してください。目標は、すべてのアプリパスを証明することではありません。目標は、新しいベースURLを通る最小の安全なパスを証明し、その後、一度に1層ずつ機能を追加していくことです。

7つのAI APIベースURL移行テスト

この順序でテストを実行してください。それぞれが、デプロイチケットに添付できる証拠を生成するはずです。

フレームワークのラッパーがステージングで既に機能していたからといって、初期のテストをスキップしないでください。ほとんどのAI APIベースURL移行テストは、SDKがサイレントに異なるキーを読み取ったり、間違ったベースURLルートを受け取ったり、有効なモデルを間違ったエンドポイントファミリーに送信したりするために失敗します。

テスト1：認証とベースURLの構成

アプリケーションの外部から開始します。キーとベースURLが最も単純なエンドポイントの形状に到達できることを証明する必要があります。

よくあるベースURLの間違いは、完全なエンドポイントをSDKに渡すことです。OpenAI互換のSDKの場合、ベースURLは通常、https://router.flatkey.ai/v1のようなAPIルートであり、SDKは/chat/completions、/responses、または別のエンドポイントを追加します。ベースURLとしてhttps://router.flatkey.ai/v1/chat/completionsを渡すと、パスが重複する可能性があります。

まず、編集済みの環境チェックを使用します。

test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"

次に、直接リクエストを1つ行います。

export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'"',
    "messages": [
      {"role": "user", "content": "Reply with exactly: base url ok"}
    ]
  }'

これが401を返す場合は、モデルを変更する前にキーと認証ヘッダーを修正してください。404を返す場合は、ホスト、/v1ルート、およびエンドポイントパスが重複していないかを確認してください。403を返す場合は、アカウント、プロジェクト、モデル、リージョン、またはIPポリシーを確認してください。OpenAIのエラーコードドキュメントでは、401は認証、429はレートまたはクォータ、500または503はサーバーまたは過負荷状態として扱われます。ゲートウェイはより詳細な情報を追加できるため、レスポンスボディを保存してください。

テスト2：モデルカタログとエンドポイントファミリー

OpenAI互換のベースURLであっても、すべてのモデル名がポータブルになるわけではありません。OpenAI APIにはモデルを一覧表示するエンドポイントがあり、そのチャット補完エンドポイントとレスポンスエンドポイントは異なるリクエスト形状を使用します。ゲートウェイやプロバイダー互換のルートは、あるエンドポイントファミリーにはモデルを公開しても、別のファミリーには公開しない場合があります。

本番設定を変更する前に、小さなモデルマップを作成してください。

合格条件は「モデル名が正しく見える」ことではありません。合格条件は、現在のFlatkeyコンソール、モデルディレクトリ、またはプロバイダーカタログに、呼び出す予定の正確なエンドポイントファミリーの正確なエイリアスが表示されることです。この作業を、OpenAI互換モデル名ガイドで、より広範なモデルガバナンスに連携させましょう。

テスト3: 通常のチャット補完

3番目のAI APIベースURL移行テストは、最小の実際の生成リクエストです。非ストリーミングにしてください。ツール、JSONスキーマ、ファイル、画像、リトライ、またはアプリのミドルウェアは含めないでください。

保存:

通常のリクエストが失敗した場合は、まだストリーミングのデバッグを行わないでください。OpenAI互換APIトラブルシューティングガイドを使用して、まずキー、ルート、エンドポイントファミリー、モデルエイリアスの問題を切り分けます。

テスト4: SDKのパリティ

curlが機能した後、SDKが同じルートを構築することを証明します。OpenAIの現在の公式ドキュメントは、開発者にJavaScriptとPythonの公式SDKを案内しています。OpenAIクックブックには、トークンとカスタムベースURLでクライアントが作成されるカスタムエンドポイントの使用法も示されています。移行のためには、残されたOPENAI_API_KEYやOPENAI_BASE_URLの値に頼るのではなく、これをコードで明示的にします。

Pythonテンプレート:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: sdk ok"}],
)

print(response.choices[0].message.content)
print(response.usage)

Nodeテンプレート:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk ok" }],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

プロセス起動時に解決されたベースURLをログに記録しますが、キーはログに記録しないでください。curlが成功し、SDKが失敗した場合は、モデルを変更する前に、環境変数の優先順位、SDKのバージョン、パスの結合、組織/プロジェクトのヘッダー、およびプロキシの動作を検査してください。

テスト5: ストリーミングまたはSSE

ストリーミングは、多くの移行がHTTPレイヤーでは正常に見えても、アプリで失敗する箇所です。OpenAIのChat Completionsリファレンスは、ストリーミングが有効な場合、JSONオブジェクトまたはストリーミングされたチャット補完チャンクのいずれかを返します。Responses APIもtext/event-streamを返すことができ、そのイベント名はChat Completionsチャンクとは異なります。

非ストリーミングリクエストが機能した後にこれを実行します:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'"',
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

合格条件:

より詳細なストリーム解析については、既存のOpenAI互換ストリーミングSSEテストと比較してください。

テスト6: ツールまたは関数呼び出し

ツール呼び出しは、スキーマと機能のリスクを追加します。OpenAIの関数呼び出しガイドでは、ツールを送信し、ツール呼び出しを受信し、アプリコードを実行し、ツール出力を返し、最後に最終的なモデルレスポンスを受信するという複数ステップのフローが説明されています。ベースURLの移行は、プレーンテキストが機能する場合でも、これらの境界のいずれかで失敗する可能性があります。

本番環境のすべてのツールから始めないでください。1つの小さな関数を使用してください:

{
  "model": "your-current-flatkey-model-alias",
  "messages": [
    {"role": "user", "content": "Use the tool for order A123."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Return a test order status.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string"}
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

プレーンなチャットは機能するのにこれが失敗する場合、デバッグしているのはベースURLではありません。モデルの能力、エンドポイントファミリー、スキーマの厳格さ、tool_choice、または選択したルートのゲートウェイサポートをデバッグしていることになります。公開されているツール呼び出し互換性ガイドでは、より広範なプロバイダーのチェックリストをカバーしています。

テスト7：使用量、クォータ、ロールバック

最後のAI APIベースURL移行テストは運用に関するものです。財務部門がそれを照合できなかったり、クォータが期待どおりに動作しなかったり、ロールバックに緊急のコード変更が必要になったりする場合、レスポンスが生成されるだけでは不十分です。

1回のスモークテストが成功したら、以下を確認します。

プレッシャーの中でも実行できるほどシンプルなロールバックファイルを使用します。

# active
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias

# rollback
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall

ロールバックを記憶に頼らないでください。以前の設定、機能フラグ、デプロイコマンド、および検証コマンドは、AI APIベースURL移行テストと同じデプロイチケットに保存してください。

保管すべきエビデンスパケット

環境ごとに、以下の質問に答える1つのパケットを保管してください。

これが、切り替え前にAI APIベースURL移行テストを実行する実践的な利点です。この成果物は、デプロイレビュー、インシデント対応、使用量の照合、および調達のエビデンスとして役立ちます。

Flatkeyが適合する場面

Flatkeyは、モデルアクセス、ルーティング、請求、使用量分析、および運用レビューを1つのキーの背後で一元化することにより、移行のスプロール化を軽減できます。それでもテストの必要性がなくなるわけではありません。これにより、エンジニアリング、財務、および運用チームが同じルートのエビデンスを検査できる単一のコントロールポイントが提供されます。

移行する前に、ライブのFlatkeyモデルと価格ページを確認し、現在のコンソールのベースURLを確認し、1つの小さなルートテストから始めてください。より広範な切り替えをまだ計画している場合は、このガイドをOpenAI互換API移行ガイドと併せて使用してください。独自のテストを実行する準備ができたら、キーを取得し、最初のリクエストは手動で検査できるほど小さく保ってください。

よくある質問

AI APIベースURL移行テストとは何ですか？

AI APIベースURL移行テストは、新しいAPIルートが認証、モデルルーティング、プレーンチャット、SDK使用、ストリーミング、ツール、使用量の読み取り、クォータの動作、およびロールバックに対して機能することを証明する、切り替え前のチェックです。

最初にcurlとSDKのどちらをテストすべきですか？

最初にcurlをテストしてください。Curlは、フレームワークの動作なしに、キー、URL、エンドポイントパス、およびモデルエイリアスを証明します。その後、同じ値でSDKをテストします。

ベースURLに/chat/completionsを含めるべきですか？

通常は含めません。SDKには/v1などのAPIルートを指定し、SDKにエンドポイントを追加させます。完全なエンドポイントは、直接のcurlリクエストでのみ使用してください。

プレーンチャットは機能するのに、なぜストリーミングは失敗するのですか？

ストリーミングが失敗する原因として、ルートがレスポンスをバッファリングする、クライアントパーサーが間違ったイベントシェイプを期待している、ミドルウェアがストリームを消費する、または選択したエンドポイントファミリーが使用しているストリームシェイプをサポートしていない、などが考えられます。

まだライブのFlatkeyリクエストを実行できない場合はどうすればよいですか？

コードスニペットをテンプレートとして保持し、公開ドキュメントとコンソールの設定を検証し、実際のキーが自社の環境で7つのAI APIベースURL移行テストを証明するまで、本番トラフィックを移動させないでください。

結論

AI APIのベースURLの変更は、単なる文字列の編集ではなく、本番環境の移行です。AI APIのベースURL移行テストを、auth、model catalog、plain chat、SDK parity、streaming、tools、usage plus rollbackの順に実行します。7つすべてに合格すると、ベースURLの変更は、遅い時間になってからのデバッグセッションではなく、管理されたカットオーバーになります。