可观测性

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Spring AI 基于 Spring 生态系统中的可观测性功能，以提供对 AI 相关操作的洞察。Spring AI 为其核心组件提供了指标和追踪功能：ChatClient（包括 Advisor）、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。

低基数 key 将被添加到指标（metric）和追踪（trace）中，而高基数 Key 仅会被添加到追踪中。

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 的观测数据。它们用于测量执行调用所花费的时间，并传播相关的追踪（trace）信息。

Table 1. 低基数 Key
Key	说明
`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`。

Table 2. 高基数 Key
Key	说明
`gen_ai.prompt`	通过聊天客户端发送的提示内容。可选。
`spring.ai.chat.client.advisor.params` （已废弃）	`Advisor` 参数 Map。对话 ID 现在包含在 `spring.ai.chat.client.conversation.id` 中。
`spring.ai.chat.client.advisors`	已配置的聊天客户端 Advisor 列表。
`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.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.chat.client.observations.include-input

是否在观测数据中包含输入内容。

false

若启用在观测数据中包含输入内容的功能，可能存在暴露敏感或隐私信息的风险。请务必谨慎操作！

聊天客户端 Advisor

当执行 Advisor 时，会记录 spring.ai.advisor 观测数据。这些数据测量 Advisor 消耗的时间（包括内部 Advisor 耗时）并传播相关追踪信息。

Table 3. 低基数 Key
Key	说明
`gen_ai.operation.name`	总是 `framework`。
`gen_ai.system`	总是 `spring_ai`.
`spring.ai.advisor.type` （已废弃）	Advisor 在请求处理中应用其逻辑的位置，可以是 `BEFORE`、`AFTER` 或 `AROUND` 之一。此区分已不再适用，因为所有 Advisor 始终为同一类型。
`spring.ai.kind`	Spring AI 中框架 API 的种类：`advisor`。

Table 4. 高基数 Key
Key	说明
`spring.ai.advisor.name`	Advisor 名。
`spring.ai.advisor.order`	Advisor 链中的 Advisor 顺序。

聊天模型

可观测性功能目前仅支持以下 AI 模型提供商的 ChatModel 实现：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhihu AI。其他 AI 模型提供商将在未来的版本中得到支持。

在调用 ChatModel 的 call 或 stream 方法时，会记录 gen_ai.client.operation 的观测数据。它们用于测量方法完成所花费的时间，并传播相关的追踪信息。

gen_ai.client.token.usage 指标用于衡量单次模型调用中所使用的输入和输出 Token 数量。

Table 5. 低基数 Key
Key	说明
`gen_ai.operation.name`	正在执行的操作的名称。
`gen_ai.system`	由客户端检测所识别的模型提供商。
`gen_ai.request.model`	请求的模型名称。
`gen_ai.response.model`	生成响应的模型名称。

Table 6. 高基数 Key
Key	说明
`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`	从模型接收到的完整响应。可选。
`spring.ai.model.request.tool.names`	提供给模型的工具定义列表。

为了测量用户 Token，上表列出了观测追踪中存在的值。请使用 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.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 的观测数据。它们用于测量工具调用完成所花费的时间，并传播相关的追踪信息。

Table 7. 低基数 Key
Key	说明
`gen_ai.operation.name`	正在执行的操作的名称。它始终为 `framework`。
`gen_ai.system`	负责该操作的提供商。它始终为 `spring_ai`。
`spring.ai.kind`	Spring AI 执行的操作类型。它始终为 `tool_call`。
`spring.ai.tool.definition.name`	工具的名称。

Table 8. 高基数 Key
Key	说明
`spring.ai.tool.definition.description`	工具的描述。
`spring.ai.tool.definition.schema`	用于调用工具的参数的 Schema。
`spring.ai.tool.call.arguments`	工具调用的输入参数。（仅在启用时）
`spring.ai.tool.call.result`	用于调用工具的参数的 Schema。（仅在启用时）

工具调用参数和结果数据

工具调用的输入参数和结果默认不会被导出，因为它们可能包含敏感信息。

Spring AI 支持将工具调用的参数和结果数据作为 span 属性进行导出。

属性说明默认值

属性	说明	默认值
`spring.ai.tools.observations.include-content`	在观测中包含工具调用内容。`true` 或 `false`	`false`

spring.ai.tools.observations.include-content

在观测中包含工具调用内容。true 或 false

false

如果你启用了在观测中包含工具调用参数和结果的功能，可能会存在暴露敏感或私有信息的风险。请谨慎操作！

EmbeddingModel

可观测性功能目前仅支持以下 AI 模型提供商的 EmbeddingModel 实现：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。其他 AI 模型提供商将在未来的版本中得到支持。

在调用嵌入模型方法时，会记录 gen_ai.client.operation 的观测数据。它们用于测量方法完成所花费的时间，并传播相关的追踪信息。

gen_ai.client.token.usage 指标用于衡量单次模型调用中所使用的输入和输出令牌数量。

Table 9. 低基数 Key
Key	说明
`gen_ai.operation.name`	正在执行的操作的名称。
`gen_ai.system`	由客户端检测所识别的模型提供商。
`gen_ai.request.model`	请求所针对的模型的名称。
`gen_ai.response.model`	生成响应的模型的名称。

Table 10. 高基数 Key
Key	说明
`gen_ai.request.embedding.dimensions`	输出嵌入结果的维度数量。
`gen_ai.usage.input_tokens`	模型输入中使用的 Token 数量。
`gen_ai.usage.total_tokens`	模型交换中使用的 Token 总数。

为了测量用户 Token，上表列出了观测追踪中存在的值。请使用 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。

图像模型

NOTE: 可观测性功能目前仅支持以下 AI 模型提供商的 ImageModel 实现：OpenAI。其他 AI 模型提供商将在未来的版本中得到支持。

在调用图像模型方法时，会记录 gen_ai.client.operation 的观测数据。它们用于测量方法完成所花费的时间，并传播相关的追踪信息。

gen_ai.client.token.usage 指标用于衡量单次模型调用中所使用的输入和输出 Token 数量。

Table 11. 低基数 Key
Key	说明
`gen_ai.operation.name`	正在执行的操作的名称。
`gen_ai.system`	由客户端检测所识别的模型提供商。
`gen_ai.request.model`	请求所针对的模型的名称。

Table 12. 高基数 Key
Key	说明
`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。

