Spring AI实战：SpringBoot项目结合Spring AI开发——结构化输出（StructuredOutputConverter）

🪁🍁 希望本文能给您带来帮助，如果有任何问题，欢迎批评指正！🐅🐾🍁🐥

---

导航参见：
Spring AI实战：SpringBoot项目结合Spring AI开发——ChatClient API详解
Spring AI实战：SpringBoot项目结合Spring AI开发——提示词(Prompt)技术与工程实战详解
Spring AI实战：SpringBoot项目结合Spring AI开发——模型参数及ChatOptions API详解
Spring AI实战：SpringBoot项目结合Spring AI开发——结构化输出（StructuredOutputConverter）

一、前言

在前面的文章中，已经介绍完了模型的输入部分，介绍过提示词的构建以及模型参数的配置，本篇文章来聚焦到模型的输出。刚开始玩 AI 接口时，是不是一开始就让它直接输出文本？但随着业务需求上升，你很快就会遇到两个字：“结构”。如果只是简单提示词 + 纯文本，结果可想而知——字段名千奇百怪，格式松散，解析代码写得你怀疑人生。Spring AI 正是为了解决这种混乱，而提供了结构化输出（Structured Output）能力。它不再只是给你一堆文本，而是可以直接解析为 Java 对象、Map、List！这就是它的魔力。

二、如何引导AI结构化输出

• AI模型输出响应并非像传统程序那样默认按某种结构化响应来输出，而是按照自然语言进行输出。
• AI模型是可以按照输入的指令、需求来进行特定的处理和输出。那么可以利用这一点，要求AI按照指定的格式结构输出。
• 所以在调用AI之前，需要在提示词中加入明确、精准的格式指令，且最好是给出格式的例子来进行引导。如果输入的指令不够明确，也会存在一定的风险导致AI无法按照预想输出。
• 再配合上模型的特定参数进一步要求AI。比如最大输出的数量，防止输出被中途截断；有些模型还具备相应格式的参数。

---

三、结构化输出重要性

大语言模型生成结构化输出的能力对依赖可靠解析结果的下游应用至关重要，例如，一个请假应用程序需要从用户输入的信息中提取请假信息，并且使用 JSON 格式返回，如果返回的 JSON 格式非法，将直接导致应用不能继续下去。由此，开发者希望快速、准确的将 AI 模型返回结果转换为 JSON、XML 或 Java Class 等数据类型，以便传递给其他应用函数和方法。

Spring AI 结构化输出转换器（Structured Output Converter）帮助将 LLM（大语言模型）的输出转为结构化格式。如下图所示，该方案围绕 LLM 文本补全端点运作：

使用通用补全 API 从大语言模型（LLM）生成结构化输出时，输入输出的处理至关重要，需谨慎对待，原因如下：

• 输入处理的重要性： 在调用 LLM 前，需通过结构化输出转换器向提示词追加格式指令，为模型生成预期输出结构提供明确指导，这些指令如同蓝图，引导模型响应符合指定格式。若输入的提示词或格式指令不清晰、不准确，模型可能无法理解要求，从而生成不符合预期的输出。

• 输出处理的必要性： LLM 调用后，转换器需将模型的原始文本输出转换为结构化类型实例，包括解析原始文本并映射为 JSON、XML 或领域特定数据结构等。但 AI 模型并不保证按请求返回结构化输出，可能因无法理解提示或生成所需结构而输出非结构化内容，因此需实现验证机制确保模型输出符合预期。

📢注意事项：
（1）StructuredOutputConverter 会尽力将模型输出转换为结构化格式，但 AI 模型并不保证按请求返回结构化输出（可能无法理解提示词或生成所需结构），建议实现验证机制以确保模型输出符合预期。
（2）StructuredOutputConverter 不用于大语言模型（LLM）的工具调用，因为此功能默认情况下本身就会提供结构化输出。

---

四、Spring AI结构化输出API

StructuredOutputConverter 接口允许从基于文本的 AI 模型输出中获取结构化结果，例如映射到 Java 类或值数组。其接口定义为：

public interface StructuredOutputConverter<T> extends Converter<String, T>, FormatProvider {
}

