可觀測性

Spring AI 構建於 Spring 生態系統中的可觀測性功能之上，以提供對 AI 相關操作的洞察。

啟用可觀測性需要 spring-boot-actuator 模組。將 Spring Boot Actuator 依賴項新增到您專案的 Maven pom.xml 構建檔案中

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

或新增到您的 Gradle build.gradle 構建檔案中。

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

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

聊天客戶端

當呼叫 ChatClient 的 call() 或 stream() 操作時，會記錄 spring.ai.chat.client 觀測。它們測量執行呼叫所花費的時間並傳播相關的跟蹤資訊。

表 1. 低基數鍵
名稱 描述

gen_ai.operation.name

始終為 framework。

gen_ai.system

始終為 spring_ai。

spring.ai.chat.client.stream

聊天模型響應是否為流 - true 或 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

是否記錄聊天客戶端提示內容。

假

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

是否記錄聊天客戶端完成內容。

假
如果您啟用聊天客戶端提示和完成資料的記錄，存在暴露敏感或私人資訊的風險。請務必小心！

輸入資料 (已棄用)

spring.ai.chat.client.observations.include-input 屬性已棄用，由 spring.ai.chat.client.observations.log-prompt 取代。請參閱 提示內容。

ChatClient 輸入資料通常很大，可能包含敏感資訊。因此，預設情況下不匯出。

Spring AI 支援記錄輸入資料，以幫助除錯和故障排除。

財產 描述 預設值

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

是否在觀測中包含輸入內容。

假
如果您在觀測中啟用輸入內容的包含，存在暴露敏感或私人資訊的風險。請務必小心！

聊天客戶端顧問

當執行顧問時，會記錄 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、Zhipu AI。未來的版本將支援更多的 AI 模型提供商。

當呼叫 ChatModel 的 call 或 stream 方法時，會記錄 gen_ai.client.operation 觀測。它們測量方法完成所花費的時間並傳播相關的跟蹤資訊。

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

假

spring.ai.chat.observations.log-completion

記錄完成內容。true 或 false

假

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

在觀測中包含錯誤日誌記錄。true 或 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 支援將工具呼叫引數和結果資料匯出為 span 屬性。

財產 描述 預設值

spring.ai.tools.observations.include-content

在觀測中包含工具呼叫內容。true 或 false

假
如果您在觀測中啟用工具呼叫引數和結果的包含，存在暴露敏感或私人資訊的風險。請務必小心！

嵌入模型

目前僅支援以下 AI 模型提供商的 EmbeddingModel 實現的可觀測性功能：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。未來的版本將支援更多的 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

假
如果您啟用影像提示資料的記錄，存在暴露敏感或私人資訊的風險。請務必小心！

向量儲存

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

查詢返回的 top-k 最相似向量。

響應資料

向量搜尋響應資料通常很大，可能包含敏感資訊。因此，預設情況下不匯出。

Spring AI 支援記錄向量搜尋響應資料，這對於故障排除場景很有用。當跟蹤可用時，日誌將包含跟蹤資訊，以便更好地進行關聯。

財產 描述 預設值

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

記錄向量儲存查詢響應內容。true 或 false

假
如果您啟用向量搜尋響應資料的記錄，存在暴露敏感或私人資訊的風險。請務必小心！

更多指標參考

本節記錄了 Spring AI 元件在 Prometheus 中顯示的指標。

指標命名約定

Spring AI 使用 Micrometer。基本指標名稱使用點（例如，gen_ai.client.operation），Prometheus 將其匯出為下劃線和標準字尾

  • 計時器 → <base>_seconds_count、<base>_seconds_sum、<base>_seconds_max，以及（如果支援）<base>_active_count

  • 計數器 → <base>_total (單調)

以下顯示了基本指標名稱如何擴充套件為 Prometheus 時間序列。

基本指標名稱 匯出的時間序列

gen_ai.client.operation

gen_ai_client_operation_seconds_count
gen_ai_client_operation_seconds_sum
gen_ai_client_operation_seconds_max
gen_ai_client_operation_active_count

db.vector.client.operation

db_vector_client_operation_seconds_count
db_vector_client_operation_seconds_sum
db_vector_client_operation_seconds_max
db_vector_client_operation_active_count

參考資料

聊天客戶端指標

指標名稱 型別 單位 描述

gen_ai_chat_client_operation_seconds_sum

計時器

秒

ChatClient 操作（call/stream）中花費的總時間

gen_ai_chat_client_operation_seconds_count

計數器

計數

完成的 ChatClient 運算元量

gen_ai_chat_client_operation_seconds_max

量規

秒

ChatClient 操作的最大觀測持續時間

gen_ai_chat_client_operation_active_count

量規

計數

當前正在進行的 ChatClient 運算元量

活動與完成: active_count 顯示正在進行的呼叫；_seconds 系列僅反映已完成的呼叫。

聊天模型指標（模型提供商執行）

指標名稱 型別 單位 描述

gen_ai_client_operation_seconds_sum

計時器

秒

執行聊天模型操作的總時間

gen_ai_client_operation_seconds_count

計數器

計數

完成的聊天模型運算元量

gen_ai_client_operation_seconds_max

量規

秒

聊天模型操作的最大觀測持續時間

gen_ai_client_operation_active_count

量規

計數

當前正在進行的聊天模型運算元量

令牌使用

指標名稱 型別 單位 描述

gen_ai_client_token_usage_total

計數器

令牌

消耗的總令牌數，按令牌型別標記

標籤

標籤 含義

gen_ai_token_type=input

傳送到模型的提示令牌

gen_ai_token_type=output

模型返回的完成令牌

gen_ai_token_type=total

輸入 + 輸出

向量儲存指標

指標名稱 型別 單位 描述

db_vector_client_operation_seconds_sum

計時器

秒

向量儲存操作（add/delete/query）中花費的總時間

db_vector_client_operation_seconds_count

計數器

計數

完成的向量儲存運算元量

db_vector_client_operation_seconds_max

量規

秒

向量儲存操作的最大觀測持續時間

db_vector_client_operation_active_count

量規

計數

當前正在進行的向量儲存運算元量

標籤

標籤 含義

db_operation_name

操作型別（add、delete、query）

db_system

向量資料庫/提供商（redis、chroma、pgvector 等）

spring_ai_kind

vector_store

理解活動與完成

  • 活動 (*_active_count) — 正在進行的操作的瞬時量規（併發/負載）。

  • 已完成 (*_seconds_sum|count|max) — 已完成操作的統計資料

  • _seconds_sum / _seconds_count → 平均延遲

  • _seconds_max → 自上次抓取以來的最高水位線（受登錄檔行為影響）

© . This site is unofficial and not affiliated with VMware.