先月、異動してきたばかりの同僚とスマートカスタマーサポートのプロトタイプを作りました。要件はシンプルで、ユーザーが質問し、モデルが回答し、少しコンテキスト記憶があり、ストリーミングでタイピング表示できるというもの。2日で終わると思っていたら、彼はAPI Keyのハードコード、リトライロジック、ストリーミング接続でそれぞれ一度ずつつまずきました。その一連の流れをこの記事にまとめたので、新人指導のメモとして読んでください。
ステップ1：まず要件を分解し、それからモデルを選ぶ
いきなりコードを書き始めないでください。スマートカスタマーサポートの能力要件は大きく3つに分かれます：意図認識、知識Q&A、マルチターンの雑談。意図認識は速くて安くなければならず、DeepSeek-V3や通義千問APIで十分です。知識Q&Aは自社の私有ドキュメントが関わるため、RAGを通す必要があり、モデルには長いコンテキストの理解が求められます。マルチターンの雑談はトーンへの要求が高く、Claude 4 SonnetやGPT-4oの方が安定しています。
私のやり方は、まず汎用モデルで一連の流れを通し、その後項目ごとに置き換えていくというものです。硅碳相変のマルチモデルルーティングはこの時に楽で、同じコードのままモデル名を変えるだけで効果を比較でき、認証を変更する必要がありません。大規模モデルAPIの選定は最強のものを選ぶのではなく、タスクに最も適合するものを選ぶのです。
ステップ2：Key管理、コードに書かないこと
Keyをソースコードにハードコードするのは、新人が最もよくやる間違いです。一度gitにコミットしてしまえば、公開したのと同じです。正しい方法は環境変数と設定ファイルの階層化です：ローカルでは.env、テストと本番では設定センターやシークレット管理サービスを使います。
マルチ環境の分離で覚えておくべき3点：開発、テスト、本番で異なるKeyを使う。各Keyに独立した额度上限を設定する。本番Keyはサーバーサイドのみに渡し、フロントエンドは絶対に取得できないようにする。私たちのプロジェクトでは硅碳相変を使い、1つのKeyでGPT-4o、Claude、DeepSeek、通義、文心、豆包などの主要モデルを呼び出せるため、複数の認証を維持する手間が省け、マルチ環境のKey切り替えも変数を変えるだけです。
ステップ3：呼び出しのカプセル化とエラーリトライ
SDKを裸で呼び出すコードは保守できません。1層カプセル化し、タイムアウト、レート制限、リトライを統一的に処理します。考え方はこうです：モデル呼び出しを1つの関数に包み、パラメータはmessagesとモデル名、内部で3種類のエラーを捕捉します——ネットワークタイムアウト、429レート制限、5xxサーバーエラー。
リトライ戦略は指数バックオフを使い、1回目は1秒待ち、2回目は2秒、3回目は4秒、最大3回まで。429は特別に処理し、返されるretry-afterヘッダーを見ます。すべてのエラーに対してリトライしないでください。パラメータエラーは100回リトライしても無駄です。モデルゲートウェイの価値はこの層にあり、リトライ、フォールバック、ログを1か所に集約し、ビジネスコードは結果を受け取るだけです。
落とし穴の注意：リトライは冪等でなければなりません。呼び出しに副作用がある場合（例えばデータベースへの書き込み）、リトライ前に前回が本当に失敗したか確認してください。
ステップ4：ストリーミング出力とフロントエンド接続
カスタマーサポート体験の核心は「タイプライター効果」です。サーバー側はSSEでtokenを一块ずつフロントエンドにプッシュし、フロントエンドはEventSourceまたはfetchのReadableStreamで受信します。
バックエンドの要点：stream=Trueを設定し、返されるdeltaを块ごとに解析し、[DONE]で終了します。フロントエンドの要点：1文字受信するごとにsetStateしないでください。20〜50ミリ秒ためてバッチレンダリングしないと、ページがスライドショーのようにカクカクになります。
もう1つの落とし穴は、ストリーミング中にユーザーがページを閉じる可能性があることです。サーバー側は接続切断イベントを監視し、タイムリーに上流リクエストをキャンセルしないと、tokenを無駄に燃やしてしまいます。従量課金では、このような無駄が積み重なります。
ステップ5：コスト監視とアラート
リリース前に必ず計測を仕込みます。毎回の呼び出しで記録するもの：モデル名、入力token数、出力token数、所要時間、リトライの有無。これらのデータを1週間ためて、初めてお金がどこに使われているかがわかります。
アラートは2本の線を設定します：1日のコストがしきい値を超えたら警告、1回の呼び出しのtokenが異常なら警告。ある時、ユーザーが文書全体を貼り付けてきて、1回の入力が数万tokenになりました。アラートがなければ、月末の請求書は見るに堪えないものになっていたでしょう。
コスト削減の経験：意図認識のような高頻度で難易度の低いタスクは、安価な国産モデルに切り替えると、コストを一截下げられます。バッチ調達とグリーンエネルギー調度が、硅碳相変のようなアグリゲーションプラットフォームの価格が公式直購入より安い理由です。私たちが比較したところ、高頻度呼び出しのシナリオでは差が顕著でした。
一言でまとめると：スマートカスタマーサポートのプロトタイプの難点はモデルではなく、エンジニアリングの細部にあります。Keyをきちんと管理し、リトライを正しく書き、ストリーミングを安定して接続し、コストを監視すれば、あとはpromptを調整するだけです。マルチモデルの統一接続とモデルルーティングの実装を深く知りたい方は、大規模モデルAPIゲートウェイ这条線に沿って読み進めてください。