Base URL and SDK Migration2026年7月27日Flatkey Team

複数モデルのプロンプトテストに使える 1 つの OpenAI 互換ベース URL

OpenAI SDK はそのままに、ベース URL を 1 つ切り替えるだけで、制御されたプロンプトテストと本番切り替えのワークフローで複数モデルを比較できます。

あなたのアプリケーションは、すでに OpenAI 互換クライアントの呼び出し方法を把握しています。モデルの選択を追加するために、プロバイダーごとにその統合を作り直す必要はありません。

Flatkey は 1 つの OpenAI 互換ベース URL を提供します。

https://router.flatkey.ai/v1

既存の OpenAI SDK クライアントをその URL に向け、Flatkey の API キーを使い、テストしたいモデルを model フィールドで指定します。リクエストラッパー、プロンプトデータセット、評価基準、アプリケーションコードは、1 つのインターフェースを中心に据えたままで構いません。

そのため Flatkey は、チームがモデル比較を始める準備ができている一方で、プロバイダー固有のアカウント設定やクライアントの書き換えを評価プロジェクトにしたくない場合に、実用的な選択肢になります。

1 つのモデルから候補リストまで、最も摩擦の少ない進め方

典型的なモデル評価は、単純な問いから始まります。別のモデルで、このワークロードの品質、レイテンシ、またはコストを改善できるか？

しかし実装作業が、その問いをすぐに覆い隠してしまうことがあります。統合を分けると、環境変数、認証パターン、再試行の挙動、レスポンスアダプター、ダッシュボード、請求関係まで分かれてしまいます。テストハーネスの準備が整うころには、元のプロンプト実験はインフラプロジェクトに変わっています。

OpenAI 互換のベース URL は、その流れを変えます。1 つのクライアント形状を保ち、モデルを主な変数にします。

安定して維持するもの	意図的に変更するもの	モデルごとに検証するもの
SDK とリクエストラッパー	`base_url` を 1 回設定	出力品質
プロンプトデータセット	各実行で `model` を変更	レイテンシ分布
評価基準	必要に応じてモデル固有のパラメータ	トークン使用量とコスト
結果保存	妥当性がある場合のみタイムアウトや再試行設定	ツール利用と構造化出力の挙動
アプリケーション側の可観測性	評価後にのみ本番ルーティング	エラーと拒否のパターン

目的は、すべてのモデルが同じように動くふりをすることではありません。目的は、避けられる統合上のばらつきを取り除き、チームが重要な差異の測定により多くの時間を使えるようにすることです。

SDK 層全体ではなく、ベース URL だけを変更する

すでに OpenAI Python SDK を使っているなら、コアとなるクライアント変更は小さく済みます。

import os
from openai import OpenAI

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

同じパターンは OpenAI JavaScript クライアントでも使えます。

import OpenAI from "openai";

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

その後は、リクエスト内で Flatkey の現在のモデルディレクトリからモデル ID を使用します。古いスプレッドシートや記事のモデル前提をハードコードしないでください。モデルの利用可否や機能は変わる可能性があります。

response = client.chat.completions.create(
    model=os.environ["EVAL_MODEL_ID"],
    messages=[
        {"role": "system", "content": "提供されたポリシーを使用して回答してください。"},
        {"role": "user", "content": evaluation_prompt},
    ],
    temperature=0,
    max_tokens=800,
)

これが導入上の中核的な利点です。評価でモデルの選択を変えても、アプリケーションは OpenAI 互換クライアントを維持できます。

焦点を絞った複数モデルのプロンプトテストワークフロー

次のワークフローを使って、ベース URL の移行を、チームが自信を持って説明できる判断に変えましょう。

1. リクエスト契約を固定する

まず、すでに本番ワークロードを表している 1 つのリクエストから始めます。最初の比較フェーズでは、以下を固定してください。

