CH 10可观测性与评估

10.1为什么 AI 应用比传统应用更难观测

传统应用的「健康」是二值的：要么返回 200，要么抛异常。AI 应用的「健康」是连续且主观的——它很可能返回 200，但内容完全是错的。这一节先把「难在哪」讲清楚，后面所有的观测手段都是为了补这些缺口。

先搞懂：什么是「可观测性」

观测能回答的四个问题

上面那张表解释了「难在哪」，下面四个问题才是我们动手建设的目标清单——后面每一节都在回答其中一个。

1. 出了什么问题？——用户投诉「答错了」，我要能立刻找到那一次的完整请求（提示词、检索结果、工具调用、模型输出）。（由 10.2 链路 + 10.3 埋点回答）
2. 花了多少钱？——按天/按租户/按接口统计 Token 与费用，能预警、能定价、能找优化点。（由 10.4 指标 + 成本回答）
3. 效果好不好？——用固定评测集跑分，改一次提示词/换一次模型就知道是变好还是变坏。（由 10.6–10.8 评估回答）
4. 瓶颈在哪个环节？——检索慢？模型慢？工具慢？还是步数太多？（由 10.4 的耗时指标 + 10.2 的链路回答）

10.2三大支柱与 Spring AI 的内置能力

可观测性在经典运维里有「三件套」，AI 应用要在其之上补一件「评估」。下面这张图是本章所有工作的总纲。

三大支柱分别回答什么问题（成对对照）

三者关系：指标告诉你「系统慢了」（仪表盘报警），链路告诉你「慢在检索那一段」（定位环节），日志告诉你「那条检索为什么慢 / 检索到了什么」（看细节）。只装其一都会缺一块——这是经典 Observability 三件套必须齐备的原因。

Spring AI 内置的观测能力

为什么这么写（为什么不用自己接 SDK）：Spring AI 基于 Micrometer Observation 构建，只要你引对了依赖、配对了 management.*，每次 ChatModel 调用、每次工具调用都会自动产生一个 Observation（在 Tracing 体系里就是一个 Span）。你不用在业务代码里手写埋点就能拿到链路——这是 2.0 开箱即用的能力。

下面把「加依赖 → 改配置 → 启动 → 发请求 → 看链路」拆成可直接照做的步骤。本章没有配套 lab 代码，以下操作都按「在课程工程里自建」的口径进行——类文件用 IDEA 新建，配置片段粘贴到现有文件。

1. 在 IDEA 左侧 Project 视图里找到工程根目录的 pom.xml，双击打开。

2. 找到已有的 <dependencies> 标签，在它内部、与现有 <dependency> 平级的位置，粘贴下面四个依赖（缺一不可：① 是 actuator 端点；② 是把 Observation 桥接到 OpenTelemetry 的实现；③ 是把 span 发到 Zipkin 的导出器；④ 是 Prometheus 抓取口）：

   <!-- 依赖（pom 里已有） -->
   <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-actuator</artifactId>
   </dependency>
   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-tracing-bridge-otel</artifactId>
   </dependency>
   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-exporter-zipkin</artifactId>
   </dependency>
   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-registry-prometheus</artifactId>
   </dependency>

3. 打开 src/main/resources/application.yml，在文件末尾（注意与 spring: 段同级缩进，顶格写 management:）粘贴以下观测配置。先整段复制，再逐项理解注释：

   # application.yml —— 观测相关配置
   management:
     endpoints:
       web:
         exposure:
           # 暴露这些端点：健康检查、指标、Prometheus 抓取口
           include: health,info,metrics,prometheus
     endpoint:
       health:
         show-details: always
     # ---------- 链路追踪 ----------
     tracing:
       # 采样率：1.0 = 全采（开发/测试）；生产建议 0.1~0.2 降低成本
       sampling:
         probability: 1.0
     zipkin:
       tracing:
         # Zipkin 接收地址
         endpoint: http://localhost:9411/api/v2/spans
     # 把 Observation 的数据（含 Prompt/响应）也发出去
     observations:
       annotations:
         enabled: true
   
   spring:
     ai:
       chat:
         observations:
           # ★ 是否把提示词、模型响应记录到 span 中
           #   开发期 true（方便排查），生产环境建议 false 或做脱敏
           log-prompt: true
           log-completion: true
       # 工具调用也会产生 span
       tools:
         observations:
           include-content: true

4. 启动 Zipkin（链路收集与展示服务）。有 Docker 直接起容器；没有则用 jar：

   # 方式一：Docker（推荐，一条命令）
   docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin
   
   # 方式二：没有 Docker，先下载 zipkin.jar（官网），再：
   java -jar zipkin.jar

   浏览器打开 http://localhost:9411，能看到 Zipkin 首页即成功。

5. 在 Pom 所在目录启动应用（重开终端确保环境变量已加载，密钥用 ${DEEPSEEK_API_KEY:} 占位符读取）：

   # 在工程根目录（含 pom.xml 的那层）执行
   mvn spring-boot:run

运行验证：先看 actuator，再看 Zipkin 链路

为什么先验证？链路是后面一切排障的入口。请按顺序确认两个入口都通，再往下走。

第 1 步：确认 Actuator 端点已暴露（这是最容易漏的验收点）：

# 访问 actuator 根路径，期望返回含 health / info / metrics / prometheus 的 JSON
curl http://localhost:8080/actuator

# 期望输出（节选，重点是_links 里出现这四个端点）
{
  "_links": {
    "self":  { "href": "http://localhost:8080/actuator" },
    "health":{ "href": "http://localhost:8080/actuator/health" },
    "info":  { "href": "http://localhost:8080/actuator/info" },
    "metrics":{ "href": "http://localhost:8080/actuator/metrics" },
    "prometheus": { "href": "http://localhost:8080/actuator/prometheus" }
  }
}

