## 01、痛点

你有没有见过这样的场景：模型明明答应了返回 JSON，结果它先来一句“好的，这是您要的分类结果：”，然后跟了一串字段；或者 priority 一会儿是 HIGH，一会儿是“高”，偶尔还直接给你一个 null。我是老李，最近带团队把大模型接进客服工单系统，差点被这个问题整不会了。今天不聊怎么把提示语写得更漂亮，只聊一件事：Spring AI 如何把模型的文本输出，变成 Java 里能直接写 if/else、进数据库、进工作流的强类型业务对象。

企业应用很少只需要一段自然语言。更多时候，我们需要的是分类结果、工单、风险等级、查询条件这种结构化数据。比如客户说“路由器一直断线，影响我下午的线上会议”，系统要的不是一段解释，而是一个对象：category 是网络故障，priority 是高，reason 是频繁掉线，needHuman 为 true。这个对象接下来要进派单逻辑、进 SLA 计算、进数据库留痕。如果它只是一个字符串，后面每一步都在走钢丝。

很多团队的第一反应，是在提示语里写一句“请返回 JSON”。然后代码里 String response = chatClient.call(...) 拿回文本，再做 substring、正则、JSON.parse、手工 setter。看起来能跑，实际上非常脆。模型可能输出 Markdown 代码块，可能前面加“好的”，可能字段名大小写不一致，可能少一个右括号，可能把 priority 写成“高”、“HIGH”、“P1”三种值。对 Java 企业系统来说，这些差异不是小问题，而是业务分支会走错的隐患。

所以今天要讨论的，不是“能不能返回 JSON”，而是怎么把这件事变成有契约、有校验、可重试的工程能力。

## 02、是什么

Spring AI 里的 Structured Output，本质是把模型文本输出转换成 Java Record/POJO 的能力。它不是一个简单的 JSON 解析器，而是分三层：

第一层，Output Converter。这是一个普通转换器，把模型输出按约定格式转成对象。它在 Spring AI 中属于 best-effort，意思是尽量解析，但不承诺语义校验。比如 BeanOutputConverter 可以把一段 JSON 字符串映射到 TicketCategory。但如果模型少一个字段、枚举值超范围，它可能给你一个字段为 null 的对象，或者直接抛异常。

第二层，Provider-native Structured Output。这是厂商原生结构化输出能力，例如在请求模型时直接传入 JSON Schema，让生成阶段就按结构输出。它不是事后分析，而是把约束下推到模型生成过程，可靠性明显高于自由文本后解析。

第三层，JSON Schema Validation。这一步在转换完成后进行严格校验，检查字段类型、必填项、枚举范围、字符串格式等。官方明确指出，普通 StructuredOutputConverter 是 best-effort，应结合 Schema Validation 使用。Spring AI 2.0 还支持校验失败后的自纠正重试，把失败原因回传给模型，让它重新生成。

所以 Structured Output 不是一个提示语技巧，而是一条从生成约束、转换、校验到重试的链路。

## 03、为什么

为什么只在提示语里写“请返回 JSON”仍然不可靠？因为大模型的输出是概率采样，天然带有不确定性。它可能在大多数情况下表现得很好，但遇到长输入、少见类型、复杂嵌套时，格式会漂移。没有 Schema 约束时，字段名可以叫 severity 也可以叫 riskLevel，枚举值可以叫 HIGH 也可以叫“高”，结构可以是对象也可以是数组。这些对自然语言阅读无所谓，对 Java 程序却是灾难。

Java 企业开发的核心假设是类型稳定。Service 方法签名写的是 TicketCategory categorize(String text)，那返回值就必须是 TicketCategory。如果内部靠字符串解析，等于把类型安全拆掉，后续所有 if/else、switch、数据库写入都在一个不可靠的地基上。尤其像工单优先级这种字段，如果拿到“高”和“HIGH”两种值，SLA 判断就可能出错。

普通的 Output Converter 只是 best-effort，它能解析合法 JSON，但不会帮你纠正模型犯的错。比如模型返回了 {"category":"网络","priority":"紧急"}，而你的 TicketCategory 里 priority 想接收枚举 HIGH/MEDIUM/LOW，转换可能失败。只有加入 Schema Validation，才能明确拒绝这种偏差，并触发重试。这也是为什么 Spring AI 官方把 Schema Validation 作为正式一环。

2.0 的自纠正重试尤其重要。它把校验失败信息作为新的约束返回给模型，让模型知道上一次哪里错了。这种闭环让结构化输出从“碰运气”变成“可收敛”。

