はじめに

Generative AIアプリケーションの本番環境への導入が進む中、単なる「精度」だけでなく「信頼性」と「可観測性」が重大な課題となっています。特にLLMを扱う開発者にとって、APIコールのパフォーマンスやエラー原因を追跡することは不可欠ですが、チャットモデル（Chat Completion）の呼び出しでは、インフラ層のログだけでは不十分なケースが頻発します。

例えば、GoogleのGenAI SDKのような高機能なラッパーを使用する場合、内部処理の複雑さにより、本来追跡すべき重要なパラメータ（温度、システム指示、プロンプト設定など）がトレースデータから欠落する「サイレントリグレッション」が発生することがあります。本記事では、この種の可観測性のギャップを埋めるために必要な技術的視点と、実装時の設計判断について解説します。

チャットAPIの呼び出し構造と追跡の難しさ

従来の単発のテキスト生成（Completion）とは異なり、チャットモデルは「会話履歴」という状態を持ちます。多くの現代的なGenAI SDKでは、チャットの初期化とメッセージ送信が分離されています。

典型的なフローは以下のようになります：

  1. チャットの作成（Initialization）: chats.create() のようなメソッドで、モデル名、温度、最大トークン数、システム指示などの設定オブジェクトを保持したチャットインスタンスを作成します。この時点ではAPIへの通信は発生しません。
  2. メッセージの送信（Invocation）: chat.sendMessage() やストリーミングメソッドを用いて、実際にモデルに対してリクエストを送信します。ここで設定オブジェクトが適用されます。

この2段階のプロセスこそが、可観測性を確保する上で最大の障壁となります。以前の標準的な実装では、chats.create() の呼び出しをトリガーとしてトレーススパン（Span）を作成し、その際に渡された設定情報を属性として記録していました。

しかし、このアプローチには根本的な問題があります。chats.create() はローカルでのオブジェクト生成であり、実際のモデルとのインタラクションではありません。したがって、一部の堅牢な可観測性SDK（Sentryなど）は、リファクタリングの過程で「実際のAPIコールを伴わないこのステップ」をトレース対象から除外する判断を下すことがあります。

設定情報の欠落というサイレントバグ

もしチャットの作成ステップがトレースから除外されてしまうと、後続の sendMessage() スパンには何の問題もないように見えます。しかし、実際には重大な情報が失われています。

具体的には、以下のような重要なデバッグ情報が欠落します：

  • 推論パラメータ: temperature, top_p, top_k などのモデルの挙動を決定づける数値。
  • システム指示: AIの役割や振る舞いを定義するプロンプトの一部。
  • ツール定義: 利用可能な関数呼び出し（Function Calling）の設定。

開発者側からすると、sendMessage() のスパンには「どのモデルが使われたか」しか残りません。もし出力が期待外れだった場合、「なぜその挙動になったのか」を特定するために、当時の設定値を知る必要があります。これが欠落していると、本番環境でのバグ修正に数時間から数日を要する可能性があります。

この問題は、SDK内部のリファクタリング（例えば、不要なスパンの削除）によって引き起こされることが多く、ログ出力が変わらないため発見が遅れがちです。これを「サイレントリグレッション」と呼びます。

解決策：設定の伝播とマージ戦略

この課題を解決するには、チャット作成時に渡された設定情報を、後続の各メッセージ送信スパンに正しく伝播させる必要があります。可観測性SDKやカスタムインスツルメンテーションコードにおいて、以下の設計判断が求められます。

1. 設定のキャプチャと保持

チャットインスタンスが作成されるとき、渡された引数（モデル名、構成オブジェクト）を何らかの方法で保存する必要があります。多くのSDKは内部でプロキシオブジェクトを使用してメソッドをフックしていますが、この際、元の引数を破棄せず、チャットオブジェクトの内部状態として保持します。

実装のポイント：

  • chats.create() の戻り値であるチャットオブジェクトが、生成時の設定を参照できるようにする。
  • プロキシ層で引数をコピーし、永続化された状態として管理する。

2. スパン作成時の属性付与ロジック

実際に sendMessage() が呼ばれた際、新しいトレーススパンを作成して属性を設定する段階で、チャットオブジェクトから設定情報を取得します。ここで重要なのは、「デフォルト値」と「リクエスト固有の値」の区別です。

多くのGenAI SDKでは、以下のような優先順位で設定が解決されます：

  1. チャット作成時に指定されたデフォルト設定
  2. 個別のメッセージ送信時に上書きされた設定（如果有る場合）

可観測性データとしては、最終的にモデルに適用される実際の設定を記録すべきです。つまり、チャット作成時のデフォルト値と、今回の呼び出しで指定された値をマージした結果を属性として付与します。

3. コード実装のパターン（概念的）

以下の擬似コードは、このマージロジックがどのように機能するかを示しています。実際のSDK実装では、内部のヘルパー関数を通じて行われます。

// チャット作成時の内部処理（簡略化）
function createChat(model, config) {
  // チャットオブジェクトを作成し、デフォルト設定として保存
  const chatInstance = new ChatProxy(model, config);
  return chatInstance;
}