看到什么算通过：浏览器或 curl 返回里能找到 prometheus 这一条链接，说明端点暴露配置生效。

第 2 步：发一个请求，再去 Zipkin 看链路：

# 启动应用并发一个请求（接口路径按你自建工程的控制器来，这里是示例）
curl -X POST http://localhost:8080/api/v1/knowledge/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"退款要几天到账","tenantId":"default"}'

# 2. 打开 Zipkin 界面 http://localhost:9411
#    选择 serviceName = springai-lab，点击 Run Query

# 3. 预期：一条 trace，展开后包含多个 span：
#    http post /api/v1/knowledge/ask          ← 你的接口
#      └─ spring.ai.chat.client               ← ChatClient 层
#           └─ spring.ai.chat                  ← 模型调用（含 model、token 数）
#   或者（带工具时）：
#      └─ ToolCallingAdvisor 循环
#           ├─ execute_tool queryOrderStatus   ← ★ 2.0 的 span 名变了
#           └─ execute_tool searchPolicy

# 预期输出（curl 返回）：一段带引用的知识问答 JSON，包含 answer 与 citations 字段。

看到什么算通过：Zipkin 里出现一条 trace，展开能看到「接口 → spring.ai.chat.client → spring.ai.chat」的层级；若带工具，能看到 execute_tool <工具名> 的 span。

10.3自己埋点：让链路包含业务信息

框架自动产生的 span 只有技术信息（耗时、模型名、Token）。要定位业务问题，还得加上业务维度：哪个租户、哪个用户、哪个场景、用了哪版提示词。这一节教你怎么用手工埋点把这些信息加进去。

① 用 ObservationRegistry 手工埋点

下面这个类把「检索」这一步包成一个自定义 span，并带上业务标签。操作步骤如下：

1. 在 IDEA 的 src/main/java/com/example/springai/ 上右键 → New → Package，输入 observe，回车（得到 com.example.springai.observe）。
2. 在 observe 包上右键 → New → Java Class，Name 填 RagObservability，回车。
3. 把下面整段代码粘贴进 RagObservability.java，Ctrl+S 保存（IDEA 会自动 import）。

package com.example.springai.observe;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class RagObservability {

    /** 由 Micrometer Tracing 自动装配；没接追踪时是 Noop 实现，不会报错 */
    private final ObservationRegistry registry;

    public RagObservability(ObservationRegistry registry) {
        this.registry = registry;
    }

    /**
     * 把"检索"这一步包成一个 span，并带上业务维度标签。
     * lowCardinalityKeyValue = 聚合维度（取值少）；highCardinalityKeyValue = 单条排查（取值多）。
     */
    public <T> T observeRetrieval(String tenantId, String query, java.util.function.Supplier<T> action) {
        Observation obs = Observation.createNotStarted("ai.rag.retrieval", registry)
                .lowCardinalityKeyValue("tenant", tenantId)
                .lowCardinalityKeyValue("stage", "retrieval")
                .highCardinalityKeyValue("query", truncate(query, 100));

        return obs.observe(action);   // 自动记录开始/结束/异常
    }

    /** 记录检索结果的质量指标（命中数、最高分）——框架 span 里没有这些 */
    public void recordRetrievalResult(int hitCount, double topScore) {
        Observation obs = Observation.createNotStarted("ai.rag.result", registry)
                .lowCardinalityKeyValue("hit", hitCount > 0 ? "yes" : "no");
        obs.start();
        try {
            obs.event(Observation.Event.of("retrieval-result"));
            obs.lowCardinalityKeyValue("hitCount", String.valueOf(hitCount));
            obs.highCardinalityKeyValue("topScore", String.format("%.4f", topScore));
        } finally {
            obs.stop();
        }
    }

    /** 把 traceId 写进 MDC，让每一行日志都自动带上 traceId */
    public void bindTraceIdToLogs(String traceId) {
        org.slf4j.MDC.put("traceId", traceId);
    }

    private String truncate(String s, int max) {
        return s == null ? "" : (s.length() <= max ? s : s.substring(0, max));
    }
}

③ 把埋点接到真实的检索调用上

类建好不会自己生效——要在你的检索方法里用 observeRetrieval 把 similaritySearch 包起来，业务标签才会进 span。典型写法：

// 在你的 KnowledgeQaService 的检索方法里
List<Document> docs = ragObservability.observeRetrieval(
        tenantId, question,
        () -> vectorStore.similaritySearch(question));

// 检索完，把「命中几条、最高分多少」也记一笔（框架 span 里没有这些）
ragObservability.recordRetrievalResult(docs.size(), topScore(docs));

看到什么算接好：再发请求去 Zipkin 看那条 trace，能找到 ai.rag.retrieval 这个 span，且它带 tenant / stage 标签——说明业务维度已经织进了链路。

② 让响应头带上 traceId（排障时用户报给你）

1. 在 com.example.springai.observe 包上右键 → New → Java Class，Name 填 TraceIdFilter。
2. 粘贴下面代码，Ctrl+S 保存。

import io.micrometer.tracing.Tracer;
import jakarta.servlet.*;
import jakarta.servlet.http.*;
import java.io.IOException;

/**
 * 把当前 traceId 放进响应头。
 * 好处：用户反馈问题时报出 traceId，你 3 秒定位；
 *      前端也可以把它展示在"反馈"弹窗里自动带上。
 */
@Component
public class TraceIdFilter extends OncePerRequestFilter {

