可観測性

Spring AI は、Spring エコシステムの可観測性機能に基づいて構築され、AI 関連の操作に関するインサイトを提供します。Spring AI は、そのコアコンポーネントである ChatClient (Advisor を含む)、ChatModel、EmbeddingModel、ImageModel、VectorStore のメトリクスとトレース機能を提供します。

低いカーディナリティキーはメトリクスとトレースに追加されますが、高いカーディナリティキーはトレースにのみ追加されます。

1.0.0-RC1 重大な変更

次の構成プロパティは、目的をより適切に反映するために名前が変更されました。

  • spring.ai.chat.client.observations.include-prompt → spring.ai.chat.client.observations.log-prompt

  • spring.ai.chat.observations.include-prompt → spring.ai.chat.observations.log-prompt

  • spring.ai.chat.observations.include-completion → spring.ai.chat.observations.log-completion

  • spring.ai.image.observations.include-prompt → spring.ai.image.observations.log-prompt

  • spring.ai.vectorstore.observations.include-query-response → spring.ai.vectorstore.observations.log-query-response

チャットクライアント

spring.ai.chat.client 観測は、ChatClient call() または stream() 操作が呼び出されたときに記録されます。呼び出しの実行に費やされた時間を測定し、関連するトレース情報を伝播します。

表 1: 低カーディナリティキー
名前 説明

gen_ai.operation.name

常に framework です。

gen_ai.system

常に spring_ai です。

spring.ai.chat.client.stream

チャットモデルのレスポンスはストリームですか - true or false

spring.ai.kind

Spring AI のフレームワーク API の種類: chat_client。

表 2: 高カーディナリティキー
名前 説明

gen_ai.prompt

チャットクライアント経由で送信されるプロンプトの内容。オプション。

spring.ai.chat.client.advisor.params (非推奨)

アドバイザーパラメーターのマップ。会話 ID が spring.ai.chat.client.conversation.id に含まれるようになりました。

spring.ai.chat.client.advisors

構成されたチャットクライアントアドバイザーのリスト。

spring.ai.chat.client.conversation.id

チャットメモリを使用する場合の会話の識別子。

spring.ai.chat.client.system.params (非推奨)

チャットクライアントのシステムパラメーター。オプション。gen_ai.prompt に置き換えられました。

spring.ai.chat.client.system.text (非推奨)

チャットクライアントのシステムテキスト。オプション。gen_ai.prompt に置き換えられました。

spring.ai.chat.client.tool.function.names (非推奨)

有効なツール機能名。spring.ai.chat.client.tool.names に置き換えられました。

spring.ai.chat.client.tool.function.callbacks (非推奨)

構成されたチャットクライアント関数のコールバックのリスト。spring.ai.chat.client.tool.names に置き換えられました。

spring.ai.chat.client.tool.names

チャットクライアントに渡されるツールの名前。

spring.ai.chat.client.user.params (非推奨)

チャットクライアントのユーザーパラメーター。オプション。gen_ai.prompt に置き換えられました。

spring.ai.chat.client.user.text (非推奨)

チャットクライアントのユーザーテキスト。オプション。gen_ai.prompt に置き換えられました。

プロンプトコンテンツ

ChatClient プロンプトの内容は通常大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、デバッグとトラブルシューティングに役立つプロンプトコンテンツのログ記録をサポートしています。

プロパティ 説明 デフォルト

spring.ai.chat.client.observations.log-prompt

チャットクライアントのプロンプトの内容をログに記録するかどうか。

false

チャットクライアントのプロンプトコンテンツのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

入力データ (非推奨)

spring.ai.chat.client.observations.include-input プロパティは非推奨となり、spring.ai.chat.client.observations.log-prompt に置き換えられました。プロンプトコンテンツを参照してください。

ChatClient 入力データは通常大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、デバッグとトラブルシューティングに役立つ入力データのログ記録をサポートしています。

プロパティ 説明 デフォルト

spring.ai.chat.client.observations.include-input

入力コンテンツを観測に含めるかどうか。

false

入力内容を観測に含めることを有効にすると、機密情報や個人情報が公開されるリスクがあります。ご注意ください。

チャットクライアントアドバイザー

spring.ai.advisor 観測は、アドバイザーの実行時に記録されます。アドバイザー内で費やされた時間（内部アドバイザーで費やされた時間を含む）を測定し、関連するトレース情報を伝播します。

表 3: 低カーディナリティキー
名前 説明

gen_ai.operation.name

常に framework です。

gen_ai.system

常に spring_ai です。

spring.ai.advisor.type (非推奨)

アドバイザーがリクエスト処理においてロジックを適用する場所は、BEFORE、AFTER、AROUND のいずれかです。すべてのアドバイザーは常に同じ型であるため、この区別は適用されません。

spring.ai.kind

Spring AI のフレームワーク API の種類: advisor。

表 4: 高カーディナリティキー
名前 説明

spring.ai.advisor.name

アドバイザーの名前。

spring.ai.advisor.order

