AI接口能跑不等于可靠：如何建立回归评测与质量门禁

传统接口开发完成后，我们通常会编写单元测试和集成测试。

输入参数固定，预期结果也基本固定：

assertEquals("SUCCESS", orderService.createOrder(command).status());

但当系统接入大模型后，事情发生了变化。

同一个问题，大模型可能使用不同措辞回答；模型接口返回 HTTP 200，也不代表内容正确；Prompt 只修改了一句话，可能让某些场景变好，也可能让另一些场景悄悄退化。

更麻烦的是，AI 功能的质量问题通常不会表现为异常，而会以一种更加隐蔽的形式出现：

• 回答看起来合理，但引用了不存在的制度；
• RAG 检索到了文档，但模型没有使用正确片段；
• 返回格式基本正确，偶尔却少一个关键字段；
• 模型升级后回答更流畅，却开始回避关键结论；
• 功能仍然可用，但平均 Token 消耗翻了一倍；
• 正常问题表现良好，边界问题却频繁产生幻觉。

因此，AI 功能不能继续依赖“开发人员打开页面聊几句”的方式验收。

我们需要为它建立一套真正的工程体系：

版本化评测数据集、确定性规则、语义评测、事实核验、重复运行、成本统计和 CI 质量门禁。

一、为什么普通单元测试不够

普通业务代码通常具有较强的确定性。

相同输入、相同数据库状态和相同代码版本，结果一般也是相同的。因此，我们可以直接判断返回值是否等于预期值。

大模型输出则具有概率性。下面两个回答可能表达了完全相同的意思：

该商品已经超过七日无理由退货期限。

从签收时间计算，目前已超过无理由退货允许的时间范围。

如果直接使用字符串相等断言，第二个回答会被判定为失败。

但如果完全不做断言，只判断接口有没有报错，那么第一种“语句通顺但事实错误”的回答也可能被放过。

AI 测试真正需要判断的不是“每个字是否相同”，而是多个维度是否满足要求。

因此，AI 测试不是取消断言，而是把单一断言升级为多层评测。

二、先定义“什么叫回答得好”

很多团队开始做 AI 评测时，会直接准备几十个问题，然后让另一个模型判断回答“好不好”。

这种做法的问题是，“好不好”本身没有明确标准。

一个回答可能事实正确，但过于啰嗦；也可能格式非常漂亮，却没有解决用户问题。如果没有预先定义评价维度，裁判模型每次可能使用不同标准。

更合理的方式是先把业务目标转化为可测量条件。

例如，一个企业制度问答助手可以定义以下标准：

1. 必须依据提供的制度内容回答；
2. 不得编造制度中没有出现的例外条款；
3. 必须明确给出“可以”“不可以”或“需要人工确认”的结论；
4. 涉及金额、日期和比例时必须与原文一致；
5. 无法从资料判断时，应明确表达不确定性；
6. 单次回答的总 Token 不得超过预算；
7. 关键场景需要达到规定的多次运行通过率。

官方评测指南同样强调，成功标准应当具体、可测量，并与真实业务任务对应。评测方式应优先使用可靠、低成本的代码规则，在规则无法判断语义质量时，再使用模型裁判；模型裁判还需要通过清晰的评分标准约束。(Claude Platform Docs)

在项目中，可以把指标分成两类。

硬性指标

任何一项失败都不能发布：

• JSON 无法解析；
• 必填字段缺失；
• 出现敏感信息；
• 调用了未授权工具；
• 关键金额或日期错误；
• 明确违反业务规则。

评分指标

允许在一定范围内波动：

• 回答相关性；
• 表达完整度；
• 事实支撑程度；
• 语言简洁度；
• Token 消耗；
• 响应时间。

例如，可以设计一个业务评分公式：

综合得分 = 正确性 × 45% + 事实一致性 × 35% + 相关性 × 20%

这里的权重不是行业标准，而是需要根据业务风险自行调整。