    private final Tracer tracer;

    public TraceIdFilter(Tracer tracer) {
        this.tracer = tracer;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                     FilterChain chain) throws ServletException, IOException {
        String traceId = tracer.currentSpan() != null
                ? tracer.currentSpan().context().traceId()
                : "no-trace";

        res.setHeader("X-Trace-Id", traceId);
        org.slf4j.MDC.put("traceId", traceId);
        try {
            chain.doFilter(req, res);
        } finally {
            org.slf4j.MDC.remove("traceId");   // ★ 必须清理，否则线程复用时会串
        }
    }
}

3. 打开 src/main/resources/logback-spring.xml（没有就新建），在 <pattern> 里加入 %X{traceId:-}，让每行日志自动带 traceId：

# logback-spring.xml 片段：让每行日志都自动带 traceId
<pattern>
  %d{HH:mm:ss.SSS} [%thread] %-5level [%X{traceId:-}] %logger{36} - %msg%n
</pattern>

# 效果：
# 14:23:01.123 [http-nio-8080-exec-1] INFO  [a3f2b1c9d8e7] c.e.s.c.KnowledgeQaService - 【RAG检索】命中 3 条

运行验证：traceId 进了响应头，也进了日志

# 发请求并打出响应头，重点看 X-Trace-Id
curl -s -D - -o /dev/null http://localhost:8080/api/v1/knowledge/ask \
  -X POST -H "Content-Type: application/json" \
  -d '{"question":"退款要几天到账","tenantId":"default"}'

# 期望响应头里出现（具体值每次不同）：
# X-Trace-Id: a3f2b1c9d8e7f0a1b2c3d4e5f6a7b8c9

看到什么算通过：① 响应头里有 X-Trace-Id；② 应用日志里对应那行带上了同样的 traceId（如 [a3f2b1c9d8e7]）；③ 在 Zipkin 用这个 traceId 能搜到那条链路。

10.4指标与成本看板

① 需要采集的核心指标

指标回答的是「整体趋势」问题。下面这张表列了 AI 应用最该有的几个指标——注意「标签（tag）」列，它直接关系到下一节的「基数陷阱」。

② 用 Micrometer 采集（一个统一的观测切面）

1. 在 com.example.springai 包（或新建 metrics 子包）上右键 → New → Java Class，Name 填 AiMetrics。
2. 粘贴下面代码，Ctrl+S 保存。它用 MeterRegistry 把调用量、延迟、Token 记录成上面的指标。

@Slf4j
@Component
public class AiMetrics {

    private final MeterRegistry registry;

    public AiMetrics(MeterRegistry registry) {
        this.registry = registry;
    }

    /** 记录一次模型调用 */
    public void recordChat(String model, String scene, String tenant,
                            long elapsedMs, int promptTokens, int completionTokens,
                            boolean success) {
        // 计数：调用量 + 成功率（标签都是低基数的）
        registry.counter("ai.chat.calls",
                "model", model, "scene", scene,
                "tenant", tenant, "status", success ? "ok" : "fail").increment();

        // 耗时分布。P95/P99 由 Prometheus 的 histogram_quantile 计算
        registry.timer("ai.chat.duration", "model", model, "scene", scene)
                .record(elapsedMs, java.util.concurrent.TimeUnit.MILLISECONDS);

        // Token 用量：用于成本核算
        registry.counter("ai.tokens.prompt", "model", model, "tenant", tenant)
                .increment(promptTokens);
        registry.counter("ai.tokens.completion", "model", model, "tenant", tenant)
                .increment(completionTokens);
    }

    /** 记录检索质量 */
    public void recordRetrieval(String tenant, int hits) {
        registry.summary("ai.rag.retrieval.hits", "tenant", tenant).record(hits);
        if (hits == 0) {
            // ★ 这个指标极其重要：它直接反映"知识库覆盖不了用户问的问题"
            registry.counter("ai.rag.empty.rate", "tenant", tenant).increment();
        }
    }

    /** 记录工具调用（含耗时） */
    public void recordTool(String toolName, long elapsedMs, boolean success) {
        registry.timer("ai.tool.duration", "tool", toolName).record(elapsedMs,
                java.util.concurrent.TimeUnit.MILLISECONDS);
        registry.counter("ai.tool.calls", "tool", toolName,
                "status", success ? "ok" : "fail").increment();
    }

    /** 记录 Agent 步数——用于发现"某个场景总是要跑 8 步"这类问题 */
    public void recordAgentSteps(String scene, int steps) {
        registry.summary("ai.agent.steps", "scene", scene).record(steps);
    }
}

运行验证：从 /actuator/prometheus 看到 Token 指标

# 先发几个请求产生调用，再抓取 Prometheus 指标，过滤出 AI 相关项
curl -s http://localhost:8080/actuator/prometheus | grep -E "ai_chat_calls|ai_tokens"

# 期望看到类似这样的行（数字随你的请求变化）：
# HELP ai_chat_calls_total
# TYPE ai_chat_calls_total counter
ai_chat_calls_total{model="deepseek-chat",scene="kb-qa",tenant="default",status="ok",} 12.0
# HELP ai_tokens_prompt_total
# TYPE ai_tokens_prompt_total counter
ai_tokens_prompt_total{model="deepseek-chat",tenant="default",} 1843.0
ai_tokens_completion_total{model="deepseek-chat",tenant="default",} 526.0

看到什么算通过：抓到的指标里出现 ai_chat_calls_total 且计数 > 0，ai_tokens_prompt_total / ai_tokens_completion_total 有非零的 Token 数字——说明你的埋点真正在累计成本数据。

