可観測性

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

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

チャットクライアント

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: 高カーディナリティキー
名前 説明

spring.ai.chat.client.advisor.params

アドバイザーパラメーターのマップ。

spring.ai.chat.client.advisors

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

spring.ai.chat.client.system.params

チャットクライアントのシステムパラメーター。オプション。

spring.ai.chat.client.system.text

チャットクライアントのシステムテキスト。オプション。

spring.ai.chat.client.tool.function.names

有効なツール機能名。

spring.ai.chat.client.tool.function.callbacks

構成されたチャットクライアント関数コールバックのリスト。

spring.ai.chat.client.user.params

チャットクライアントのユーザーパラメーター。オプション。

spring.ai.chat.client.user.text

チャットクライアントユーザーテキスト。オプション。

入力データ

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

アドバイザーがリクエスト処理でロジックを適用する場合は、BEFOREAFTER、または 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

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

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

gen_ai.content.prompt

チャットプロンプトの内容を含むイベント。オプション。

gen_ai.content.completion

チャット補完の内容を含むイベント。オプション。

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

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

Spring AI は、OpenTelemetry トレースバックエンドを使用する場合、チャットプロンプトと完了データをスパンイベントとしてエクスポートすることをサポートしますが、OpenZipkin トレースバックエンドを使用する場合、データはスパン属性としてエクスポートされます。

さらに、Spring AI はチャットプロンプトと完了データのログ記録をサポートしており、シナリオのトラブルシューティングに役立ちます。

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

spring.ai.chat.observations.include-prompt

観察にプロンプトの内容を含めます。true または false

false

spring.ai.chat.observations.include-completion

完了コンテンツを観察に含めます。true または false

false

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

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

false

チャットプロンプトと完了データを観察に含めることを有効にすると、機密情報や個人情報が公開されるリスクがあります。ご注意ください。

EmbeddingModel

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

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

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

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

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

gen_ai.request.model

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

gen_ai.response.model

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

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

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 メトリクスは、単一のモデル呼び出しで使用される入力トークンと出力トークンの数を測定します。
表 10: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

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

gen_ai.request.model

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

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

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 を使用します。
表 12: イベント
名前 説明

gen_ai.content.prompt

イメージプロンプトのコンテンツを含むイベント。オプション。

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

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

Spring AI は、OpenTelemetry トレースバックエンドを使用する場合、イメージプロンプトデータをスパンイベントとしてエクスポートすることをサポートしますが、OpenZipkin トレースバックエンドを使用する場合、データはスパン属性としてエクスポートされます。

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

spring.ai.image.observations.include-prompt

true or false

false

観察結果にイメージプロンプトデータを含めるように設定した場合、機密情報や個人情報が公開されるリスクがあります。ご注意ください。

ベクトルストア

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

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

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

db.operation.name

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

db.system

クライアントインストルメンテーションによって識別されるデータベース管理システム (DBMS) 製品。pg_vectorazurecassandrachromaelasticsearchmilvusneo4jopensearchqdrantredistypesenseweaviatepineconeoraclemongodbgemfirehanasimple のいずれか。

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 個の最も類似したベクトル。

表 15: イベント
名前 説明

db.vector.content.query.response

ベクトル検索レスポンスデータを含むイベント。オプション。

レスポンスデータ

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

Spring AI は、OpenTelemetry トレースバックエンドを使用する場合、ベクトル検索レスポンスデータをスパンイベントとしてエクスポートすることをサポートしますが、OpenZipkin トレースバックエンドを使用する場合、データはスパン属性としてエクスポートされます。

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

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

true or false

false

観測にベクトル検索レスポンスデータを含めるように設定した場合、機密情報や個人情報が公開されるリスクがあります。ご注意ください。