可观测性
Spring AI 构建在 Spring 生态系统的可观测性功能之上，以提供对 AI 相关操作的洞察。Spring AI 为其核心组件提供了指标和跟踪功能，这些组件包括：ChatClient（包括 Advisor）、ChatModel、EmbeddingModel、ImageModel 和 VectorStore。
低基数键将被添加到指标和跟踪中，而高基数键将仅添加到跟踪中。
聊天客户端
当调用 ChatClient 的 call() 或 stream() 操作时，会记录 spring.ai.chat.client 的观测信息。这些观测信息用于测量执行调用所花费的时间，并传播相关的追踪信息。
表 1. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 始终为 framework。 |
gen_ai.system | 始终为 spring_ai。 |
spring.ai.chat.client.stream | 聊天模型响应是否为流式 - true 或 false |
spring.ai.kind | Spring AI 中框架 API 的类型：chat_client。 |
表 2. 高基数键
| 名称 | 描述 |
|---|---|
spring.ai.chat.client.advisor.params | 顾问参数的映射。 |
spring.ai.chat.client.advisors | 配置的聊天客户端顾问列表。 |
spring.ai.chat.client.system.params | 聊天客户端系统参数。可选。 |
spring.ai.chat.client.system.text | 聊天客户端系统文本。可选。 |
spring.ai.chat.client.tool.function.names | 启用的工具函数名称。 |
spring.ai.chat.client.tool.function.callbacks | 配置的聊天客户端函数回调列表。 |
spring.ai.chat.client.user.params | 聊天客户端用户参数。可选。 |
spring.ai.chat.client.user.text | 聊天客户端用户文本。可选。 |
输入数据
ChatClient 的输入数据通常较大，并且可能包含敏感信息。出于这些原因，默认情况下不会导出这些数据。
Spring AI 支持将所有追踪后端的输入数据导出为 span 属性。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.client.observations.include-input | 是否在观察中包含输入内容。 | false |
如果启用将输入内容包含在观察中，可能会暴露敏感或私人信息。请务必小心！
聊天客户端顾问
当执行围绕 advisor 的调用或流时，会记录 spring.ai.advisor 的观察结果。它们测量在 advisor 中花费的时间（包括在内部 advisor 上花费的时间）并传播相关的跟踪信息。
表 3. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 始终为 framework。 |
gen_ai.system | 始终为 spring_ai。 |
spring.ai.advisor.type | 顾问在请求处理中应用其逻辑的位置，取值为 BEFORE、AFTER 或 AROUND 之一。 |
spring.ai.kind | Spring AI 中框架 API 的类型：advisor。 |
表 4. 高基数键
| 名称 | 描述 |
|---|---|
spring.ai.advisor.name | 顾问的名称。 |
spring.ai.advisor.order | 顾问在顾问链中的顺序。 |
聊天模型
目前仅支持以下 AI 模型提供商的 ChatModel 实现的可观测性功能：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhiu AI。未来版本将支持更多的 AI 模型提供商。
在调用 ChatModel 的 call 或 stream 方法时，会记录 gen_ai.client.operation 的观测数据。这些数据测量了方法完成所花费的时间，并传播了相关的追踪信息。
gen_ai.client.token.usage 指标用于衡量单次模型调用所使用的输入和输出 token 数量。
表 5. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 客户端仪器识别的模型提供商。 |
gen_ai.request.model | 请求所针对的模型名称。 |
gen_ai.response.model | 生成响应的模型名称。 |
表 6. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.frequency_penalty | 模型请求的频率惩罚设置。 |
gen_ai.request.max_tokens | 模型为请求生成的最大 token 数量。 |
gen_ai.request.presence_penalty | 模型请求的存在惩罚设置。 |
gen_ai.request.stop_sequences | 模型用于停止生成更多 token 的序列列表。 |
gen_ai.request.temperature | 模型请求的温度设置。 |
gen_ai.request.top_k | 模型请求的 top_k 采样设置。 |
gen_ai.request.top_p | 模型请求的 top_p 采样设置。 |
gen_ai.response.finish_reasons | 模型停止生成 token 的原因，对应于接收到的每个生成结果。 |
gen_ai.response.id | AI 响应的唯一标识符。 |
gen_ai.usage.input_tokens | 模型输入（提示）中使用的 token 数量。 |
gen_ai.usage.output_tokens | 模型输出（完成）中使用的 token 数量。 |
gen_ai.usage.total_tokens | 模型交换中使用的总 token 数量。 |
gen_ai.prompt | 发送给模型的完整提示。可选。 |
gen_ai.completion | 从模型接收到的完整响应。可选。 |
为了测量用户令牌，上表列出了观察跟踪中存在的值。使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。
表 7. 事件
| 名称 | 描述 |
|---|---|
gen_ai.content.prompt | 包含聊天提示内容的事件。可选。 |
gen_ai.content.completion | 包含聊天完成内容的事件。可选。 |
聊天提示与完成数据
聊天提示和完成数据通常很大，可能包含敏感信息。出于这些原因，默认情况下不会导出这些数据。
如果你使用 OpenTelemetry 作为追踪后端，Spring AI 支持将聊天提示和完成数据导出为 span 事件；而如果你使用 OpenZipkin 作为追踪后端，数据则会导出为 span 属性。
此外，Spring AI 支持记录聊天提示和完成数据，这对于故障排除场景非常有用。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.observations.include-prompt | 在观察中是否包含提示内容。true 或 false | false |
spring.ai.chat.observations.include-completion | 在观察中是否包含完成内容。true 或 false | false |
spring.ai.chat.observations.include-error-logging | 在观察中是否包含错误日志。true 或 false | false |
如果启用将聊天提示和完成数据包含在观察中，可能会暴露敏感或私人信息。请务必小心！
嵌入模型
目前，可观测性功能仅支持以下 AI 模型提供商的 EmbeddingModel 实现：Azure OpenAI、Mistral AI、Ollama 和 OpenAI。未来的版本将支持更多的 AI 模型提供商。
gen_ai.client.operation 观测记录在嵌入模型方法调用上。它们测量方法完成所花费的时间，并传播相关的追踪信息。
gen_ai.client.token.usage 指标用于衡量单次模型调用中使用的输入和输出 token 数量。
表 8. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 客户端检测到的模型提供者。 |
gen_ai.request.model | 请求所针对的模型的名称。 |
gen_ai.response.model | 生成响应的模型的名称。 |
表 9. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.embedding.dimensions | 生成的输出嵌入向量的维度数。 |
gen_ai.usage.input_tokens | 模型输入中使用的 token 数量。 |
gen_ai.usage.total_tokens | 模型交互中使用的总 token 数量。 |
对于测量用户令牌，上表列出了观察跟踪中的值。使用由 EmbeddingModel 提供的指标名称 gen_ai.client.token.usage。
图像模型
目前仅支持以下 AI 模型提供商的 ImageModel 实现的可观测性功能：OpenAI。未来版本将支持更多的 AI 模型提供商。
gen_ai.client.operation 的观测记录在图像模型方法调用时进行。它们测量方法完成所花费的时间，并传播相关的跟踪信息。
gen_ai.client.token.usage 指标用于衡量单次模型调用中使用的输入和输出 token 数量。
表 10. 低基数键
| 名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称。 |
gen_ai.system | 由客户端仪表识别的模型提供商。 |
gen_ai.request.model | 请求所针对的模型的名称。 |
表 11. 高基数键
| 名称 | 描述 |
|---|---|
gen_ai.request.image.response_format | 生成图像返回的格式。 |
gen_ai.request.image.size | 要生成的图像的尺寸。 |
gen_ai.request.image.style | 要生成的图像的风格。 |
gen_ai.response.id | AI 响应的唯一标识符。 |
gen_ai.response.model | 生成响应的模型名称。 |
gen_ai.usage.input_tokens | 模型输入（提示）中使用的 token 数量。 |
gen_ai.usage.output_tokens | 模型输出（生成内容）中使用的 token 数量。 |
gen_ai.usage.total_tokens | 模型交互中使用的 token 总数。 |
gen_ai.prompt | 发送给模型的完整提示。可选。 |
为了测量用户令牌（token），之前的表格列出了观测跟踪（observation trace）中存在的值。请使用由 ImageModel 提供的指标名称 gen_ai.client.token.usage。
表 12. 事件
| 名称 | 描述 |
|---|---|
gen_ai.content.prompt | 包含图像提示内容的事件。可选。 |
图像提示数据
图像提示数据通常较大，且可能包含敏感信息。由于这些原因，默认情况下不会导出这些数据。
Spring AI 支持将图像提示数据导出为 span 事件，前提是你使用了 OpenTelemetry 作为追踪后端；而如果使用 OpenZipkin 作为追踪后端，数据则会作为 span 属性导出。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.image.observations.include-prompt | true 或 false | false |
如果您启用了在观测数据中包含图像提示数据的功能，可能会暴露敏感或私人信息。请务必小心！
向量存储
Spring AI 中的所有向量存储实现都经过配置，通过 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、hana、simple 之一。 |
spring.ai.kind | Spring AI 中的框架 API 类型：vector_store。 |
表 14. 高基数键
| 名称 | 描述 |
|---|---|
db.collection.name | 数据库中集合（表、容器）的名称。 |
db.namespace | 数据库的名称，完全限定在服务器地址和端口内。 |
db.record.id | 记录标识符（如果存在）。 |
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 | 查询返回的最相似的前 k 个向量。 |
表 15. 事件
| 名称 | 描述 |
|---|---|
db.vector.content.query.response | 包含向量搜索响应数据的事件。可选。 |
响应数据
向量搜索响应数据通常较大，且可能包含敏感信息。因此，默认情况下不会导出这些数据。
如果你使用 OpenTelemetry 作为追踪后端，Spring AI 支持将向量搜索响应数据导出为 span 事件；而如果你使用 OpenZipkin 作为追踪后端，数据则会导出为 span 属性。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.observations.include-query-response | true 或 false | false |
如果启用将向量搜索响应数据包含在观测结果中，可能会暴露敏感或私人信息。请务必小心！