成本怎么看（把计数器变成「每天花多少」）

指标已累计到 ai_tokens_prompt_total / ai_tokens_completion_total（单位：token）。要算「昨天花了多少钱」，用 Prometheus 的 increase 取一天增量，再乘单价（价格表单位是「元 / 百万 token」）：

# 昨天各租户的输入 token 增量（再 × 单价/1e6 即金额）
sum by (tenant) (increase(ai_tokens_prompt_total[1d]))
# 输出同理用 ai_tokens_completion_total

# 金额 = 增量token × 单价 ÷ 1,000,000
# 例如：增量 2,000,000 token，deepseek-chat 输入 1 元/百万 → 2 元

为什么除以 100 万：价格表单位是「元 / 百万 token」，而计数器是「个」，所以必须除以 1,000,000。把单价误写成「元 / token」（少六个零）是最常见的算账错误，会让成本看着像零。

③ 成本怎么算

为什么用 BigDecimal 而不是 double？因为财务数据不容许浮点误差——累积到月度账单时，0.1 + 0.2 != 0.3 这类误差会变成实打实的钱。下面的价格表配置化，统计时按模型换算。

先在 application.yml 的 spring.ai 段下方同级追加价格表（注意缩进与 spring: 平级）：

# application.yml —— 价格表（单位：元 / 百万 token）
ai:
  pricing:
    models:
      deepseek-chat:
        input: 1.0        # 输入 1 元/百万 token
        output: 2.0       # 输出 2 元/百万 token
      qwen-plus:
        input: 0.8
        output: 2.0
      gpt-4o-mini:
        input: 1.1
        output: 4.4
      ollama-local:
        input: 0.0        # 本地模型：不花钱，但占机器
        output: 0.0

/** 把 Token 换算成费用。用 BigDecimal 而不是 double——财务数据不容许浮点误差。 */
public BigDecimal calculateCost(String model, long promptTokens, long completionTokens) {
    ModelPrice price = priceTable.get(model);
    if (price == null) {
        log.warn("模型 {} 未配置价格，按 0 计算", model);
        return BigDecimal.ZERO;
    }
    BigDecimal million = new BigDecimal("1000000");
    return price.input().multiply(BigDecimal.valueOf(promptTokens)).divide(million, 6, RoundingMode.HALF_UP)
            .add(price.output().multiply(BigDecimal.valueOf(completionTokens)).divide(million, 6, RoundingMode.HALF_UP));
}

③ 指标在 Prometheus 里叫什么名字

你在代码里写的 registry.counter("ai.chat.calls", ...)，进到 Prometheus 后会自动加上 _total 后缀、并把标签变成 {model="...",tenant="..."}。所以查的时候要写 ai_chat_calls_total，而不是 ai_chat_calls——这是学生最常见的「查不到」原因。

看到什么算对：访问 /actuator/prometheus 时，你能搜到带下划线、点号变下划线的指标名；PromQL 里用这些名字才能出图。

④ 几个可以直接抄的 Prometheus 查询

# 最近的模型调用 QPS（按模型分组）
sum by (model) (rate(ai_chat_calls_total[5m]))

# 模型调用的 P95 延迟（毫秒）
histogram_quantile(0.95, sum by (le, model) (rate(ai_chat_duration_seconds_bucket[5m]))) * 1000

# 失败率（按场景）
sum by (scene) (rate(ai_chat_calls_total{status="fail"}[5m]))
  / sum by (scene) (rate(ai_chat_calls_total[5m]))

# 每小时的输入 Token 总量（按租户）——成本看板的核心图
sum by (tenant) (increase(ai_tokens_prompt_total[1h]))

# 检索为空的比例——知识库覆盖度指标，超过 30% 说明知识库该补内容了
sum(rate(ai_rag_empty_rate_total[1h])) / sum(rate(ai_rag_retrieval_hits_count[1h]))

⑤ 把指标变成「自动报警」

看板是给人看的，报警是系统自己叫的。下面两条 Prometheus 告警规则（放到 prometheus/rules/*.yml）能在异常刚出现时就通知你，而不是等用户投诉：

# 规则一：检索为空率过高 → 知识库覆盖出问题
- alert: RagEmptyRateHigh
  expr: sum(rate(ai_rag_empty_rate_total[1h])) / sum(rate(ai_rag_retrieval_hits_count[1h])) > 0.3
  for: 10m
  labels: { severity: warning }
  annotations:
    summary: "检索为空率超过 30%（知识库可能漏了高频问题）"

# 规则二：调用失败率突增 → 模型服务可能限流/宕机
- alert: ChatFailRateSpike
  expr: sum(rate(ai_chat_calls_total{status="fail"}[5m])) / sum(rate(ai_chat_calls_total[5m])) > 0.05
  for: 5m
  labels: { severity: page }
  annotations:
    summary: "模型调用失败率超过 5%"

看到什么算接好：在 Prometheus 的 Alerts 页面能看到这两条规则处于 INACTIVE（正常）或 PENDING/FIRING（异常）；故意把知识库清空跑评测，第一条应在 10 分钟内变 FIRING。

10.5日志规范与脱敏

AI 应用该打什么日志

为什么日志规范在 AI 应用里比传统应用更重要？因为 Prompt 和用户对话里可能含有身份证号、银行卡号、商业机密。一旦你把完整 Prompt 打到 INFO 级并进了日志收集系统，等于把这些数据明文同步到了第三方平台。下面是正确的日志写法与脱敏工具。

1. 确认你的 KnowledgeQaService（或等价服务类）里，模型调用前后用结构化 + 关键字段 + 脱敏后的方式打日志，而不是 log.info(answer) 一把梭：

// ✅ 推荐：结构化 + 关键字段 + 可追溯（敏感字段先脱敏）
log.info("【模型调用】traceId={} scene={} model={} 耗时={}ms promptTokens={} completionTokens={} 状态={}",
        traceId, scene, model, elapsedMs, promptTokens, completionTokens, "ok");

log.info("【RAG检索】traceId={} tenant={} query={} 命中={} 最高分={}",
        traceId, tenant, mask(query), hits.size(), topScore);

log.info("【工具调用】traceId={} tool={} 参数={} 耗时={}ms 结果长度={}",
        traceId, toolName, maskArgs(args), cost, result.length());

脱敏：什么绝对不能进日志

2. 在 com.example.springai 包上右键 → New → Java Class，Name 填 Mask（建为不可实例化工具类），粘贴下面代码并保存：

/** 一个简单的脱敏工具 */
public final class Mask {
    private Mask() {}

