可观测性

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. 高基数键
名称 描述

gen_ai.prompt

通过聊天客户端发送的 Prompt 内容。可选。

spring.ai.chat.client.advisor.params (已弃用)

顾问参数 Map。对话 ID 现在包含在 spring.ai.chat.client.conversation.id 中。

spring.ai.chat.client.advisors

配置的聊天客户端顾问列表。

spring.ai.chat.client.conversation.id

使用聊天记忆时的对话标识符。

spring.ai.chat.client.system.params (已弃用)

聊天客户端系统参数。可选。已由 gen_ai.prompt 取代。

spring.ai.chat.client.system.text (已弃用)

聊天客户端系统文本。可选。已由 gen_ai.prompt 取代。

spring.ai.chat.client.tool.function.names (已弃用)

已启用的工具函数名称。已由 spring.ai.chat.client.tool.names 取代。

spring.ai.chat.client.tool.function.callbacks (已弃用)

配置的聊天客户端函数回调列表。已由 spring.ai.chat.client.tool.names 取代。

spring.ai.chat.client.tool.names

传递给聊天客户端的工具名称。

spring.ai.chat.client.user.params (已弃用)

聊天客户端用户参数。可选。已由 gen_ai.prompt 取代。

spring.ai.chat.client.user.text (已弃用)

聊天客户端用户文本。可选。已由 gen_ai.prompt 取代。

Prompt 内容

ChatClient 的 Prompt 内容通常很大，并可能包含敏感信息。因此，默认情况下不导出它。

Spring AI 支持将 Prompt 内容导出为跨所有追踪后端 Span 属性/事件。

属性 描述 默认值

spring.ai.chat.client.observations.include-prompt

是否在可观测项中包含聊天客户端 Prompt 内容。

false
如果启用在可观测项中包含聊天客户端 Prompt 内容，则存在暴露敏感或私人信息的风险。请小心谨慎！

输入数据 (已弃用)

属性 spring.ai.chat.client.observations.include-input 已弃用，由 spring.ai.chat.client.observations.include-prompt 替代。请参阅 Prompt 内容。

ChatClient 的输入数据通常很大，并可能包含敏感信息。因此，默认情况下不导出它。

Spring AI 支持将输入数据导出为跨所有追踪后端 Span 属性/事件。

属性 描述 默认值

spring.ai.chat.client.observations.include-input

是否在可观测项中包含输入内容。

false
如果启用在可观测项中包含输入内容，则存在暴露敏感或私人信息的风险。请小心谨慎！

聊天客户端顾问

当顾问执行时，会记录 spring.ai.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

模型输入 (Prompt) 中使用的 Token 数量。

gen_ai.usage.output_tokens

模型输出 (Completion) 中使用的 Token 数量。

gen_ai.usage.total_tokens

模型交互中使用的总 Token 数量。

gen_ai.prompt

发送给模型的完整 Prompt。可选。

gen_ai.completion

从模型接收到的完整响应。可选。
为了测量用户 Token，上表列出了可观测追踪中存在的值。使用由 ChatModel 提供的指标名称 gen_ai.client.token.usage。
表 7. 事件
名称 描述

gen_ai.content.prompt

包含聊天 Prompt 内容的事件。可选。

gen_ai.content.completion

包含聊天 Completion 内容的事件。可选。

聊天 Prompt 和 Completion 数据

聊天 Prompt 和 Completion 数据通常很大，并可能包含敏感信息。因此，默认情况下不导出它。

如果使用 OpenTelemetry 追踪后端，Spring AI 支持将聊天 Prompt 和 Completion 数据导出为 Span 事件；如果使用 OpenZipkin 追踪后端，数据则导出为 Span 属性。

此外，Spring AI 支持记录聊天 Prompt 和 Completion 数据，这对于故障排除场景非常有用。

属性 描述 默认值

spring.ai.chat.observations.include-prompt

在可观测项中包含 Prompt 内容。true 或 false

false

spring.ai.chat.observations.include-completion

在可观测项中包含 Completion 内容。true 或 false

false

spring.ai.chat.observations.include-error-logging

在可观测项中包含错误日志记录。true 或 false

false
如果启用在可观测项中包含聊天 Prompt 和 Completion 数据，则存在暴露敏感或私人信息的风险。请小心谨慎！

嵌入模型

当前仅支持来自以下 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 数量。
为了测量用户 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

模型输入 (Prompt) 中使用的 Token 数量。

gen_ai.usage.output_tokens

模型输出 (生成) 中使用的 Token 数量。

gen_ai.usage.total_tokens

模型交互中使用的总 Token 数量。

gen_ai.prompt

发送给模型的完整 Prompt。可选。
为了测量用户 Token，上表列出了可观测追踪中存在的值。使用由 ImageModel 提供的指标名称 gen_ai.client.token.usage。
表 12. 事件
名称 描述

gen_ai.content.prompt

包含图像 Prompt 内容的事件。可选。

图像 Prompt 数据

图像 Prompt 数据通常很大，并可能包含敏感信息。因此，默认情况下不导出它。

如果使用 OpenTelemetry 追踪后端，Spring AI 支持将图像 Prompt 数据导出为 Span 事件；如果使用 OpenZipkin 追踪后端，数据则导出为 Span 属性。

属性 描述 默认值

spring.ai.image.observations.include-prompt

true 或 false

false
如果启用在可观测项中包含图像 Prompt 数据，则存在暴露敏感或私人信息的风险。请小心谨慎！

向量存储

Spring AI 中的所有向量存储实现都已进行工具化，通过 Micrometer 提供指标和分布式追踪数据。

与向量存储交互时，会记录 db.vector.client.operation 可观测项。它们测量在 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

查询返回的 Top-k 最相似向量。
表 15. 事件
名称 描述

db.vector.content.query.response

包含向量搜索响应数据的事件。可选。

响应数据

向量搜索响应数据通常很大，并可能包含敏感信息。因此，默认情况下不导出它。

如果使用 OpenTelemetry 追踪后端，Spring AI 支持将向量搜索响应数据导出为 Span 事件；如果使用 OpenZipkin 追踪后端，数据则导出为 Span 属性。

属性 描述 默认值

spring.ai.vectorstore.observations.include-query-response

true 或 false

false
如果启用在可观测项中包含向量搜索响应数据，则存在暴露敏感或私人信息的风险。请小心谨慎！