アドバイザーチェーンのアドバイザーオーダー。

チャットモデル

可観測性機能は現在、次の AI モデルプロバイダーの ChatModel 実装でのみサポートされています: Anthropic、Azure、OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhiu AI。追加の AI モデルプロバイダーは、将来のリリースでサポートされる予定です。

gen_ai.client.operation 観測は、ChatModel call または stream メソッドを呼び出すときに記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

gen_ai.client.token.usage メトリクスは、単一のモデル呼び出しで使用される入力トークンと出力トークンの数を測定します。
表 5: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

クライアントインストルメンテーションによって識別されるモデルプロバイダー。

gen_ai.request.model

リクエストが行われているモデルの名前。

gen_ai.response.model

レスポンスを生成したモデルの名前。

表 6: 高カーディナリティキー
名前 説明

gen_ai.request.frequency_penalty

モデルリクエストの頻度ペナルティ設定。

gen_ai.request.max_tokens

モデルがリクエストに対して生成するトークンの最大数。

gen_ai.request.presence_penalty

モデルリクエストのプレゼンスペナルティ設定。

gen_ai.request.stop_sequences

モデルがそれ以上のトークンの生成を停止するために使用するシーケンスのリスト。

gen_ai.request.temperature

モデルリクエストの温度設定。

gen_ai.request.top_k

モデルリクエストの top_k サンプリング設定。

gen_ai.request.top_p

モデルリクエストの top_p サンプリング設定。

gen_ai.response.finish_reasons

受信した各世代に対応する、モデルがトークンの生成を停止した理由。

gen_ai.response.id

AI レスポンスの一意の識別子。

gen_ai.usage.input_tokens

モデル入力 (プロンプト) で使用されるトークンの数。

gen_ai.usage.output_tokens

モデル出力（完了）で使用されるトークンの数。

gen_ai.usage.total_tokens

モデル交換で使用されるトークンの合計数。

gen_ai.prompt

モデルに送信される完全なプロンプト。オプション。

gen_ai.completion

モデルから受信した完全なレスポンス。オプション。

spring.ai.model.request.tool.names

リクエストでモデルに提供されるツール定義のリスト。

ユーザートークンを測定する場合、前の表には観測トレースに存在する値がリストされています。ChatModel によって提供されるメトリクス名 gen_ai.client.token.usage を使用します。

チャットプロンプトと完了データ

チャットプロンプトと完了データは通常サイズが大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、チャットプロンプトと完了データのログ記録をサポートしており、トラブルシューティングに役立ちます。トレースが利用可能な場合、ログにはトレース情報が含まれるため、相関関係の精度が向上します。

プロパティ 説明 デフォルト

spring.ai.chat.observations.log-prompt

プロンプトの内容をログに記録します。true または false

false

spring.ai.chat.observations.log-completion

完了内容をログに記録します。true または false

false

spring.ai.chat.observations.include-error-logging

観測にエラーログを含めます。true または false

false

チャットプロンプトと完了データのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

ツール呼び出し

spring.ai.tool 観測は、チャットモデルのインタラクションのコンテキストでツール呼び出しを実行した際に記録されます。呼び出し完了までに費やされた時間を測定し、関連するトレース情報を伝播します。

表 7: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行中の操作の名前。常に framework です。

gen_ai.system

操作を担当するプロバイダー。常に spring_ai です。

spring.ai.kind

Spring AI が実行する操作の種類。常に tool_call です。

spring.ai.tool.definition.name

ツールの名前。

表 8: 高カーディナリティキー

名前

説明

spring.ai.tool.definition.description

ツールの説明。

spring.ai.tool.definition.schema

ツールを呼び出すために使用されるパラメーターのスキーマ。

spring.ai.tool.call.arguments

ツール呼び出しへの入力引数。(有効になっている場合のみ)

spring.ai.tool.call.result

ツールを呼び出すために使用されるパラメーターのスキーマ。(有効になっている場合のみ)

ツール呼び出し引数と結果データ

入力引数とツール呼び出しの結果は、潜在的に機密情報である可能性があるため、デフォルトではエクスポートされません。

Spring AI は、ツール呼び出し引数と結果データをスパン属性としてエクスポートすることをサポートしています。

プロパティ 説明 デフォルト

spring.ai.tools.observations.include-content

観測にツール呼び出しコンテンツを含めます。true または false

false

ツール呼び出しの引数と結果を観測に含めるように設定した場合、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

EmbeddingModel

可観測性機能は現在、Azure、OpenAI、Mistral AI、Ollama、OpenAI の AI モデルプロバイダーの EmbeddingModel 実装でのみサポートされています。追加の AI モデルプロバイダーは、将来のリリースでサポートされる予定です。

gen_ai.client.operation の観測は、埋め込みモデルメソッド呼び出しに記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

gen_ai.client.token.usage メトリクスは、単一のモデル呼び出しで使用される入力トークンと出力トークンの数を測定します。
表 9: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

クライアントインストルメンテーションによって識別されるモデルプロバイダー。