    /** 手机号：138****8888 */
    public static String phone(String s) {
        return s == null ? null : s.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
    }

    /** 身份证：110***********1234 */
    public static String idCard(String s) {
        return s == null ? null : s.replaceAll("(\\d{3})\\d+(\\d{4})", "$1***********$2");
    }

    /** 通用长文本：只保留前 n 字符，其余用哈希代替（可对比是否同一条） */
    public static String text(String s, int n) {
        if (s == null) return null;
        if (s.length() <= n) return s;
        return s.substring(0, n) + "…[len=" + s.length() + ",hash="
                + Integer.toHexString(s.hashCode()) + "]";
    }
}

脱敏在日志里的实际效果对比：

# ❌ 错误：直接打原始对话（含手机号/身份证）
log.info("用户说：{}", "我的手机号13812345678，身份证110101199003071234");
# ✅ 正确：先 mask 再打
log.info("用户说：{}", Mask.text("我的手机号13812345678，身份证110101199003071234", 20));
# 期望日志输出：用户说：我的手机号138****8888，身份证110***********1234…

用 JSON 日志 + MDC，让 traceId 可被日志系统索引

纯文本日志难检索。生产建议用 JSON 格式输出（Logback 的 JsonEncoder），并把 traceId 作为固定字段，这样在 ELK / Loki 里能直接按 traceId 过滤整条链路的所有日志：

# logback-spring.xml 片段：JSON 输出 + traceId 字段
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
  <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
    <providers>
      <timestamp/>
      <logLevel/>
      <message/>
      <mdc/>   # ★ MDC 里的 traceId 会被自动展开成 "traceId": "a3f2..." 字段
    </providers>
  </encoder>
</appender>

看到什么算对：一条日志是 {"level":"INFO","message":"【RAG检索】命中 3 条","traceId":"a3f2..."} 这样的 JSON，traceId 是顶层字段，能被日志平台直接检索。

运行验证：日志里不再出现明文敏感信息

# 发一个含手机号的请求（示例），然后看应用日志
grep -R "1381234" logs/        # 期望：找不到完整手机号
grep -R "sk-" logs/           # 期望：找不到完整 API Key
# 期望日志里看到的是 138****8888 这种脱敏形态

看到什么算通过：日志里手机号/身份证被掩码，API Key 无明文；同时业务字段（traceId、命中数、耗时）仍清晰可查。

10.6评估：从「感觉还行」走向「有数据」

这是本章最有价值也最容易被跳过的一节。没有评估，你的调优就是盲猜。有了评估，你能明确说出：「这次改动让准确率从 76% 提升到 84%，成本增加 12%」。

① 先建评测集（最重要的一步）

为什么评测集最重要？因为它是后面所有指标、所有质量门禁的「标尺」。没有一把稳定的尺子，你连「变好了还是变坏了」都说不清。建议用 JSON 维护在代码仓库里——能走 Code Review，能进 CI。

1. 在 IDEA 的 src/test/resources/ 上右键 → New → Directory，输入 eval，回车。
2. 在 eval 目录上右键 → New → File，Name 填 qa-dataset.json，把下面这份评测集整段粘贴保存（先 4 条跑通，再扩到 30+）。
3. （可选）再建 qa-dataset-hard.json 放难例——每次线上答错的 case 都补进来。

[
  {
    "id": "q001",
    "question": "退款要几天到账？",
    "expectedAnswer": "审核通过后 3 个工作日内退回原支付账户。",
    "relevantKeywords": ["3 个工作日", "原支付账户"],
    "expectedSources": ["refund-policy.md"],
    "category": "售后",
    "difficulty": "easy"
  },
  {
    "id": "q002",
    "question": "我买的东西不想要了，钱什么时候能退给我？",
    "expectedAnswer": "订单完成后 7 天内可提交退款申请；审核通过后 3 个工作日内退回原支付账户。",
    "relevantKeywords": ["7 天", "3 个工作日"],
    "expectedSources": ["refund-policy.md"],
    "category": "售后",
    "difficulty": "medium",
    "note": "口语化提问，原文无'退款'二字，考查语义检索"
  },
  {
    "id": "q003",
    "question": "公司年会在哪一天举办？",
    "expectedAnswer": "资料中未提及。",
    "relevantKeywords": [],
    "expectedSources": [],
    "category": "知识库外",
    "difficulty": "easy",
    "note": "★ 考查'不瞎编'能力。这类题必须占评测集的 10~15%"
  },
  {
    "id": "q004",
    "question": "生鲜商品签收后还能退吗？",
    "expectedAnswer": "生鲜类商品一经签收不支持无理由退款。",
    "relevantKeywords": ["生鲜", "不支持"],
    "expectedSources": ["refund-policy.md"],
    "category": "售后",
    "difficulty": "medium"
  }
]

