# LLM APIを変更する前にストリーミングとツール呼び出しの互換性をどうテストしますか？ > LLM APIの移行はチャットのデモではなく、記録可能な契約フィクスチャで検証します。実際のコーディング作業を送る前に、テキストストリーミング、強制ツール1件、分割引数、複数呼び出し、ツール結果からの継続、キャンセル、エラー、使用量集計を確認してください。 10分間のチャットテストでは、再試行後の呼び出し重複、最後のストリームイベントより前に実行されたJSON、誤ったロールで返されたツール結果、書き込みを残したままのキャンセルといった重要な失敗を見逃します。有効な移行ゲートは、固定リクエストを実際のパーサーと実行機構へ通し、構造的不変条件を評価します。 最初のスイートはローカルで実行できる程度に小さくし、モデル間で比較できるよう決定的にします。目的は知能の順位付けではありません。新しいAPIが既存のエージェントループを安全に駆動できることを証明するためのものです。 ## 依存する契約を定義する プロバイダーをテストする前に、クライアントが必要とする挙動を書き出します。「OpenAI互換」のような曖昧なラベルは避けてください。 | 契約領域 | 必要な不変条件 | 保存する証拠 | |---|---|---| | 認証 | 想定したエンドポイントがキーを受け付ける | ステータスとリクエストID | | テキストストリーム | 差分が1つの最終メッセージに組み立てられる | 順序付きの生イベント | | ツールストリーム | 実行前に呼び出しが確定する | 呼び出しバッファと最終イベント | | 対応付け | 結果が正しい呼び出しに結び付く | 呼び出しIDの対応表 | | 再試行 | 呼び出しが最大1回だけ実行される | 冪等性ログ | | 使用量 | カウンターが存在するか、利用不可と示される | 最終レスポンスのメタデータ | プロトコル対応はモデルごとに異なります。Atlas Cloudは複数のリクエスト形式を提供しているため、テスト経路を決める前に現在の[`supported_apis`ガイド](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis)を確認してください。 ## 決定的な4つのツールを作る 異なる失敗モードを明らかにするフィクスチャを使います。 * `echo_json`: 検証済みの引数をそのまま返す。 * `read_fixture`: サンドボックス内の既知のファイルを1つ読む。 * `delayed_value`: 制御された遅延後に完了する。 * `always_error`: 安定した構造化エラーを返す。 各ツールには `additionalProperties: false` を指定した厳密なスキーマを与えます。重複実行を検出できるよう一意のフィクスチャIDも含めます。現在の天気、検索結果、変化するリポジトリには依存させません。 ## 段階的な互換性マトリクスを実行する ストリーミングの前に非ストリーミングを、複数呼び出しの前に単一呼び出しをテストします。 | 段階 | プロンプトの挙動 | 合格条件 | |---|---|---| | A | 通常のテキストを返す | 最終テキストと停止状態が届く | | B | `echo_json` を強制する | 名前と有効な引数が届く | | C | `echo_json` をストリーミングする | 断片が1回だけ組み立てられる | | D | 2つの読み取りツールを呼ぶ | 両方の結果が正しく対応付けられる | | E | 1件のツールエラーを受け取る | モデルが修復するか正常に終了する | | F | ストリーム途中でキャンセルする | 遅延したツール実行が発生しない | すべての候補で同じスキーマと意味上同じリクエストを使います。ネイティブプロトコルが異なる外枠を必要とする場合も、通信表現だけを適応し、フィクスチャの意図は同一に保ちます。 ## SDKより下で生イベントを取得する 高水準のSDKオブジェクトは本番環境では便利ですが、移行時の差異を隠すことがあります。単調増加する連番、レスポンスID、出力インデックス、呼び出しID、イベント種別、マスク済みペイロード長とともに各サーバーイベントを書き出すデバッグトランスポートを追加します。 関数引数のストリーミングは増分です。呼び出しごとに組み立て、最終引数イベントを待ちます。各断片を解析しようとするより、次の状態機械の方が安全です。 ```text START -> CALL_OPEN -> ARGUMENT_DELTAS -> CALL_DONE -> VALIDATED -> EXECUTED | | +-> CANCELLED <---+ ``` 後戻りする遷移や二重実行は拒否します。`EXECUTED` 後、モデルが結果を受け取る前に接続が切れた場合は、書き込みを無条件に繰り返さず冪等性キーを使ってください。 ## ツール結果の完全な往復をテストする 有効なツール呼び出しは契約の半分にすぎません。プロトコルが期待するメッセージまたは項目タイプで結果を返し、その結果にある既知のフィールドを引用した最終回答をモデルに要求します。 大きな結果、空の結果、Unicode、構造化エラーをテストします。結果をコンテキストへ戻す前にサイズを制限してください。最初の大きなツール結果がアダプターの前提を超えるまで、移行が成功したように見える場合があります。 ## 文章ではなく不変条件を比較する 2つのモデルが異なる言い回しを使っただけでテストを失敗させてはいけません。観測可能な性質を検証します。 * 想定したツール名が選択された。 * 引数がJSON Schemaの検証を通った。 * すべての呼び出しIDが一意で対応付けられた。 * 各ツールが意図どおり0回または1回実行された。 * 許可した呼び出し上限内でループが終了した。 * 最終回答がフィクスチャの結果を使用した。 候補固有のスナップショットはデバッグ専用に保存します。合格条件はプロバイダー中立に保ってください。 ## 失敗とキャンセルのケースを追加する 最初の引数断片の後、呼び出し完了後、ツール実行後にそれぞれストリームを切断します。429、タイムアウト、不正なJSON、未知のツール名を注入し、クライアントがリクエストを再試行するのか、安全に再開するのか、有用なエラーで停止するのかを確認します。 最も危険なのは明白な失敗ではなく、状態変更ツールを繰り返す曖昧な再試行です。書き込みには明示的な冪等性を要求し、実行識別子が不明ならテストを失敗させます。 ## スイートをリリースゲートにする 設定変更ごとに高速なスモークスイートを実行し、SDKまたはゲートウェイ更新では完全なマトリクスを実行します。モデル、プロトコル、ベースURL、スキーマハッシュ、ストリーミングフラグ、クライアントバージョン、時刻を結果とともに保存してください。 Atlas Cloudはストリーミングと非ストリーミングのLLMリクエストに対応し、1つの[モデルカタログ](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis)から候補を探せます。共通アクセスが同一機能を意味するわけではないため、選んだモデルごとに同じゲートを実行します。 ## 結論 LLM APIの移行は状態を持つプロトコル変更としてテストします。決定的なツールから始め、生イベントを記録し、ストリーミング引数は完了時だけ組み立て、ツール結果の往復を検証し、再試行とキャンセルを注入してください。1件のチャット回答が良かったからではなく、契約スイートが合格したときだけ新しいモデルを昇格させます。 ## FAQ ### 最初の互換性テストでは何を確認すべきですか？ 非ストリーミングのテキストリクエスト1件と、強制した読み取り専用ツール呼び出し1件から始めます。これにより、エンドポイント、認証、スキーマ、基本的なレスポンス形式の問題を切り分けられます。 ### 生のストリーミングイベントを記録するのはなぜですか？ SDKのヘルパーはイベント順序やフィールド差異を隠すことがあります。生のイベントを見れば、呼び出しID、引数断片、完了マーカー、エラー、使用量が実際にどう届くか分かります。 ### 完全に同じ文章かどうかでプロバイダーを比較できますか？ 通常はできません。表現ではなく、有効な呼び出し、必須フィールド、実行回数、最終状態、タスク結果などの構造的不変条件を比較してください。 ### 不正なツール引数はどうテストすべきですか？ 構造化された検証エラーをモデルへ返し、安全でない入力を実行せず、定めた呼び出し上限内でループが修復または終了することを確認します。 ### テストスイートで書き込みツールを使うべきですか？ 最初は決定的な読み取り専用ツールを使います。呼び出しの組み立て、検証、重複排除、エラー復旧が通った後にだけ、サンドボックス化した書き込みフィクスチャを追加してください。 ### 互換性テストはどの頻度で実行すべきですか？ モデルまたはプロトコルを変更するたびにスモークテストを実行し、SDKバージョン、スキーマ、ゲートウェイ、ストリームパーサーが変わったときは完全なスイートを実行します。