同じじ機能で、フロントエンドが4つのモデルを呼びび出しす:GPT-4oがフォールバックを担当し、DeepSeekが主力推論を実行し、Qwenが中国語の長文を処理し、Doubaoがカスタマーサポートの応答文を担当する。4つのSDK、4つの認証方式、4つのドキュメント。リリース初週は、これらの差異を揃ええるだけで2人日を費やした。
これは誇張ではない。4社のモデルを接続した後、ビジネスコードのうちモデル呼びび出ししに関連する部分が3倍近くくまで膨らみれ上がったと集計している。モデルを1つ変えるたびに、呼びび出しし方、解析ロジック、エラー処理を書き直しす必要がある。さらに厄介なのは、ベンダーがSDKをアップグレードするたびに、再テストが必要になることだ。この記事では、私たちが踏みんだ落としとし穴と最終的に落としち着いたゲートウェイ方案を一通りり整理する。同じじように複数モデルの間で苦しんでいるチームの助けになれば幸いいだ。
一、認証:4つの体系、4つの書き方
最初にぶつかったのは認証だ。OpenAI系はBearer Token方式で、リクエストヘッダにAuthorization: Bearer sk-xxxを入れればよい。QwenはAccessKey署名が必要で、リクエストごとにAK/SKでHMACを計算し、タイムスタンプとランダム文字列を組みみ合わせわせる必要がある。DoubaoはAK/SKにタイムスタンプを加ええるが、署名アルゴリズムはQwenとも異なる。DeepSeekはOpenAI形式と互換性があるものの、独自のbase_urlとモデル名マッピングを持つち、初期化方法も公式SDKと完全には一致しない。
結果として、コードのあちこちがif-elseだらけになる。ベンダーごとに1つのclientインスタンス、各インスタンスに1つの設定。鍵の管理はさらに頭が痛い——4社のKeyが4か所に保存され、ローテーションの際は4か所を変更する必要があり、1つ漏れらせば本番障害になる。
その後、私たちは接続層で統一を行った:外部には1つのAPI Keyだけを公開し、内部でプロトコル翻訳を行う。具体的な方法は、接続層がベンダーのルーティングテーブルを維持つし、各ベンダーがそれぞれの認証アダプタに対応する。ビジネス側は1つのKeyだけを持つち、リクエストは接続層に到達し、接続層がモデル名に基づいて対応するベンダーを見つけ、アダプタで署名と転送を完了する。
私たちは後にbase_urlをtoken8341に統一して試してみたところ、1つのKeyでGPT-4o、Claude、Gemini、DeepSeek、Qwen、ERNIE、Doubaoを呼びび出しせ、OpenAI SDKと互換性があり、base_urlを1行変更するだけで切りり替ええられる。認証の面倒な作業は接続層の外に遮られ、ビジネスコードはかなりきれいになった。鍵のローテーションも1か所の操作になり、運用コストは一桁下がった。
二、SSEストリーミングチャンク:4つの形式、1つのレンダリング
SSEストリーミングチャンクは2つ目の落としとし穴で、しかも認証よりも見えにくい。GPT-4oのchunkではdelta.contentがnullになることがあり、特に最初のchunkと最後のchunkで、フロントエンドがnullチェックせずに直し接レンダリングするとundefinedが一瞬表示される。DeepSeekは最後のchunkにusageが付き、しかもそのusageフィールドの構造はOpenAIと完全には同じじではない。Qwenのeventタイプはさらに細かく分かれ、add、finish、errorなど複数のイベントタイプがあり、各イベントのpayload構造が異なる。Doubaoの終了マーカーもまた違い、特殊なfinish_reasonフィールドでストリームの終了を識別する。
フロントエンドが4つの形式を受け取りると、レンダリングロジックは一気に破綻する。私たちは最初、フロントエンドで適応する方案を取りり、4つの解析関数を書いたが、新しいモデルを追加えするたびにフロントエンドを変更することになった。後にゲートウェイ層で正規化する方式に変更した:OpenAIのchunk構造に統一し、空のdeltaは直し接フィルタリングし、usageは別途抽出しして累積する。具体的なルールは——全ベンダーのストリーミング応答をdata: {"choices":[{"delta":{"content":"..."}}]}の形式に変換し、終了は統一的にdata: [DONE]でマークし、usageは最後のchunkでOpenAI形式で返す。
フロントエンドは1つの形式しか認識せず、バックエンドが誰に接続しているかを気にする必要がない。この変更により、フロントエンドのモデル関連コードは400行超から約80行に減り、しかも新モデル追加え時にフロントエンドの変更はゼロになった。
三、エラーコード:HTTP 200の中にエラーが潜む
エラーコードの混乱度は予想を超えていた。同じじレート制限でも、OpenAIは429にrate_limit_exceededを付けて返し、Qwenはcodeフィールド付きのビジネスエラーを返し、DoubaoはエラーをHTTP 200のbodyに押し込みんでしまう——ステータスコードは200だが、bodyにerrorフィールドがある。DeepSeekはほとんどの場合わせOpenAIと一致するが、時折独自のエラー構造を返すことがある。
監視アラートは全く統一できない。「429ならアラート」というルールは書けない。なぜなら一部のベンダーはレート制限時に429を返さないからだ。HTTPステータスコードだけを見ることもできない。なぜならDoubaoの200の中身がエラーかもしれないからだ。
私たちは接続層にマッピングテーブルを構築し、各社のエラーコードを内部エラー体系に収束させた:レート制限、タイムアウト、認証失敗、コンテンツ審査、サービス利用不可。具体的なマッピングロジックは——まずHTTPステータスコードを見て、次にbody内のerror codeを見て、両者を組みみ合わせわせて判断する。例えばDoubaoが200を返すがbodyにerrorがあれば、error codeでマッピングする。Qwenが400にビジネスcodeを付けて返せば、codeでマッピングする。アラートルールは1つだけ書き、調査時には元のエラーコードを見る。
このマッピングテーブルは約60件以上のルールを維持つし、4社のベンダーの一般的なエラーシナリオをカバーしている。リリース後、アラートの正確率は以前の約60%から95%以上に向上し、誤報はほぼなくなった。
四、使用量統計:4つの数字が合わせわない
使用量統計の基準が異なることは最も見落としとされやすいが、財務照合わせの時には必ず露呈する。GPT-4oのtokenカウントはsystem promptを含み、DeepSeekはキャッシュヒットしたtokenを別途課金し、Qwenは入力と出し力を分けて計算し、Doubaoの課金単位はまた異なる。財務照合わせ時に4つの数字が合わせわず、各モデルの実際コストを全く計算できない。
集約方案は、ゲートウェイ層で各リクエストのmodel、input_tokens、output_tokens、cache_hitを記録し、統一的にtoken課金基準でDBに保存する。具体的な方法は——ゲートウェイがリクエスト転送時にリクエスト開始と終了時刻を記録し、応答から各社のusageフィールドを抽出しし、標準形式に統一的に変換する。課金単位が異なるベンダーについては、ゲートウェイ層で一度換算し、すべてper-tokenコストに折算する。
これにより、基盤がどの会社に接続していても、コストを同じじテーブルに揃ええて見ることができる。私たちは後にこのテーブルに基づいてコストダッシュボードも作り、モデル別、ビジネスライン別、日次次元で分解して見られるようにした。ある時、あるビジネスラインのコストが突然40%上昇したことに気づき、調べたところルーティング戦略が大量のリクエストをGPT-4oに送っていたことがわかり、ルーティングを調整するとすぐにコストは下がった。統一された使用量集約がなければ、このような問題は全く発見できなかっただろう。
五、モデルゲートウェイの4層アーキテクチャ
モデルゲートウェイはどの層を担うべきか?私の分け方は4層だ。
第1層プロトコル翻訳。各社のリクエスト・レスポンス形式をOpenAI互換インターフェースに統一する。この層はビジネスコードが唯一直し接触れる層であり、標準OpenAI形式のリクエストを各ベンダーの形式に翻訳し、レスポンスを翻訳して戻す役割を担う。
第2層ルーティング。タスクタイプに応じてモデルを選択する。例えば中国語長文はQwen、コードはDeepSeek、フォールバックはGPT-4o。ルーティング戦略は設定化でき、タスクタイプ別、優先度別、コスト別など多様な次元をサポートする。私たちはさらに降級ロジックも加ええた——主モデルがタイムアウトまたはレート制限の場合わせ、自動的にフォールバックモデルに切りり替ええる。
第3層使用量集約。統一的な課金とクォータ。各リクエストのtoken消費、キャッシュヒット、応答時間をこの層で記録し、外部に統一的な使用量照会インターフェースを提供する。
第4層可観測性。ログ、分散トレーシング、エラーコードの収束。各リクエストにはtrace_idがあり、入口から出し口まで全链路を追跡できる。エラーコードはこの層で統一マッピングし、アラートルールもこの層でのみ設定する。
ビジネスコードは第1層のインターフェースだけを呼びび出しし、後の3層はビジネスコードにとって透過的だ。このようにする利点は——モデルを変えてもビジネスコードを変更する必要がなく、モデルを追加えしてもビジネスコードを変更する必要がなく、ルーティング戦略を調整してもビジネスコードを変更する必要がないことだ。ビジネスチームは「モデルを1つ呼びび出ししたい」ということだけを気にすればよく、残りはゲートウェイに任せればよい。
六、落としとし穴回避の注意点
ビジネスコードで各社のSDKを直し接importしないこと。一度ベンダーがインターフェースをアップグレードしたり、モデルを変えたりすると、変更範囲が大きく広がる。私たちはビジネスコードで直し接SDKを呼びび出ししていたチームを見たことがあり、後にモデルを変える際に30以上のファイルを変更し、1週間テストしてからリリースした。
接続層に2日余分に費やせば、後で2週間節約できる。この投資対効果は私たちのところで実証済みだ——ゲートウェイのリリース後、新しいモデルを追加えするにはゲートウェイ層にアダプタを1つ追加えするだけでよく、ビジネスコードはゼロ変更で、半日で接続とテストが完了する。
もう2つ小さな提案がある:1つはできるだけ早く使用量集約を行い、財務照合わせの時に計算が合わせわないと気づくまで待たないこと。もう1つはエラーコードマッピングテーブルを継続的に維持つし、新しいベンダーを接続する際の最初の作業としてエラーコードマッピングを補完することだ。
著者:孫浩然
公開日:2026年11月9日