运行验证：评测集是合法 JSON 且能被解析

# 用 python 快速校验 JSON 语法（无需任何依赖）
python -c "import json,sys; d=json.load(open('src/test/resources/eval/qa-dataset.json')); print('OK, 共', len(d), '条')"

# 期望输出：OK, 共 4 条

看到什么算通过：命令打印 OK, 共 N 条 且无 JSON 解析报错；每条都含 question 与 relevantKeywords 字段（知识库外的题这两项为空数组是正常且必要的）。

② 三层评测：分别度量不同环节

评测要分层次，因为「检索错了」和「检索对了但模型答偏了」是两种完全不同的故障，修复手段也不同。

10.7内置与自定义 Evaluator

Spring AI 的两个内置评估器

为什么用评估器而不是直接比字符串？因为答案可能换了个说法但意思对（"3 个工作日" vs "三个工作日"）。模型做裁判（LLM-as-a-Judge）能理解语义等价，比字符串精确匹配更接近真实质量。

1. 在测试或业务代码里，用 ChatClient.builder(chatModel) 构造评估器。先构造 RelevancyEvaluator 与 FactCheckingEvaluator（注意它们内部就是再调一次模型，所以每次评估都有成本和延迟）：

import org.springframework.ai.evaluation.*;
import org.springframework.ai.document.Document;

/** ① RelevancyEvaluator —— 答案是否与"提供的资料 + 用户问题"相关。 */
RelevancyEvaluator relevancy = RelevancyEvaluator.builder()
        .chatClientBuilder(ChatClient.builder(chatModel))
        .build();

/** ② FactCheckingEvaluator —— 答案是否有资料支撑（查幻觉）。 */
FactCheckingEvaluator factCheck = FactCheckingEvaluator.builder()
        .chatClientBuilder(ChatClient.builder(chatModel))
        .build();

String question = "退款要几天到账？";
List<Document> retrievedDocs = vectorStore.similaritySearch(question);
String answer = ragService.ask(question).answer();

// 构造评估请求：用户问题 + 检索到的资料 + 模型回答
EvaluationRequest request = new EvaluationRequest(question, retrievedDocs, answer);

EvaluationResponse res = relevancy.evaluate(request);
System.out.println("通过：" + res.isPass());
System.out.println("得分：" + res.getScore());       // 0.0 ~ 1.0
System.out.println("反馈：" + res.getFeedback());    // 模型给出的理由（价值很高）

运行验证：跑一次内置评估器看 isPass / score

# 期望控制台输出（数值随模型与问题变化）：
# 通过：true
# 得分：0.92
# 反馈：答案与提供的退款政策资料一致，明确给出了 3 个工作日的时限。

看到什么算通过：res.isPass() 返回布尔、getScore() 是 0~1 之间的数、getFeedback() 有可阅读的判分理由——说明评估器真的调了模型并给出了语义判断。

自定义 Evaluator：更贴合业务的判定

2. 在 com.example.springai.eval 包上右键 → New → Java Class，Name 填 KeywordCoverageEvaluator，让它 implements Evaluator，粘贴下面代码保存。它用关键词覆盖做零成本规则判定，适合进 CI。

import org.springframework.ai.evaluation.Evaluator;
import org.springframework.ai.evaluation.EvaluationRequest;
import org.springframework.ai.evaluation.EvaluationResponse;

/** 自定义评估器：规则判定 + 关键词覆盖。零成本、零延迟，适合放进 CI。 */
@Component
public class KeywordCoverageEvaluator implements Evaluator {

    private final List<String> requiredKeywords;

    public KeywordCoverageEvaluator(List<String> requiredKeywords) {
        this.requiredKeywords = requiredKeywords;
    }

    @Override
    public EvaluationResponse evaluate(EvaluationRequest request) {
        String answer = request.getResponseContent();

        // 情况一：期望"查不到"（知识库外的问题）
        if (requiredKeywords.isEmpty()) {
            // ★ 关键校验：回答里不能出现具体数字/日期，否则说明它在编
            boolean looksFabricated = answer.matches(".*\\d{4}[-/年].*")
                    || answer.contains("应该是") || answer.contains("一般来说");
            return new EvaluationResponse(!looksFabricated,
                    looksFabricated ? 0.0f : 1.0f,
                    looksFabricated ? "疑似编造了具体信息" : "正确地表示无法回答");
        }

        // 情况二：统计关键词覆盖数
        int hit = 0;
        List<String> missing = new java.util.ArrayList<>();
        for (String kw : requiredKeywords) {
            // 归一化：去掉空格，统一全半角数字
            if (normalize(answer).contains(normalize(kw))) {
                hit++;
            } else {
                missing.add(kw);
            }
        }

        float score = (float) hit / requiredKeywords.size();
        boolean pass = score >= 0.6f;      // 阈值：覆盖 60% 以上算通过

        return new EvaluationResponse(pass, score,
                missing.isEmpty() ? "全部关键词覆盖" : "缺失关键词：" + missing);
    }

    /** 归一化：把中文数字和常见变体统一，提高规则判定的宽容度 */
    private String normalize(String s) {
        if (s == null) return "";
        return s.replace(" ", "").replace("　", "")
                .replace("三个", "3个").replace("七个", "7个")
                .replace("三天", "3天").replace("七天", "7天")
                .toLowerCase();
    }
}

10.8完整示例：自动化评测 + 报告

把评测做成一个可以随时运行的测试，每次改提示词/换模型/调参数后跑一次，看指标变化。这是本章最实用的交付物。

