当前位置：首页 > news >正文

Spring AI 结构化输出详解

news 来源：原创 2025/9/12 19:28:31

一、Spring AI 结构化输出的定义与核心概念

Spring AI 提供了一种强大的功能，允许开发者将大型语言模型（LLM）的输出从字符串转换为结构化格式，如 JSON、XML 或 Java 对象。这种结构化输出能力对于依赖可靠解析输出值的下游应用程序至关重要。

通过 Spring AI 的结构化输出转换器，开发者可以快速将 AI 模型的结果转换为可以传递给其他应用程序函数和方法的数据类型。转换器在 LLM 调用之前将期望的输出格式附加到 prompt 中，为模型提供生成所需输出结构的明确指导。在 LLM 调用之后，转换器获取模型的输出文本并将其转换为结构化类型的实例。
在这里插入图片描述

二、结构化输出的技术原理

结构化输出的技术原理可以分为以下几个关键步骤：

附加格式说明
在 LLM 调用之前，转换器会将期望的输出格式（output format instruction）附加到 prompt 中。这些指令充当蓝图，塑造模型的响应以符合指定的格式。例如：

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 following this format without deviation.

模型生成响应
LLM 根据 prompt 中的格式说明生成符合要求的输出。
解析与转换
转换器获取模型的输出文本，并将其解析为结构化类型的实例。此过程涉及将原始文本输出映射到相应的结构化数据表示，如 JSON、XML 或特定于域的数据结构。

三、Spring AI 提供的转换器实现

Spring AI 提供了多种转换器实现，以满足不同的结构化输出需求：

BeanOutputConverter
- 使用指定的 Java 类（例如 Bean）或 ParameterizedTypeReference 配置。
- 指示 AI 模型生成符合 JSON 模式的响应，随后利用 ObjectMapper 将 JSON 输出反序列化为目标类的 Java 对象实例。
MapOutputConverter
- 指导 AI 模型生成符合 RFC8259 的 JSON 响应。
- 包含一个转换器实现，利用提供的 MessageConverter 将 JSON 负载转换为 java.util.Map<String, Object> 实例。
ListOutputConverter
- 指导 AI 模型生成逗号分隔的格式化输出。
- 最终转换器将模型文本输出转换为 java.util.List。

四、结构化输出的应用场景

结构化输出技术广泛应用于以下场景：

智能助手
将模型输出转换为结构化数据，用于驱动智能助手的应用逻辑。
数据分析
将模型生成的分析结果转换为结构化格式，便于后续的数据处理和可视化。
内容生成
将模型生成的内容转换为特定的结构化格式，用于内容管理系统或自动化生成报告。

五、结构化输出的实现方式

以下是一些使用 Spring AI 结构化输出的代码示例：

1. 使用 `BeanOutputConverter`

import com.alibaba.cloud.ai.client.ChatClient;
import com.alibaba.cloud.ai.client.model.ChatModel;
import com.alibaba.cloud.ai.client.output.BeanOutputConverter;public class StructuredOutputExample {public static void main(String[] args) {ChatModel chatModel = ChatModel.create("your-model-id");// 定义目标类record ActorsFilms(String actor, List<String> movies) {}// 创建 BeanOutputConverterBeanOutputConverter<ActorsFilms> beanOutputConverter = new BeanOutputConverter<>(ActorsFilms.class);// 获取格式说明String format = beanOutputConverter.getFormat();// 构建 promptString actor = "Tom Hanks";String template = """Generate the filmography of 5 movies for {actor}.{format}""";// 调用模型Generation generation = chatModel.call(new PromptTemplate(template, Map.of("actor", actor, "format", format)).create()).getResult();// 转换为目标类ActorsFilms actorsFilms = beanOutputConverter.convert(generation.getOutput().getContent());System.out.println("Actor: " + actorsFilms.actor());System.out.println("Movies: " + actorsFilms.movies());}
}

2. 使用 `MapOutputConverter`

import com.alibaba.cloud.ai.client.ChatClient;
import com.alibaba.cloud.ai.client.model.ChatModel;
import com.alibaba.cloud.ai.client.output.MapOutputConverter;import java.util.Map;public class MapOutputExample {public static void main(String[] args) {ChatModel chatModel = ChatModel.create("your-model-id");// 创建 MapOutputConverterMapOutputConverter mapOutputConverter = new MapOutputConverter();// 构建 promptString subject = "an array of numbers from 1 to 9 under their key name 'numbers'";String prompt = "Provide me a List of " + subject;// 调用模型Generation generation = chatModel.call(new Prompt(prompt)).getResult();// 转换为 MapMap<String, Object> result = mapOutputConverter.convert(generation.getOutput().getContent());System.out.println("Result: " + result);}
}

3. 使用 `ListOutputConverter`

import com.alibaba.cloud.ai.client.ChatClient;
import com.alibaba.cloud.ai.client.model.ChatModel;
import com.alibaba.cloud.ai.client.output.ListOutputConverter;import java.util.List;public class ListOutputExample {public static void main(String[] args) {ChatModel chatModel = ChatModel.create("your-model-id");// 创建 ListOutputConverterListOutputConverter listOutputConverter = new ListOutputConverter(new DefaultConversionService());// 构建 promptString subject = "ice cream flavors";String prompt = "List five " + subject;// 调用模型Generation generation = chatModel.call(new Prompt(prompt)).getResult();// 转换为 ListList<String> flavors = listOutputConverter.convert(generation.getOutput().getContent());System.out.println("Flavors: " + flavors);}
}

4. 使用 `ChatClient` 进行结构化输出

import com.alibaba.cloud.ai.client.ChatClient;
import com.alibaba.cloud.ai.client.model.ChatModel;public class ChatClientExample {public static void main(String[] args) {ChatModel chatModel = ChatModel.create("your-model-id");// 定义目标类record ActorsFilms(String actor, List<String> movies) {}// 使用 ChatClient 转换为 ActorsFilms 对象ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt().user(u -> u.text("Generate the filmography of 5 movies for {actor}.").param("actor", "Tom Hanks")).call().entity(ActorsFilms.class);System.out.println("Actor: " + actorsFilms.actor());System.out.println("Movies: " + actorsFilms.movies());}
}

六、结构化输出的未来发展方向

多模态输出
结合文本、图像、音频等多种模态数据，提升输出的多样性和准确性。
实时转换
提高转换器的实时性，支持更快速的输出解析和转换。
领域特定转换
针对特定领域（如医疗、法律）提供定制化的结构化输出转换器。
自动化优化
通过机器学习技术自动优化转换器的性能和准确性。

七、总结

Spring AI 的结构化输出功能为开发者提供了一种强大的工具，可以将 LLM 的输出转换为结构化格式，从而满足下游应用程序的需求。通过使用 Spring AI 提供的转换器实现，开发者可以轻松地将模型输出转换为 JSON、XML 或 Java 对象，提高开发效率和应用可靠性。随着技术的不断发展，结构化输出将在更多领域发挥重要作用，为开发者提供更多智能化的解决方案。

一、Spring AI 结构化输出的定义与核心概念

二、结构化输出的技术原理

三、Spring AI 提供的转换器实现

四、结构化输出的应用场景

五、结构化输出的实现方式

1. 使用 BeanOutputConverter

2. 使用 MapOutputConverter

3. 使用 ListOutputConverter

4. 使用 ChatClient 进行结构化输出