gen_ai.request.model

リクエストが行われているモデルの名前。

gen_ai.response.model

レスポンスを生成したモデルの名前。

表 10: 高カーディナリティキー
名前 説明

gen_ai.request.embedding.dimensions

結果として得られる出力埋め込みの次元数。

gen_ai.usage.input_tokens

モデル入力で使用されるトークンの数。

gen_ai.usage.total_tokens

モデル交換で使用されるトークンの合計数。

ユーザートークンを測定する場合、前の表には観測トレースに存在する値がリストされています。EmbeddingModel によって提供されるメトリクス名 gen_ai.client.token.usage を使用します。

イメージモデル

可観測性機能は現在、次の AI モデルプロバイダーの ImageModel 実装でのみサポートされています: OpenAI。追加の AI モデルプロバイダーは、将来のリリースでサポートされる予定です。

gen_ai.client.operation の観測は、イメージモデルメソッドの呼び出し時に記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

gen_ai.client.token.usage メトリクスは、単一のモデル呼び出しで使用される入力トークンと出力トークンの数を測定します。
表 11: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

クライアントインストルメンテーションによって識別されるモデルプロバイダー。

gen_ai.request.model

リクエストが行われているモデルの名前。

表 12: 高カーディナリティキー
名前 説明

gen_ai.request.image.response_format

生成されたイメージが返される形式。

gen_ai.request.image.size

生成するイメージのサイズ。

gen_ai.request.image.style

生成するイメージのスタイル。

gen_ai.response.id

AI レスポンスの一意の識別子。

gen_ai.response.model

レスポンスを生成したモデルの名前。

gen_ai.usage.input_tokens

モデル入力 (プロンプト) で使用されるトークンの数。

gen_ai.usage.output_tokens

モデル出力（生成）で使用されるトークンの数。

gen_ai.usage.total_tokens

モデル交換で使用されるトークンの合計数。

gen_ai.prompt

モデルに送信される完全なプロンプト。オプション。

ユーザートークンを測定する場合、前の表には観測トレースに存在する値がリストされています。ImageModel によって提供されるメトリクス名 gen_ai.client.token.usage を使用します。

イメージプロンプトデータ

イメージプロンプトデータは通常サイズが大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、トラブルシューティングに役立つイメージプロンプトデータのログ記録をサポートしています。トレースが利用可能な場合、ログにはトレース情報が含まれるため、相関関係の精度が向上します。

プロパティ 説明 デフォルト

spring.ai.image.observations.log-prompt

イメージプロンプトの内容をログに記録します。true または false

false

イメージプロンプトデータのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

ベクトルストア

Spring AI のすべてのベクトルストア実装は、Micrometer を通じてメトリクスと分散トレースデータを提供するようにインストルメント化されています。

db.vector.client.operation の観測は、ベクトルストアとやり取りするときに記録されます。query、add、remove 操作に費やされた時間を測定し、関連するトレース情報を伝播します。

表 13: 低カーディナリティキー
名前 説明

db.operation.name

実行される操作またはコマンドの名前。add、delete、または query のいずれかです。

db.system

クライアントインストルメンテーションによって識別されるデータベース管理システム (DBMS) 製品。pg_vector、azure、cassandra、chroma、elasticsearch、milvus、neo4j、opensearch、qdrant、redis、typesense、weaviate、pinecone、oracle、mongodb、gemfire、hana、simple のいずれか。

spring.ai.kind

Spring AI のフレームワーク API の種類: vector_store。

表 14: 高カーディナリティキー
名前 説明

db.collection.name

データベース内のコレクション (テーブル、コンテナー) の名前。

db.namespace

サーバーアドレスとポート内で完全修飾されたデータベースの名前。

db.record.id

存在する場合はレコード識別子。

db.search.similarity_metric

類似性検索で使用されるメトリクス。

db.vector.dimension_count

ベクトルの次元。

db.vector.field_name

ベクトルの名前フィールド (フィールド名など)。

db.vector.query.content

実行中の検索クエリの内容。

db.vector.query.filter

検索クエリで使用されるメタデータフィルター。

db.vector.query.response.documents

類似検索クエリから返されたドキュメント。オプション。

db.vector.query.similarity_threshold

すべての検索スコアを受け入れる類似度しきい値。しきい値が 0.0 の場合、すべての類似度が受け入れられるか、類似度しきい値フィルタリングが無効になります。しきい値が 1.0 の場合、完全一致が必要です。

db.vector.query.top_k

クエリによって返される上位 k 個の最も類似したベクトル。

レスポンスデータ

ベクトル検索レスポンスデータは通常大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、トラブルシューティングに役立つベクトル検索レスポンスデータのログ記録をサポートしています。トレースが利用可能な場合、ログにはトレース情報が含まれるため、相関関係の精度が向上します。

プロパティ 説明 デフォルト

spring.ai.vectorstore.observations.log-query-response

ベクトルストアクエリレスポンスの内容をログに記録します。true または false

false

ベクトル検索レスポンスデータのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。