结构化输出:让模型稳定返回对象
本篇要点:能把模型输出稳定地落成 Java 对象,并在格式跑偏、字段缺失时知道该补哪一层。 前置:《Spring AI 入门:ChatClient 与模型接入》已经跑通 ChatClient,本篇在它的调用链上再加一道类型转换。
1. 为什么需要它
2026 年 8 月,工单自动分类上线。模型返回的东西长这样:
好的,分类结果如下:
```json
{"category": "退换货", "priority": "高"}
```转换器在第一个"好"字上就崩了:
Unrecognized token '好的': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false')修完格式,又冒出第二种失败:JSON 是干净的,但少了 priority 字段。记录类里那个字段是 null,下游一个 switch 直接 NPE。
统计了一周:失败率 0.7%。一天八万张工单,五百多条要进死信队列等人工重跑。这个数字不是模型不行:模型每次都给了可读的答案,是我的代码假设了它一定给"机器可读"的答案。
这一章解决的就是这个假设:怎么让文本变成类型,以及类型不对的时候,系统该退到哪里。
2. 核心概念
2.1 entity() 做了三件事,但不保证结果
chatClient.prompt().call().entity(Ticket.class) 背后是三件事:从你的 Java 类型生成一份 JSON Schema;把 schema 和"请按这个格式输出"的说明拼进 prompt;拿到响应后反序列化。
注意中间那步的措辞:是"拼进 prompt",不是"下发给模型运行时"。所以默认路径下,entity() 是请求(request),不是约束(constraint)。官方文档的说法是 best effort——模型被请求按 schema 输出,但没有任何机制强制它。
反例:把 entity() 当成契约。它崩起来有三种常见姿势:JSON 前后多一段散文(就是本篇开头那种)、字段缺失、字段类型漂移(该给数字给了"三百")。
还有一个形状上的坑:schema 里的字段顺序跟着 record 的声明顺序走,可以用 @JsonPropertyOrder({"category", "priority", "evidence"}) 固定下来。这个顺序对生成质量到底有多大影响,我没做过对照实验,不敢下结论;但它至少能让两次实验可比——否则你改一个字段描述,顺序也跟着变了,说不清是哪个改动起的作用。
2.2 两个开关:一个管响应,一个管请求
2.0 给 entity() 加了第二个参数 Consumer<EntityParamSpec>,里面有两个开关。
validateSchema() 管响应侧。它自动注册一个 StructuredOutputValidationAdvisor,拿到响应后按 schema 校验;不通过就把具体错误(比如 missing required field 'priority')追加到 prompt 里重新请求,默认最多 3 次。因为错误是具体的,第二次不是盲重试,模型知道该补什么。这个 advisor 还会把每次重试的 token 用量累加,所以你看到的计费是三次之和。
useProviderStructuredOutput() 管请求侧。它把 schema 作为 API 级字段发给厂商,让模型运行时在解码阶段就挡住不合规的输出。听起来更彻底,但有两个前提:一是 provider 得支持原生结构化输出;二是 Spring AI 的判断方式是看 chat options 有没有实现 StructuredOutputChatOptions,没实现就静默忽略,回落到提示词模式。也就是说,你加了这一句,可能一点效果都没有,而且不报错。
两个开关可以叠加,官方推荐在"下游不能容忍形状漂移"时同时打开。
代价要算清楚。按一次调用 1.5 秒、800 token 这个量级估(千字工单上很常见),连续失败三次就是 4.5 秒和 2400 token——延迟和成本都翻三倍。所以这个开关适合放在"抽不出来比慢更糟"的场景(工单分类、审批结论),不适合放在聊天这种每轮都跑的地方。
EntityParamSpec 这一套是 2.0 才有的 API。《工具调用:把 Java 方法暴露给模型》起的示例把基线放在 1.1.8,那套代码里 .entity(Class) 照样能用,但校验和重试得自己接——下一节那个外层循环就是干这个的,把 MAX_ATTEMPTS 调大即可。
2.3 形状对了不代表语义对
JSON Schema 能保证的是结构:字段在不在、类型对不对、枚举值在不在集合里。它保证不了语义。
一张工单分类成 退换货、优先级 中、依据是原文里的一段话。这三个字段形状全对,但"依据"可能是模型编的,优先级可能和你们的 SLA 规则冲突。这些只有你的代码知道。
所以校验分两层:框架管形状,Bean Validation 管业务。@NotNull 挡空值,@Min 挡负数,自定义的 @AssertTrue 挡"退款金额大于订单金额"这种跨字段规则。
还有一件低成本高回报的事:给字段加 @JsonPropertyDescription。这段文字会进 schema 的 description,直接影响模型填得准不准。写"工单类别,只能是:退换货、物流、发票、其他",比只写字段名 category 的效果差一个量级。
2.4 流式和结构化不能混
.entity() 只能跟在 call() 后面。这一点在官方文档里是明确写死的:类型化解析需要完整响应,而 stream() 返回的是文本分片。开了 validateSchema() 之后更不行,那个 advisor 本身就要等完整响应才能校验。
所以"边流式边解析"在 Spring AI 里做不到。要同时满足"用户看着字长出来"和"落库存结构化数据",只有两条路:
一条是发两次请求:第一次流式给人看,第二次非流式抽取落库。代价是 token 翻倍,好处是两个诉求各自最优。
另一条是只发非流式,前端用骨架屏等一次返回。判断标准很朴素:这段内容用户需不需要"看着它长出来"。客服摘要不需要,聊天需要。按这个标准分,能省掉一半重复调用。
2.5 生产封装:兜底和留痕
框架的 advisor 只管 schema 校验失败那一条路。网络异常、5xx、你自己写的 converter 抛的异常,都不走那条回路。所以生产代码还需要一层外壳:
- 泛型方法,接收目标类型,返回
Optional<T>,把"没抽出来"变成正常返回值而不是异常; - 留痕。至少要记下类型、尝试次数和原始响应长度;排查阶段可以临时开
log.debug打出原文,但要清楚那会写进用户的工单内容,《可观测与护栏:成本、延迟与安全》讲脱敏时会回头处理它; - 打点:成功、失败、重试次数各一个计数器。《AI 功能的测试策略》做回归测试时,这批数据就是你的样本集。
图 3-1 一次结构化调用的完整回路:形状由框架管,语义由你的代码管,出口只有一个
如图 3-1 所示,失败最终都汇到同一个出口。这条设计的意义在于:调用方永远只处理两种结果——有对象,或者没有;而不是在业务代码里到处 catch 各种解析异常。
3. 动手实践
第一个版本,最小可用。类型用 record,字段加描述,只开 validateSchema()——它不依赖 provider 能力,任何 OpenAI 兼容端点都能跑。
依赖和配置沿用《Spring AI 入门:ChatClient 与模型接入》(spring-ai-bom:2.0.2 + spring-ai-starter-model-openai + spring-boot-starter-web),另外补一个 spring-boot-starter-validation,2.3 节讲的 @NotNull、@Min 都来自它。
写代码之前先做一件很多人跳过的事:把 schema 打印出来看一眼。new BeanOutputConverter<>(TicketClassification.class).getJsonSchema() 这一行返回的就是模型看到的完整 schema,在单元测试里断言一次,比在线上等着失败率上升便宜得多。
打印出来能看到两样东西:哪些字段进了 required,以及 @JsonPropertyDescription 的文字有没有真的落到 description 里。字段名拼错、描述忘了写、某个字段压根没进 schema,这些都在这张 schema 里暴露。
package com.example.crm.ai;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;
/** 字段描述会进 JSON Schema 的 description,直接影响模型填得准不准 */
record TicketClassification(
@JsonPropertyDescription("工单类别,只能是:退换货、物流、发票、其他") String category,
@JsonPropertyDescription("优先级,只能是:高、中、低") String priority,
@JsonPropertyDescription("判断依据,引用工单原文关键短语,不超过 20 字") String evidence) {
}
@Service
class TicketClassifier {
private final ChatClient chatClient;
TicketClassifier(ChatClient chatClient) {
this.chatClient = chatClient;
}
TicketClassification classify(String ticket) {
return chatClient.prompt()
.user(u -> u.text("给这张工单分类:{ticket}").param("ticket", ticket))
.call()
.entity(TicketClassification.class, spec -> spec.validateSchema());
}
}
@Component
class StructuredDemoRunner implements ApplicationRunner {
private final TicketClassifier classifier;
StructuredDemoRunner(TicketClassifier classifier) {
this.classifier = classifier;
}
@Override
public void run(ApplicationArguments args) {
System.out.println(classifier.classify("收到的电饭煲内胆有划痕,要求换货,已拍照。"));
}
}运行结果:
TicketClassification[category=退换货, priority=中, evidence=内胆有划痕,要求换货]把 validateSchema() 换成 useProviderStructuredOutput().validateSchema() 再跑一次。如果端点实现了 json_schema 格式的 response_format,你在抓包里能看到请求体多了一个 schema 字段;如果没实现,很可能直接 400。遇到 400 就把这个开关去掉——兼容端点在这里最常翻车,而报错体通常只告诉你响应格式不支持,不会告诉你该怎么办。
第二个版本加上外层兜底。注意它在两次之间不做退避,也没打算"修复"问题——它只是让失败变成可处理的状态。
package com.example.crm.ai;
import java.util.Optional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.converter.BeanOutputConverter;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;
@Service
class StructuredExtractor {
private static final Logger log = LoggerFactory.getLogger(StructuredExtractor.class);
private static final int MAX_ATTEMPTS = 2;
private final ChatClient chatClient;
StructuredExtractor(ChatClient chatClient) {
this.chatClient = chatClient;
}
/** 失败返回 empty,不抛异常;日志记原因和原文长度,不打印原文本身 */
<T> Optional<T> extract(String prompt, Class<T> type) {
BeanOutputConverter<T> converter = new BeanOutputConverter<>(type);
for (int attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
String raw = null;
try {
raw = chatClient.prompt()
.user(prompt + System.lineSeparator() + converter.getFormat())
.call()
.content();
T value = converter.convert(raw);
if (value != null) {
return Optional.of(value);
}
log.warn("抽取结果为空,第 {} 次,类型 {},原文长度 {}", attempt, type.getSimpleName(),
raw == null ? 0 : raw.length());
} catch (Exception e) {
log.warn("抽取失败,第 {} 次,类型 {},原因 {},原文长度 {}", attempt, type.getSimpleName(),
e.getMessage(), raw == null ? 0 : raw.length());
}
}
return Optional.empty();
}
}
@Component
class ExtractorDemoRunner implements ApplicationRunner {
private final StructuredExtractor extractor;
ExtractorDemoRunner(StructuredExtractor extractor) {
this.extractor = extractor;
}
@Override
public void run(ApplicationArguments args) {
Optional<TicketClassification> result = extractor.extract(
"给这张工单分类:收到的电饭煲内胆有划痕,要求换货。", TicketClassification.class);
result.ifPresentOrElse(
r -> System.out.println("成功:" + r),
() -> System.out.println("失败:进入人工队列"));
}
}运行结果(第一次失败、第二次成功的日志):
WARN 12345 --- [main] c.e.crm.ai.StructuredExtractor : 抽取失败,第 1 次,类型 TicketClassification,原因 Unexpected character ('好' (code 22909)): expected a valid value
INFO 12345 --- [main] c.e.crm.ai.ExtractorDemoRunner : 成功:TicketClassification[category=退换货, priority=中, evidence=内胆有划痕]这段日志要说清楚一件事:第二次成功靠的是采样随机性,不是重试逻辑。同样的 prompt、同样的温度,第二次也可能再失败一次。所以外层重试只是兜底,真正降低失败率的是三件事:字段描述写清楚、validateSchema() 打开、必要时上原生结构化。
失败模式对照表,出问题时先来这里定位。
| 现象 | 根因 | 处置 |
|---|---|---|
Unrecognized token '好的' | JSON 前后有散文或代码围栏 | 收紧 system 提示;自定义 converter 剥围栏 |
missing required field | 字段被省略或判为可选 | 加 @JsonPropertyDescription;validateSchema() 打开 |
400 / response_format is not supported | 兼容端点未实现原生结构化 | 去掉 useProviderStructuredOutput() |
| 顶层数组解析失败 | OpenAI 原生不支持顶层数组 | 用容器 record 包一层(record FilmographyList(List<X> items)) |
数字变字符串("300") | 模型对类型理解漂移 | 字段用 String 接住再自行解析,或 schema 里加格式约束 |
4. 常见误解
"entity() 会约束模型。" 默认路径下它只是把 schema 写进提示词,属于请求而非约束。要约束得打开 useProviderStructuredOutput(),而它还有 provider 支持的前提。
"开了原生结构化就不会失败。" 原生只保证形状合规,不保证语义正确;而且支持面是部分的,$ref、深层嵌套数组、oneOf 之类常在限制名单里。官方文档自己也建议和 validateSchema() 一起用。
"流式返回也能解析成对象。" 不能,entity() 只能配 call(),validateSchema() 也不支持流式。要两边都要,就发两次请求,或者放弃其中一个。
5. 小结
entity()做三件事:生成 schema、写进 prompt、反序列化。默认是请求而不是约束。validateSchema()管响应侧,把具体错误回灌 prompt,默认重试 3 次;useProviderStructuredOutput()管请求侧,不支持时静默忽略。- schema 校验只管形状,语义校验要用 Bean Validation 自己补。
- 字段描述(
@JsonPropertyDescription)是提升填写质量最便宜的手段。 - 生产代码要有一层外壳:返回
Optional、保留原文、打点成功与重试次数。
6. 相关文章
到这一章为止,模型只能"说"。《工具调用:把 Java 方法暴露给模型》先让它"做":把 queryOrder、submitRefund 这样的 Java 方法用 @Tool 暴露出去,让模型自己决定调哪个、传什么参数——同时把超时、权限和幂等守住在服务端。这条路走到《MCP Server:让模型安全调用 Java 业务能力》会变成 MCP:工具不再是进程内方法,而是另一个进程能发现、能调用的服务。