跳到主要内容
版本:2.0.1

可观测性

QWen Max 中英对照 Observability

Spring AI 基于 Spring 生态系统中的可观测性功能,提供对 AI 相关操作的洞察。它为其核心组件提供指标和追踪能力:ChatClient(包括 Advisor)、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。

请参考 Spring Boot Metrics 和 Spring Boot Tracing 文档,以在您的应用程序中启用 metrics 和 tracing 支持。

备注

低基数 key 将被添加到 metrics 和 traces 中,而高基数 key 仅会被添加到 traces 中。

聊天客户端​

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

表 1. 低基数键

名称描述
gen_ai.operation.name始终为 framework。
gen_ai.system始终为 spring_ai。
spring.ai.chat.client.stream聊天模型响应是否为流 - true or false
spring.ai.kindSpring AI 中的框架 API 类型:chat_client。

表 2. 高基数键

名称描述
spring.ai.chat.client.advisors已配置的 chat client advisors 列表。
spring.ai.chat.client.conversation.id使用 chat memory 时的 conversation 标识符。
spring.ai.chat.client.tool.names传递给 chat client 的 tools 名称。

Prompt 与 Completion 数据​

ChatClient prompt 和 completion 数据通常较大,并且可能包含敏感信息。因此,默认情况下不会导出。

Spring AI 支持记录 prompt 和 completion 数据,以帮助调试和故障排除。

属性描述默认值
spring.ai.chat.client.observations.log-prompt是否记录 chat client 的 prompt 内容。false
spring.ai.chat.client.observations.log-completion是否记录 chat client 的 completion 内容。false
注意

如果您启用 chat client 的 prompt 和 completion data 日志记录,可能会暴露敏感或私密信息。请谨慎!

Chat Client Advisors​

当执行 advisor 时,会记录 spring.ai.advisor 观测。它们用于衡量 advisor 花费的时间(包括内部 advisor 花费的时间),并传播相关的 tracing 信息。

表 3. 低基数键

名称描述
gen_ai.operation.name始终为 framework。
gen_ai.system始终为 spring_ai。
spring.ai.advisor.nameadvisor 的名称。
spring.ai.kindSpring AI 中框架 API 的类型:advisor。

表 4. 高基数键

名称描述
spring.ai.advisor.orderAdvisor 在 advisor chain 中的顺序。

Chat Model​

备注

OpenAI 和 Anthropic chat 模型确实会发出 HTTP-layer observations(chat-model 层 + HTTP 层),但针对 streaming 调用存在一个特定限制。HTTP-layer observation 会携带 HTTP method、URI、status code,并在网络传输中向下游服务(AI 网关、代理、OpenAI 兼容的推理服务器)传播 traceparent。

对于同步调用,okhttp.requests span 会正确嵌套在 gen_ai.client.operation span 之下。对于 streaming 调用,HTTP span 会被记录,但不会作为 chat-model span 的子 span —— SDK 的异步 streaming 路径在调用 Spring AI 的 HTTP 客户端之前会跳转到 ForkJoinPool.commonPool(),从而在该边界处丢失调用线程的 observation 上下文。

详情请参见 OpenAI chat 文档 和 Anthropic chat 文档。

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

important

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

表 5. 低基数键

名称描述
gen_ai.operation.name正在执行的操作名称。
gen_ai.system由客户端插桩识别的模型提供商。
gen_ai.request.model请求所使用的模型名称。
gen_ai.response.model生成响应的模型名称。

表 6. 高基数键

备注

对于测量用户 token,前面的表格列出了 observation trace 中存在的值。使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。

Chat Prompt 和 Completion 数据​

chat prompt 和 completion 数据通常较大,并且可能包含敏感信息。因此,默认情况下不会导出这些数据。

Spring AI 支持记录聊天提示和补全数据的日志,适用于故障排查场景。当启用追踪时,日志将包含追踪信息,以便更好地进行关联。

属性描述默认值
spring.ai.chat.observations.log-prompt记录提示词内容,取值为 true 或 falsefalse
spring.ai.chat.observations.log-completion记录补全内容,取值为 true 或 falsefalse
spring.ai.chat.observations.include-error-logging在观测中包含错误日志记录,取值为 true 或 falsefalse
注意