① 评测集映射

1. 在 src/test/java/com/example/springai/ 上右键 → New → Package，输入 eval，回车。
2. 在 eval 包上右键 → New → Java Class，Name 填 EvalDataset，粘贴下面 record 保存（字段要和 10.6 的 JSON 一一对应）：

package com.example.springai.eval;

import java.util.List;

public record EvalDataset(
        String id,
        String question,
        String expectedAnswer,
        List<String> relevantKeywords,
        List<String> expectedSources,
        String category,
        String difficulty
) {}

② 评测执行器

3. 在 eval 包上右键 → New → Java Class，Name 填 EvalRunner，粘贴下面代码保存。它是评测的「发动机」：逐条调用 RAG 服务、判定检索与答案、汇总成报告。

@Slf4j
@Component
public class EvalRunner {

    private final KnowledgeQaService qaService;      // 第 5 章的 RAG 服务

    public EvalRunner(KnowledgeQaService qaService) {
        this.qaService = qaService;
    }

    /** 单条评测的明细记录 */
    public record ItemResult(
            String id, String question, String answer,
            boolean retrievalHit,          // 检索层：期望来源是否命中
            boolean answerPass,            // 生成层：关键词覆盖是否达标
            double retrievalScore,        // 关键词覆盖率
            long elapsedMs,
            String note
    ) {}

    /** 整体指标汇总 */
    public record EvalReport(
            String modelName, String promptVersion,
            int total,
            double retrievalHitRate,       // ★ 检索命中率
            double answerPassRate,         // ★ 答案通过率
            double avgScore, long avgElapsedMs, long p95ElapsedMs,
            List<ItemResult> details
    ) {}

    /** 跑完整评测。 */
    public EvalReport run(List<EvalDataset> datasets, String scene) {
        List<ItemResult> results = new java.util.ArrayList<>();

        for (EvalDataset item : datasets) {
            long t0 = System.currentTimeMillis();
            String answer;
            List<String> actualSources = new java.util.ArrayList<>();

            try {
                // 调用真实的 RAG 服务（等价于线上链路）
                var ragAnswer = qaService.ask(item.question(), "default");
                answer = ragAnswer.answer();
                ragAnswer.citations().forEach(c -> actualSources.add(c.source()));
            } catch (Exception e) {
                log.error("评测 {} 执行失败", item.id(), e);
                answer = " + e.getMessage() + ">";
            }
            long elapsed = System.currentTimeMillis() - t0;

            // ---------- 检索层判定 ----------
            boolean retrievalHit;
            if (item.expectedSources().isEmpty()) {
                retrievalHit = actualSources.isEmpty();   // 期望"检索不到"的题
            } else {
                retrievalHit = item.expectedSources().stream().anyMatch(actualSources::contains);
            }

            // ---------- 生成层判定（关键词覆盖） ----------
            double score = keywordCoverage(answer, item.relevantKeywords());
            boolean pass = score >= 0.6;

            results.add(new ItemResult(item.id(), item.question(),
                    truncate(answer, 120), retrievalHit, pass, score, elapsed,
                    pass ? "" : "关键词未覆盖：" + missingKeywords(answer, item.relevantKeywords())));

            log.info("评测 {} {} | 检索={} 通过={} 分数={:.2f} 耗时={}ms",
                    item.id(), pass ? "✅" : "❌",
                    retrievalHit, pass, score, elapsed);
        }

        // ---------- 汇总 ----------
        int n = results.size();
        double hitRate = results.stream().filter(ItemResult::retrievalHit).count() * 1.0 / n;
        double passRate = results.stream().filter(ItemResult::answerPass).count() * 1.0 / n;
        double avgScore = results.stream().mapToDouble(ItemResult::retrievalScore).average().orElse(0);

        List<Long> latencies = results.stream().map(ItemResult::elapsedMs).sorted().toList();
        long avgLatency = (long) latencies.stream().mapToLong(Long::longValue).average().orElse(0);
        long p95 = latencies.isEmpty() ? 0
                : latencies.get((int) Math.min(latencies.size() - 1, latencies.size() * 0.95));

        return new EvalReport(scene, "v1", n,
                round(hitRate), round(passRate), round(avgScore), avgLatency, p95, results);
    }

    private double keywordCoverage(String answer, List<String> keywords) {
        if (keywords.isEmpty()) {
            boolean fabricated = answer.matches(".*\\d{4}[-/年].*");
            return fabricated ? 0.0 : 1.0;
        }
        long hit = keywords.stream().filter(k -> normalize(answer).contains(normalize(k))).count();
        return hit * 1.0 / keywords.size();
    }

    private List<String> missingKeywords(String answer, List<String> keywords) {
        return keywords.stream()
                .filter(k -> !normalize(answer).contains(normalize(k)))
                .toList();
    }

    private String normalize(String s) {
        return s.replace(" ", "").replace("三个", "3个")
                .replace("三天", "3天").replace("七天", "7天");
    }

    private double round(double v) { return Math.round(v * 10000) / 10000.0; }

    private String truncate(String s, int n) {
        return s == null ? "" : (s.length() <= n ? s : s.substring(0, n) + "…");
    }
}

③ 输出 Markdown 报告（方便对比历史）

4. 在 EvalRunner.java 里追加下面 toMarkdown 方法（与已有方法平级），保存：