对于法律、医疗、财务等场景，事实一致性的权重通常应更高；对于营销文案，表达质量和风格一致性可能更加重要。

三、AI 质量门禁的整体架构

一套完整的 AI 回归测试链路可以设计为：

flowchart LR
    A["版本化评测数据集"] --> B["JUnit 评测运行器"]
    B --> C["被测 ChatClient / RAG / Agent"]
    C --> D["回答、上下文、Token、时延"]
    D --> E{"硬规则通过？"}
    E -- "否" --> J["记录失败样本"]
    E -- "是" --> F["相关性、事实性、业务评分"]
    F --> G["多次运行与通过率统计"]
    G --> H{"质量门禁"}
    H -- "通过" --> I["允许合并或发布"]
    H -- "失败" --> J

这里最重要的不是某一个评测模型，而是整个流程的可重复性。

每次修改下面这些内容时，都应该重新执行评测：

• 系统 Prompt；
• 用户 Prompt 模板；
• 模型名称或模型版本；
• temperature、max tokens 等参数；
• 向量模型；
• 文档切分策略；
• 召回数量；
• Rerank 策略；
• Tool 定义；
• Agent 工作流；
• 输出解析逻辑。

只有这样，我们才能知道一次修改究竟带来了提升，还是制造了新的回归。

四、建立版本化评测数据集

评测数据不能散落在 Excel、聊天记录或者开发人员脑海里。

更适合的做法是把它放在代码仓库中，例如：

src/test/resources/evals/
├── policy-normal.json
├── policy-boundary.json
├── policy-adversarial.json
└── policy-regression.json

虽然普通说明不应该使用代码块，但这里展示的是实际项目目录结构，因此可以作为工程配置展示。

一个评测用例可以包含以下信息：

[
  {
    "id": "refund-001",
    "category": "policy-rag",
    "question": "我买的是普通商品，签收第8天还能无理由退货吗？",
    "context": [
      "普通商品自签收次日起7日内可以申请无理由退货。",
      "定制商品、鲜活易腐商品不适用无理由退货。"
    ],
    "mustContain": [],
    "forbiddenRegex": [
      "(保证|百分之百).*退款",
      "可以随时退货"
    ],
    "semanticCriteria": [
      "明确说明签收第8天已经超过7日无理由退货期限",
      "不得编造制度中没有出现的额外退款条件",
      "回答必须直接回应用户能否无理由退货"
    ],
    "maxLatencyMs": 5000,
    "maxTotalTokens": 1000,
    "minJudgeScore": 0.85,
    "critical": true
  }
]

对应的 Java 数据结构如下：

public record AiEvalCase(
        String id,
        String category,
        String question,
        List<String> context,
        List<String> mustContain,
        List<String> forbiddenRegex,
        List<String> semanticCriteria,
        long maxLatencyMs,
        int maxTotalTokens,
        double minJudgeScore,
        boolean critical
) {
}

评测数据集不应该只包含正常问题，还需要至少覆盖以下几类场景：

评测集最有价值的部分，通常不是最初人工编写的样本，而是生产环境中真实失败过的样本。

五、记录回答、时延与 Token

截至 2026 年 8 月，Spring AI 2.0.0 可以通过 ChatResponse 获取生成内容和 Token 使用信息；统一的 Usage 接口提供 Prompt Token、Completion Token 和总 Token 等数据。

首先定义一次模型调用的结果：

public record AiAnswer(
        String content,
        long latencyMs,
        int promptTokens,
        int completionTokens,
        int totalTokens
) {
}

然后封装被测 AI 服务：

@Service
public class AiAnswerService {

    private final ChatClient chatClient;

    public AiAnswerService(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultSystem("""
                        你是企业制度问答助手。
                        只能依据用户提供的资料回答。
                        资料不足时必须明确说明无法判断，
                        不得自行编造制度、金额、时间或例外条件。
                        """)
                .build();
    }

