结构化输出这件事,第一次做会觉得很简单:让模型返回 JSON,用 Jackson 一转,收工。等到它进生产,你会发现真正的问题不是"转不过去",而是转过去了,但数据是错的。
先看两个线上症状,它们看起来毫无关系,根因却是同一个。
症状一:风控系统报警,说某个意图识别模型的平均置信度只有 0.12,怀疑模型退化。捞了原始请求日志才发现,模型的输出长这样:
{
"intent":"refund_status","orderNo":"SO20261012001","confidence":0.93}
置信度明明给了 0.93。但业务代码拿到的是 0.0 —— 因为我们的 record 里还有一个 items 字段,模型没输出,Jackson 给 List 字段填了 null;而 confidence 那次是因为模型压根没返回这个字段,于是 double 被填成 0.0。全程没有异常、没有 WARN,监控上只表现为"模型突然变笨了"。
症状二:切到支持 strict 模式的服务端约束后,接口开始零星 400,错误信息是 Invalid schema for response_format。schema 是框架自动生成的,人工检查怎么看都合法。
这两件事的共同点是:我们把"能反序列化"当成了"契约被满足"。这两个判断差得很远,中间隔着的正是本篇要补的三层 —— 强 schema、前置校验、修复重试。
工程基线:JDK 21 + Spring Boot 3.5.16 + Spring AI 1.1.8(Jackson 由 Boot 管理,实测 2.21.4)。所有结论都在 agent-demo 里跑过,配套代码在 basics 模块 ch08 包。
一、先看清框架给了你什么
BeanOutputConverter 是 Spring AI 里把"文本 → 对象"这件事收敛起来的入口,ChatClient.entity(Class) 底层用的也是它。它的 getJsonSchema() 返回一份 JSON Schema,getFormat() 返回一段要求模型按 schema 输出的提示词。
对我们这个抽取契约,getJsonSchema() 的实测输出是:
{
"$schema" : "https://json-schema.org/draft/2020-12/schema",
"type" : "object",
"properties" : {
"confidence" : {
"type" : "number" },
"intent" : {
"type" : "string",
"enum" : [ "REFUND_STATUS", "COMPLAINT", "CANCELLATION", "OTHER" ]
},
"items" : {
"type" : "array",
"items" : {
"type" : "object",
"properties" : {
"qty" : {
"type" : "integer" }, "sku" : {
"type" : "string" } },
"required" : [ "qty", "sku" ]
}
},
"note" : {
"type" : "string" },
"orderNo" : {
"type" : "string" }
},
"required" : [ "confidence", "intent", "items", "note", "orderNo" ],
"additionalProperties" : false
}
三个必须记住的事实:
| 观察点 | 实测结果 | 影响 |
|---|---|---|
required |
包含全部字段,包括业务上可空的 note |
strict 模式下模型必须输出 note,想表达"没有"只能给空串 |
enum |
是 Java 枚举常量名,全大写 | 模型输出 refund_status 直接反序列化失败 |
additionalProperties |
每个 object 都已是 false |
不用自己补,但升级版本后要复核 |
这份 required 不是 bug,是明确的实现选择。反编译 BeanOutputConverter 的源码能看到这一行:
private void generateSchema() {
JacksonModule jacksonModule = new JacksonModule(
JacksonOption.RESPECT_JSONPROPERTY_REQUIRED,
JacksonOption.RESPECT_JSONPROPERTY_ORDER);
SchemaGeneratorConfigBuilder configBuilder = new <
1万+



被折叠的 条评论
为什么被折叠?



