|
此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3! |
可观测性
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 破坏性变更 以下配置属性已被重命名,以更好地反映其用途:
|
ChatClient
当调用 ChatClient 的 spring.ai.chat.client 或 call() 操作时,会记录 stream() 次观察。
它们测量执行调用所花费的时间,并传播相关的跟踪信息。
| 姓名 | <description> </description> |
|---|---|
|
始终为 |
|
始终为 |
|
聊天模型响应是否为流 - |
|
Spring AI 中的框架 API 类型: |
| 姓名 | <description> </description> |
|---|---|
|
通过聊天客户端发送的提示内容。可选。 |
|
顾问参数映射。对话ID现在包含在 |
|
已配置的聊天客户端顾问列表。 |
|
使用聊天记忆时的对话标识符。 |
|
聊天客户端系统参数。可选。被 |
|
聊天客户端系统文本。可选。已被 |
|
已启用的工具函数名称。已被 |
|
已配置的聊天客户端函数回调列表。已被 |
|
传递给聊天客户端的工具名称。 |
|
聊天客户端用户参数。可选。被 |
|
聊天客户端用户文本。可选。已被 |
提示和完成数据
ChatClient 提示和完成数据通常很大,并且可能包含敏感信息。
由于这些原因,默认情况下不会导出这些数据。
Spring AI 支持记录提示和完成数据,以帮助进行调试和故障排除。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
|
是否记录聊天客户端提示内容。 |
|
|
是否记录聊天客户端完成内容。 |
|
| 如果您启用聊天客户端提示和完成数据的日志记录,可能会泄露敏感或私密信息。请务必小心! |
输入数据(已弃用)
spring.ai.chat.client.observations.include-input 属性已弃用,已被 spring.ai.chat.client.observations.log-prompt 取代。参见 提示内容。 |
ChatClient 输入数据通常很大,且可能包含敏感信息。
由于这些原因,默认情况下不导出。
Spring AI 支持记录输入数据以帮助进行调试和故障排除。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
|
是否在观察结果中包含输入内容。 |
|
| 如果您启用在观察结果中包含输入内容,则存在泄露敏感或私有信息的风险。请务必小心! |
聊天客户端顾问
当执行通知(advisor)时,会记录 spring.ai.advisor 个观察点。
它们测量在通知中花费的时间(包括在内部通知上花费的时间)并传播相关的跟踪信息。
| 姓名 | <description> </description> |
|---|---|
|
始终为 |
|
始终为 |
|
顾问在请求处理中应用其逻辑的位置,可以是 |
|
Spring AI 中的框架 API 类型: |
| 姓名 | <description> </description> |
|---|---|
|
顾问的名称。 |
|
顾问链中的顾问顺序。 |
ChatModel
目前仅支持来自以下 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 指标衡量单个模型调用所使用的输入和输出Tokens的数量。 |
| 姓名 | <description> </description> |
|---|---|
|
正在执行的操作的名称。 |
|
由客户端检测识别的模型提供者。 |
|
请求所针对的模型的名称。 |
|
生成响应的模型的名称。 |
| 姓名 | <description> </description> |
|---|---|
|
The frequency penalty setting for the model request. |
|
模型为请求生成的最大Tokens数。 |
|
模型请求的存在惩罚设置。 |
|
模型将用来停止生成更多标记的序列列表。 |
|
模型请求的温度设置。 |
|
模型请求的 top_k 采样设置。 |
|
模型请求的 top_p 采样设置。 |
|
模型停止生成Tokens的原因,对应于每次接收到的生成。 |
|
AI 响应的唯一标识符。 |
|
模型输入(提示词)中使用的Tokens数量。 |
|
模型输出(补全)中使用的Tokens数量。 |
|
模型交换中使用的Tokens总数。 |
|
发送给模型的完整提示词。可选。 |
|
从模型接收到的完整响应。可选。 |
|
请求中提供给模型的工具定义列表。 |
对于测量用户Tokens,上表列出了观测跟踪中存在的值。
使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。 |
聊天提示和完成数据
聊天提示和完成数据通常很大,并且可能包含敏感信息。 出于这些原因,默认情况下不会导出它们。
Spring AI 支持记录聊天提示和完成数据,这对于故障排除场景非常有用。当跟踪可用时,日志将包含跟踪信息以便更好地关联。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
|
记录提示内容。 |
|
|
记录完成的内容。 |
|
|
在观察中包含错误日志。 |
|
| 如果您启用了聊天提示和完成数据的日志记录,则存在泄露敏感或私人信息的风险。请务必小心! |
工具调用
在聊天模型交互的上下文中执行工具调用时,会记录 spring.ai.tool 个观测点。它们测量工具调用完成所花费的时间,并传播相关的追踪信息。
| 姓名 | <description> </description> |
|---|---|
|
正在执行的操作的名称。它总是 |
|
负责操作的提供者。它总是 |
|
Spring AI 执行的操作类型。它始终是 |
|
工具的名称。 |
姓名 |
<description> </description> |
|
工具描述。 |
|
用于调用工具的参数架构。 |
|
工具调用的输入参数。(仅在启用时) |
|
用于调用工具的参数架构。(仅在启用时) |
嵌入模型
可观测性功能目前仅支持来自以下
AI 模型提供商的 EmbeddingModel 实现:Azure OpenAI、Mistral AI、Ollama 和 OpenAI。
未来的版本将支持更多的 AI 模型提供商。 |
gen_ai.client.operation 次观测记录在嵌入模型方法调用上。
它们测量方法完成所花费的时间,并传播相关的跟踪信息。
gen_ai.client.token.usage 指标衡量单个模型调用所使用的输入和输出Tokens的数量。 |
| 姓名 | <description> </description> |
|---|---|
|
正在执行的操作的名称。 |
|
由客户端检测识别的模型提供者。 |
|
请求所针对的模型的名称。 |
|
生成响应的模型的名称。 |
| 姓名 | <description> </description> |
|---|---|
|
结果输出嵌入的维度数量。 |
|
模型输入中使用的Tokens数量。 |
|
模型交换中使用的Tokens总数。 |
对于测量用户Tokens,上表列出了观测跟踪中存在的值。
使用由 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。 |
图像模型
可观测性功能目前仅支持来自以下 AI 模型提供商的 ImageModel 实现:OpenAI。
未来的版本将支持更多的 AI 模型提供商。 |
gen_ai.client.operation 次观察记录在图像模型方法调用上。
它们测量方法完成所花费的时间,并传播相关的跟踪信息。
gen_ai.client.token.usage 指标衡量单个模型调用所使用的输入和输出Tokens的数量。 |
| 姓名 | <description> </description> |
|---|---|
|
正在执行的操作的名称。 |
|
由客户端检测识别的模型提供者。 |
|
请求所针对的模型的名称。 |
| 姓名 | <description> </description> |
|---|---|
|
生成的图像返回的格式。 |
|
要生成的图像的大小。 |
|
要生成的图像的风格。 |
|
AI 响应的唯一标识符。 |
|
生成响应的模型的名称。 |
|
模型输入(提示词)中使用的Tokens数量。 |
|
模型输出(生成)中使用的Tokens数量。 |
|
模型交换中使用的Tokens总数。 |
|
发送给模型的完整提示词。可选。 |
对于测量用户Tokens,上表列出了观测跟踪中存在的值。
使用由 ImageModel 提供的指标名称 gen_ai.client.token.usage。 |
向量存储
Spring AI 中的所有向量存储实现都通过 Micrometer 提供了指标和分布式追踪数据的监控功能。
在与向量存储交互时,会记录db.vector.client.operation个观察结果。
它们测量在query、add和remove操作上花费的时间,并传播相关的跟踪信息。
| 姓名 | <description> </description> |
|---|---|
|
正在执行的操作或命令的名称。可以是 |
|
由客户端工具识别的数据库管理系统(DBMS)产品。可以是 |
|
Spring AI 中的框架 API 类型: |
| 姓名 | <description> </description> |
|---|---|
|
数据库中集合(表、容器)的名称。 |
|
数据库的名称,在服务器地址和端口中完全限定。 |
|
如果存在,则为记录标识符。 |
|
相似性搜索中使用的度量标准。 |
|
向量的维度。 |
|
The name field as of the vector (e.g. a field name). |
|
正在执行的搜索查询的内容。 |
|
搜索查询中使用的元数据过滤器。 |
|
相似性搜索查询返回的文档。可选。 |
|
接受所有搜索分数的相似度阈值。阈值为 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 时间序列。
|
<p>参考文献</p>
-
OpenTelemetry — 生成式AI的语义约定(概览)
-
Micrometer — 命名仪表
聊天客户端指标
| 指标名称 | 类型 | 单元 | <description> </description> |
|---|---|---|---|
|
计时器 |
秒 |
在 ChatClient 操作(调用/流)中花费的总时间 |
|
计数器 |
计数 |
已完成的 ChatClient 操作数量 |
|
仪表 |
秒 |
ChatClient 操作的最大观察持续时间 |
|
仪表 |
计数 |
当前正在进行的 ChatClient 操作数量 |
进行中 vs 已完成: active_count 显示正在进行的调用; _seconds 系列仅反映已完成的调用。
聊天模型指标(模型提供方执行)
| 指标名称 | 类型 | 单元 | <description> </description> |
|---|---|---|---|
|
计时器 |
秒 |
执行聊天模型操作的总时间 |
|
计数器 |
计数 |
已完成的聊天模型操作数量 |
|
仪表 |
秒 |
聊天模型操作的最大观察持续时间 |
|
仪表 |
计数 |
当前正在进行的聊天模型操作数量 |