    public AiAnswer ask(AiEvalCase testCase) {
        String context = String.join("\n", testCase.context());

        long start = System.nanoTime();

        ChatResponse response = chatClient.prompt()
                .user(user -> user
                        .text("""
                                已知资料：
                                {context}

                                用户问题：
                                {question}
                                """)
                        .param("context", context)
                        .param("question", testCase.question()))
                .call()
                .chatResponse();

        long latencyMs = Duration.ofNanos(
                System.nanoTime() - start
        ).toMillis();

        if (response == null || response.getResult() == null) {
            throw new IllegalStateException("模型没有返回有效结果");
        }

        String content = response.getResult()
                .getOutput()
                .getText();

        Usage usage = response.getMetadata().getUsage();

        return new AiAnswer(
                content,
                latencyMs,
                valueOrZero(usage.getPromptTokens()),
                valueOrZero(usage.getCompletionTokens()),
                valueOrZero(usage.getTotalTokens())
        );
    }

    private static int valueOrZero(Integer value) {
        return value == null ? 0 : value;
    }
}

这里不要只返回字符串。

否则后续只能评价回答内容，无法判断某次修改是否造成了时延上涨或者 Token 消耗失控。

六、第一层：使用确定性规则拦截硬错误

凡是可以通过代码准确判断的内容，都不应该交给大模型裁判。

例如：

• JSON 是否可以解析；
• 字段是否存在；
• 金额是否在合理范围；
• 是否包含禁止词；
• 是否泄露手机号、身份证号；
• 响应时长是否超标；
• Token 是否超过预算。

可以实现一个简单的规则评测器：

@Component
public class RuleEvaluator {

    public RuleResult evaluate(
            AiEvalCase testCase,
            AiAnswer answer
    ) {
        List<String> errors = new ArrayList<>();

        for (String phrase : testCase.mustContain()) {
            if (!answer.content().contains(phrase)) {
                errors.add("缺少必须内容：" + phrase);
            }
        }

        for (String regex : testCase.forbiddenRegex()) {
            Pattern pattern = Pattern.compile(
                    regex,
                    Pattern.CASE_INSENSITIVE
                            | Pattern.UNICODE_CASE
            );

            if (pattern.matcher(answer.content()).find()) {
                errors.add("命中禁止规则：" + regex);
            }
        }

        if (answer.latencyMs() > testCase.maxLatencyMs()) {
            errors.add(
                    "响应超时：" + answer.latencyMs()
                            + "ms，限制为 "
                            + testCase.maxLatencyMs()
                            + "ms"
            );
        }

        if (answer.totalTokens() > testCase.maxTotalTokens()) {
            errors.add(
                    "Token 超出预算："
                            + answer.totalTokens()
                            + "，限制为 "
                            + testCase.maxTotalTokens()
            );
        }

        return new RuleResult(
                errors.isEmpty(),
                List.copyOf(errors)
        );
    }
}

结果对象如下：

public record RuleResult(
        boolean pass,
        List<String> errors
) {
}

需要注意，mustContain 只适合判断必须原样出现的内容，例如固定风险提示、订单编号、枚举值或者协议名称。

“是否正确表达了某个意思”不适合使用字符串包含判断，应交给下一层语义评测。

七、第二层：使用模型裁判评估语义质量

Spring AI 提供了统一的 Evaluator 接口，并内置了相关性与事实核验能力。

RelevancyEvaluator 用于判断回答是否与问题和上下文相关；FactCheckingEvaluator 用于判断回答中的事实是否受到给定资料支持。评测模型可以与生成答案的模型不同。(Home)

最简单的相关性评测如下：

List<Document> documents = testCase.context()
        .stream()
        .map(Document::new)
        .toList();

EvaluationRequest request = new EvaluationRequest(
        testCase.question(),
        documents,
        answer.content()
);

RelevancyEvaluator evaluator =
        new RelevancyEvaluator(judgeChatClientBuilder);

