API Migration LLMアプリのテスト:実践的な計画
LLMアプリのAPI移行テストは、通常のREST APIのテストとは異なります。同じプロンプトでも毎回異なるテキストが返されるためです。あなたは正確な文字列ではなく、回答のプロパティをテストします。
最終更新

まとめ
- 正確一致の期待値ではなく、ルールベースのチェック付きで50〜200件の実際のプロンプトからゴールデンセットを構築します。
- ノイズを減らすためにtemperatureとseedを固定しますが、同一のテキストが返ることは期待しないでください。
- 新旧ルートのレイテンシパーセンタイルとリクエストごとのコストを記録します。
- ロールアウト開始前にロールバックトリガーを記録します。
実際にテストするもの
従来のAPIではレスポンスをバイト単位で比較しますが、言語モデルではそれがすぐに破綻します。代わりに、製品が依存する回答のプロパティを決定し、それらをテストします。
- 形状。 有効な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"]
}
リスクでケースにタグ付けします:ツール呼び出し、長いコンテキスト、ストリーミング、非英語、非常に短い回答、非常に長い回答。後で本番環境でバグが発生した場合、セットに追加します。セットは回帰テストスイートへと成長します。
記録用ハーネスの作成
スクリプト1つで、ルート全体に対してセットを実行し、チェックを適用して数値を保存してください。変動を減らすために、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
自由形式の回答には、安価な長さの範囲(例えば、古い回答の半分〜2倍以内)と、拒否フレーズをフラグするための短いリストを追加します。そして、20件の出力を並べて目視で確認してください。ルールは回帰を検出し、目視確認はトーン(口調)のズレを検知します。両方行ってください。
JSON出力の場合、response_formatを{"type":"json_object"}に設定し、上記のチェックは安価であるため、依然として検証を行ってください。
意図的に失敗パスをテストする
ハッピーパスのプロンプトはほぼすべてのプロバイダで成功します。移行時に問題が顕在化する箇所は失敗なので、ユーザーが行う前に意図的に失敗を引き起こしてください。
- 無効なキー。 間違ったキーでリクエストを送信し、アプリが健全なメッセージを表示し、ループで再試行しないことを確認します。
- レート制限。 フルキーで8リクエスト以上、試用キーで2リクエストを同時に送信し、コードがHTTP 429を
concurrencyコードで処理し、毎分の制限を超えた場合にrate_limitedコードを処理することを確認します。 - 一時的な過負荷。
Retry-After: 5付きの429ステータスコードは、即座なリトライではなく、5秒間の待機を引き起こすべきです。 - 過大な入力。 100,000トークンのウィンドウに近いプロンプトと、それを超えるプロンプトを送信します。アプリはクラッシュするのではなく、トリミングまたは要約すべきです。
- 大きなボディ。 制限は8 MBです。より大きなペイロードはアプリ側で拒否することを確認します。
- ストリームの切断。 ストリーミング中に接続を切断し、同時接続枠(スロット)が解放されることを確認します。
これらそれぞれに、フェイクサーバーに対してCIで実行される自動化テストと、本番サーバーに対して手動で1回実行するテストが必要です。
ストリーミングとツール呼び出しを確認
ストリーミングとツールはレスポンスの形状を変更するため、プレーンテキストベースのゴールデンセットではそれらが見逃されます。それぞれにケースを追加してください。
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"メッセージとして送信される2ターン目が通常の回答を生成することを確認するチェックを追加してください。ストリーミングの場合、チャンクが届き、最終的な使用量が表示され、コードがストリームの末尾で読み取りを停止することをアサートします。
ルートごとのレイテンシとコストを追跡
古いルートと新しいルートの両方でセットを実行し、中央値と95パーセンタイルの秒数、エラー数、トークン数、コストなど、同じ列を比較してください。この記事にはどのプロバイダーについてもレイテンシ数値は記載されていません。それはあなたのプロンプトとネットワークに依存するためです。ご自身で測定してください。
新しいルートのコストは、トークン数にレート(100万トークンあたり入力$0.15、出力$0.50)を掛けたものです。例:平均入力1,200トークン、出力300トークンのゴールデンプロンプト200件。
- 入力: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リクエスト、1分あたり60リクエストを許可するため、200件のプロンプトには少なくとも3分半かかります。失敗または拒否されたリクエストには課金されません。各呼び出し後にX-Balance-USDヘッダーから残高を確認し、自分の計算を確認することもできます。
シャドウトラフィックと段階的なロールアウト
ゴールデンセットが合格したら、回答を表示せずに本番リクエストを新しいルートにコピーします。結果をログに記録し、同じチェックで本番レスポンスと比較します。シャドウ実行には同時実行数の制限が必要です: 完全なキーは同時に8リクエストまで許可されるため、ミラーリングされた呼び出しを一度にすべて送信するのではなくキューに入れます。
その後、実際のユーザーを5%、25%、50%、100%などの段階で段階的に移動します。各ステップでは、エラー率、失敗したチェック、苦情が横ばいになるまで待ちます。
ロールバックルールを事前に決定する
最初のユーザーが移動される前に閾値を記録しておき、その場の判断が機械的に行えるようにします。
| シグナル | トリガーの例 |
|---|---|
| 本番トラフィックでのチェック失敗 | 合意された割合以上のルールチェックが失敗する |
| HTTP 429または5xxのレート | 旧ルートのベースラインを継続的に上回る |
| レイテンシ p95 | 製品のタイムアウト予算を超える |
| リクエストあたりのコスト | 設定されたマージンを見積もりより上回る |
| ユーザーからの報告 | 同じ動作に関するクラスタ |
ロールバックはデプロイではなく設定変更であるべきです。100%移行後も、少なくとも数日間は古いルートに資金を供給し、設定を維持してください。テストを実行する準備ができたら、APIキーを取得してトライアルを受け取り、大規模なランには料金表を確認し、エンドポイントの詳細はドキュメントを参照してください。
その他のガイド
よくある質問
ゴールデンプロンプトにはいくつ必要ですか?
50〜200件の実際のプロンプトがほとんどのアプリをカバーします。数よりも品質が重要なので、扱いにくいケースや以前失敗していたケースを含めてください。
正確な差分比較で出力を比較できますか?
確実ではありません。温度0で固定シードを使用しても、出力は可変として扱い、有効なJSON、必須の事実、長さなどのルールでテストしてください。
テスト中にコストを追跡するにはどうすればよいですか?
使用トークン数に、入力1Mトークンあたり$0.15、出力1Mトークンあたり$0.50を掛け、実際の残高についてはX-Balance-USDヘッダーを確認してください。
ロールバックのトリガーは何にするべきですか?
まず閾値を定義します: 失敗したチェック、429または5xxのレート、タイムアウトに対するレイテンシ、見積もりに対するコスト。
APIキーを取得
登録し、キーをコピーし、ベースURLを更新します。セットアップは完了です。