可观测性

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 支持将输入数据作为跨所有跟踪后端的跨度属性导出。

属性描述默认值

属性	描述	默认值
`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、千帆、智谱 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`	从模型接收到的完整响应。可选。

为了测量用户令牌，上表列出了观测跟踪中存在的数值。使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。

表 7. 事件
名称	描述
`gen_ai.content.prompt`	包含聊天提示内容的事件。可选。
`gen_ai.content.completion`	包含聊天完成内容的事件。可选。

聊天提示和完成数据

聊天提示和完成数据通常很大，并且可能包含敏感信息。出于这些原因，默认情况下不导出它。

如果使用 OpenTelemetry 跟踪后端，Spring AI 支持将聊天提示和完成数据作为跨度事件导出，而如果使用 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`

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 指标测量单个模型调用使用的输入和输出令牌数量。

表 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`	包含图像提示内容的事件。可选。

图像提示数据

图像提示数据通常很大，并且可能包含敏感信息。由于这些原因，默认情况下不会导出它。

如果您使用 OpenTelemetry 跟踪后端，则 Spring AI 支持将图像提示数据导出为跨度事件，而如果您使用 OpenZipkin 跟踪后端，则数据将导出为跨度属性。

属性描述默认值

属性	描述	默认值
`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 支持将向量搜索响应数据导出为跨度事件，而如果您使用 OpenZipkin 跟踪后端，则数据将导出为跨度属性。

属性描述默认值

属性	描述	默认值
`spring.ai.vectorstore.observations.include-query-response`	`true` 或 `false`	`false`

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

true 或 false

false

如果您启用了在观察结果中包含向量搜索响应数据，则存在泄露敏感或私人信息的风险。请小心！