可觀察性

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. 高基數鍵
名稱	描述
`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 支援跨所有追蹤後端將輸入資料作為 span 屬性匯出。

屬性描述預設值

屬性	描述	預設值
`spring.ai.chat.client.observations.include-input`	是否在觀察中包含輸入內容。	`false`

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`	模型輸入（提示詞）中使用的 token 數量。
`gen_ai.usage.output_tokens`	模型輸出（完成）中使用的 token 數量。
`gen_ai.usage.total_tokens`	模型交換中使用的 token 總數。
`gen_ai.prompt`	發送給模型的完整提示詞。選填。
`gen_ai.completion`	從模型接收到的完整回應。選填。

為了測量使用者 token，上表列出了觀察追蹤中存在的值。使用由 ChatModel 提供的指標名稱 gen_ai.client.token.usage。

表 7. 事件
名稱	描述
`gen_ai.content.prompt`	包含聊天提示詞內容的事件。選填。
`gen_ai.content.completion`	包含聊天完成內容的事件。選填。

聊天提示詞和完成資料

聊天提示詞和完成資料通常很大，並且可能包含敏感資訊。由於這些原因，預設情況下不會匯出它。

如果您使用 OpenTelemetry 追蹤後端，Spring AI 支援將聊天提示詞和完成資料作為 span 事件匯出，而如果您使用 OpenZipkin 追蹤後端，則資料會作為 span 屬性匯出。

此外，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`

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

如果您啟用在觀察中包含聊天提示詞和完成資料，則存在暴露敏感或私人資訊的風險。請務必小心！

嵌入模型

目前僅以下 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`	模型輸入（提示詞）中使用的 token 數量。
`gen_ai.usage.output_tokens`	模型輸出（產生）中使用的 token 數量。
`gen_ai.usage.total_tokens`	模型交換中使用的 token 總數。
`gen_ai.prompt`	發送給模型的完整提示詞。選填。

為了測量使用者 token，上表列出了觀察追蹤中存在的值。使用由 ImageModel 提供的指標名稱 gen_ai.client.token.usage。

表 12. 事件
名稱	描述
`gen_ai.content.prompt`	包含影像提示詞內容的事件。選填。

影像提示詞資料

影像提示詞資料通常很大，並且可能包含敏感資訊。由於這些原因，預設情況下不會匯出它。

如果您使用 OpenTelemetry 追蹤後端，Spring AI 支援將影像提示詞資料作為 span 事件匯出，而如果您使用 OpenZipkin 追蹤後端，則資料會作為 span 屬性匯出。

屬性描述預設值

屬性	描述	預設值
`spring.ai.image.observations.include-prompt`	`true` 或 `false`	`false`

spring.ai.image.observations.include-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 個最相似向量。

表 15. 事件
名稱	描述
`db.vector.content.query.response`	包含向量搜尋回應資料的事件。選填。

回應資料

向量搜尋回應資料通常很大，並且可能包含敏感資訊。由於這些原因，預設情況下不會匯出它。

如果您使用 OpenTelemetry 追蹤後端，Spring AI 支援將向量搜尋回應資料作為 span 事件匯出，而如果您使用 OpenZipkin 追蹤後端，則資料會作為 span 屬性匯出。

屬性描述預設值

屬性	描述	預設值
`spring.ai.vectorstore.observations.include-query-response`	`true` 或 `false`	`false`

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

true 或 false

false

如果您啟用在觀察中包含向量搜尋回應資料，則存在暴露敏感或私人資訊的風險。請務必小心！