public String toMarkdown(EvalReport r) {
    StringBuilder sb = new StringBuilder();
    sb.append("# RAG 评测报告\n\n");
    sb.append("| 指标 | 值 |\n|---|---|\n");
    sb.append("| 场景 | ").append(r.modelName()).append(" |\n");
    sb.append("| 提示词版本 | ").append(r.promptVersion()).append(" |\n");
    sb.append("| 样本数 | ").append(r.total()).append(" |\n");
    sb.append("| **检索命中率** | **").append(pct(r.retrievalHitRate())).append("** |\n");
    sb.append("| **答案通过率** | **").append(pct(r.answerPassRate())).append("** |\n");
    sb.append("| 平均分数 | ").append(r.avgScore()).append(" |\n");
    sb.append("| 平均耗时 | ").append(r.avgElapsedMs()).append(" ms |\n");
    sb.append("| P95 耗时 | ").append(r.p95ElapsedMs()).append(" ms |\n\n");

    sb.append("## 未通过明细（改进重点）\n\n");
    sb.append("| ID | 问题 | 检索 | 失败原因 |\n|---|---|---|---|\n");
    r.details().stream().filter(d -> !d.answerPass()).forEach(d ->
            sb.append("| ").append(d.id()).append(" | ")
              .append(truncate(d.question(), 40)).append(" | ")
              .append(d.retrievalHit() ? "命中" : "**未命中**").append(" | ")
              .append(d.note()).append(" |\n"));
    return sb.toString();
}

private String pct(double v) { return String.format("%.1f%%", v * 100); }

④ JUnit 测试入口

5. 在 eval 包上右键 → New → Java Class，Name 填 RagEvaluationTest，把种类（Kind）设为 Test（或建完后在类上加 @SpringBootTest），粘贴下面代码保存：

@SpringBootTest
@ActiveProfiles("local")
class RagEvaluationTest {

    @Autowired EvalRunner evalRunner;
    @Autowired ObjectMapper objectMapper;

    @Test
    void 跑一遍RAG评测并输出报告() throws Exception {
        // 1. 加载评测集
        List<EvalDataset> dataset = objectMapper.readValue(
                new ClassPathResource("eval/qa-dataset.json").getInputStream(),
                new TypeReference<List<EvalDataset>>() {});

        // 2. 执行评测
        EvalReport report = evalRunner.run(dataset, "kb-qa-v1");

        // 3. 输出报告到 target 目录（不污染源码目录）
        String md = evalRunner.toMarkdown(report);
        Files.writeString(Path.of("target/eval-report.md"), md);
        System.out.println(md);

        // 4. ★ 质量门禁：低于阈值就让 CI 红掉，防止劣化上线
        assertThat(report.retrievalHitRate())
                .as("检索命中率不能低于 80%%").isGreaterThanOrEqualTo(0.80);
        assertThat(report.answerPassRate())
                .as("答案通过率不能低于 75%%").isGreaterThanOrEqualTo(0.75);
        assertThat(report.avgElapsedMs())
                .as("平均耗时不能超过 8 秒").isLessThan(8000L);
    }
}

运行验证：跑通测试，看到两个核心比率

# 在工程根目录执行（Maven 测试，只跑这一个测试类）
mvn -q test -Dtest=RagEvaluationTest

# 期望：BUILD SUCCESS，且控制台打印出报告，含这两个关键数字：
# | **检索命中率** | **86.7%** |
# | **答案通过率** | **80.0%** |
# 同时 target/eval-report.md 文件被生成

# 验收文件是否落盘
ls -l target/eval-report.md

看到什么算通过：① BUILD SUCCESS；② 控制台或报告里有「检索命中率」和「答案通过率」两个非零数字；③ target/eval-report.md 存在。若门禁不达标，测试会 BUILD FAILURE 并打印 检索命中率不能低于 80% 之类断言信息——这正是门禁在起作用。

⑤ 报告长什么样

# RAG 评测报告

| 指标 | 值 |
|---|---|
| 场景 | kb-qa-v1 |
| 提示词版本 | v1 |
| 样本数 | 30 |
| **检索命中率** | **86.7%** |
| **答案通过率** | **80.0%** |
| 平均分数 | 0.812 |
| 平均耗时 | 3240 ms |
| P95 耗时 | 6180 ms |

## 未通过明细（改进重点）

| ID | 问题 | 检索 | 失败原因 |
|---|---|---|---|
| q007 | 会员积分怎么兑换 | **未命中** | 缺失关键词：500分、10元 |
| q013 | 发票什么时候能开出来 | 命中 | 缺失关键词：3个工作日 |
| q021 | 我要投诉 | 命中 | 缺失关键词：投诉渠道 |

# 读报告的方法：
# ① 检索"未命中"的题 → 去补知识库 / 调切分 / 调阈值
# ② 检索命中但答案不过的题 → 去改提示词
# ③ 全对但耗时高的题 → 去优化 topK / 减少上下文长度

# CI 脚本片段：每次 push/PR 都跑评测，失败则流水线红、阻止合并
mvn -q test -Dtest=RagEvaluationTest

10.9常见坑排错

10.10自测题

10.11实操作业与本章验收

• Zipkin 中能看到完整链路，且能说明 2.0 与 1.x 在工具 span 名上的差异。
• 应用暴露 /actuator/prometheus，至少能查到 ai.chat.calls 与 ai.tokens.prompt 两个指标。
• 评测集 ≥ 30 条，含知识库外问题（10~15%）与口语化改写问题；报告含检索命中率与答案通过率。
• 评测接入 JUnit 质量门禁（检索命中率 ≥ 80%、答案通过率 ≥ 75%、平均耗时 < 8s）。
• 生产日志不记录完整 Prompt；代码中存在脱敏工具类且被使用。
• 能口头解释指标标签基数陷阱，并举例说明哪些维度适合作标签、哪些必须进 Trace。