## 04、架构

整个链路可以抽象成下面这样：

```
客户问题文本
   |
   v
模型调用（可选：原生 JSON Schema 约束）
   |
   v
原始文本输出
   |
   v
Output Converter（BeanOutputConverter 等）
   |
   v
JSON Schema Validation（类型、必填、枚举、格式）
   |-- 失败：自纠正重试，回传错误给模型
   v
TicketCategory Record / POJO
   |
   v
if/else、数据库、工作流
```

三层能力并不互斥。Provider-native Structured Output 解决的是“生成阶段尽量按 Schema 走”；Output Converter 解决的是“把文本转成 Java 对象”；Schema Validation 解决的是“转换结果是否真的可信”。把它们叠加在一起，才是一条完整的企业级输出链路。

在 Spring AI 中，开发者通常只需要定义目标类型，框架会生成相应的 JSON Schema，并在调用模型时携带。不同服务商对原生结构化输出的叫法和参数略有差异，但核心都是把 JSON Schema 下推到生成阶段，而不是在提示语里软性要求。

## 05、实战

回到工单分析场景。先定义一个不可变 Record，字段一眼看懂：

```java
public record TicketCategory(
    String category,
    String priority,
    String reason,
    boolean needHuman
) {}
```

然后配置结构化输出。以 Spring AI 常见用法为例：

```java
// 1. 创建转换器
BeanOutputConverter<TicketCategory> converter =
        new BeanOutputConverter<>(TicketCategory.class);

// 2. 获取 JSON Schema
String schema = converter.getJsonSchema();

// 3. 调用模型，传入原生 JSON Schema 约束
ChatResponse response = chatClient.prompt()
        .user("分析客户问题：" + customerText)
        .options(OpenAiChatOptions.builder()
                .responseFormat(new ResponseFormat("json_schema", schema))
                .build())
        .call()
        .chatResponse();

// 4. 转换为 TicketCategory
TicketCategory ticket = converter.convert(
        response.getResult().getOutput().getContent()
);
```

这里没有手工截字符串，也没有用正则去猜字段。模型输出在转换时已经对到 Record 的字段上。为了确保 priority 这类字段不越界，建议接着做 Schema Validation：

```java
if (ticket.category() == null || ticket.priority() == null) {
    // 触发一次带错误信息的纠正重试
    ticket = retryWithSchemaError(customerText, validationErrors);
}
```

2.0 的自纠正重试可以封装得更干净。核心思路是把校验失败字段和原因回传给模型，例如告诉它“priority 只能是 HIGH、MEDIUM、LOW，你返回了‘高’”，让它重新输出。

拿到 ticket 后，业务代码可以直接写：

```java
if (ticket.needHuman()) {
    dispatchToHuman(ticket);
} else {
    autoReply(ticket);
}

ticketRepository.save(ticket);
```

这就是强类型业务对象的价值。TicketCategory 可以进入 Service、Repository、工作流参数，和普通 Java 对象没有区别。

## 06、洞见

很多人把 Spring AI 当成一个调用大模型的封装库，觉得只是少写几行 HTTP 请求。但更深一层看，它真正适合 Java 企业开发的一点，是让 AI Output 从“文本”进入“强类型业务对象”。

传统做法里，模型输出是一段文字。哪怕它看起来像 JSON，对代码来说仍然是 String。后续要进 if/else，就得先解析；要进数据库，就得手工 map；要进工作流，就得拼 DTO。每一步都可能因为字段漂移而崩。Spring AI 的 Structured Output 改变了这个边界：模型输出在框架层被转换成 Record/POJO，类型契约重新建立。编译器、单元测试、序列化、Bean Validation，这些 Java 世界成熟的工具链都能接上。

这个转变看似只是加了一个 Converter，实际上决定了 AI 能力能否进入企业核心流程。没有强类型输出，AI 只能做聊天机器人、摘要、问答这类对容错较高的场景。有强类型输出，AI 才能参与派单、风控、审批、查询构造这些需要确定性分支的业务。

所以选型时不要只看“支不支持 JSON”。要看它能不能把输出接进你的类型系统，能不能校验，失败时能不能自纠正。这才是 Java 企业开发要的可靠性。

## 07、行动

落到行动上，一句话：后续所有需要进入 if/else、数据库或工作流的数据，禁止直接解析自由文本。

具体可以按这个清单走：

