不知不觉,Spring AI 系列已经写到第 24 篇了。前几篇我们把 ChatClient、Prompt、RAG、Function Calling 都过了一遍,这次聊一个我在实际项目中几乎每个功能都会撞上的问题:怎么让大模型返回的数据,不是一段“人话”,而是一份干净、直接能用的结构化数据。
这事儿的痛点在真实场景里太常见了。上个月我做一个合同要素抽取的功能,输入是一份几十页的招标文件,我要从里面提取“项目编号、采购人、预算金额、投标截止时间”这几个字段。第一次用最朴素的方式让模型返回 JSON,结果模型给了我一段解释:“好的,根据文档内容,我提取到以下信息:项目编号是 XX...”然后才跟着一段不完整的 JSON,还带 ```json 代码块标记。我写了个正则清洗,刚跑通一个文档,换一个文档格式又变了,直接被逼疯。
后来我把项目升到 Spring AI 1.x,认真用了它的结构化输出 API,这个问题才算真正解决。Spring AI 1.x 把这个需求封装成了一套非常顺手的 API:你定义一个 Java record,框架负责把“让模型输出指定 JSON 格式”的提示词自动塞进请求,然后在拿到模型回复后自动解析成对应的 Java 对象。你不需要手写格式提示词,不需要写解析器,更不需要面对那堆乱七八糟的清洗逻辑。这篇文章我就把这套 API 从接口到实战,再到我踩过的坑,完整拆一遍。
1. 为什么需要结构化输出
1.1 大模型输出的“自由”反而是问题
大模型的本职工作是“预测下一个 token”,不是“严格遵守数据格式”。你可以通过提示词要求它输出 JSON,但它并没有内置的、百分百可靠的保证机制。实际生产里,模型回复可能长这样:
text复制根据您的要求,以下是提取出的结果:
```json
{
"name": "张三",
"age": 28,
"city": "杭州"
}
如果您还有其他需求,请随时告诉我。
code复制
这段内容从人的视角完全正常,但对程序来说是灾难。你要处理前置解释、尾部补充、代码块包裹,还要担心名字是“张三”还是“Zhang San”,年龄到底是不是字符串“28”。
我习惯用一个类比:让一个优秀实习生写报告,他内容写得很好,但格式总有自己的喜好,一会儿用表格一会儿用列表,一会儿中文冒号一会儿英文冒号。你需要的不是一个更聪明的实习生,而是一套“无论谁来写,交上来格式都一致”的模板和检查流程。结构化输出 API 干的就是这件事,只不过模板和检查都由 Spring AI 自动完成了。
### 1.2 结构化输出在做什么
Spring AI 1.x 的结构化输出,本质上是把“让模型按格式输出 + 把输出转成类型”这两步走封装成了标准接口。你在业务代码里做的事情极其简单:
```java
Person person = chatClient.prompt()
.user("张三今年28岁,住在杭州")
.call()
.entity(Person.class);
框架在背后帮你做了三件事:第一条,根据 Person.class 生成 JSON Schema 或格式说明,通过提示词注入给模型;第二条,调用大模型拿到原始文本;第三条,把原始文本清洗、反序列化成 Person 对象。如果解析失败,还有容错机制兜底。
这套能力解决的不只是“解析 JSON”这个小事。它更大的价值是让“大模型返回”这件事在代码层面变成了一次普通的类型转换,后面的逻辑不用再关心“这段文本是不是合法 JSON”“字段够不够全”“要不要转义”,类型不匹配在运行早期就能暴露出来,而不是等到写库的时候才炸。
对于“用 Spring AI 开发 Agent、做 NL2SQL、做文档解析生成结构化文本(比如合同、招标文件里按页码/章节/段落输出字段)”这些场景,结构化输出几乎可以说是必经之路。你不可能让下游系统直接消费大模型的自由文本,除非你想体验什么叫“线上的不确定性”。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心 API 全家桶
2.1 StructuredOutputConverter 接口
Spring AI 1.x 所有结构化输出转换器,都实现了同一个接口:
java复制public interface StructuredOutputConverter<T> {
String getFormat();
T convert(String text);
}
这个接口非常薄,只有两个方法。getFormat() 返回的是要给模型看的格式说明字符串,它会在请求时被拼到提示词里,告诉模型“你应该输出什么形状的东西”;convert(String text) 接收模型返回的原始文本,输出转换好的目标类型 T。
选这个设计的原因,我理解是把“提示词生成”和“结果解析”绑定在同一个对象里。你拿到一个 converter,既能知道怎么引导模型,又知道怎么解析结果,不会出现“提示词是一套、Parser 是另一套”的割裂感。
实际开发中,实现这个接口最多的场景是:公司内部有自定义的输出协议,比如加密串、压缩格式、特定编码,或者团队希望把解析结果先写日志再往下游传。但绝大多数场景我们不需要自己实现,直接用 Spring AI 内置的几个实现就够了。
2.2 BeanOutputConverter:主力转换器
BeanOutputConverter<T> 是我用得最频繁的转换器,没有之一。它做的事情,是把任意 Java Bean 或 record 类型作为目标,让模型输出匹配的 JSON,然后自动反序列化。
核心用法有两种。第一种是拿到格式模板,手动拼进自己的提示词:
java复制Bean