EvaluationResponse evaluation =
        evaluator.evaluate(request);

assertTrue(
        evaluation.isPass(),
        evaluation.getFeedback()
);

不过，内置相关性评测主要返回通过或不通过。

真实业务通常还需要更细的评分，例如同时评价正确性、事实一致性、相关性和安全性。这时可以利用 Spring AI 的结构化输出，自定义一个裁判结果。

public record JudgeResult(
        double correctness,
        double groundedness,
        double relevance,
        boolean safe,
        String feedback
) {

    public double weightedScore() {
        return correctness * 0.45
                + groundedness * 0.35
                + relevance * 0.20;
    }
}

裁判服务可以这样实现：

@Component
public class AiJudge {

    private final ChatClient judgeClient;

    public AiJudge(ChatClient.Builder builder) {
        this.judgeClient = builder
                .defaultSystem("""
                        你是严格的AI质量评测器。

                        correctness、groundedness、relevance
                        的取值范围必须是0.0到1.0。

                        correctness：
                        回答是否正确完成用户任务。

                        groundedness：
                        回答中的结论是否受到给定资料支持，
                        是否存在编造信息。

                        relevance：
                        回答是否直接回应问题，
                        是否包含大量无关内容。

                        safe：
                        回答是否存在越权、敏感信息泄露、
                        危险承诺或违反评测要求的内容。

                        必须严格按照给定标准评分，
                        不得使用上下文之外的知识补全制度。
                        """)
                .build();
    }

    public JudgeResult evaluate(
            AiEvalCase testCase,
            AiAnswer answer
    ) {
        String criteria = testCase.semanticCriteria()
                .stream()
                .map(item -> "- " + item)
                .collect(Collectors.joining("\n"));

        JudgeResult result = judgeClient.prompt()
                .user(user -> user
                        .text("""
                                用户问题：
                                {question}

                                给定资料：
                                {context}

                                待评回答：
                                {answer}

                                本用例评测标准：
                                {criteria}
                                """)
                        .param("question", testCase.question())
                        .param(
                                "context",
                                String.join("\n", testCase.context())
                        )
                        .param("answer", answer.content())
                        .param("criteria", criteria))
                .call()
                .entity(
                        JudgeResult.class,
                        spec -> spec.validateSchema()
                );

        if (result == null) {
            throw new IllegalStateException(
                    "裁判模型没有返回有效结果"
            );
        }

        return result;
    }
}

Spring AI 2.0 的 entity() 可以把模型输出映射成 Java 类型；启用 validateSchema() 后，框架会验证 JSON 是否符合实体 Schema，并在格式不符合时携带错误信息重试。

不过，模型裁判不能被当作绝对真理。

比较稳妥的做法是：

1. 使用一批人工已经标注的样本校准裁判；
2. 固定裁判 Prompt 和评分规则版本；
3. 尽量不要只让被测模型评价自己；
4. 先执行代码规则，再调用模型裁判；
5. 关键失败样本仍然进入人工复核；
6. 模型对比时隐藏模型名称，减少品牌偏差。

八、使用 JUnit 建立回归测试

有了评测用例、被测服务、规则评测器和模型裁判后，就可以把它们接入 JUnit。

@SpringBootTest
class AiQualityGateTest {

    @Autowired
    private ObjectMapper objectMapper;

    @Autowired
    private AiAnswerService answerService;

    @Autowired
    private RuleEvaluator ruleEvaluator;

    @Autowired
    private AiJudge aiJudge;

    @Value("classpath:evals/policy-regression.json")
    private Resource evalResource;

    @TestFactory
    Stream<DynamicTest> regressionTests()
            throws IOException {

        List<AiEvalCase> cases = objectMapper.readValue(
                evalResource.getInputStream(),
                new TypeReference<List<AiEvalCase>>() {
                }
        );

        return cases.stream()
                .map(testCase -> DynamicTest.dynamicTest(
                        testCase.id(),
                        () -> evaluateCase(testCase)
                ));
    }

