可观测性
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 构建脚本文件中。
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}Spring AI 为其核心组件提供指标和跟踪功能： ChatClient（包括 Advisor），
ChatModel、EmbeddingModel、ImageModel 和 VectorStore。
| 低基数键将被添加到指标和跟踪中，而高基数键仅会被添加到跟踪中。 |
|
1.0.0-RC1 重大变更 以下配置属性已被重命名，以更好地反映其用途：
|
ChatClient
当调用 ChatClient 的 call() 或 stream() 操作时，会记录 spring.ai.chat.client 条观测。
它们用于测量执行调用所花费的时间，并传播相关的跟踪信息。
| 名称 | 描述 |
|---|---|
|
始终 |
|
始终 |
|
聊天模型的响应是否为流 - |
|
Spring AI 中的框架 API 类型： |
| 名称 | 描述 |
|---|---|
|
通过聊天客户端发送的提示内容。可选。 |
|
顾问参数映射。会话ID现在包含在 |
|
已配置的聊天客户端顾问列表。 |
|
使用聊天记忆时的会话标识符。 |
|
聊天客户端系统参数。可选。已被 |
|
聊天客户端系统文本。可选。已被 |
|
启用的工具函数名称。已被 |
|
已配置的聊天客户端函数回调列表。已被 |
|
传递给聊天客户端的工具名称。 |
|
聊天客户端用户参数。可选。已被 |
|
聊天客户端用户文本。可选。已被 |
提示与完成数据
ChatClient 提示和补全数据通常较大，并且可能包含敏感信息。
出于这些原因，它默认不会被导出。
Spring AI 支持将提示和完成数据记录到日志中，以帮助调试和故障排除。
| 属性 | 描述 | 默认 |
|---|---|---|
|
是否记录聊天客户端提示内容。 |
|
|
是否记录聊天客户端完成内容。 |
|
| 如果您启用聊天客户端提示和完成数据的日志记录，可能会存在泄露敏感或隐私信息的风险。请务必谨慎！ |
输入数据（已弃用）
spring.ai.chat.client.observations.include-input 属性已弃用，由 spring.ai.chat.client.observations.log-prompt 取代。请参阅 提示内容。 |
输入数据ChatClient通常较大，并且可能包含敏感信息。
出于这些原因，它默认不会被导出。
Spring AI 支持将输入数据记录到日志中，以帮助调试和故障排除。
| 属性 | 描述 | 默认 |
|---|---|---|
|
是否在观测中包含输入内容。 |
|
| 如果您启用在观测中包含输入内容的功能，可能会存在泄露敏感或隐私信息的风险。请务必谨慎！ |
聊天客户端顾问
当执行顾问时，会记录spring.ai.advisor个观测值。
它们用于测量顾问的耗时（包括在内部顾问上花费的时间），并传播相关的跟踪信息。
| 名称 | 描述 |
|---|---|
|
始终 |
|
始终 |
|
在请求处理过程中，顾问应用其逻辑的位置为 |
|
Spring AI 中的框架 API 类型： |
| 名称 | 描述 |
|---|---|
|
顾问的姓名。 |
|
顾问链中的顾问顺序。 |
聊天模型
可观察性功能目前仅支持以下AI模型提供商的ChatModel个实现：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhipu AI。
未来版本将支持更多AI模型提供商。 |
调用 ChatModel 的 gen_ai.client.operation 观察结果是在调用 call 或 stream 方法时记录的。
它们用于测量方法完成所花费的时间，并传播相关的跟踪信息。
The gen_ai.client.token.usage metrics measures number of input and output tokens used by a single model call. |
| 名称 | 描述 |
|---|---|
|
执行的操作名称。 |
|
由客户端仪表化标识的模型提供商。 |
|
请求所针对的模型名称。 |
|
生成响应的模型名称。 |
| 名称 | 描述 |
|---|---|
|
模型请求的频率惩罚设置。 |
|
模型为一次请求生成的最大标记数。 |
|
模型请求的在场惩罚设置。 |
|
模型将用于停止生成更多标记的序列列表。 |
|
模型请求的温度设置。 |
|
模型请求的 top_k 采样设置。 |
|
模型请求的 top_p 采样设置。 |
|
模型停止生成标记的原因，对应于每个接收到的生成结果。 |
|
AI 响应的唯一标识符。 |
|
模型输入（提示）中使用的标记数量。 |
|
模型输出（完成）中使用的标记数量。 |
|
模型交换中使用的总标记数。 |
|
发送给模型的完整提示。可选。 |
|
模型返回的完整响应。可选。 |
|
请求中提供给模型的工具定义列表。 |
对于用户Tokens的度量，上表列出了观测跟踪中存在的值。
使用由ChatModel提供的指标名称gen_ai.client.token.usage。 |
聊天提示与完成数据
聊天提示和完成数据通常较大，并且可能包含敏感信息。 出于这些原因，它们默认不会被导出。
Spring AI 支持记录聊天提示和完成数据，这对于故障排查场景非常有用。当跟踪功能可用时，日志将包含跟踪信息，以便更好地进行关联。
| 属性 | 描述 | 默认 |
|---|---|---|
|
记录提示内容。 |
|
|
记录完成内容。 |
|
|
在观测中包含错误日志。 |
|
| 如果您启用聊天提示和完成数据的日志记录，可能会存在泄露敏感或私人信息的风险。请务必谨慎！ |
工具调用
在聊天模型交互的上下文中执行工具调用时，会记录spring.ai.tool个观测值。这些观测值用于衡量工具调用完成所花费的时间，并传播相关的追踪信息。
| 名称 | 描述 |
|---|---|
|
执行的操作名称。它始终为 |
|
负责该操作的提供者。它始终为 |
|
Spring AI 执行的操作类型。始终为 |
|
工具的名称。 |
名称 |
描述 |
|
该工具的描述。 |
|
调用该工具所使用的参数模式。 |
|
工具调用的输入参数。（仅在启用时） |
|
用于调用该工具的参数架构。（仅在启用时） |
嵌入模型
可观察性功能目前仅支持以下 AI 模型提供商的 EmbeddingModel 个实现：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。
未来版本将支持更多 AI 模型提供商。 |
gen_ai.client.operation 个观测记录在嵌入模型方法调用上。
它们用于测量方法完成所花费的时间，并传播相关的跟踪信息。
The gen_ai.client.token.usage metrics measures number of input and output tokens used by a single model call. |
| 名称 | 描述 |
|---|---|
|
执行的操作名称。 |
|
由客户端仪表化标识的模型提供商。 |
|
请求所针对的模型名称。 |
|
生成响应的模型名称。 |
| 名称 | 描述 |
|---|---|
|
生成的输出嵌入所具有的维度数量。 |
|
模型输入中使用的标记数量。 |
|
模型交换中使用的总标记数。 |
对于用户Tokens的度量，上表列出了观测跟踪中存在的值。
使用由EmbeddingModel提供的指标名称gen_ai.client.token.usage。 |
图像模型
可观察性功能目前仅支持来自以下AI模型提供商的ImageModel个实现：OpenAI。
未来版本将支持更多AI模型提供商。 |
gen_ai.client.operation 个观测记录在图像模型方法调用上。
它们用于测量方法完成所花费的时间，并传播相关的跟踪信息。
The gen_ai.client.token.usage metrics measures number of input and output tokens used by a single model call. |
| 名称 | 描述 |
|---|---|
|
执行的操作名称。 |
|
由客户端仪表化标识的模型提供商。 |
|
请求所针对的模型名称。 |
| 名称 | 描述 |
|---|---|
|
生成的图像返回的格式。 |
|
要生成的图像大小。 |
|
生成图像的样式。 |
|
AI 响应的唯一标识符。 |
|
生成响应的模型名称。 |
|
模型输入（提示）中使用的标记数量。 |
|
模型输出（生成）中使用的标记数量。 |
|
模型交换中使用的总标记数。 |
|
发送给模型的完整提示。可选。 |
对于用户Tokens的度量，上表列出了观测跟踪中存在的值。
使用由ImageModel提供的指标名称gen_ai.client.token.usage。 |
向量商店
Spring AI 中的所有向量存储实现都已进行插桩，以通过 Micrometer 提供指标和分布式追踪数据。
观察结果db.vector.client.operation是在与向量存储交互时记录的。
它们用于测量在query、add和remove操作上花费的时间，并传播相关的追踪信息。
| 名称 | 描述 |
|---|---|
|
正在执行的操作或命令的名称。取值为 |
|
客户端仪表化所识别的数据库管理系统（DBMS）产品。取值为 |
|
Spring AI 中的框架 API 类型： |
| 名称 | 描述 |
|---|---|
|
数据库中的集合（表、容器）的名称。 |
|
数据库的名称，需在服务器地址和端口范围内完整指定。 |
|
如果存在，则为记录标识符。 |
|
用于相似性搜索的指标。 |
|
向量的维度。 |
|
向量中的名称字段（例如，字段名称）。 |
|
正在执行的搜索查询内容。 |
|
搜索查询中使用的元数据过滤器。 |
|
从相似性搜索查询中返回的文档。可选。 |
|
相似度阈值，用于接受所有搜索得分。阈值为 0.0 表示接受任何相似度，或禁用相似度阈值过滤。阈值为 1.0 表示需要完全匹配。 |
|
查询返回的前 k 个最相似的向量。 |
更多指标参考
本节记录了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 时间序列。
|
参考资料
-
OpenTelemetry — 生成式AI的语义约定（概述）
-
Micrometer — 命名仪表
聊天客户端指标
| 指标名称 | 类型 | 单元 | 描述 |
|---|---|---|---|
|
定时器 |
秒 |
ChatClient 操作（调用/流）所花费的总时间 |
|
计数器 |
计数 |
已完成的 ChatClient 操作数量 |
|
仪表盘 |
秒 |
ChatClient 操作的最大观测持续时间 |
|
仪表盘 |
计数 |
当前正在进行的 ChatClient 操作数量 |
进行中与已完成: active_count 显示正在进行的调用；_seconds 系列仅反映已完成的调用。
聊天模型指标（模型提供商执行）
| 指标名称 | 类型 | 单元 | 描述 |
|---|---|---|---|
|
定时器 |
秒 |
执行聊天模型操作的总时间 |
|
计数器 |
计数 |
已完成的聊天模型操作数量 |
|
仪表盘 |
秒 |
聊天模型操作的最大观测持续时间 |
|
仪表盘 |
计数 |
当前正在进行的聊天模型操作数量 |