一、可观测性

Spring AI 基于 Spring 生态系统中的可观测性功能，为与 AI 相关的操作提供洞察。

启用可观测性需要 spring-boot-actuator 模块。将 Spring Boot Actuator 依赖项添加到项目的 Maven pom.xml 构建文件中：

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.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-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 观测数据。它们测量执行调用所花费的时间，并传播相关的追踪信息。

表 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.operation），Prometheus 导出时带有下划线和标准后缀：

• 计时器 → _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 → 自上次抓取以来的最高值（取决于注册表行为）