AI 功能的测试策略
本篇要点:给 AI 功能建一套「改动能被挡住、跑起来不烧钱」的测试。前置:《批处理与异步:大规模 AI 任务编排》把批量任务编排好了,这一章回答它凭什么算跑对了。
为什么需要它
Prompt 里改了一个词,把「简洁回答」改成「严格按以下格式回答」。三天后结构化输出的解析失败率从 0.3% 涨到 4%。
回滚之后我做的第一件事是看测试。42 个单测全绿,一个没红。原因很快就找到了:所有测试都 mock 了 ChatClient,返回的是测试里写死的那段 JSON。我把 prompt 改成了火星文,这些测试照样全绿——它们验证的是 Mockito 的 thenReturn,不是我的 prompt。
这是 AI 功能测试最容易掉进去的坑:被测对象其实包含「prompt + 解析 + 兜底」这一整段,而你只测了 if/else。模型本身不是你的代码,不该被 mock 掉;该被替换掉的是它背后的网络调用。
这一章要建的是四层:纯函数层、录制回放层、黄金文件层、真实调用层。前两层每次提交都跑,第三层合并前跑,第四层每天夜里跑一次。
核心概念
确定性的接缝放在哪
测试里能控制的只有边界。AI 功能有两条边界可选:ChatModel 接口,和它下面的 HTTP。选哪个决定了你能测到什么。
替换 ChatModel 快,但你测不到 JSON 序列化、响应字段映射、finish_reason 处理这些真正出错的地方——《结构化输出:让模型稳定返回对象》那些结构化输出解析失败,八成出在这一层。替换 HTTP 慢一点,但整条链路都是真的,只有字节是假的。
类比:测数据库访问时用 H2 还是 Testcontainers。H2 快,但 SQL 方言差异最后会在生产暴露;Testcontainers 慢,测的是真库。AI 这边我站在 Testcontainers 那侧——用本地 HTTP 桩,其余全真。
反例:Mockito.mock(ChatModel.class) 然后 when(...).thenReturn(...)。你连自己写的 OutputConverter 都没进过。
录制回放:存的是整帧,不是那段文字
录制回放(record and replay)指把一次真实的响应完整存下来,回放时按字节原样返回。
关键在「完整」。只存 choices[0].message.content 那段字符串,会丢掉三样东西:usage(成本断言没法做)、finish_reason(截断检测没法做)、tool_calls(《工具调用:把 Java 方法暴露给模型》的工具链路完全测不到)。我第一版就是这么存的,结果工具调用的回归测试全成了摆设。
供应商的响应格式会变,所以 fixture 要跟代码一起进仓库、跟 PR 一起评审。改 fixture 等于改契约,这个动作应该显眼。
黄金文件:把 prompt 当代码审
黄金文件测试(golden test)断言的是「渲染后的 prompt 与基线逐字一致」。prompt 模板加变量渲染成一段文本,把这段文本存成文件;改了模板,测试红,你得同时更新文件,diff 会出现在 code review 里。
它不是断言模型输出,是断言你的输入。这一层最便宜也最有效——我上面那次事故,一个黄金文件测试就能拦住。
反例:断言「输出包含『退款』两个字」。这种弱断言在 90% 的输入上都会通过,剩下的 10% 才是你想抓的。
输出断言分三级
结构断言查「能不能解析、字段齐不齐、枚举值合不合法」,纯 Java,零成本,应该覆盖每一个 prompt。语义断言查「关键事实在不在检索到的原文里」,可以用字符串包含,也可以用 RelevancyEvaluator 这类模型裁判。质量断言查「答得好不好」,只能靠模型裁判或人工,成本最高。
三级别混着放。把模型裁判塞进 PR 门禁,你会得到一批随机失败的红色,然后所有人开始习惯性重跑。
表 10-1 四层测试各自的位置与代价
| 层级 | 是否联网 | 单次耗时 | 何时跑 | 失败意味着 |
|---|---|---|---|---|
| 纯函数(模板渲染、解析、脱敏) | 否 | 毫秒 | 每次提交 | 代码有 bug |
| 录制回放(HTTP 桩) | 否 | 百毫秒 | 每次提交 | 契约或映射层坏了 |
| 黄金文件(prompt 文本) | 否 | 毫秒 | 每次提交 | 有人改了 prompt,需确认 |
| 真实调用(少量样本) | 是 | 分钟 | 每夜或手动 | 供应商变了,或模型行为漂移 |
如图 10-1 所示,越往下越贵、越少、越晚跑。倒过来放,CI 会先崩在成本上。
图 10-1 三层阻断加一层观察
动手实践
依赖:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>spring-boot-starter-test 已经带了 JUnit 5、AssertJ、Mockito,不需要再单独引。回放桩用 JDK 自带的 com.sun.net.httpserver,一个额外依赖都不用加。
第一步:搭一个能回放的 HTTP 桩
代码 10-1 起一个监听随机端口的服务,把 fixture 文件原样吐回去。用随机端口是为了让并行跑的测试不打架。
package com.example.aitest;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.nio.file.Files;
import java.nio.file.Path;
/** 把录下来的一次真实响应按字节回放,端口由系统分配 */
public final class ModelReplayServer implements AutoCloseable {
private final HttpServer server;
public ModelReplayServer(Path fixture) throws IOException {
byte[] body = Files.readAllBytes(fixture);
this.server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
this.server.createContext("/v1/chat/completions", exchange -> {
exchange.getResponseHeaders().add("Content-Type", "application/json");
exchange.sendResponseHeaders(200, body.length);
try (OutputStream out = exchange.getResponseBody()) {
out.write(body);
}
});
this.server.start();
}
public String baseUrl() {
return "http://127.0.0.1:" + server.getAddress().getPort();
}
@Override
public void close() {
server.stop(0);
}
}这个类本身没有输出,能编译、能 close() 干净就够了——它的效果在下一步的测试结果里看。
配一个 src/test/resources/fixtures/tag-completion.json,内容就是从真实响应里复制来的整帧(这里只留关键字段):
{
"id": "chatcmpl-rec-0001",
"object": "chat.completion",
"created": 1763308442,
"model": "recorded-model",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "{\"category\":\"REFUND\",\"confidence\":0.92}" },
"finish_reason": "stop"
}],
"usage": { "prompt_tokens": 312, "completion_tokens": 34, "total_tokens": 346 }
}这个文件怎么来?我会写一个只在本地跑的录制程序:正常调一次接口,把 ChatResponse 序列化后按响应形态命名落盘。一次录制通常要覆盖四种形态——正常、被截断(finish_reason=length)、带工具调用、以及供应商返回 400 的那份错误体。只录正常那条,等于只测了最好的情况。
录制之前先脱敏。fixture 会进 git,永久留在历史里,真实客服对话里的手机号和订单号必须换成假数据,且长度与格式保持一致——把 11 位手机号换成 3 位,正则相关的那部分测试就失真了。
第二步:让整条链路跑在回放上
代码 10-2 用 @DynamicPropertySource 把随机端口喂给自动配置,ChatClient 由容器注入,走的还是生产那条路径。
package com.example.aitest;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.file.Path;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
@SpringBootTest
class TicketTagReplayTest {
private static ModelReplayServer server;
@DynamicPropertySource
static void replayProperties(DynamicPropertyRegistry registry) throws IOException {
server = new ModelReplayServer(Path.of("src/test/resources/fixtures/tag-completion.json"));
registry.add("spring.ai.openai.base-url", server::baseUrl);
registry.add("spring.ai.openai.api-key", () -> "test-key");
}
@Autowired
ChatClient chatClient;
@Test
void 解析录制响应并读出成本() {
ChatResponse resp = chatClient.prompt()
.system("你是工单分类器,只输出给定枚举中的一个类别,不要解释。")
.user("标题:退款没到账\n正文:上周申请的退款一直没到账,订单 SO202611160001")
.call()
.chatResponse();
assertThat(resp.getResult().getOutput().getText()).contains("REFUND");
assertThat(resp.getMetadata().getUsage().getPromptTokens()).isEqualTo(312);
assertThat(resp.getMetadata().getUsage().getTotalTokens()).isEqualTo(346);
}
@AfterAll
static void stop() {
if (server != null) {
server.close();
}
}
}运行结果:
$ mvn -q test -Dtest=TicketTagReplayTest
2026-11-16T22:41:07.221+08:00 INFO 51882 --- [ main] o.s.a.o.OpenAiChatModel : Request to /v1/chat/completions
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.812 s3.8 秒里大半是 Spring 上下文启动。这条测试零 API 成本,可以在每次提交跑。
第三步:黄金文件守住 prompt
package com.example.aitest;
import static org.assertj.core.api.Assertions.assertThat;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.ai.template.st.StTemplateRenderer;
class TagPromptGoldenTest {
private static final Path GOLDEN = Path.of("src/test/resources/golden/tag-prompt.txt");
// 提示词里要出现 JSON 的花括号,所以占位符改用 < > 两种定界符
private static final String TEMPLATE = """
你是工单分类器。可选类别:<categories>
只输出 JSON,形如 {"category":"REFUND","confidence":0.0}
标题:<title>
正文:<body>
""";
@Test
void 渲染结果与基线逐字一致() throws Exception {
PromptTemplate tpl = PromptTemplate.builder()
.renderer(StTemplateRenderer.builder()
.startDelimiterToken('<')
.endDelimiterToken('>')
.build())
.template(TEMPLATE)
.build();
String rendered = tpl.render(Map.of(
"categories", "REFUND,LOGISTICS,OTHER",
"title", "退款没到账",
"body", "上周申请的退款一直没到账"));
String expected = Files.readString(GOLDEN, StandardCharsets.UTF_8);
assertThat(rendered).isEqualTo(expected);
}
}默认渲染器用的是 StringTemplate,占位符是 {}。一旦提示词里要写 JSON 示例,{"category":...} 里的 { 就会被当成占位符,运行时报「找不到 category 这个变量」——我第一次写这类模板卡了半小时。官方给的办法是把定界符换成 < >,代码里那三行 renderer(...) 就是干这个的。
更新基线的方式是删掉文件重跑一次、把打印出来的渲染结果粘进去,确认 diff 合理后提交。不要写「测试自动覆盖基线」的开关——那等于关掉了这个测试。
运行结果(改了一个词之后):
$ mvn -q test -Dtest=TagPromptGoldenTest
org.opentest4j.AssertionFailedError:
expected: "你是工单分类器。可选类别:REFUND,LOGISTICS,OTHER ..."
but was: "你是工单分类助手。可选类别:REFUND,LOGISTICS,OTHER ..."一个字的差异,在 code review 里是一行 diff,在线上是 4% 的解析失败。
第四步:真实调用挡在 PR 之外
真实调用层的测试用 @Tag("llm") 标记,默认被 surefire 排除,要跑的时候用一个 profile 把排除项顶掉:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<excludedGroups>llm</excludedGroups>
</configuration>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>llm</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<excludedGroups combine.self="override" />
<groups>llm</groups>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>combine.self="override" 不能省。默认的 <excludedGroups> 是子元素,Maven 合并配置时不会把同名元素覆盖掉,结果就是「指定了 groups 仍然一条都不跑」,我第一次配这个恰好在演示前十分钟。
@Tag("llm") // org.junit.jupiter.api.Tag
@EnabledIfEnvironmentVariable(named = "OPENAI_API_KEY", matches = ".+")
class TagQualityNightlyTest {
private static int tokensSpent;
@Test
void 二十条样本的语义通过率不低于八成() {
// 每条的真实调用都累加 response.getMetadata().getUsage().getTotalTokens()
assertThat(tokensSpent).isLessThan(20_000); // 成本闸门
}
}运行结果:
$ mvn -q verify -Pllm
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0没配 key 的机器上是:
[INFO] Tests run: 0, Failures: 0, Errors: 0, Skipped: 3跳过 3 条是预期行为,不是失败。CI 里要显式检查「跳过数不超过预期」,否则这类测试会悄悄全被跳过,一年后你才发现它早就不跑了。
夜间任务我给它单独设了总额:单次运行最多 20 条样本、合计不超过 2 万 token,超了就抛异常终止。理由是这类任务最容易被「顺手加两个 case」慢慢养大,某天你发现月度账单里有一笔来自 CI 的固定支出。
常见误解
很多人以为覆盖率 80% 就安心了。 覆盖率算的是分支被执行过,不是行为被验证过。你那个 mock 掉 ChatClient 的测试,覆盖了 service 的每个 if,而对 prompt 的行为一无所知。对 AI 功能,我更看「有没有黄金文件」和「回放 fixture 覆盖了几种响应形态」这两个数。
很多人以为 temperature 设成 0 就是确定性的。 其实 0 只降低方差,不消除。浮点累加顺序、服务端批处理、供应商分批次的模型更新,都会让同样的输入偶尔给出不同输出。确定性只能来自录制回放:字节是死的,模型是活的。
很多人以为用大模型当裁判就能自动评测。 裁判自己有偏好,实测里普遍偏向更长的答案和排在前面的选项;它本身的版本也在变。所以裁判只适合做趋势观察,阈值放宽、失败只告警。要拿它当门禁,得先把你选定的裁判模型版本锁死,再用人工标注的 50 条样本校一遍一致性,这两步没做之前别开门禁。
小结
- 被测对象包含 prompt 和解析,不只是 if/else;mock 掉
ChatModel等于把要测的东西一起扔了。 - 接缝放在 HTTP 层:本地桩 + 整帧 fixture,序列化、字段映射、
usage全都是真的。 - 黄金文件守输入,回放守契约,真实调用守漂移;三层职责不同,别互相替代。
- 输出断言分结构、语义、质量三级,模型裁判只进观察层,不进阻断层。
- 真实调用用
@Tag加环境变量双重开关,并且检查跳过数,防止整套测试悄悄停摆。
相关主题
到这里,一个 Java 侧的 AI 功能从接入、工具、检索、记忆到观测、批处理、测试,每一段都摸过一遍了。但有些事 Java 做起来就是别扭:自己训模型、跑本地推理、做 embedding 微调。《进阶:Java 与 Python 模型服务协作》讲和 Python 服务怎么分工——gRPC 契约怎么定、模型版本怎么灰度、Python 那边挂了 Java 这边怎么不被拖死。