十二、可观测性

1. 是什么 / 怎么开

Spring AI 基于 Spring 生态的 Micrometer + Observation，对 AI 组件做指标（metrics）+ 链路追踪（tracing）。

开关：加 Actuator 依赖即可。

xml 复制代码

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

被插桩的组件：ChatClient（含 Advisor）、ChatModel、EmbeddingModel、ImageModel、VectorStore。

规则：低基数键 → 指标 + 追踪都有；高基数键 → 只在追踪里（避免指标维度爆炸）。

想看数据还要暴露端点：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  endpoint:
    health:
      show-details: always

2. 各组件的观测点与关键标签

组件	观测名	低基数键（进指标）	高基数键（只在 trace）
ChatClient	`spring.ai.chat.client`	`gen_ai.operation.name=framework`、`gen_ai.system=spring_ai`、`spring.ai.chat.client.stream`、`spring.ai.kind=chat_client`	`gen_ai.prompt`、`spring.ai.chat.client.advisors`、`spring.ai.chat.client.conversation.id`、`spring.ai.chat.client.tool.names`
Advisor	`spring.ai.advisor`	`gen_ai.operation.name`、`gen_ai.system`、`spring.ai.kind=advisor`	`spring.ai.advisor.name`、`spring.ai.advisor.order`
ChatModel	`gen_ai.client.operation`	`gen_ai.request.model`、`gen_ai.response.model`、`gen_ai.system`	温度/top_p/max_tokens 等请求参数、`gen_ai.response.finish_reasons`、`gen_ai.usage.input_tokens`、`gen_ai.usage.output_tokens`、`gen_ai.prompt`、`gen_ai.completion`
Tool 调用	`spring.ai.tool`	`gen_ai.system=spring_ai`、`spring.ai.kind=tool_call`、`spring.ai.tool.definition.name`	`spring.ai.tool.definition.description`、`spring.ai.tool.definition.schema`、`spring.ai.tool.call.arguments`、`spring.ai.tool.call.result`
EmbeddingModel	`gen_ai.client.operation`	同 ChatModel	`gen_ai.request.embedding.dimensions`、`gen_ai.usage.*`
VectorStore	`db.vector.client.operation`	`db.operation.name`(add/delete/query)、`db.system`(...)、`spring.ai.kind=vector_store`	`db.vector.query.content`、`db.vector.query.top_k`、`db.vector.query.similarity_threshold`、`db.vector.query.filter`、`db.vector.dimension_count`、`db.vector.query.response.documents`

db.system 取值：pg_vector / azure / cassandra / chroma / elasticsearch / milvus / neo4j / opensearch / qdrant / redis / typesense / weaviate / pinecone / oracle / mongodb / gemfire / hana / simple（SimpleVectorStore → simple）。

3. 敏感数据开关（默认全部关闭）

提示词、补全、工具参数、检索结果通常又大又敏感，默认不导出，需要显式打开（生产慎开）：

yaml 复制代码

spring:
  ai:
    chat:
      client:
        observations:
          log-prompt: false        # ChatClient 提示词
          log-completion: false    # ChatClient 补全
      observations:
        log-prompt: false          # ChatModel 提示词
        log-completion: false      # ChatModel 补全
        include-error-logging: false
    image:
      observations:
        log-prompt: false          # 图像提示
    vectorstore:
      observations:
        log-query-response: false  # 向量检索返回的文档
    tools:
      observations:
        include-content: false     # 工具调用参数 + 结果

⚠ 1.0.0-RC1 重命名（旧写法已失效）：

旧属性	新属性
`spring.ai.chat.client.observations.include-prompt`	`...log-prompt`
`spring.ai.chat.observations.include-prompt`	`...log-prompt`
`spring.ai.chat.observations.include-completion`	`...log-completion`
`spring.ai.image.observations.include-prompt`	`...log-prompt`
`spring.ai.vectorstore.observations.include-query-response`	`...log-query-response`
`spring.ai.chat.client.observations.include-input`（已弃用）	`...log-prompt`

4. 已弃用的高基数键（别再按老的查）

spring.ai.chat.client.system.text / system.params / user.text / user.params → 统一看 gen_ai.prompt
spring.ai.chat.client.tool.function.names / tool.function.callbacks → spring.ai.chat.client.tool.names
spring.ai.chat.client.advisor.params → 会话 ID 看 spring.ai.chat.client.conversation.id
spring.ai.advisor.type（BEFORE/AFTER/AROUND）→ 已无意义，所有 advisor 同一类型

5. Prometheus 指标速查

Micrometer 用点号命名（如 gen_ai.client.operation），Prometheus 导出为下划线 + 标准后缀：

计时器 → <base>_seconds_count / _seconds_sum / _seconds_max / _active_count
计数器 → <base>_total

基础名	导出的时间序列	含义
`gen_ai.client.operation`	`gen_ai_client_operation_seconds_{count,sum,max}`、`gen_ai_client_operation_active_count`	模型调用耗时 / 并发数
ChatClient	`gen_ai_chat_client_operation_seconds_{count,sum,max}`、`gen_ai_chat_client_operation_active_count`	ChatClient 调用耗时 / 并发数
`gen_ai.client.token.usage`	`gen_ai_client_token_usage_total`	Token 消耗，标签 `gen_ai_token_type=input/output/total`
`db.vector.client.operation`	`db_vector_client_operation_seconds_{count,sum,max}`、`db_vector_client_operation_active_count`	向量库 add/delete/query 耗时，标签 `db_operation_name`、`db_system`、`spring_ai_kind=vector_store`

怎么读：

*_active_count = 正在进行的操作数（看并发/负载）
_seconds_sum / _seconds_count = 平均延迟
_seconds_max = 上次抓取以来的最大耗时（高水位）

6. 模型支持范围（不是所有厂商都有观测）

ChatModel：Anthropic、Azure OpenAI、Mistral AI、Ollama、OpenAI、Vertex AI、MiniMax、Moonshot、QianFan、Zhipu AI
EmbeddingModel：Azure OpenAI、Mistral AI、Ollama、OpenAI
ImageModel：OpenAI

本项目用的是 OpenAI 协议兼容的 DeepSeek，走 spring-ai-starter-model-openai → ChatModel / EmbeddingModel 观测都可用（gen_ai.system 记为 openai）。

7. 落地建议

生产环境默认别开 log-prompt / log-completion / include-content / log-query-response，只在排查问题时临时打开。
排查顺序：先看 gen_ai_client_operation_seconds_max（哪次慢）→ 再看 trace 里的 gen_ai.prompt、db.vector.query.content（慢在哪）。
想看分布式链路还需要 tracing 桥接（micrometer-tracing-bridge-otel + exporter），否则只有指标没有 trace，高基数键也就看不到。