可觀測性

Spring AI 基於 Spring 生態系統中的可觀測性特性，為 AI 相關操作提供洞察。Spring AI 為其核心元件提供了指標和追蹤能力：ChatClient（包括 Advisor）、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。

低基數鍵將新增到指標和追蹤中，而高基數鍵將僅新增到追蹤中。

聊天客戶端

當呼叫 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

透過聊天客戶端傳送的 Prompt 內容。可選。

spring.ai.chat.client.advisor.params (已棄用)

顧問引數 Map。對話 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 取代。

Prompt 內容

ChatClient 的 Prompt 內容通常很大，並可能包含敏感資訊。因此，預設情況下不匯出它。

Spring AI 支援將 Prompt 內容匯出為跨所有追蹤後端 Span 屬性/事件。

屬性 描述 預設值

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

是否在可觀測項中包含聊天客戶端 Prompt 內容。

false
如果啟用在可觀測項中包含聊天客戶端 Prompt 內容，則存在暴露敏感或私人資訊的風險。請小心謹慎！

輸入資料 (已棄用)

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

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

Spring AI 支援將輸入資料匯出為跨所有追蹤後端 Span 屬性/事件。

屬性 描述 預設值

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 模型提供商將在未來版本中支援。

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

gen_ai.client.token.usage 指標測量單次模型呼叫使用的輸入和輸出 Token 數量。
表 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

模型為請求生成的最大 Token 數量。

gen_ai.request.presence_penalty

模型請求的存在懲罰設定。

gen_ai.request.stop_sequences

模型將用於停止生成進一步 Token 的序列列表。

gen_ai.request.temperature

模型請求的溫度設定。

gen_ai.request.top_k

模型請求的 top_k 取樣設定。

gen_ai.request.top_p

模型請求的 top_p 取樣設定。

gen_ai.response.finish_reasons

模型停止生成 Token 的原因，對應於收到的每個生成結果。

gen_ai.response.id

AI 響應的唯一識別符號。

gen_ai.usage.input_tokens

模型輸入 (Prompt) 中使用的 Token 數量。

gen_ai.usage.output_tokens

模型輸出 (Completion) 中使用的 Token 數量。

gen_ai.usage.total_tokens

模型互動中使用的總 Token 數量。

gen_ai.prompt

傳送給模型的完整 Prompt。可選。

gen_ai.completion

從模型接收到的完整響應。可選。
為了測量使用者 Token，上表列出了可觀測追蹤中存在的值。使用由 ChatModel 提供的指標名稱 gen_ai.client.token.usage。
表 7. 事件
名稱 描述

gen_ai.content.prompt

包含聊天 Prompt 內容的事件。可選。

gen_ai.content.completion

包含聊天 Completion 內容的事件。可選。

聊天 Prompt 和 Completion 資料

聊天 Prompt 和 Completion 資料通常很大，並可能包含敏感資訊。因此，預設情況下不匯出它。

如果使用 OpenTelemetry 追蹤後端，Spring AI 支援將聊天 Prompt 和 Completion 資料匯出為 Span 事件；如果使用 OpenZipkin 追蹤後端，資料則匯出為 Span 屬性。

此外，Spring AI 支援記錄聊天 Prompt 和 Completion 資料，這對於故障排除場景非常有用。

屬性 描述 預設值

spring.ai.chat.observations.include-prompt

在可觀測項中包含 Prompt 內容。true 或 false

false

spring.ai.chat.observations.include-completion

在可觀測項中包含 Completion 內容。true 或 false

false

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

在可觀測項中包含錯誤日誌記錄。true 或 false

false
如果啟用在可觀測項中包含聊天 Prompt 和 Completion 資料，則存在暴露敏感或私人資訊的風險。請小心謹慎！

嵌入模型

當前僅支援來自以下 AI 模型提供商的 EmbeddingModel 實現的可觀測性特性：Azure OpenAI, Mistral AI, Ollama, 和 OpenAI。額外的 AI 模型提供商將在未來版本中支援。

在呼叫嵌入模型方法時，會記錄 gen_ai.client.operation 可觀測項。它們測量方法完成所花費的時間並傳播相關的追蹤資訊。

gen_ai.client.token.usage 指標測量單次模型呼叫使用的輸入和輸出 Token 數量。
表 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

模型輸入中使用的 Token 數量。

gen_ai.usage.total_tokens

模型互動中使用的總 Token 數量。
為了測量使用者 Token，上表列出了可觀測追蹤中存在的值。使用由 EmbeddingModel 提供的指標名稱 gen_ai.client.token.usage。

影像模型

當前僅支援來自以下 AI 模型提供商的 ImageModel 實現的可觀測性特性：OpenAI。額外的 AI 模型提供商將在未來版本中支援。

在呼叫影像模型方法時，會記錄 gen_ai.client.operation 可觀測項。它們測量方法完成所花費的時間並傳播相關的追蹤資訊。

gen_ai.client.token.usage 指標測量單次模型呼叫使用的輸入和輸出 Token 數量。
表 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

模型輸入 (Prompt) 中使用的 Token 數量。

gen_ai.usage.output_tokens

模型輸出 (生成) 中使用的 Token 數量。

gen_ai.usage.total_tokens

模型互動中使用的總 Token 數量。

gen_ai.prompt

傳送給模型的完整 Prompt。可選。
為了測量使用者 Token，上表列出了可觀測追蹤中存在的值。使用由 ImageModel 提供的指標名稱 gen_ai.client.token.usage。
表 12. 事件
名稱 描述

gen_ai.content.prompt

包含影像 Prompt 內容的事件。可選。

影像 Prompt 資料

影像 Prompt 資料通常很大，並可能包含敏感資訊。因此，預設情況下不匯出它。

如果使用 OpenTelemetry 追蹤後端，Spring AI 支援將影像 Prompt 資料匯出為 Span 事件；如果使用 OpenZipkin 追蹤後端，資料則匯出為 Span 屬性。

屬性 描述 預設值

spring.ai.image.observations.include-prompt

true 或 false

false
如果啟用在可觀測項中包含影像 Prompt 資料，則存在暴露敏感或私人資訊的風險。請小心謹慎！

向量儲存

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 最相似向量。
表 15. 事件
名稱 描述

db.vector.content.query.response

包含向量搜尋響應資料的事件。可選。

響應資料

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

如果使用 OpenTelemetry 追蹤後端，Spring AI 支援將向量搜尋響應資料匯出為 Span 事件；如果使用 OpenZipkin 追蹤後端，資料則匯出為 Span 屬性。

屬性 描述 預設值

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

true 或 false

false
如果啟用在可觀測項中包含向量搜尋響應資料，則存在暴露敏感或私人資訊的風險。請小心謹慎！