Skip to content

结构化输出:让模型稳定返回对象 ​

本篇要点:能把模型输出稳定地落成 Java 对象,并在格式跑偏、字段缺失时知道该补哪一层。 前置:《Spring AI 入门:ChatClient 与模型接入》已经跑通 ChatClient,本篇在它的调用链上再加一道类型转换。

1. 为什么需要它 ​

2026 年 8 月,工单自动分类上线。模型返回的东西长这样:

text
好的,分类结果如下:
```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 里暴露。

java
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 就把这个开关去掉——兼容端点在这里最常翻车,而报错体通常只告诉你响应格式不支持,不会告诉你该怎么办。

第二个版本加上外层兜底。注意它在两次之间不做退避,也没打算"修复"问题——它只是让失败变成可处理的状态。

java
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:工具不再是进程内方法,而是另一个进程能发现、能调用的服务。