图像提示数据

图像提示数据通常较大，且可能包含敏感信息。出于这些原因，它们默认不会被导出。

Spring AI 支持记录图像提示数据，这在故障排查场景中非常有用。当追踪功能可用时，日志将包含追踪信息，以便更好地进行关联。

属性说明默认值

属性	说明	默认值
`spring.ai.image.observations.log-prompt`	记录图像提示内容。`true` 或 `false`	`false`

spring.ai.image.observations.log-prompt

记录图像提示内容。true 或 false

false

如果你启用了图像提示数据的日志记录，可能会存在暴露敏感或私有信息的风险。请谨慎操作！

向量存储

Spring AI 中的所有向量存储实现都进行了监控，以通过 Micrometer 提供指标和分布式追踪数据。

在与向量存储进行交互时，会记录 db.vector.client.operation 的观测数据。它们用于测量 query、add 和 remove 操作所花费的时间，并传播相关的追踪信息。

Table 13. 低基数 Key
Key	说明
`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`。

Table 14. 高基数 Key
Key	说明
`db.collection.name`	数据库中的集合（表、容器）的名称。
`db.namespace`	数据库名称（包含完整的服务器地址和端口路径）。
`db.record.id`	若存在，则为记录标识符。
`db.search.similarity_metric`	相似性搜索中使用的度量（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`	`false`

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

记录向量存储查询响应内容。true 或 false

false

如果你启用了向量搜索响应数据的日志记录，可能会存在暴露敏感或私有信息的风险。请谨慎操作！