可观察性（Observability）

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

Chat Client

spring.ai.chat.client 的观察是在当 ChatClient 的 call() 或 stream() 操作被调用时，记录观察结果。它们会测量执行调用所花费的时间，并传播相关的跟踪信息。

表 1. 低基数键

属性 描述
gen_ai.operation.name 总是 framework。
gen_ai.system 总是 spring_ai。
spring.ai.chat.client.stream 聊天模型响应是流吗？true or 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 取代。

Prompt Content

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

Spring AI 支持记录提示内容，以帮助调试和排除故障。

属性 描述 默认值
spring.ai.chat.client.observations.log-prompt 是否记录聊天客户端提示内容。 false

Chat Client Advisors

spring.ai.advisor 执行 Advisor 程序时会记录观察结果。它们会测量 Advisor 程序所花费的时间（包括内部Advisor 程序所花费的时间），并传播相关的跟踪信息。

表 3. 低基数键

属性 描述
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。

表 4. 高基数键

属性 描述
spring.ai.advisor.name Advisor 的名称。
spring.ai.advisor.order Advisor 链中的顺序。

聊天模型

可观察性功能目前仅支持以下 AI 模型提供商的 ChatModel 实现：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan 和 Zhipu AI。未来版本将支持更多 AI 模型提供商。

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

表 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 请求中提供给模型的工具定义列表

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

聊天提示和完成数据

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

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.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 false

嵌入模型

EmbeddingModel 可观察性功能目前仅支持以下 AI 模型提供商的实现：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。未来版本将支持其他 AI 模型提供商。
这些gen_ai.client.operation观察记录在嵌入模型方法调用中。它们测量方法完成所花费的时间并传播相关的跟踪信息。

表 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 模型交换中使用的代币总数。

图像模型

可观察性功能目前仅支持ImageModel以下 AI 模型提供商的实现：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 发送给模型的完整提示。可选

为了测量用户令牌，上表列出了观察轨迹中存在的值。请使用gen_ai.client.token.usage提供的指标名称

图像提示数据

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

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

属性 描述 默认值
spring.ai.image.observations.log-prompt 记录图片提示内容。true或者false false

如果您启用图片提示数据的记录，则存在泄露敏感或隐私信息的风险。请务必小心！

向量存储

Spring AI 中的所有向量存储实现都经过检测，可通过 Micrometer 提供指标和分布式跟踪数据。

与 Vector Store 交互时会记录观察结果。它们会测量、和操作db.vector.client.operation所花费的时间，并传播相关的跟踪信息。queryaddremove

表 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 个最相似的向量。

响应数据

向量搜索响应数据通常很大，并且可能包含敏感信息。因此，默认情况下不会导出这些数据。

Spring AI 支持记录向量搜索响应数据，这对于故障排除场景非常有用。当跟踪可用时，日志将包含跟踪信息，以便更好地进行关联。

属性 描述 默认值
spring.ai.vectorstore.observations.log-query-response 记录向量存储查询响应内容。true或者false （未指定默认值）
作者：Jeebiz  创建时间：2025-08-04 00:14
最后编辑：Jeebiz  更新时间：2025-08-08 00:47