如果你启用对 chat prompt 和 completion 数据的日志记录,可能会暴露敏感或隐私信息。请务必小心!

Tool Calling​

spring.ai.tool 观测会在聊天模型交互上下文中执行工具调用时被记录。它们衡量工具调用完成所花费的时间,并传播相关追踪信息。

表 7. 低基数键

名称描述
gen_ai.operation.name正在执行的操作的名称。它始终为 execute_tool。
gen_ai.system负责该操作的提供者。它始终为 spring_ai。
spring.ai.kind由 Spring AI 执行的操作类型。它始终为 tool_call。
spring.ai.tool.definition.name工具的名称。
spring.ai.tool.type工具的类型。默认情况下为 function。

表 8. High Cardinality Keys

名称描述
spring.ai.tool.definition.description工具的描述。
spring.ai.tool.definition.schema用于调用工具的参数的 Schema。
spring.ai.tool.call.id由 chat model 识别的 tool call 的 ID。
spring.ai.tool.call.argumentstool call 的输入参数。(仅在启用时)
spring.ai.tool.call.resulttool call 执行的结果。(仅在启用时)

Tool Call 参数和结果数据​

工具调用的输入参数和结果默认不会被导出,因为它们可能具有敏感性。

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

属性描述默认值
spring.ai.tools.observations.include-content在 observations 中包含工具调用内容。true 或 falsefalse
注意

如果你启用将 tool call 参数和结果包含在 observations 中,可能会有暴露敏感或私有信息的风险。请小心!

EmbeddingModel​

备注

可观测性功能目前仅支持以下 AI 模型提供商的 EmbeddingModel 实现:Mistral AI、Ollama 和 OpenAI。未来的版本将支持更多 AI 模型提供商。

gen_ai.client.operation 观测记录在 embedding model 方法调用上。它们衡量方法完成所花费的时间,并传播相关 tracing 信息。

important

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

表 9. 低基数键

名称描述
gen_ai.operation.name正在执行的操作的名称。
gen_ai.system由客户端插桩识别的模型提供者。
gen_ai.request.model请求所指向的模型的名称。
gen_ai.response.model生成响应的模型的名称。

表 10. 高基数键

名称描述
gen_ai.request.embedding.dimensions生成的输出 embeddings 的维度数量。
gen_ai.usage.input_tokens模型输入中使用的 token 数量。
gen_ai.usage.total_tokens模型交互中使用的 token 总数。
备注

对于测量 user tokens,前面的表格列出了 observation trace 中存在的值。请使用由 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。

图像模型​

备注

目前,可观测性功能仅支持来自以下 AI 模型提供商的 ImageModel 实现:OpenAI。未来的版本将支持更多 AI 模型提供商。

gen_ai.client.operation 观测值会在图像模型方法调用时被记录。它们衡量方法完成所花费的时间,并传播相关的 tracing 信息。

表 11. 低基数键

名称描述
gen_ai.operation.name正在执行的操作的名称。
gen_ai.system由客户端插桩识别的模型提供者。
gen_ai.request.model请求所指向的模型的名称。

表 12. 高基数键

名称描述
gen_ai.request.image.response_format返回生成图像的格式。
gen_ai.request.image.size要生成的图像尺寸(例如 1024x1024)。
gen_ai.request.image.style要生成的图像风格。

图像提示数据​

图像 prompt 数据通常较大,并且可能包含敏感信息。因此,默认不导出。

Spring AI 支持记录图像 prompt 数据,便于故障排查场景。当 tracing 可用时,日志将包含 trace 信息,以便更好地进行关联。

PropertyDescriptionDefault
spring.ai.image.observations.log-prompt记录图像 prompt 内容。true 或 falsefalse
注意

如果你启用图像 prompt 数据的日志记录,存在暴露敏感或私密信息的风险。请务必小心!

Vector Stores​

Spring AI 中的所有 vector store 实现都通过 Micrometer 进行了插桩,以提供指标和分布式追踪数据。

db.vector.client.operation 观测会在与 Vector Store 交互时记录。它们测量 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、simple。
spring.ai.kindSpring AI 中框架 API 的类型:vector_store。