先用 Java Record/POJO 定义输出契约。字段、类型、必填、枚举值要在代码里写清楚，不要等到解析失败才发现模型乱编。
调用模型时优先使用 Provider-native Structured Output，把 JSON Schema 下推到生成阶段。
把普通 Output Converter 当解析器，不要把它当可靠性保障。官方都说了它是 best-effort。
转换之后必须做 Schema Validation，检查类型、必填、枚举、格式。
开启校验失败后的自纠正重试，并限制重试次数和超时，避免无限循环。
业务层仍要做轻量防御，比如 null 检查、默认值、枚举兜底。
为结构化输出建立回归用例，覆盖边界输入，例如长文本、少字段、错误枚举、空字符串。

一个简单判断：如果这个数据只用于展示给用户看，可以宽松一些；如果它要进 if/else、进数据库、进工作流，就必须走强类型链路。没有例外。

## 08、小结

Spring AI 的结构化输出不是又一个 JSON 解析工具，而是一条从模型生成、转换、校验到重试的完整链路。Provider-native Structured Output 尽量让模型在生成阶段不跑偏，Output Converter 把文本转成 Java 对象，JSON Schema Validation 保证转换结果可信，2.0 的自纠正重试再兜住最后一段。

对企业开发来说，最有价值的不是“模型会返回 JSON”，而是返回的 JSON 能变成 TicketCategory、RiskLevel、SearchCondition 这样的强类型业务对象。类型边界一旦重新建立，后面的 if/else、数据库、工作流才真正安全。

## 09、链接与概念说明

概念说明：

Output Converter：Spring AI 中把模型文本输出转换为 Java 对象的转换器，常见有 BeanOutputConverter、MapOutputConverter、ListOutputConverter。它是 best-effort，只负责解析，不承诺严格校验。
Provider-native Structured Output：服务商提供的原生结构化输出能力，可在请求阶段携带 JSON Schema，要求模型按结构生成。不同服务商参数略有差异，但核心思想一致。
JSON Schema Validation：基于 JSON Schema 对输出对象做严格校验，检查字段类型、必填项、枚举值、格式等。校验失败时可以触发自纠正重试。
强类型业务对象：用 Java Record/POJO 承载 AI 输出，让结果进入类型系统，可编译、可测试、可序列化。

参考 Spring AI 官方文档：https://docs.spring.io/spring-ai/reference/ 

（不同版本 API 名称和包路径可能略有变化，建议以上线版本官方文档为准。）

你有没有见过这样的场景：模型明明答应了返回 JSON，结果它先来一句“好的，这是您要的分类结果：”，然后跟了一串字段；或者 priority 一会儿是 HIGH，一会儿是“高”，偶尔还直接给你一个 null。我是老李，最近带团队把大模型接进客服工单系统，差点被这个问题整不会了。今天不聊怎么把提示语写得更漂亮，只聊一件事：Spring AI 如何把模型的文本输出，变成 Java 里能直接写 if/else、进数据库、进工作流的强类型业务对象。

《Spring AI 2.0实战》第4招 文本变Java对象

大模型只返回 JSON 并不保险，Spring AI 用 Output Converter、原生结构化输出和 Schema Validation 把结果变成强类

架构师

编程语言

SpringAI结构化输出将模型文本转换为强类型Java对象，通过Provider-native约束、BeanOutputConverter转换和JSONSchemaValidation校验三层链路，确保数据契约可靠。支持失败自纠正重试，让AI输出直接进入if/else、数据库及工作流，解决字段漂移和枚举值不一致问题，适用于工单分类、风险评级等企业级场景。

聊天机器人

结构化数据

单元测试

代码解释

客服工单

数据库

路由器

编译器

路由

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SpringAI结构化输出将模型文本转换为强类型Java对象，通过Provider-native约束、BeanOutputConverter转换和JSONSchemaValidation校验三层链路，确保数据契约可靠。支持失败自纠正重试，让AI输出直接进入if/else、数据库及工作流，解决字段漂移和枚举值不一致问题，...

《Spring AI 2.0实战》第4招 文本变Java对象-腾讯云开发者社区-腾讯云

《Spring AI 2.0实战》第4招文本变Java对象

《Spring AI 2.0实战》第4招文本变Java对象

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring AI 2.0实战》第4招 文本变Java对象

《Spring AI 2.0实战》第4招 文本变Java对象

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring AI 2.0实战》第4招文本变Java对象

《Spring AI 2.0实战》第4招文本变Java对象