システムプロンプトとユーザープロンプト
入力例
temperature とトークン制限
ツール定義またはレスポンススキーマ
タイムアウトポリシー
評価ルーブリック

プロンプト、モデル、再試行ポリシーを同時に変更すると、どの変更が結果を生んだのか分からなくなります。

2. 小さく代表的な評価セットを作成する

何百もの合成プロンプトから始めないでください。ユーザーが実際に作成するケースをカバーする 20〜50 件の例から始めます。

一般的で頻度の高いリクエスト
長い入力や乱雑な入力
あいまいな指示
安全性に敏感、または拒否が発生しやすいケース
構造化出力のエッジケース
アプリケーションがツールを使用する場合は、ツール呼び出しのケース

評価トラフィックを送る前に、個人データとシークレットを削除してください。最良の評価セットは、検査できる程度に小さく、かつ意味のある失敗を明らかにできるほど代表的です。

3. 同じケースを各候補モデルに通す

Flatkey のベース URL とリクエストラッパーは固定します。候補リストにあるモデル ID を順に試してください。

import time

candidate_models = [
    "MODEL_ID_A",
    "MODEL_ID_B",
    "MODEL_ID_C",
]

results = []

for model_id in candidate_models:
    for case in evaluation_cases:
        started_at = time.perf_counter()
        try:
            response = client.chat.completions.create(
                model=model_id,
                messages=case["messages"],
                temperature=0,
                max_tokens=case.get("max_tokens", 800),
            )
            elapsed_ms = round((time.perf_counter() - started_at) * 1000)
            results.append({
                "case_id": case["id"],
                "model": model_id,
                "latency_ms": elapsed_ms,
                "output": response.choices[0].message.content,
                "usage": response.usage.model_dump() if response.usage else None,
                "error": None,
            })
        except Exception as error:
            results.append({
                "case_id": case["id"],
                "model": model_id,
                "latency_ms": None,
                "output": None,
                "usage": None,
                "error": type(error).__name__,
            })

共有の例ではプレースホルダーを使用し、テストを実行する前にライブディレクトリから現在のモデル ID を選択してください。また、候補となる各モデルが、ワークロードに必要な機能をサポートしていることも確認してください。

4. モデルの評判ではなく、結果を採点する

役立つスコアカードは、必須要件と好みを分けて考えます。

Dimension	Example question	Suggested treatment
Correctness	Did the response satisfy the task?	Human or task-specific grader
Instruction following	Did it obey constraints and format?	Pass/fail plus notes
Structured output	Did the payload parse and match the schema?	Automated validation
Tool behavior	Were calls valid and appropriately selected?	Automated checks plus review
Latency	How long did successful requests take?	Median and tail percentiles
Reliability	How often did requests fail or time out?	Error rate by class
Usage	How many input and output tokens were reported?	Per-case and aggregate
Cost	What would the evaluated workload cost?	Calculate with current pricing

たとえ安価であっても、必須要件を満たさない候補は除外してください。残ったモデルについては、自社製品にとって重要なトレードオフを比較します。

5. 本番の動作で最終候補を再テストする

最初のパスは制御された条件で行うべきです。最終候補のパスは現実的であるべきです。

インターフェースがストリーミングするならストリーミングをテストしてください。エージェントがツールを使うならツール呼び出しをテストしてください。下流のコードが構造化出力を解析するなら構造化出力をテストしてください。実際のタイムアウトとリトライ設定を適用し、アプリケーションがレート制限、中断されたストリーム、不正な形式の応答、あいまいな完了状態をどう処理するかを検証してください。

Flatkey's Usage Logs を使えば、リクエストがゲートウェイに到達したことの確認や、リクエストアクティビティの確認に役立ちます。アプリケーション側のリクエスト ID とタイミングデータも保持して、ゲートウェイの可視性とユーザー体験を結び付けられるようにしてください。

リトライと切り替えの詳細については、レート制限とリトライに関する OpenAI クライアント移行ガイドを参照してください。