表 14. 高基数键

名称描述
db.collection.name数据库中 collection(table、container)的名称。
db.namespace数据库名称,在服务器地址和端口内完全限定。
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 个最相似向量。

响应数据​

vector search 响应数据通常较大,并且可能包含敏感信息。出于这些原因,默认情况下不会导出该数据。

Spring AI 支持记录向量搜索响应数据,适用于故障排查场景。当追踪可用时,日志将包含追踪信息,以便更好地进行关联。

属性描述默认值
spring.ai.vectorstore.observations.log-query-response记录向量存储查询响应内容。 true 或 falsefalse
注意

如果启用 vector search 响应数据的日志记录,可能会有暴露敏感或私密信息的风险。请务必谨慎!

更多 Metrics 参考​

本节介绍 Spring AI 组件在 Prometheus 中呈现的指标。

指标命名规范​

Spring AI 使用 Micrometer。基础指标名称使用点号(例如 gen_ai.client.operation),Prometheus 导出时会使用下划线和标准后缀:

  • 计时器 → <base>_seconds_count、<base>_seconds_sum、<base>_seconds_max 以及(受支持时)<base>_active_count

  • 计数器 → <base>_total(单调递增)

备注

以下展示基础指标名称如何展开为 Prometheus 时间序列。

基础指标名称导出的时间序列
gen_ai.client.operationgen_ai_client_operation_seconds_count
gen_ai_client_operation_seconds_sum
gen_ai_client_operation_seconds_max
gen_ai_client_operation_active_count
db.vector.client.operationdb_vector_client_operation_seconds_count
db_vector_client_operation_seconds_sum
db_vector_client_operation_seconds_max
db_vector_client_operation_active_count

参考文献​

聊天客户端指标​

指标名称类型单位描述
gen_ai_chat_client_operation_seconds_sumTimer秒ChatClient 操作(call/stream)的总耗时
gen_ai_chat_client_operation_seconds_countCounter次数已完成的 ChatClient 操作数量
gen_ai_chat_client_operation_seconds_maxGauge秒ChatClient 操作的最大观测时长
gen_ai_chat_client_operation_active_countGauge次数当前正在进行的 ChatClient 操作数量

Active 与 Completed:**_active_count_** 显示进行中的调用;_seconds 序列仅反映已完成的调用。

聊天模型指标(模型提供商执行)​

指标名称类型单位描述
gen_ai_client_operation_seconds_sumTimerseconds执行聊天模型操作的总时间
gen_ai_client_operation_seconds_countCountercount已完成的聊天模型操作数量
gen_ai_client_operation_seconds_maxGaugeseconds观察到的聊天模型操作的最大持续时间
gen_ai_client_operation_active_countGaugecount当前正在进行的聊天模型操作数量

Token 使用量​

指标名称类型单位描述
gen_ai_client_token_usage_totalCountertokens消耗的总 tokens 数,按 token 类型标记

标签​

标签含义
gen_ai_token_type=input发送给模型的 Prompt tokens
gen_ai_token_type=output模型返回的 Completion tokens
gen_ai_token_type=total输入 + 输出

向量存储指标​

Metric NameTypeUnitDescription
db_vector_client_operation_seconds_sumTimer秒向量存储操作 (add/delete/query) 花费的总时间
db_vector_client_operation_seconds_countCounter计数已完成的向量存储操作数量
db_vector_client_operation_seconds_maxGauge秒观察到的向量存储操作最大持续时间
db_vector_client_operation_active_countGauge计数当前正在进行的向量存储操作数量

标签​

标签含义
db_operation_name操作类型 (add, delete, query)
db_system向量 DB/提供商 (redis, chroma, pgvector, …)
spring_ai_kindvector_store

理解 Active 与 Completed​

  • Active (*_active_count) — 进行中操作的瞬时 gauge(并发/负载)。

  • Completed (*_seconds_sum|count|max) — 已完成操作的统计信息:

  • _seconds_sum / _seconds_count → 平均延迟

  • _seconds_max → 自上次 scrape 以来的最高值(取决于 registry 行为)