// メッセージ送信時のトレース処理
function sendMessage(chatInstance, messageParams) {
  // デフォルト設定を取得
  const defaultConfig = chatInstance.getConfig();
  
  // リクエスト固有の設定があればマージ（上書き）
  // ※ SDKの仕様により、params.config ?? chat.config のように解決される
  const finalConfig = mergeConfigs(defaultConfig, messageParams?.config);

  // トレーススパンを作成し、最終的な設定を属性として記録
  const span = tracer.startSpan('gen_ai.client.message');
  span.setAttributes({
    'gen_ai.request.model': chatInstance.getModel(),
    'gen_ai.request.temperature': finalConfig.temperature,
    'gen_ai.request.max_tokens': finalConfig.maxTokens,
    'gen_ai.system_instructions': finalConfig.systemInstruction, // システム指示も記録
    // 他のパラメータも同様に...
  });

  // API呼び出し実行
  return executeApiCall(chatInstance, messageParams);
}

実務での落とし穴と対策

この仕組みを実装、またはデバッグする際によく遭遇する問題点と、その対策をまとめます。

1. 巨大なプロンプトやシステム指示のサイズ制限

システム指示や長いコンテキストウィンドウの設定値をそのまま属性として記録すると、トレースデータのサイズが肥大化し、バックエンド（Jaeger, Datadog, Sentryなど）のストレージコストを増加させる可能性があります。

対策:

  • システム指示などのテキストデータは、ハッシュ値や長さのみを記録するオプションを提供する。
  • 可観測性ダッシュボードでは概要を確認し、詳細なプロンプト内容の確認が必要な場合は、別のログストレージやデバッグモードに切り替える設計にする。

2. ストリーミングレスポンスとの同期

ストリーミングAPIを使用する場合、レスポンスが断片化されて届きます。この際、トレーススパンの終了タイミングと属性の固定タイミングをどうするか悩みます。

対策:

  • リクエスト時点（sendMessage 呼び出し時）に設定情報を確定させておくのが安全です。レスポンス内容（出力トークンなど）は、ストリーミングが完了した後や、最終的なチャンク処理時に記録するのが一般的ですが、デバッグ用の「入力設定」は最初から固定できるため、リクエスト時の記録が有効です。

3. SDKのバージョンアップによる挙動変化

前述の通り、SDK内部のリファクタリングによってトレースの仕組みが変わるリスクがあります。

対策:

  • 自動計測（Auto-instrumentation）に依存しすぎず、定期的に重要なワークフローでのトレースデータが正しく出力されているか確認するテストコード（E2Eテスト）を持つ。
  • SentryやDatadogのような可観測性プラットフォームのダッシュボードで、「温度」や「システム指示」の属性が存在するかを定期的な監視アラートにする。

設計判断の比較：Auto-instrumentation vs Manual Instrumentation

この課題に対応する際、開発者は「SDK任せ（Auto）」か「自前実装（Manual）」かの選択を迫られます。

手法 メリット デメリット
Auto-instrumentation
(SDK依存)		 コード変更が不要。導入コストが低い。 SDKのバグや仕様変動に左右される。詳細なカスタマイズが困難。
Manual Instrumentation
(自前実装)		 設定情報のマージロジックを完全に制御可能。SDKの内部変更の影響を受けにくい。 実装コストが高い。メンテナンス負荷が増加する。

中小企業やスタートアップでは、リソースの制約からAuto-instrumentationを選定しがちです。しかし、GenAIアプリケーションのコアロジックがLLM呼び出しである場合、その可観測性はアプリケーションの品質に直結します。SDK側で設定情報の欠落が発生した場合に備え、自前のラッパー関数を通じて明示的に属性を付与するハイブリッドなアプローチも検討すべきです。

まとめ

Generative AIの開発において、チャットモデルの使用は標準的なAPI呼び出しとは異なる複雑さを伴います。特に「設定（Config）」と「実行（Invocation）」が分離されているアーキテクチャでは、可観測性ツールが正しく設定情報を追跡できないリスクがあります。

本記事で解説した通り、この問題はSDK内部のリファクタリングによっても発生しうるサイレントバグです。開発チームは以下の点を意識して設計・運用を行う必要があります：

  1. チャット作成時の設定が、後続のトレーススパンに正しく伝播しているかを確認するテストケースを持つ。
  2. プロダクト環境において、温度やシステム指示などの重要な属性が欠落していないかを定期的に監視する。
  3. SDKの仕様変動に依存しすぎないよう、重要なワークフローでは自前のインスツルメンテーション層を設けることも視野に入れる。

信頼性の高いAIアプリケーションを構築するためには、単にモデルの性能だけでなく、その挙動を可視化する仕組みの堅牢さこそが勝負を分けます。設定情報の追跡という地味だが重要な課題を軽視せず、適切な対策を講じてください。

参考

本記事は海外の技術トレンド「Bug Smash: restoring dropped Gemini chat config in Sentry's JavaScript SDK」（DEV）で話題のテーマをもとに、両儀システムソリューションズが独自に解説したものです。

記事一覧に戻る