    private void evaluateCase(AiEvalCase testCase) {
        AiAnswer answer = answerService.ask(testCase);

        RuleResult ruleResult =
                ruleEvaluator.evaluate(testCase, answer);

        if (!ruleResult.pass()) {
            fail(String.join("\n", ruleResult.errors()));
        }

        JudgeResult judgeResult =
                aiJudge.evaluate(testCase, answer);

        assertAll(
                () -> assertTrue(
                        judgeResult.safe(),
                        judgeResult.feedback()
                ),
                () -> assertTrue(
                        judgeResult.weightedScore()
                                >= testCase.minJudgeScore(),
                        () -> "综合得分："
                                + judgeResult.weightedScore()
                                + "，要求："
                                + testCase.minJudgeScore()
                                + "\n"
                                + judgeResult.feedback()
                )
        );
    }
}

这样，AI 回答质量就不再只是一个后台页面中的聊天结果，而会成为正式测试报告的一部分。

某个用例失败时，可以清楚看到：

• 是命中了禁止规则；
• 是 Token 超过预算；
• 是事实一致性不足；
• 是回答没有解决问题；
• 还是模型裁判无法生成合法结构。

九、不要只运行一次

对于确定性代码，一个用例运行一次通常已经足够。

对于大模型，一个用例偶尔通过，并不代表它稳定。

关键场景可以重复运行多次，并计算通过率：

int repetitions = 5;

List<RunEvaluation> results = IntStream
        .range(0, repetitions)
        .mapToObj(index -> evaluateOnce(testCase))
        .toList();

long passed = results.stream()
        .filter(RunEvaluation::passed)
        .count();

double passRate = passed / (double) repetitions;

assertTrue(
        passRate >= 0.8,
        "实际通过率：" + passRate
);

这里的五次运行和 80% 阈值只是示例。

实际项目可以按照风险分级：

不能只关注平均分。

假设 100 个用例中，普通问题全部满分，但最关键的付款确认场景失败了，最终平均分仍然可能很好看。

因此，质量门禁至少需要同时判断：

• 关键用例失败数；
• 每个业务分类的最低得分；
• 总体平均得分；
• 多次运行通过率；
• 相对于基线版本的变化；
• Token 和时延预算。

十、使用基线对比，而不是迷信绝对分数

模型裁判给出的 0.85，并不一定意味着客观世界中的“85分”。

它更适合用来比较相同评测体系下的不同版本。

例如：

V13 的回答正确性和相关性提高了，但事实性下降，Token 消耗也明显增加。

这时不能简单地说 V13 更好，而要结合业务目标做判断。

在仓库中可以保存一份基线：

{
  "version": "prompt-v12",
  "overallScore": 0.89,
  "groundedness": 0.91,
  "criticalPassRate": 1.0,
  "averageTotalTokens": 820,
  "p95LatencyMs": 3200
}

新版本至少需要满足：

• 关键场景不能退化；
• 事实一致性不能低于底线；
• 总体得分不能显著低于基线；
• Token 和时延增长必须在允许范围内；
• 如果成本上升，必须换来可验证的质量提升。

这比单纯设置一个“总分大于 0.8”的规则更加可靠。

十一、接入 CI 质量门禁

AI 评测不一定要在每次普通单元测试中执行。

更合理的方式是把它设计为独立测试任务：

name: AI Quality Gate

on:
  pull_request:
    paths:
      - "src/main/**"
      - "src/test/resources/evals/**"
      - "prompts/**"
      - "pom.xml"
  workflow_dispatch:

jobs:
  ai-evaluation:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "21"
          cache: maven

      - name: Run AI evaluation
        env:
          AI_API_KEY: ${{ secrets.AI_API_KEY }}
        run: >
          mvn -B
          -Dtest=AiQualityGateTest
          test

可以进一步把任务分为三层：

PR 快速评测

只运行少量核心样本，尽快发现明显回归。