该接口继承了 Spring 的 Converter<String, T> 和 FormatProvider 接口，其中 Converter 接口定义如下：

/*** 类型转换的核心接口，将源类型对象转换为目标类型对象* 实现类需实现线程安全的转换逻辑** @param <S> 源类型* @param <T> 目标类型*/
@FunctionalInterface
public interface Converter<S, T> {/*** 将源对象转换为目标类型* * @param source 源对象，可为 null* @return 转换后的目标对象，可为 null* @throws IllegalArgumentException 当源对象无法转换为目标类型时抛出*/@NullableT convert(S source);/*** 返回一个组合转换器，先执行当前转换器，再执行 after 转换器* * @param <U>   最终结果类型* @param after 后续要应用的转换器，不能为 null* @return 组合转换器实例* @throws IllegalArgumentException 当 after 为 null 时抛出*/default <U> Converter<S, U> andThen(Converter<? super T, ? extends U> after) {Assert.notNull(after, "'after' Converter must not be null");return (s) -> {// 执行当前转换器T initialResult = this.convert(s);// 仅当前转换结果非空时执行后续转换器return initialResult != null ? after.convert(initialResult) : null;};}
}

FormatProvider 接口定义如下：

/*** 格式提供者接口，用于标识支持格式信息获取的组件* 实现类通常用于提供数据格式描述，如JSON、XML等*/
public interface FormatProvider {/*** 获取格式描述字符串* * @return 格式描述*/String getFormat();
}

下面是 MapOutputConverter 类中的 getFormat() 方法：

public class MapOutputConverter extends AbstractMessageOutputConverter<Map<String, Object>> {//...public String getFormat() {String raw = "Your response should be in JSON format.\nThe data structure for the JSON should match this Java class: %s\nDo not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.\nRemove the ```json markdown surrounding the output including the trailing \"```\".\n";return String.format(raw, HashMap.class.getName());}
}

下图展示了使用结构化输出 API 时的数据流：

FormatProvider 向 AI 模型提供特定格式指南，使其生成可被 Converter 转换为目标类型 T 的文本输出。Converter<String, T> 负责将模型的文本输出转换为指定类型 T 的实例。

4.1 可用的转换器

目前 Spring AI 提供了以下 StructuredOutputConverter 接口实现类：

它们之间的类图如下：

4.1.1 AbstractConversionServiceOutputConverter 抽象类

该抽象类仅提供预配置的 GenericConversionService 用于将 LLM 输出转换为目标格式，未提供默认 FormatProvider 实现，它使用 Spring 框架的 ConversionService 将文本（通常是 JSON 格式）转换成 Java 的 POJO（类、Map、List 等）。源码如下：

package org.springframework.ai.converter;import org.springframework.core.convert.support.DefaultConversionService;public abstract class AbstractConversionServiceOutputConverter<T> implements StructuredOutputConverter<T> {private final DefaultConversionService conversionService;public AbstractConversionServiceOutputConverter(DefaultConversionService conversionService) {this.conversionService = conversionService;}public DefaultConversionService getConversionService() {return this.conversionService;}
}

其中，DefaultConversionService 继承了 GenericConversionService，定义如下：

public class DefaultConversionService extends GenericConversionService {//...
}

4.1.2 AbstractMessageOutputConverter 抽象类

该抽象类提供预配置的 MessageConverter 用于从 LLM 输出的Message 对象中提取内容，并将其转换为结构化 Java 对象（如 POJO、List、Map 等），其未提供默认 FormatProvider 实现。源码如下：

package org.springframework.ai.converter;import org.springframework.messaging.converter.MessageConverter;public abstract class AbstractMessageOutputConverter<T> implements StructuredOutputConverter<T> {private MessageConverter messageConverter;public AbstractMessageOutputConverter(MessageConverter messageConverter) {this.messageConverter = messageConverter;}public MessageConverter getMessageConverter() {return this.messageConverter;}
}

4.1.3 BeanOutputConverter 类

BeanOutputConverter<T> ：配置指定的 Java 类（例如 Bean）或 ParameterizedTypeReference，此转换器使用 FormatProvider 实现，指导 AI 模型生成符合从指定 Java 类派生的 DRAFT_2020_12、JSON Schema 的 JSON 响应。随后，它使用 ObjectMapper 将 JSON 输出反序列化为目标类的 Java 对象实例。

源码如下：

/*** 将JSON格式输出转换为Java Bean的结构化输出转换器* * @param <T> 目标Bean类型*/
public class BeanOutputConverter<T> implements StructuredOutputConverter<T> {private final Logger logger;/** 目标Bean的Type类型信息，用于泛型类型解析 */private final Type type;/** 用于JSON与Java对象转换的Jackson ObjectMapper */private final ObjectMapper objectMapper;/** 生成的JSON Schema字符串，用于提示LLM生成符合结构的JSON */private String jsonSchema;//...
}

4.1.4 MapOutputConverter 类

该类扩展了 AbstractMessageOutputConverter 的功能，通过一个 FormatProvider 实现，引导 AI 模型生成符合 RFC8259 标准的 JSON 响应。此外，它还包含一个转换器实现，该实现利用提供的MessageConverter 将 JSON 有效负载转换为 java.util.Map<String, Object> 实例。

源码如下：

/*** 将JSON格式文本转换为Map<String, Object>的输出转换器* 支持处理带```json```标记的markdown格式JSON文本*/
public class MapOutputConverter extends AbstractMessageOutputConverter<Map<String, Object>> {/*** 使用Jackson JSON消息转换器初始化*/public MapOutputConverter() {super(new MappingJackson2MessageConverter());}/*** 将JSON格式字符串转换为Map对象* * @param text 待转换的JSON文本，可为markdown格式（带```json```标记）* @return 转换后的Map对象* @throws IllegalArgumentException 当文本无法解析为JSON时抛出*/@Overridepublic Map<String, Object> convert(@NonNull String text) {// 移除markdown代码块标记（如果存在）if (text.startsWith("```json") && text.endsWith("```")) {text = text.substring(7, text.length() - 3);}// 构建消息对象并使用Jackson转换器进行解析Message<?> message = MessageBuilder.withPayload(text.getBytes(StandardCharsets.UTF_8)).build();return (Map<String, Object>) getMessageConverter().fromMessage(message, HashMap.class);}/*** 获取格式描述，用于提示模型输出符合要求的JSON格式* * @return 格式描述字符串，包含Java类信息和JSON规范要求*/@Overridepublic String getFormat() {String template = "Your response should be in JSON format.\n" +"The data structure for the JSON should match this Java class: %s\n" +"Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.\n" +"Remove the ```json markdown surrounding the output including the trailing \"```\".\n";return String.format(template, HashMap.class.getName());}
}

4.1.5 ListOutputConverter 类

该类继承了 AbstractConversionServiceOutputConverter，包含专为逗号分隔列表输出定制的 FormatProvider 实现。该转换器利用提供的 ConversionService 将模型文本输出转换为 java.util.List。

源码如下：

/*** 将逗号分隔的字符串转换为List<String>的输出转换器* 支持将"a,b,c"格式的文本转换为对应的字符串列表*/
public class ListOutputConverter extends AbstractConversionServiceOutputConverter<List<String>> {/*** 使用默认转换服务初始化转换器*/public ListOutputConverter() {this(new DefaultConversionService());}/*** 使用自定义转换服务初始化转换器* * @param defaultConversionService 自定义转换服务实例*/public ListOutputConverter(DefaultConversionService defaultConversionService) {super(defaultConversionService);}/*** 获取格式描述，用于提示模型输出符合要求的逗号分隔值列表* * @return 格式描述字符串，包含示例格式说明*/@Overridepublic String getFormat() {return "Respond with only a list of comma-separated values, without any leading or trailing text.\nExample format: foo, bar, baz\n";}/*** 将逗号分隔的字符串转换为List<String>* * @param text 待转换的字符串，格式应为"value1,value2,value3"* @return 转换后的字符串列表* @throws IllegalArgumentException 当转换失败时抛出*/@Overridepublic List<String> convert(@NonNull String text) {return (List<String>) getConversionService().convert(text, List.class);}
}

---

五、使用Spring AI封装好的转换器

5.1 Bean输出转换器

以下示例展示如何使用 BeanOutputConverter 生成演员作品表，先使用高阶 Fluent 式 ChatClient API 应用 BeanOutputConverter 的方式：

@RestController
public class ConverterTestController {@Resource(name = "openAiChatModel")private ChatModel chatModel;// 定义 Recordrecord ActorsFilms(String actor, List<String> movies) {}@GetMapping(value = "/converter/demo1")public ActorsFilms demo1(@RequestParam("actor") String actor) {return ChatClient.create(chatModel).prompt()// 日志Advisor,输出请求/响应日志.advisors(new SimpleLoggerAdvisor())// 用户提示词.user(u -> u.text("生成{actor}的5部电影作品表。").param("actor", actor))// 调用实体大模型.call()// 将结果转换成实体.entity(ActorsFilms.class);}
}

运行应用，效果如下图：

后端输出日志如下：

2025-10-12T13:13:45.924+08:00 DEBUG 8960 --- [nio-8082-exec-2] o.s.a.c.c.advisor.SimpleLoggerAdvisor    : request: ChatClientRequest[prompt=Prompt{messages=[UserMessage{content='生成周星驰的5部电影作品表。', properties={messageType=USER}, messageType=USER}], modelOptions=OpenAiChatOptions: {"streamUsage":false,"model":"gpt-4","temperature":0.7}}, context={spring.ai.chat.client.output.format=Your response should be in JSON format.
Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
Do not include markdown code blocks in your response.
Remove the ```json markdown from the output.
Here is the JSON Schema instance your output must adhere to:
```{"$schema" : "https://json-schema.org/draft/2020-12/schema","type" : "object","properties" : {"actor" : {"type" : "string"},"movies" : {"type" : "array","items" : {"type" : "string"}}},"additionalProperties" : false
}```
}]

仔细观察上述输出日志，modelOptions 选项中多出了很多关于输出格式的说明，如“spring.ai.chat.client.output.format=Your response should be in JSON format…”。

除了通过 Fluent 式，还可以直接使用底层 ChatModel API，例如：

@RestController
public class ConverterTestController {@Resource(name = "openAiChatModel")private ChatModel chatModel;// 定义 Recordrecord ActorsFilms(String actor, List<String> movies) {}@GetMapping(value = "/converter/demo2")public ActorsFilms demo2(@RequestParam("actor") String actor) {// 创建转换器 BeanOutputConverterBeanOutputConverter<ActorsFilms> beanOutputConverter = new BeanOutputConverter<>(ActorsFilms.class);// 提示词PromptTemplate promptTemplate = new PromptTemplate("""生成{actor}的5部电影作品表。{format}""");promptTemplate.add("actor", actor);promptTemplate.add("format", beanOutputConverter.getFormat());// 调用大模型ChatClient chatClient = ChatClient.builder(chatModel).defaultAdvisors(new SimpleLoggerAdvisor()).build();String result = chatClient.prompt(promptTemplate.create()).call().content();// 使用 BeanOutputConverter 对结果进行转换操作return beanOutputConverter.convert(Optional.ofNullable(result).orElse(""));}}

运行示例，输出效果如下图：

5.2 生成模式中的属性顺序

BeanOutputConverter 通过 @JsonPropertyOrder 注解支持自定义 JSON Schema 中的属性顺序，该注解允许指定属性在模式中的精确出现顺序（无视 class 或 record 中的声明顺序）。

例如，要确保 ActorsFilms 记录中的特定属性顺序：

@RestController
public class ConverterTestController {@Resource(name = "openAiChatModel")private ChatModel chatModel;// 定义 Record@JsonPropertyOrder({"movies", "actor"})record ActorsFilms(String actor, List<String> movies) {}@GetMapping(value = "/converter/demo1")public ActorsFilms demo1(@RequestParam("actor") String actor) {return ChatClient.create(chatModel).prompt()// 日志Advisor,输出请求/响应日志.advisors(new SimpleLoggerAdvisor())// 用户提示词.user(u -> u.text("生成{actor}的5部电影作品表。").param("actor", actor))// 调用实体大模型.call()// 将结果转换成实体.entity(ActorsFilms.class);}
}

这样movies属性就在actor前面展示

5.3 泛型 Bean 类型

使用 ParameterizedTypeReference 构造函数指定更复杂的目标类结构。例如，表示演员及其作品表的列表：

下面是使用ChatClient API应用 BeanOutputConverter 的方法：

@GetMapping("/converter/demo3")
List<ActorsFilms> demo3(@RequestParam("actor1") String actor1, @RequestParam("actor2") String actor2) {return ChatClient.create(chatModel).prompt().advisors(new SimpleLoggerAdvisor()).user(u -> u.text("为 {actor1} 和 {actor2} 生成 5 部电影的电影作品。").param("actor1", actor1).param("actor2", actor2)).call().entity(new ParameterizedTypeReference<List<ActorsFilms>>() {});
}

运行示例，效果如下图：

后端输出日志如下：

2025-10-12T14:37:13.034+08:00 DEBUG 13552 --- [nio-8082-exec-2] o.s.a.c.c.advisor.SimpleLoggerAdvisor    : request: ChatClientRequest[prompt=Prompt{messages=[UserMessage{content='为 周星驰 和 吴孟达 生成 5 部电影的电影作品。', properties={messageType=USER}, messageType=USER}], modelOptions=OpenAiChatOptions: {"streamUsage":false,"model":"gpt-4","temperature":0.7}}, context={spring.ai.chat.client.output.format=Your response should be in JSON format.
Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
Do not include markdown code blocks in your response.
Remove the ```json markdown from the output.
Here is the JSON Schema instance your output must adhere to:
```{"$schema" : "https://json-schema.org/draft/2020-12/schema","type" : "array","items" : {"type" : "object","properties" : {"movies" : {"type" : "array","items" : {"type" : "string"}},"actor" : {"type" : "string"}},"additionalProperties" : false}
}```
}]

使用ChatModel API应用 BeanOutputConverter 的方法：

@GetMapping("/converter/demo4")
List<ActorsFilms> demo4(@RequestParam("actor1") String actor1, @RequestParam("actor2") String actor2) {// 1. 创建输出转换器BeanOutputConverter<List<ActorsFilms>> outputConverter = new BeanOutputConverter<>(new ParameterizedTypeReference<List<ActorsFilms>>() {});String format = outputConverter.getFormat();// 2. 新版创建PromptTemplate的方式PromptTemplate promptTemplate = new PromptTemplate("为 {actor1} 和 {actor2} 生成 5 部电影的电影作品。\n{format}");// 3. 创建Prompt时传入变量Prompt prompt = promptTemplate.create(Map.of("actor1", actor1, "actor2", actor2, "format", format));// 4. 调用模型并转换结果Generation generation = chatModel.call(prompt).getResult();return outputConverter.convert(generation.getOutput().getText());
}

5.4 Map输出转换器

以下代码片段显示如何使用 MapOutputConverter 将模型输出转换为地图中的数字列表。

下面是使用ChatClient API应用 MapOutputConverter 的方法：

@GetMapping("/converter/demo5")
Map<String, Object> demo5(@RequestParam("subject") String subject) {return ChatClient.create(chatModel).prompt().advisors(new SimpleLoggerAdvisor()).user(u -> u.text("为我提供 {subject}").param("subject", subject)).call().entity(new ParameterizedTypeReference<Map<String, Object>>() {});
}

运行示例，效果如下图：

后端输出日志如下：

2025-10-12T14:38:48.725+08:00 DEBUG 13552 --- [nio-8082-exec-5] o.s.a.c.c.advisor.SimpleLoggerAdvisor    : request: ChatClientRequest[prompt=Prompt{messages=[UserMessage{content='为我提供 一个从1到6的数字数组，键名为numbers', properties={messageType=USER}, messageType=USER}], modelOptions=OpenAiChatOptions: {"streamUsage":false,"model":"gpt-4","temperature":0.7}}, context={spring.ai.chat.client.output.format=Your response should be in JSON format.
Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
Do not include markdown code blocks in your response.
Remove the ```json markdown from the output.
Here is the JSON Schema instance your output must adhere to:
```{"$schema" : "https://json-schema.org/draft/2020-12/schema","type" : "object","additionalProperties" : false
}```
}]

使用ChatModel API应用 MapOutputConverter 的方法：

@GetMapping("/converter/demo6")
Map<String, Object> demo6(@RequestParam("subject") String subject) {// 1. 创建输出转换器MapOutputConverter mapOutputConverter = new MapOutputConverter();String format = mapOutputConverter.getFormat();// 2. 新版创建PromptTemplate的方式PromptTemplate promptTemplate = new PromptTemplate("为我提供 {subject}。\n{format}");// 3. 创建Prompt时传入变量Prompt prompt = promptTemplate.create(Map.of("subject", subject, "format", format));// 4. 调用模型并转换结果Generation generation = chatModel.call(prompt).getResult();return mapOutputConverter.convert(generation.getOutput().getText());
}

5.5 List输出转换器

以下片段展示如何使用 ListOutputConverter 将模型输出转换为冰淇淋口味列表：

下面是使用ChatClient API应用 ListOutputConverter 的方法：

@GetMapping("/converter/demo7")
List<String> demo7(@RequestParam("subject") String subject) {return ChatClient.create(chatModel).prompt().user(u -> u.text("用中文列出五种 {subject}").param("subject", subject)).call().entity(new ListOutputConverter(new DefaultConversionService()));
}

运行示例，效果如下图：

后端输出日志如下：

2025-10-12T14:43:47.853+08:00 DEBUG 16808 --- [nio-8082-exec-1] o.s.a.c.c.advisor.SimpleLoggerAdvisor    : request: ChatClientRequest[prompt=Prompt{messages=[UserMessage{content='用中文列出五种 冰淇淋口味', properties={messageType=USER}, messageType=USER}], modelOptions=OpenAiChatOptions: {"streamUsage":false,"model":"gpt-4","temperature":0.7}}, context={spring.ai.chat.client.output.format=Respond with only a list of comma-separated values, without any leading or trailing text.
Example format: foo, bar, baz
}]

使用ChatModel API应用 ListOutputConverter 的方法：

@GetMapping("/converter/demo8")
List<String> demo8(@RequestParam("subject") String subject) {// 1. 创建输出转换器ListOutputConverter listOutputConverter = new ListOutputConverter(new DefaultConversionService());String format = listOutputConverter.getFormat();// 2. 新版创建PromptTemplate的方式PromptTemplate promptTemplate = new PromptTemplate("用中文列出五种 {subject}。\n{format}");// 3. 创建Prompt时传入变量Prompt prompt = promptTemplate.create(Map.of("subject", subject, "format", format));// 4. 调用模型并转换结果Generation generation = chatModel.call(prompt).getResult();return listOutputConverter.convert(generation.getOutput().getText());
}

---

六、转换器是如何介入与AI交互过程的

在前面的实战中，我们已经直接使用了转换器，但是它是放到哪了呢？前面有图已经表示是追加到了提示词中，那它是何时被追加到提示词消息的呢？

通过简单翻看了下源码，发现是在ChatModelCallAdvisor中与AI交互之前，通过Prompt对提示词增强修改追加在UserMessage中了。如下图：

在ChatModelCallAdvisor中有响应格式的提示词增强，那ChatModelStreamAdvisor中有没有？答案是没有的。

这里如果说stream模式的请求无法做Convert，但实际中应该还是会需要Format指定输出格式吧。看下来使用stream模式是没有参数可传入的，以后看会不会升级，目前是只能在Advisor中自己实现了。另外至于转换，是在与AI交互响应后整个Advisor链执行完了再调用的.convert()方法。这里源码比较分散，就暂时不放图了。

---

七、总结

本篇文章主要介绍了Spring AI中的几种输出转换器的源代码，然后基于不同的输出转换器给出了实战案例。结构化输出是决定了AI应用编程的程序可控以及是否可持续运行的重要因素。个人看法，它真的能提升开发效率，不需要去花太多时间写正则等垃圾代码，其次，它值得在中大型项目中推广，因为结构化输出能显著提高接口稳定性。

---

八、参考资料

• Spring AI 官方文档
• 【Spring AI 1.0.0】Spring AI 1.0.0框架快速入门(3)——Structured Output Converter（结构化输出转换器）

---

创作不易，如果有帮助到你的话请给点个赞吧！我是Wasteland，下期文章再见！