Spring AI之结构化输出

原创

已于 2025-04-07 01:44:34 修改 · 1.8k 阅读

标签

#spring #人工智能 #java

于 2025-04-02 17:56:29 首次发布

文章目录

自2024年5月2日起，旧的 OutputParser、BeanOutputParser、ListOutputParser 和 MapOutputParser 类已被弃用，取而代之的是新的 StructuredOutputConverter、BeanOutputConverter、ListOutputConverter 和 MapOutputConverter 实现。新类是旧类的直接替代品，功能相同。此次变更的主要原因是命名调整（因原名称中的"解析（parsing）"并不准确），同时新实现与Spring框架的 org.springframework.core.convert.converter 包对齐，引入了改进功能。

大型语言模型（LLM）生成结构化输出的能力对依赖可靠解析结果值的下游应用至关重要。开发者希望将AI模型的输出快速转换为JSON、XML或Java类等数据类型，以便传递给其他应用程序功能或方法。
Spring AI的结构化输出转换器可将LLM输出转换为结构化格式。如下图所示，该方法围绕LLM文本补全端点（text completion endpoint）展开：

结构化输出转换器架构
通过通用补全API从LLM生成结构化输出时，需谨慎处理输入和输出。结构化输出转换器在LLM调用前后均发挥关键作用，确保实现预期的输出结构。

LLM调用前 ：转换器将格式指令附加到提示词（prompt）中，为模型生成目标结构提供明确指导。这些指令充当"蓝图"，引导模型响应符合指定格式。
LLM调用后 ：转换器将模型的原始文本输出转换为结构化类型实例。此过程包括解析原始文本并将其映射到对应的结构化数据表示（如JSON、XML或领域特定数据结构）

StructuredOutputConverter 会尽力将模型输出转换为结构化格式，但无法保证LLM必然返回请求的结构。模型可能无法理解提示词或无法按要求生成结构化输出，因此建议实现验证机制以确保输出符合预期。

此外，StructuredOutputConverter 不用于LLM工具调用（Tool Calling），因为该功能默认已提供结构化输出
在这里插入图片描述

结构化输出API

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

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

}

该接口结合了Spring的 Converter<String, T> 接口和 FormatProvider 接口：

public interface FormatProvider {
   
   

String getFormat();

}

下图展示了使用结构化输出API时的数据流：
在这里插入图片描述

结构化输出API数据流

FormatProvider 向AI模型提供特定格式化指南，使其生成的文本输出可通过 Converter 转换为指定目标类型 T。以下为格式指令示例：

您的响应应为JSON格式。  
JSON的数据结构需与Java类 `java.util.HashMap` 匹配。  
仅提供符合RFC8259标准的JSON响应，无需任何解释或偏离指定格式。

格式指令通常通过 PromptTemplate 附加到用户输入末尾，例如：

StructuredOutputConverter outputConverter = ...;
String userInputTemplate = """
    ... 用户文本输入 ....
    {format}
    """; // 用户输入中包含"format"占位符
Prompt prompt = new Prompt(
   new PromptTemplate(
           this.userInputTemplate,
          Map.of(..., "format", outputConverter.getFormat()) // 用转换器的格式替换"format"占位符
   ).createMessage());

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

可用转换器

Spring AI目前提供以下转换器实现：
结构化输出类层次结构
在这里插入图片描述

AbstractConversionServiceOutputConverter
提供预配置的 GenericConversionService，用于将LLM输出转换为所需格式。未提供默认的 FormatProvider 实现。
AbstractMessageOutputConverter
提供预配置的 MessageConverter，用于将LLM输出转换为所需格式。未提供默认的 FormatProvider 实现。
BeanOutputConverter
配置了指定Java类（如Bean）或 ParameterizedTypeReference，其 FormatProvider 实现会引导AI模型生成符合基于该Java类推导出的JSON Schema（DRAFT_2020_12）的JSON响应。随后使用 ObjectMapper 将JSON反序列化为目标Java类的实例。
MapOutputConverter
扩展 AbstractMessageOutputConverter，其 FormatProvider 实现引导AI模型生成符合RFC8259标准的JSON响应。内置转换器通过提供的 MessageConverter 将JSON负载转换为 java.util.Map<String, Object> 实例。
ListOutputConverter
扩展 AbstractConversionServiceOutputConverter，其 FormatProvider 实现专为逗号分隔的列表输出设计。转换器使用提供的 ConversionService 将模型文本输出转换为 java.util.List。