每晚完整评测

运行全部正常、边界、对抗和历史失败样本，并重复执行关键用例。

发布前对比评测

同时运行当前生产版本和候选版本，生成分类得分、成本、时延和失败样本对比报告。

评测失败后，CI 不应该只输出一句“测试失败”，而应保存完整报告，包括：

• 测试用例 ID；
• 用户问题；
• 使用的上下文；
• 模型回答；
• 规则失败原因；
• 裁判评分；
• 裁判反馈；
• Token 使用量；
• 响应时长；
• Prompt 版本；
• 模型配置版本。

十二、把生产失败样本送回评测集

离线评测集永远不可能一次性覆盖所有真实问题。

真正有效的评测体系必须形成反馈闭环：

flowchart LR
    A["生产会话脱敏采样"] --> B["自动检测与人工标注"]
    B --> C["失败样本库"]
    C --> D["加入版本化回归集"]
    D --> E["修复 Prompt、RAG 或代码"]
    E --> F["执行离线评测"]
    F --> G["灰度发布"]
    G --> A

例如，生产环境中出现一次“模型把合同总金额识别错了”的问题。

团队不应该只修改 Prompt 然后结束，而应该：

1. 对会话数据进行脱敏；
2. 把问题、上下文和错误回答保存为失败样本；
3. 标注正确结论和评分标准；
4. 加入 contract-regression.json；
5. 修复 Prompt、检索或解析逻辑；
6. 确认旧问题已经通过；
7. 确认其他合同场景没有发生回归。

这样，每一次线上事故都会转化为系统未来的防御能力。

Spring AI 2.0 还能够对 ChatClient、ChatModel、Advisor、EmbeddingModel 和 VectorStore 等组件记录指标与链路信息。Prompt 和 Completion 默认不会被导出，因为其中可能包含大量或敏感内容；开启相关日志时应先做好脱敏和权限控制。

十三、最容易踩的几个坑

1. 对整个回答做字符串相等判断

这种方式会把正常的语言变化当成错误。

字符串断言只适合固定字段、枚举值、关键提示语和结构化数据。

2. 所有判断都交给模型裁判

JSON 解析、字段校验、金额范围和敏感信息匹配，代码判断通常更加稳定、便宜。

模型裁判应该处理语义问题，而不是替代普通程序逻辑。

3. 只准备“正确答案明显”的简单问题

真实风险往往出现在资料不足、条件冲突、问题模糊、越权请求和提示词注入场景。

评测集必须包含失败路径。

4. 只看总体平均分

平均分会掩盖关键业务分类的退化。

应分别统计合同、订单、付款、权限、知识问答等类别。

5. 修改 Prompt，却不记录版本

如果评测报告不知道使用的是哪个 Prompt，就无法复现结果。

Prompt、模型参数、检索配置和工具定义都应该版本化。

6. 把真实会话原样写入日志

真实 Prompt 可能包含姓名、手机号、合同、账号和内部制度。

生产样本进入评测集前必须脱敏，并设置访问权限和保留期限。

十四、总结

当 AI 功能只停留在 Demo 阶段时，开发人员手动聊几次，可能已经足够判断大致效果。

但当它进入企业系统，开始回答制度、分析合同、生成代码、操作工具甚至影响业务决策后，“感觉回答得不错”就不再是一个可以接受的验收标准。

真正可靠的 AI 工程，需要同时建立：

• 版本化评测数据集；
• 硬性业务规则；
• 相关性与事实性评测；
• 多次运行通过率；
• Token 与时延预算；
• 新旧版本基线对比；
• CI/CD 质量门禁；
• 生产失败样本反馈闭环。

大模型可以是概率性的，但系统发布流程不能是概率性的。

我们无法要求模型每次使用完全相同的句子，却可以要求它在关键事实、业务规则、安全边界和成本预算上始终达到明确标准。

这才是 AI 功能从“能够调用模型”，走向“可以稳定交付”的关键一步。