从AI“说人话”到“说结构话”：Spring AI结构化输出实战解析

作为一名AI应用开发者，你是否遇到过这样的困扰：大语言模型（LLM）的回答虽然内容准确，但格式千变万化，难以被程序直接使用？今天，我们就来聊聊Spring AI中的结构化输出转换器，看看如何让AI输出"规规矩矩"的数据，像Java对象、Map、List一样可靠。

一、为什么需要结构化输出？

大语言模型天然擅长生成自然语言，但在企业级应用中，我们往往需要将AI的回答与业务流程对接。例如：

从对话中提取"恋爱报告"，包含标题和建议列表
获取一份格式固定的电影清单
解析用户意图，生成结构化的操作指令

如果AI每次返回的格式都不同，下游程序将难以稳定解析。这时，结构化输出转换器就派上了用场。

二、Spring AI结构化输出转换器原理

Spring AI通过两个核心接口实现结构化输出：

1. `FormatProvider`接口：调用前"格式化指令"

在向AI发送请求之前，转换器会在提示词后追加格式说明，告诉模型"请按这个结构返回"。例如，我们希望AI返回一个恋爱报告对象：

json 复制代码

{
  "title": "张三的恋爱报告",
  "suggestions": ["多沟通", "增加约会频率"]
}

转换器会生成类似这样的格式指令：

javascript 复制代码

返回格式必须是 JSON，匹配以下结构：
{
    "title": "string",
    "suggestions": ["string1", "string2"]
}
请只返回 JSON，不要有任何其他内容。

2. `Converter<String, T>`接口：调用后"反序列化"

AI返回的文本（通常是JSON）会被Converter转换成我们指定的Java类型（如LoveReport、List<String>等）。

这两个步骤结合起来，就实现了"从自然语言到结构化数据"的完整闭环。

三、实战：恋爱报告的结构化输出

我们来看一个具体例子。假设我们有一个恋爱咨询应用，用户倾诉后，我们希望AI生成一份结构化的恋爱报告。

1. 定义报告类

arduino 复制代码

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

这是一个简单的Java Record，包含标题和建议列表。

2. 使用`entity()`方法获取结构化对象

scss 复制代码

public LoveReport doChatWithReport(String message, String chatId) {
    LoveReport report = 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()
            .entity(LoveReport.class);  // 关键：转换为LoveReport对象
    return report;
}

重点解析：

.entity(LoveReport.class)：Spring AI会自动在请求中加入格式指令，并将返回的JSON转换为LoveReport实例。
系统提示词中我们明确要求"生成恋爱结果"，帮助模型理解输出目标。

3. 更复杂的结构：使用`ParameterizedTypeReference`

如果我们要返回一个List<LoveReport>，可以这样写：

scss 复制代码

List<LoveReport> reports = chatClient.prompt()
        .user("为小明和小红分别生成恋爱报告")
        .call()
        .entity(new ParameterizedTypeReference<List<LoveReport>>() {});

这适用于嵌套泛型等复杂场景。

四、其他内置转换器示例

Spring AI还提供了多种开箱即用的转换器：

1. 输出为`Map`

javascript 复制代码

Map<String, Object> result = chatClient.prompt()
        .user("给我一个1到9的数字列表，key为numbers")
        .call()
        .entity(new ParameterizedTypeReference<Map<String, Object>>() {});

2. 输出为`List<String>`

sql 复制代码

List<String> flavors = chatClient.prompt()
        .user("列出5种冰淇淋口味")
        .call()
        .entity(new ListOutputConverter(new DefaultConversionService()));

五、最佳实践建议

明确格式指令：在系统提示或用户提示中清晰描述期望的输出结构，尤其是字段含义。
添加验证与异常处理：AI输出可能不完全符合预期，建议对转换后的对象做非空校验或格式校验。
选择合适的模型：不同模型对指令遵循能力不同，优先选择支持结构化输出（如JSON模式）的模型。
复杂结构用ParameterizedTypeReference：当返回类型涉及泛型时，这是更安全的选择。

六、总结

Spring AI的结构化输出转换器，本质上是通过前置格式约束 与后置类型转换，让AI的输出从"自由文本"变为"可控数据"。它不仅简化了开发者的解析工作，也为AI应用与业务系统的深度集成铺平了道路。

在你的下一个AI项目中，不妨试试这套机制，让AI不仅"会说话"，更能"说结构话"。