Spring AI能力不断增强，包括其可观测性，主要包含一些指标和追踪能力。下面我们将详细的介绍一下 Spring AI框架的 Observability
概念
Spring AI 基于 Spring 生态系统中的可观察性功能构建，以提供对 AI 相关操作的了解。 Spring AI为其核心组件 ChatClient(包括 Advisor)、ChatModel、EmbeddingModel、ImageModel 和 VectorStore 提供指标和追踪功能。
Spring AI 官方文档说明：低基数键将添加到指标和跟踪中，而高基数键将仅添加到跟踪中。
低基数键和高基数键
在数据库和监控系统中，Low cardinality keys（低基数键）和High cardinality keys（高基数键）是描述数据列中不同值的数量或独特性的术语。
Low cardinality keys（低基数键）
- 指的是数据列中不同值的数量相对较少的键。例如，一个表示性别的列可能只有“男”和“女”两个值，或者一个表示国家代码的列可能只有几百个不同的值。
- 比如在ClickHouse数据库中，
LowCardinality是一种数据类型修饰符，用于优化存储和查询性能。
High cardinality keys（高基数键）
- 指的是数据列中不同值的数量非常多的键。例如，一个表示用户ID的列可能会有成千上万个不同的值，因为每个用户都有一个唯一的ID。
- 在时序数据库中，高基数问题尤其突出，因为时间线的数量（即所有标签列的基数乘积）可能会导致内存使用量急剧增加，影响写入性能和查询速度。高基数的数据集意味着数据量大，这会对数据库的写入、查询和存储三个方面带来影响，尤其是在写入时对索引的影响最大
在监控和追踪系统中，低基数键可能会被用于度量指标和追踪，因为它们具有较少的不同值，这有助于减少存储和计算资源的使用。而高基数键则可能只被用于追踪，因为它们包含大量的不同值，这可能会导致资源使用量大幅增加。
引申问题：如何优化数据库中高基数列的查询效率，如何存储高基数健列的数据？
Chat Client - 聊天客户端
Spring.ai.chat.client的可观测性，主要记录ChatClient在调用 call() 或者 stream() 方法时所花费的时间，并传播一些相关的追踪信息。
Low cardinality keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.operation.name | 生成式AI操作的名称- framework |
gen_ai.system | 生成式AI系统指标- spring_ai |
spring.ai.chat.client.stream | 是否流式返回 - true or false |
spring.ai.kind | Spring AI 中的框架 API 类型- chat_client |
High cardinality keys
| 指标项名称 | 描述 |
|---|---|
spring.ai.chat.client.advisor.params | advisor参数 |
spring.ai.chat.client.advisors | chat client 配置 advisor列表 |
spring.ai.chat.client.system.params | Chat client 系统配置参数（可选） |
spring.ai.chat.client.system.text | Chat client 输入的System类型的Message（可选） |
spring.ai.chat.client.tool.function.names | 开启函数/工具的名称列表 |
spring.ai.chat.client.tool.function.callbacks | chat client 配置的函数回调列表 |
spring.ai.chat.client.user.params | Chat client 用户参数 （可选） |
spring.ai.chat.client.user.text | Chat client 输入的User类型的Message （可选） |
ChatClient 输入数据通常很大，并且可能包含敏感信息。由于这些原因，默认未开启。但开发者可以根据需求进行开启，但是开启之后可能会存在暴露敏感或私人信息的风险。一定注意！！！！
spring.ai.chat.client.observations.include-input 设置为true即可开启，默认false。
Chat Advisors - 聊天客户顾问(拦截器)
对于Advisors在专栏的文章中基本上也没有太多的提及，这项能力也是在 Spring AI 框架不断发展优化设计而来，后面会出一篇关于 Advisors介绍和使用的文章，本篇文章还是重点关注可观测性的内容。
spring.ai.advisor观测值记录在调用 call() 或者 stream() 方法，在advisor中花费的时间（包括花费在内部advisors的时间）并传播相关的跟踪信息。
Low cardinality keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.operation.name | 生成式AI操作的名称，值： framework |
gen_ai.system | 生成式AI系统指标，值：spring_ai |
spring.ai.advisor.type | advisor 在请求处理的逻辑，值：BEFORE、AFTER 或 AROUND 之一 |
spring.ai.kind | Spring AI 中的框架 API 类型，值：advisor |
High cardinality keys
| ｜指标项名称 | 描述 |
|---|---|
spring.ai.advisor.name | advisor名称 |
spring.ai.advisor.order | advisor在advisor链中的位置或者说在链中的顺序 |
Chat Model - 聊天模型
gen_ai.client.operation的观测性结果是在调用 ChatModel call() 或者 stream() 方法记录方法所花费的时间并传播相关的跟踪信息。
Spring AI 框架并未支持所有的 AI 大模型实现可观测性功能，目前仅支持如下 AI 大模型；
- Moonshot ---- 月之暗面大模型 国产
- QianFan ---- 百度千帆大模型 国产
- ZhuPu AI ---- 清华智普大模型 国产
- OpenAI
- Ollama
- Mistral AI
- Vertex AI
- MiniMax
- Anthropic
- Azure OpenAI
未来的版本会支持其它的 AI 大模型的可观测性功能。
Low cardinality keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称 |
gen_ai.system | 由客户端检测标识的模型提供程序 |
gen_ai.request.model | 要向其发出请求的模型的名称 |
gen_ai.response.model | 生成响应的模型的名称 |
High cardinality keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.request.frequency_penalty | 模型请求的频率损失设置 |
gen_ai.request.max_tokens | 模型为请求生成的最大令牌数 |
gen_ai.request.presence_penalty | 模型请求的存在惩罚设置 |
gen_ai.request.stop_sequences | 模型将用于停止生成更多标记的序列列表 |
gen_ai.request.temperature | 模型请求的创新性能力指标设置 |
gen_ai.request.top_k | 模型请求的 top_k 采样设置 |
gen_ai.request.top_p | 模型请求的 top_p 采样设置 |
gen_ai.response.finish_reasons | 模型停止生成令牌的原因 |
gen_ai.response.id | AI 响应的唯一标识符 |
gen_ai.usage.input_tokens | 模型输入 （prompt） 中使用的标记数 |
gen_ai.usage.output_tokens | 模型输出 （completion） 中使用的标记数 |
gen_ai.usage.total_tokens | 模型交换中使用的标记总数 |
gen_ai.prompt | 发送到模型的完整提示。自选 |
gen_ai.completion | 从模型收到的完整响应。自选 |
Events
| 指标项名称 | 描述 |
|---|---|
gen_ai.content.prompt | 事件，包括聊天提示的内容。自选 |
gen_ai.content.completion | 事件，包括聊天完成的内容。自选 |
Chat Prompt and Completion Data
Spring AI 支持记录聊天提示和完成数据，这对于故障排除场景非常有用！要学会合理使用。
对于聊天提示和模型回答数据通常很大，并且可能包含敏感信息的原因，默认情况时关闭状态。 Spring AI支持聊天提示和模型回答数据导出为span事件或者导出span属性，方便追踪框架（OpenTelemetry/OpenZipkin）追踪。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.chat.observations.include-prompt | 观察提示内容 | false |
spring.ai.chat.observations.include-completion | 观察模型返回内容 | false |
spring.ai.chat.observations.include-error-logging | 记录错误记录 | false |
EmbeddingModel - 嵌入模型
gen_ai.client.operation 观察结果记录在嵌入模型方法调用时，记录方法调用完成花费的时间，并传播相关的跟踪信息。
Spring AI 框架在1.0.0-SNAPSHOT 版本只支持如下 AI 模型提供商的嵌入模型；
- OpenAI
- Ollama
- Azure OpenAI
- Mistral AI
在未来的版本中，会陆续支持其它 AI 模型提供商的嵌入模型。
Low Cardinality Keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称 |
gen_ai.system | 由客户端检测标识的模型提供程序 |
gen_ai.request.model | 要向其发出请求的模型的名称 |
gen_ai.response.model | 生成 响应 的模型的名称 |
High Cardinality Keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.request.embedding.dimensions | 生成的输出嵌入具有的维度数 |
gen_ai.usage.input_tokens | 模型输入中使用的标记数 |
gen_ai.usage.total_tokens | 模型交换中使用的标记总数 |
Image Model - 图像大模型
gen_ai.client.operation 观察结果记录在图像模型方法调用时，记录方法调用完成花费的时间，并传播相关的跟踪信息。
Spring AI 框架在1.0.0-SNAPSHOT 版本只支持 OpenAI 的ImageModel。未来会支持更多的 AI ImageModel的监测。
Low Cardinality Keys
| 指标项名称 | 描述 |
|---|---|
gen_ai.operation.name | 正在执行的操作的名称 |
gen_ai.system | 由客户端检测标识的模型提供程序 |
gen_ai.request.model | 要向其发出请求的模型的名称 |
High Cardinality Keys
| 指标项名称 | 描述 |
|---|---|
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） 中使用的标记数 |
gen_ai.usage.output_tokens | 模型输出 （generation） 中使用的令牌数 |
gen_ai.usage.total_tokens | 模型交换中使用的token总数 |
gen_ai.prompt | 发送到模型的完整提示。自选 |
Image Prompt Data - 图片提示数据
图片提示数据通常都比较大，并且可能包含敏感信息。基于以上原因，则默认不开启提示数据的追踪记录。如果因业务需求可以通过如下属性开关控制。
| 属性名称 | 属性描述 | 默认着 |
|---|---|---|
spring.ai.image.observations.include-prompt | true：开启/ false：不开启 | false |
开启后，一定要注意风险～～～
Vector Stores - 向量存储
db.vector.client.operation 在与 Vector Store交互时记录观测结果。主要记录查询、添加、删除操作花费的时间，并传播相关的跟踪信息。
Low Cardinality Keys
| 指标名称 | 描述 |
|---|---|
db.operation.name | 正在执行的操作或命令的名称。add、delete 或 query 之一 |
db.system | 使用的数据库名称。比如：pg_vector、milvus、neo4j |
spring.ai.kind | Spring AI 中的框架 API 类型：vector_store |
High Cardinality Keys
| 指标名称 | Description 描述 |
|---|---|
db.collection.name | 操作集合名称，比如相当于数据库表 |
db.namespace | 数据库的名称，在服务器地址和端口中完全限定 |
db.record.id | 记录标识符（如果存在） |
db.search.similarity_metric | 相似性搜索中使用的维度 |
db.vector.dimension_count | 向量数据库存储使用的维度 |
db.vector.field_name | 作为向量的 name 字段（例如，字段名称） |
db.vector.query.content | 正在执行的搜索查询的内容 |
db.vector.query.filter | 搜索查询中使用的元数据筛选条件 |
db.vector.query.response.documents | 从相似性搜索查询返回的文档。自选 |
db.vector.query.similarity_threshold | 搜索匹配相似度阈值，1.0: 表示完全匹配 |
db.vector.query.top_k | 查询返回的前k个最相似的向量 |
Events
| 指标名称 | 描述 |
|---|---|
db.vector.content.query.response | 事件，包括向量搜索响应数据。自选 |
响应数据
向量搜索响应数据通常很大，并且可能包含敏感信息。由于这些原因，默认情况下不开启。
| 属性名称 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.observations.include-query-response | true:开启，false:不开启 | false |
开启时一定的注意～～～，信息安全～～～
总结
本篇文章介绍了 Spring AI 框架对 Chat Client、Chat Advisor、ChatModel、EmbeddingModel、ImageModel 以及 Vector Store 等操作监控追踪指标进行详细的介绍。了解这些指标后，就可以结合一些监控工具比如 Prometheus + Kibna， 后续会搭建实践一下。
