Spring AI 结构化输出转换器

在使用大型语言模型生成结构化数据时往往面临输入格式不规范、输出难以解析还有后端业务集成复杂等痛点。Spring AI 的结构化输出转换器为这些问题提供了程序化的方法。它可以在 LLM 调用前后自动添加格式指令、解析模型输出，并将结果映射为 Java 对象、Map 或 List。

常见痛点回顾

• **输入模板模糊**：开发者经常忘记给模型明确的“请返回 JSON”提示，导致返回的文本不符合预期。
• **输出解析失误**：手写正则或手工拆分字符串极易出错，特别是嵌套结构或多行文本。老实说，
• **调试困难**：缺少统一的日志与错误报告。使得定位是哪一步出了问题变得繁琐。
• **代码耦合度高**：每个业务场景都需要自行实现转换逻辑，导致重复代码堆积。

可用转换器

Spring AI 提供了多种内置转换器，满足不同场景需求：

BeanOutputConverter。MapOutputConverter 和 ListOutputConverter 内置默认的 FormatProvider 实现，可直接用于大多数 JSON/YAML 等结构化格式。

转换器的两种使用方式

以 BeanOutputConverter 为例子演示

假设我们想获取演员电影作品信息，定义目标记录：

record ActorsFilms {}

// 使用 ChatClient
ActorsFilms actorsFilms = ChatClient.create
.prompt
.user
.param)
.call
.entity;

或者直接使用低级 ChatModel API 与 BeanOutputConverter 配合：

BeanOutputConverter beanOut = new BeanOutputConverter<>;String format = beanOut.getFormat;String actor = "Tom Hanks";String template = """
Generate filmography of {actor}.
{format}
""";Generation gen = chatModel.call(
PromptTemplate.builder.template
.variables)
.build.create).getResult;ActorsFilms result = beanOut.convert.getText);

对比使用结构化输出对返回内容的影响

输出 vs 原始文本

// Structured
record ActorsFilms {}
String prompt = "Generate movies that {actor} has performed in.";ActorsFilms filmsStructured = ChatClient.create
.prompt
.user.param)
.call
.entity;// Plain Text
String plainText = ChatClient.create
.prompt
.user.param)
.call
.content;printComparison;

通过比较可以看到：

• 结构化输出：{“actor”: “Robert Downey Jr.”。“movies”: }
• 非结构化文本："Robert Downey Jr. has acted in Iron Man,Avengers..." 等无法直接映射为对象。

Map mapResult = ChatClient.create
.prompt
.user
.param)
.call
.entity{});
String mapPlainText = ChatClient.create
.prompt
.user
.param)
.call
.content;printComparison;

• 结构化 Map：{“books”: }
• 原始文本："Here are some books you should read..." 无法直接按字段提取。

输出 vs 原始文本

// Structured List
List flavorsStructured = ChatClient.create
.prompt
.user.param)
.call
.entity));其实，// Plain Text
String flavorsPlainText = ChatClient.create
.prompt
.user
.call
.content;printComparison;

• 结构化列表："
• 原始文本："Here are five ice cream flavors: Vanilla...". Parsing requires regex."
• 调试友好性提高：`printComparison` 自动打印两种结果，让开发者一眼看出差异与错误源头。"
• 代码复用率提高：`ListOutputConverter`/`MapOutputConverter`/`BeanOutputConverter` 均可复用，不必针对每个接口重写解析逻辑。"
• 可插拔 FormatProvider：`FormatProvider` 可自定义支持 YAML、JSON5、XML 等多种格式，满足不同业务需求。"

与常用方法建议

• 始终使用 Spring AI 的 **Structure Output Converter** 来避免手动字符串处理带来的错误。*让模型先返回标准 JSON，再由框架完成映射和校验。说起来，*
• *统一管理 FormatProvider*：如果团队内部对 JSON 与 YAML 有不同约束。可以通过配置文件统一切换，无需改动业务代码。
• *对比工具 `printComparison`*：在调试阶段快速对比原始文本与已解析结果，可显著缩短定位时间。
• *捕获并记录异常*：将 Converter 抛出的异常包装为业务异常，方便上层统一处理。
• 说到*性能监控*。开启 `spring.ai.output-converter.log-level=DEBUG` 可以实时查看生成指令与解析过程，帮助评估 LLM 调用成本与延迟。💡 小贴士:
  • - 当模型返回内容未比较符合指定格式时可先通过 `FormatProvider.getErrorHandler` 获取详细报错信息，以便快速修正提示词或模型参数；说起来，- 对于复杂嵌套对象。可考虑组合多个 `BeanOutputConverters` 或自定义 `CustomMappingStrategy` 来精准控制字段映射；- 若业务需要批量请求同一模型并保持一致格式。可在 `@Configuration` 中注册全局默认 Converter，避免每处调用重复创建实例。

  这份教程帮助你从痛点出发，在 Spring AI 中比较容易做到高质量、可维护的 结构化输出。祝编码愉快 🚀