一、可观测性Spring AI 基于 Spring 生态系统中的可观测性功能为与 AI 相关的操作提供洞察。启用可观测性需要 spring-boot-actuator 模块。将 Spring Boot Actuator 依赖项添加到项目的 Maven pom.xml 构建文件中dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-actuator/artifactId/dependency或添加到 Gradle build.gradle 构建文件中dependencies{implementationorg.springframework.boot:spring-boot-starter-actuator}Spring AI 为其核心组件提供度量和追踪能力ChatClient包括 Advisor、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。低基数键将添加到度量和追踪中而高基数键仅添加到追踪中。1.0.0-RC1 破坏性变更以下配置属性已重命名以更好地反映其用途spring.ai.chat.client.observations.include-prompt → spring.ai.chat.client.observations.log-promptspring.ai.chat.observations.include-prompt → spring.ai.chat.observations.log-promptspring.ai.chat.observations.include-completion → spring.ai.chat.observations.log-completionspring.ai.image.observations.include-prompt → spring.ai.image.observations.log-promptspring.ai.vectorstore.observations.include-query-response → spring.ai.vectorstore.observations.log-query-response二、聊天客户端当调用 ChatClient 的 call() 或 stream() 操作时会记录 spring.ai.chat.client 观测数据。它们测量执行调用所花费的时间并传播相关的追踪信息。表 1. 低基数键表 2. 高基数键2.1 提示和完成数据ChatClient 的提示和完成数据通常很大并且可能包含敏感信息。出于这些原因默认情况下不会导出它们。Spring AI 支持记录提示和完成数据以帮助调试和故障排除。如果启用记录聊天客户端提示和完成数据则存在暴露敏感或私人信息的风险。请务必小心2.2 输入数据已弃用spring.ai.chat.client.observations.include-input 属性已弃用由 spring.ai.chat.client.observations.log-prompt 取代。请参阅“提示内容”。ChatClient 的输入数据通常很大并且可能包含敏感信息。出于这些原因默认情况下不会导出它们。Spring AI 支持记录输入数据以帮助调试和故障排除。如果启用在观测中包含输入内容则存在暴露敏感或私人信息的风险。请务必小心2.3 聊天客户端顾问当执行顾问时会记录 spring.ai.advisor 观测数据。它们测量在顾问中花费的时间包括内部顾问花费的时间并传播相关的追踪信息。表 3. 低基数键表 4. 高基数键三、聊天模型目前仅支持来自以下 AI 模型提供商的 ChatModel 实现的可观测性功能Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhipu AI。未来版本将支持更多 AI 模型提供商。当调用 ChatModel 的 call 或 stream 方法时会记录 gen_ai.client.operation 观测数据。它们测量方法完成所花费的时间并传播相关的追踪信息。gen_ai.client.token.usage 度量衡量单次模型调用使用的输入和输出令牌数量。表 5. 低基数键表 6. 高基数键对于度量用户令牌上表列出了观测追踪中存在的值。请使用 ChatModel 提供的度量名称 gen_ai.client.token.usage。3.1 聊天提示和完成数据聊天提示和完成数据通常很大并且可能包含敏感信息。出于这些原因默认情况下不会导出它们。Spring AI 支持记录聊天提示和完成数据这对于故障排除场景非常有用。当追踪可用时日志将包含用于更好关联的追踪信息。如果启用记录聊天提示和完成数据则存在暴露敏感或私人信息的风险。请务必小心四、工具调用在聊天模型交互的上下文中执行工具调用时会记录 spring.ai.tool 观测数据。它们测量工具调用完成所花费的时间并传播相关的追踪信息。表 7. 低基数键表 8. 高基数键4.1 工具调用参数和结果数据工具调用的输入参数和结果默认情况下不会导出因为它们可能具有潜在敏感性。Spring AI 支持将工具调用参数和结果数据导出为跨度属性。如果启用在观测中包含工具调用参数和结果则存在暴露敏感或私人信息的风险。请务必小心五、嵌入模型目前仅支持来自以下 AI 模型提供商的 EmbeddingModel 实现的可观测性功能Azure OpenAI、Mistral AI、Ollama 和 OpenAI。未来版本将支持更多 AI 模型提供商。在嵌入模型方法调用时会记录 gen_ai.client.operation 观测数据。它们测量方法完成所花费的时间并传播相关的追踪信息。gen_ai.client.token.usage 度量衡量单次模型调用使用的输入和输出令牌数量。表 9. 低基数键表 10. 高基数键对于度量用户令牌上表列出了观测追踪中存在的值。请使用 EmbeddingModel 提供的度量名称 gen_ai.client.token.usage。六、图像模型目前仅支持来自以下 AI 模型提供商的 ImageModel 实现的可观测性功能OpenAI。未来版本将支持更多 AI 模型提供商。在图像模型方法调用时会记录 gen_ai.client.operation 观测数据。它们测量方法完成所花费的时间并传播相关的追踪信息。gen_ai.client.token.usage 度量衡量单次模型调用使用的输入和输出令牌数量。表 11. 低基数键表 12. 高基数键对于度量用户令牌上表列出了观测追踪中存在的值。请使用 ImageModel 提供的度量名称 gen_ai.client.token.usage。6.1 图像提示数据图像提示数据通常很大并且可能包含敏感信息。出于这些原因默认情况下不会导出它们。Spring AI 支持记录图像提示数据这对于故障排除场景非常有用。当追踪可用时日志将包含用于更好关联的追踪信息。如果启用记录图像提示数据则存在暴露敏感或私人信息的风险。请务必小心七、向量存储Spring AI 中的所有向量存储实现都已通过 Micrometer 进行检测以提供度量和分布式追踪数据。当与向量存储交互时会记录 db.vector.client.operation 观测数据。它们测量查询、添加和删除操作所花费的时间并传播相关的追踪信息。表 13. 低基数键表 14. 高基数键7.1 响应数据向量搜索响应数据通常很大并且可能包含敏感信息。出于这些原因默认情况下不会导出它们。Spring AI 支持记录向量搜索响应数据这对于故障排除场景非常有用。当追踪可用时日志将包含用于更好关联的追踪信息。如果启用记录向量搜索响应数据则存在暴露敏感或私人信息的风险。请务必小心八、更多度量参考本节记录了 Spring AI 组件在 Prometheus 中呈现时发出的度量。8.1 度量命名约定Spring AI 使用 Micrometer。基本度量名称使用点例如 gen_ai.client.operationPrometheus 导出时带有下划线和标准后缀计时器 → _seconds_count、_seconds_sum、_seconds_max 以及如果支持_active_count计数器 → _total单调递增以下显示了基本度量名称如何扩展为 Prometheus 时间序列。参考资料OpenTelemetry — 生成式 AI 的语义约定概述Micrometer — 命名度量8.2 聊天客户端度量活动与已完成active_count 显示正在进行的调用_seconds 系列仅反映已完成的调用。8.3 聊天模型度量模型提供商执行8.4 令牌使用情况标签8.5 向量存储度量标签8.6 理解活动与已完成活动*_active_count— 正在进行的操作的瞬时仪表并发/负载。已完成*_seconds_sum|count|max— 已完成操作的统计信息_seconds_sum / _seconds_count → 平均延迟_seconds_max → 自上次抓取以来的最高值取决于注册表行为