3、结构化输出（Structured Output）

结构化输出转换器

自 2024 年 5 月 2 日起， 旧的OutputParser、BeanOutputParser和ListOutputParser类MapOutputParser已弃用，取而代之的是新的StructuredOutputConverter、BeanOutputConverter和实现。后者是前者的直接替代品，并提供相同的功能。更改的原因主要是命名方面，因为无需进行任何解析，同时也与 Spring包保持一致，带来了一些改进的功能。 org.springframework.core.convert.converter.ListOutputConverterMapOutputConverter

LLM 生成结构化输出的能力对于依赖可靠解析输出值的下游应用程序至关重要。开发人员希望快速将 AI 模型的结果转换为可传递给其他应用程序函数和方法的数据类型，例如 JSON、XML 或 Java 类。

Spring AI Structured Output Converters 有助于将 LLM 输出转换为结构化格式。如下图所示，此方法围绕 LLM 文本补全端点运行：

使用通用补全 API 从大型语言模型 (LLM) 生成结构化输出需要仔细处理输入和输出。结构化输出转换器在 LLM 调用前后起着至关重要的作用，确保实现所需的输出结构。

在 LLM 调用之前，转换器会将格式指令附加到提示中，为模型提供生成所需输出结构的明确指导。这些指令充当蓝图，塑造模型的响应以符合指定的格式。

LLM 调用后，转换器会获取模型的输出文本，并将其转换为结构化类型的实例。此转换过程包括解析原始文本输出并将其映射到相应的结构化数据表示形式，例如 JSON、XML 或特定于域的数据结构。

我们 StructuredOutputConverter 尽力将模型输出转换为结构化输出。AI 模型无法保证按要求返回结构化输出。模型可能无法理解提示或无法按要求生成结构化输出。请考虑实施验证机制，以确保模型输出符合预期。

结构化输出 API

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

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

}

它结合了 Spring Converter<String, T> 接口和FormatProvider 接口

public interface FormatProvider {
    String getFormat();
}

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

为 AI 模型提供特定的格式指南，使其能够生成文本输出，并使用FormatProvider将其转换为指定的目标类型。以下是此类格式说明的示例：TConverter

您的回复应采用 JSON 格式。
JSON 的数据结构应该与这个 Java 类匹配：java.util.HashMap
不包含任何解释，仅提供符合 RFC8259 的 JSON 响应，遵循此格式，不得有偏差。

格式说明通常使用PromptTemplate附加到用户输入的末尾，如下所示：

    StructuredOutputConverter outputConverter = ...
    String userInputTemplate = """
        ... user text input ....
        {format}
        """; // user input with a "format" placeholder.
    Prompt prompt = new Prompt(
            PromptTemplate.builder()
                        .template(this.userInputTemplate)
                        .variables(Map.of(..., "format", this.outputConverter.getFormat())) // replace the "format" placeholder with the converter's format.
                        .build().createMessage()
    );

Converter<String, T> 负责将模型的输出文本转换为指定类型的实例T。

可用的转换器

目前，Spring AI 提供 AbstractConversionServiceOutputConverter 和AbstractMessageOutputConverter、BeanOutputConverter、MapOutputConverter、ListOutputConverter实现：

• AbstractConversionServiceOutputConverter<T> - 提供预配置的GenericConversionService，用于将 LLM 输出转换为所需格式。未FormatProvider提供默认实现。
• AbstractMessageOutputConverter<T> - 提供预配置的MessageConverter，用于将 LLM 输出转换为所需格式。未FormatProvider提供默认实现。
• BeanOutputConverter<T> - 此转换器配置了指定的 Java 类（例如 Bean）或ParameterizedTypeReferenceFormatProvider ，并采用一种实现方式，指示 AI 模型生成符合 的 JSON 响应DRAFT_2020_12，该响应JSON Schema派生自指定的 Java 类。随后，它利用ObjectMapper将 JSON 输出反序列化为目标类的 Java 对象实例。
• MapOutputConverterAbstractMessageOutputConverter -通过一个FormatProvider可指导 AI 模型生成符合 RFC8259 标准的 JSON 响应的实现来扩展功能。此外，它还包含一个转换器实现，该实现利用提供的MessageConverterJSON 负载转换为java.util.Map<String, Object>实例。
• ListOutputConverter - 扩展了 AbstractConversionServiceOutputConverter，并包含一个FormatProvider针对逗号分隔列表输出定制的实现。转换器实现使用提供的ConversionService，将模型文本输出转换为java.util.List。

使用转换器

