该文章转载自: 点击链接
结构化输出转换器会尽最大努力（Best-Effort）完成任务。但 AI 模型偶尔也会“调皮”，不完全按指令办事。因此，在代码中加入验证和异常处理机制，是保证程序健壮性的好习惯。
还在为解析大模型返回的非结构化文本而头疼吗？还在用一堆 if-else 和正则表达式做着繁琐的字符串切割吗？现在，有了 Spring AI 的 结构化输出转换器（Structured Output Converter），这一切都将成为过去式！
这个神器能将大语言模型（LLM）返回的原始文本，精准地转换为你想要的任何结构化数据，无论是 JSON、XML 还是一个具体的 Java 对象。对于需要稳定、可靠地处理 AI 输出的应用程序来说，这简直是天降福音！
工作原理：AI 如何秒懂你的数据需求？
结构化输出转换器的魔法主要分两步：
- 调用前 - “约法三章”: 在你向大模型发送请求前，转换器会自动在你的提示词（Prompt）末尾附加上清晰的格式指令。这就像告诉一位厨师：“我点的这道菜，请务必做成五角星形状。” 它明确告知模型，你的答案必须符合某种格式。
- 调用后 - “格式转换”: 模型返回文本后，转换器会立即施展“变形术”，将文本精准地转换成你指定的 Java 类实例，比如
List、Map或者自定义的Bean。
温馨提示 ：结构化输出转换器会尽最大努力（Best-Effort）完成任务。但 AI 模型偶尔也会“调皮”，不完全按指令办事。因此，在代码中加入验证和异常处理机制，是保证程序健壮性的好习惯。
深入探秘：揭开 StructuredOutputConverter 的神秘面纱
想知道这背后的技术实现吗？核心在于 StructuredOutputConverter<T> 接口，它像一个多面手，同时扮演两个角色：
public interface StructuredOutputConverter<T> extends Converter<String, T>, FormatProvider {
}• FormatProvider 接口：负责生成“格式说明书”，告诉 AI 模型应该如何输出。
• Spring Converter<String, T> 接口：负责将模型返回的字符串，转换为你想要的目标类型 T 。
public interface FormatProvider {
String getFormat();
}Spring AI 已经内置了多种开箱即用的转换器，满足你不同场景的需求：
• BeanOutputConverter ：将输出转换为 Java Bean 对象，最常用的神器！
• MapOutputConverter ：将输出转换为 Map 结构。
• ListOutputConverter ：将输出转换为 List 结构。
• AbstractConversionServiceOutputConverter ：提供通用转换服务的基类。
• AbstractMessageOutputConverter ：支持 Spring AI Message 格式的转换。
它们的家族关系如下图所示：
现在，我们再来梳理一遍完整的工作流程：
1. 生成格式指令 ： FormatProvider 会生成类似下面的指令，并附加到你的提示词中。这相当于给 AI 划重点，告诉它必须按这个 JSON Schema 来回答。
Your response should be in JSON format.
The data structure for the JSON should match this Java class: java.util.HashMap
Do not include any explanations, only provide a RFC8259 compliant JSON response...通常，我们会用 PromptTemplate 来优雅地实现这一点：
StructuredOutputConverter outputConverter = ...
String userInputTemplate = """
... 你的业务提示词 ....
{format}
"""; // 预留一个 {format} 占位符
Prompt prompt = new Prompt(
new PromptTemplate(
userInputTemplate,
Map.of(..., "format", outputConverter.getFormat()) // 将格式指令填入占位符
).createMessage());2. 转换输出 ： Converter 将模型返回的 JSON 字符串，反序列化为你指定的 Java 对象。
整个过程无缝衔接，对开发者极其友好。
上手实战：三行代码，让 AI 输出“言听计从”
官方文档提供了丰富的示例，我们来看几个最经典的。
1. BeanOutputConverter ：将 AI 输出直接转换为自定义 Java 类。
// 1. 定义一个简单的 Java Record
record ActorsFilms(String actor, List<String> movies) {}
// 2. 一行代码调用并完成转换！
ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
.user("Generate 5 movies for Tom Hanks.")
.call()
.entity(ActorsFilms.class); // 指定目标类型，搞定！处理复杂的泛型列表也同样简单，只需使用 ParameterizedTypeReference ：
// 轻松转换为对象列表
List<ActorsFilms> actorsFilms = ChatClient.create(chatModel).prompt()
.user("Generate the filmography of 5 movies for Tom Hanks and Bill Murray.")
.call()
.entity(new ParameterizedTypeReference<List<ActorsFilms>>() {});2. MapOutputConverter ：将输出转换为 Map。
Map<String, Object> result = ChatClient.create(chatModel).prompt()
.user(u -> u.text("Provide me a List of {subject}")
.param("subject", "an array of numbers from 1 to 9 under they key name 'numbers'"))
.call()
.entity(new ParameterizedTypeReference<Map<String, Object>>() {});3. ListOutputConverter ：将输出转换为字符串列表。
List<String> flavors = ChatClient.create(chatModel).prompt()
.user(u -> u.text("List five {subject}")
.param("subject", "ice cream flavors"))
.call()
.entity(new ListOutputConverter(new DefaultConversionService()));1.2.3.4.5.兼容性王者：主流模型全支持
根据官方文档，以下主流 AI 模型均已通过测试，完美支持 List 、 Map 和 Bean 结构化输出：
| AI 模型 | 示例测试代码 |
|---|---|
| OpenAI | OpenAiChatModelIT |
| Anthropic Claude 3 | AnthropicChatModelIT.java |
| Azure OpenAI | AzureOpenAiChatModelIT.java |
| Mistral AI | MistralAiChatModelIT.java |
| Ollama | OllamaChatModelIT.java |
| Vertex AI Gemini | VertexAiGeminiChatModelIT.java |
更棒的是，许多模型提供了 内置 JSON 模式 ，这让结构化输出的可靠性更上一层楼。启用后，模型会保证输出严格符合 JSON 格式。
• OpenAI: 提供 JSON_OBJECT 响应格式。
• Azure OpenAI: 设置 { "type": "json_object" } 启用 JSON 模式。
• Ollama: 提供 format: 'json' 选项。
• Mistral AI: 设置 responseFormat: { "type": "json_object" } 启用 JSON 模式。
实战演练：AI 变身“旅游规划师”，自动生成旅行报告
下面，我们来构建一个实用的功能：让 AI 为用户生成一份包含标题和建议列表的旅游报告。
1. 引入 JSON Schema 依赖 ：这是让转换器理解 Java 类结构的关键。
<dependency>
<groupId>com.github.victools</groupId>
<artifactId>jsonschema-generator</artifactId>
<version>4.38.0</version>
</dependency>2. 定义旅游报告类 ：使用 Java Record，代码简洁优雅。
record SightSeeingReport(String title, List<String> suggestions) {
}3. 编写业务代码 ：在原有的 ChatClient 基础上，只需一行 .entity() 即可实现结构化输出。
/**
* 为用户生成一份专属的旅游报告
* @param message 用户的问题
* @param chatId 会话ID
* @return 结构化的旅游报告对象
*/
public SightSeeingReport doChatWithReport(String message, String chatId) {
SightSeeingReport sightSeeingReport = chatClient
.prompt()
// 强化系统提示，要求生成包含标题和建议的报告
.system(SYSTEM_PROMPT + "每次对话后都要生成旅游结果，标题为{用户名}的旅游报告，内容为建议列表")
.user(message)
.advisors(spec ->
spec.param(CHAT_MEMORY_CONVERSATION_ID_KEY, chatId)
.param(CHAT_MEMORY_RETRIEVE_SIZE_KEY, 10)
)
.call()
// 魔法发生的地方！直接将结果转换为 SightSeeingReport 对象
.entity(SightSeeingReport.class);
log.info("AI 生成的旅游报告: {}", sightSeeingReport);
return sightSeeingReport;
}1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.4. 编写单元测试 ：
@Resource
private App app;@Test
void doChatWithReport() {
String chatId = UUID.randomUUID().toString();
String message = "你好，我想去北京旅游，请帮我规划一下";
App.SightSeeingReport sightSeeingReport = app.doChatWithReport(message, chatId);
Assertions.assertNotNull(sightSeeingReport);
}运行测试，通过 Debug 我们可以清晰地看到，框架自动将我们的 SightSeeingReport 类转换为了详细的 JSON Schema，并添加到了提示词中，指导 AI 生成了我们期望的 JSON 格式数据，并最终成功转换为了 SightSeeingReport 对象实例。整个过程如丝般顺滑！
格式指令的完整内容如下，我们发现对象被转换为了 JSON Schema 描述语言：
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" : {
"suggestions" : {
"type" : "array",
"items" : {
"type" : "string"
}
},
"title" : {
"type" : "string"
}
},
"additionalProperties" : false
}\`\`\`AI 生成的内容如图，是 JSON 格式文本：
转换器成功将 JSON 文本转换为了对象：
高手秘籍：用好结构化输出的四大心法
1. 指令清晰 ：给模型的格式指导越清晰、越具体越好。
2. 验证兜底 ：务必实现输出验证和异常处理逻辑，应对 AI 的“小脾气”。
3. 选对模型 ：优先选择官方支持或提供内置 JSON 模式的模型，可靠性更高。
4. 巧用泛型 ：处理复杂数据结构（如 List<Map<String, MyObject>> ）时， ParameterizedTypeReference 是你的得力助手。
Spring AI 的结构化输出功能，极大地简化了与大模型交互的复杂度，让开发者能更专注于业务逻辑，而不是繁琐的数据解析。它就像一座桥梁，无缝连接了 AI 的创造力与 Java 应用的严谨性。