Spring AI 骚操作：让大模型乖乖听话，直接返回 Java 对象！

还在为解析大模型返回的非结构化文本而头疼吗？还在用一堆 if-else 和正则表达式做着繁琐的字符串切割吗？现在，有了 Spring AI 的 结构化输出转换器(Structured Output Converter)，这一切都将成为过去式！

这个神器能将大语言模型(LLM)返回的原始文本，精准地转换为你想要的任何结构化数据，无论是 JSON、XML 还是一个具体的 Java 对象。对于需要稳定、可靠地处理 AI 输出的应用程序来说，这简直是天降福音！

工作原理：AI 如何秒懂你的数据需求？

结构化输出转换器的魔法主要分两步：

• 调用前 - “约法三章”: 在你向大模型发送请求前，转换器会自动在你的提示词(Prompt)末尾附加上清晰的格式指令。这就像告诉一位厨师：“我点的这道菜，请务必做成五角星形状。” 它明确告知模型，你的答案必须符合某种格式。
• 调用后 - “格式转换”: 模型返回文本后，转换器会立即施展“变形术”，将文本精准地转换成你指定的 Java 类实例，比如 List、Map 或者自定义的 Bean。

图1: 结构化输出工作流：先“约法三章”，再“格式转换”

温馨提示：结构化输出转换器会尽最大努力(Best-Effort)完成任务。但 AI 模型偶尔也会“调皮”，不完全按指令办事。因此，在代码中加入验证和异常处理机制，是保证程序健壮性的好习惯。

深入探秘：揭开 StructuredOutputConverter 的神秘面纱

想知道这背后的技术实现吗？核心在于 StructuredOutputConverter<T> 接口，它像一个多面手，同时扮演两个角色：

登录后复制

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

}

• 1.
• 2.
• 3.

• FormatProvider 接口：负责生成“格式说明书”，告诉 AI 模型应该如何输出。
• Spring Converter<String, T> 接口：负责将模型返回的字符串，转换为你想要的目标类型 T。

登录后复制

public interface FormatProvider {
    String getFormat();
}

• 1.
• 2.
• 3.

Spring AI 已经内置了多种开箱即用的转换器，满足你不同场景的需求：

• BeanOutputConverter：将输出转换为 Java Bean 对象，最常用的神器！
• MapOutputConverter：将输出转换为 Map 结构。
• ListOutputConverter：将输出转换为 List 结构。
• AbstractConversionServiceOutputConverter：提供通用转换服务的基类。
• AbstractMessageOutputConverter：支持 Spring AI Message 格式的转换。

它们的家族关系如下图所示：

图2: StructuredOutputConverter 核心类图

现在，我们再来梳理一遍完整的工作流程：

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...

• 1.
• 2.
• 3.

通常，我们会用 PromptTemplate 来优雅地实现这一点：

登录后复制

StructuredOutputConverter outputConverter = ...
String userInputTemplate = """
        ... 你的业务提示词 ....
        {format} 
        """; // 预留一个 {format} 占位符
Prompt prompt = new Prompt(
        new PromptTemplate(
                userInputTemplate,
                Map.of(..., "format", outputConverter.getFormat()) // 将格式指令填入占位符
        ).createMessage());

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.

2. 转换输出：Converter 将模型返回的 JSON 字符串，反序列化为你指定的 Java 对象。

整个过程无缝衔接，对开发者极其友好。

图3: 提示词与转换器协同工作流程

上手实战：三行代码，让 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); // 指定目标类型，搞定！

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.

处理复杂的泛型列表也同样简单，只需使用 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>>() {});

• 1.
• 2.
• 3.
• 4.
• 5.

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>>() {});

• 1.
• 2.
• 3.
• 4.
• 5.

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>

• 1.
• 2.
• 3.
• 4.
• 5.

2. 定义旅游报告类：使用 Java Record，代码简洁优雅。

登录后复制

record SightSeeingReport(String title, List<String> suggestions) {
}

• 1.
• 2.

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;

• 1.
• 2.

登录后复制

@Test
void doChatWithReport() {
    String chatId = UUID.randomUUID().toString();
    String message = "你好，我想去北京旅游，请帮我规划一下";
    App.SightSeeingReport sightSeeingReport = app.doChatWithReport(message, chatId);
    Assertions.assertNotNull(sightSeeingReport);
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.

运行测试，通过 Debug 我们可以清晰地看到，框架自动将我们的 SightSeeingReport 类转换为了详细的 JSON Schema，并添加到了提示词中，指导 AI 生成了我们期望的 JSON 格式数据，并最终成功转换为了 SightSeeingReport 对象实例。整个过程如丝般顺滑！

图4: Debug 模式下查看自动生成的格式指令和最终转换的对象

格式指令的完整内容如下，我们发现对象被转换为了 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
}```

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.
• 18.
• 19.
• 20.
• 21.

AI 生成的内容如图，是 JSON 格式文本：

转换器成功将 JSON 文本转换为了对象：

高手秘籍：用好结构化输出的四大心法

1. 指令清晰：给模型的格式指导越清晰、越具体越好。
2. 验证兜底：务必实现输出验证和异常处理逻辑，应对 AI 的“小脾气”。
3. 选对模型：优先选择官方支持或提供内置 JSON 模式的模型，可靠性更高。
4. 巧用泛型：处理复杂数据结构(如 List<Map<String, MyObject>>)时，ParameterizedTypeReference 是你的得力助手。

Spring AI 的结构化输出功能，极大地简化了与大模型交互的复杂度，让开发者能更专注于业务逻辑，而不是繁琐的数据解析。它就像一座桥梁，无缝连接了 AI 的创造力与 Java 应用的严谨性。

赶快在你的项目中试试吧！体验一下让 AI “言听计从”的快感。

你对 Spring AI 的哪个特性最感兴趣？欢迎在评论区留言讨论！ 如果觉得本文对你有帮助，别忘了点赞、分享三连哦！