以下部分提供了如何使用可用的转换器生成结构化输出的指南。

Bean 输出转换器

以下示例显示如何使用BeanOutputConverter来生成演员的电影作品。

代表演员电影作品的目标记录：

record ActorsFilms(String actor, List<String> movies) {
}

以下是如何使用高级、流式的 ChatClientAPI 应用 BeanOutputConverter：

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);

或者直接使用低级 ChatModel API：

BeanOutputConverter<ActorsFilms> beanOutputConverter =
    new BeanOutputConverter<>(ActorsFilms.class);

String format = this.beanOutputConverter.getFormat();

String actor = "Tom Hanks";

String template = """
        Generate the filmography of 5 movies for {actor}.
        {format}
        """;

Generation generation = chatModel.call(
    PromptTemplate.builder().template(this.template).variables(Map.of("actor", this.actor, "format", this.format)).build().create()).getResult();

ActorsFilms actorsFilms = this.beanOutputConverter.convert(this.generation.getOutput().getText());

生成的 Schema 中的属性排序

BeanOutputConverter 支持通过 @JsonPropertyOrder 注解在生成的 JSON 架构中自定义属性排序。此注解允许您指定属性在 Schema 中出现的确切顺序，而不管它们在类或记录中的声明顺序如何。

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

@JsonPropertyOrder({"actor", "movies"})
record ActorsFilms(String actor, List<String> movies) {}

此注释适用于记录和常规 Java 类。

通用 Bean 类型

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

或者直接使用低级 ChatModel API：

BeanOutputConverter<List<ActorsFilms>> outputConverter = new BeanOutputConverter<>(
        new ParameterizedTypeReference<List<ActorsFilms>>() { });

String format = this.outputConverter.getFormat();
String template = """
        Generate the filmography of 5 movies for Tom Hanks and Bill Murray.
        {format}
        """;

Prompt prompt = PromptTemplate.builder().template(this.template).variables(Map.of("format", this.format)).build().create();

Generation generation = chatModel.call(this.prompt).getResult();

List<ActorsFilms> actorsFilms = this.outputConverter.convert(this.generation.getOutput().getText());

MapOutputConverter

以下代码片段展示了如何使用 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>>() {});

或者直接使用低级 ChatModel API：

MapOutputConverter mapOutputConverter = new MapOutputConverter();

String format = this.mapOutputConverter.getFormat();
String template = """
        Provide me a List of {subject}
        {format}
        """;

Prompt prompt = PromptTemplate.builder().template(this.template)
.variables(Map.of("subject", "an array of numbers from 1 to 9 under they key name 'numbers'", "format", this.format)).build().create();

Generation generation = chatModel.call(this.prompt).getResult();

Map<String, Object> result = this.mapOutputConverter.convert(this.generation.getOutput().getText());

ListOutputConverter

以下代码片段展示了如何使用 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()));

或者直接使用低级 ChatModel API：

ListOutputConverter listOutputConverter = new ListOutputConverter(new DefaultConversionService());

String format = this.listOutputConverter.getFormat();
String template = """
        List five {subject}
        {format}
        """;

Prompt prompt = PromptTemplate.builder().template(this.template).variables(Map.of("subject", "ice cream flavors", "format", this.format)).build().create();

Generation generation = this.chatModel.call(this.prompt).getResult();

List<String> list = this.listOutputConverter.convert(this.generation.getOutput().getText());

支持的 AI 模型

以下 AI 模型已经过测试，支持 List、Map 和 Bean 结构化输出。

内置 JSON 模式

一些 AI 模型提供专用的配置选项来生成结构化（通常是 JSON）输出。

• OpenAI 结构化输出 可以确保您的模型生成的响应严格符合您提供的 JSON 模式。您可以选择 ，JSON_OBJECT 以保证模型生成的消息为有效的 JSON；或者JSON_SCHEMA选择 ，以保证模型生成的响应与您提供的模式匹配（spring.ai.openai.chat.options.responseFormat选项）。
• *Azure OpenAI *- 提供spring.ai.azure.openai.chat.options.responseFormat指定模型必须输出格式的选项。设置为{ “type”: “json_object” }启用 JSON 模式，可确保模型生成的消息为有效的 JSON。
• Ollama - 提供一个spring.ai.ollama.chat.options.format选项来指定返回响应的格式。目前，唯一接受的值是json。
• *Mistral AI *- 提供一个spring.ai.mistralai.chat.options.responseFormat选项来指定返回响应的格式。将其设置为{ “type”: “json_object” }启用 JSON 模式，这可以保证模型生成的消息是有效的 JSON。