AI项目博客
记录 AI 工程实践与大模型应用
        找回密码
当前位置：AI项目博客 AI框架 AI Alibaba 正文

Spring AI Alibaba 30｜Structured Output 结构化输出 · 输出 Schema 策略

2026-08-10 分类：AI Alibaba 阅读(19) 评论(0)

结构化输出允许 Agent 以特定的、可预测的格式返回数据。相比于解析自然语言响应，您可以直接获得 JSON 对象或 Java POJO 形式的结构化数据，应用程序可以直接使用。

Spring AI Alibaba 的 ReactAgent.Builder 通过 outputSchema 和 outputType 方法处理结构化输出。当您设置所需的结构化输出模式时，Agent 会自动在用户消息中增加模式指令，模型会根据指定的格式生成数据。

ReactAgent agent = ReactAgent.builder()
  .name("agent")
  .model(chatModel)
  .outputSchema(schemaString)  // Custom JSON schema as String
  // OR
  .outputType(MyClass.class)   // Java class - auto-converted to schema
  .build();

Spring AI Alibaba 支持两种方式控制结构化输出：

  • outputSchema(String schema): 提供 JSON schema 字符串。推荐使用 BeanOutputConverter 从 Java 类自动生成 schema，也可以手动提供自定义的 schema 字符串
  • outputType(Class<?> type): 提供 Java 类 – 使用 BeanOutputConverter 自动转换为 JSON schema（推荐方式，类型安全）
  • 不指定: 返回非结构化的自然语言响应

推荐做法：使用 BeanOutputConverter 生成 schema，既保证了类型安全，又实现了自动 schema 生成，代码更易维护。

结构化响应在 Agent 的 AssistantMessage 中作为 JSON 文本返回，可以解析为您需要的格式。

您可以使用 BeanOutputConverter 从 Java 类自动生成 JSON schema，或者直接提供 JSON schema 字符串。推荐使用 BeanOutputConverter 以获得类型安全和自动 schema 生成。

方法签名

Builder outputSchema(String outputSchema)

参数:

  • outputSchema (String, 必需): 定义结构化输出格式的 JSON schema 字符串。可以通过 BeanOutputConverter.getFormat() 方法从 Java 类自动生成，也可以手动提供自定义的 schema 字符串。

示例

基本 JSON Schema:

使用 BeanOutputConverter 从 Java 类自动生成 JSON Schema：

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.converter.BeanOutputConverter;

// 定义输出类型
public static class ContactInfo {
  private String name;
  private String email;
  private String phone;

  // Getters and Setters
  public String getName() { return name; }
  public void setName(String name) { this.name = name; }
  public String getEmail() { return email; }
  public void setEmail(String email) { this.email = email; }
  public String getPhone() { return phone; }
  public void setPhone(String phone) { this.phone = phone; }
}

// 使用 BeanOutputConverter 生成 outputSchema
BeanOutputConverter<ContactInfo> outputConverter = new BeanOutputConverter<>(ContactInfo.class);
String format = outputConverter.getFormat();

ReactAgent agent = ReactAgent.builder()
  .name("contact_extractor")
  .model(chatModel)
  .outputSchema(format)
  .build();

AssistantMessage result = agent.call(
  "从以下信息提取联系方式：张三，zhangsan@example.com，(555) 123-4567"
);

System.out.println(result.getText());
// 输出: {"name": "张三", "email": "zhangsan@example.com", "phone": "(555) 123-4567"}

复杂嵌套 Schema:

使用 BeanOutputConverter 处理复杂嵌套结构：

import org.springframework.ai.converter.BeanOutputConverter;

// 定义输出类型（包含嵌套类）
public static class ProductReview {
  private int rating;
  private String sentiment;
  private String[] keyPoints;
  private ReviewDetails details;

  // Getters and Setters
  public int getRating() { return rating; }
  public void setRating(int rating) { this.rating = rating; }
  public String getSentiment() { return sentiment; }
  public void setSentiment(String sentiment) { this.sentiment = sentiment; }
  public String[] getKeyPoints() { return keyPoints; }
  public void setKeyPoints(String[] keyPoints) { this.keyPoints = keyPoints; }
  public ReviewDetails getDetails() { return details; }
  public void setDetails(ReviewDetails details) { this.details = details; }

  public static class ReviewDetails {
      private String[] pros;
      private String[] cons;
      // Getters and Setters
  }
}

// 使用 BeanOutputConverter 生成 outputSchema
BeanOutputConverter<ProductReview> outputConverter = new BeanOutputConverter<>(ProductReview.class);
String format = outputConverter.getFormat();

ReactAgent agent = ReactAgent.builder()
  .name("review_analyzer")
  .model(chatModel)
  .outputSchema(format)
  .build();

AssistantMessage result = agent.call(
  "分析评价：这个产品很棒，5星好评。配送快速，但价格稍贵。"
);

System.out.println(result.getText());
// 输出: {"rating": 5, "sentiment": "正面", "keyPoints": [...], "details": {...}}

结构化分析 Schema:

使用 BeanOutputConverter 处理包含实体识别的复杂结构：

import org.springframework.ai.converter.BeanOutputConverter;

// 定义输出类型（包含嵌套实体类）
public static class TextAnalysis {
  private String summary;
  private String[] keywords;
  private String sentiment;
  private Entities entities;

  // Getters and Setters
  public String getSummary() { return summary; }
  public void setSummary(String summary) { this.summary = summary; }
  public String[] getKeywords() { return keywords; }
  public void setKeywords(String[] keywords) { this.keywords = keywords; }
  public String getSentiment() { return sentiment; }
  public void setSentiment(String sentiment) { this.sentiment = sentiment; }
  public Entities getEntities() { return entities; }
  public void setEntities(Entities entities) { this.entities = entities; }

  public static class Entities {
      private String[] persons;
      private String[] locations;
      private String[] organizations;
      // Getters and Setters
  }
}

// 使用 BeanOutputConverter 生成 outputSchema
BeanOutputConverter<TextAnalysis> outputConverter = new BeanOutputConverter<>(TextAnalysis.class);
String format = outputConverter.getFormat();

ReactAgent agent = ReactAgent.builder()
  .name("text_analyzer")
  .model(chatModel)
  .outputSchema(format)
  .build();

AssistantMessage result = agent.call(
  "分析这段文字：昨天，李明在北京参加了阿里巴巴公司的技术大会，感受到了创新的力量。"
);

System.out.println(result.getText());

使用 BeanOutputConverter 生成 schema 提供了类型安全和自动生成的优势。如果您需要完全自定义的 schema 格式，也可以直接提供 JSON schema 字符串。outputSchema 方法支持两种方式，为您提供最大的灵活性。

对于类型安全的结构化输出，您可以提供 Java 类，Spring AI Alibaba 将使用 BeanOutputConverter 自动将其转换为 JSON schema。这种方法确保了编译时类型安全和自动 schema 生成。

方法签名

Builder outputType(Class<?> outputType)

参数:

  • outputType (Class<?>, 必需): 定义输出结构的 Java 类。该类应该是带有标准 getter 和 setter 的 POJO。

示例

使用 outputType 是最简洁的方式，框架会自动使用 BeanOutputConverter 将 Java 类转换为 JSON schema：

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.checkpoint.savers.MemorySaver;
import org.springframework.ai.chat.messages.AssistantMessage;

// 定义输出类型
public static class ContactInfo {
  private String name;
  private String email;
  private String phone;

  // Getters and Setters
  public String getName() { return name; }
  public void setName(String name) { this.name = name; }
  public String getEmail() { return email; }
  public void setEmail(String email) { this.email = email; }
  public String getPhone() { return phone; }
  public void setPhone(String phone) { this.phone = phone; }
}

// 直接使用 outputType，框架会自动处理 schema 转换
ReactAgent agent = ReactAgent.builder()
  .name("contact_extractor")
  .model(chatModel)
  .outputType(ContactInfo.class)  
  .saver(new MemorySaver())
  .build();

AssistantMessage result = agent.call(
  "从以下信息提取联系方式：张三，zhangsan@example.com，(555) 123-4567"
);

System.out.println(result.getText());
// 输出: {"name": "张三", "email": "zhangsan@example.com", "phone": "(555) 123-4567"}

outputType vs outputSchema：

  • outputType: 更简洁，直接传入 Java 类，框架自动处理（推荐）
  • outputSchema: 需要手动使用 BeanOutputConverter 生成 schema，或提供自定义字符串，提供更多控制

当 outputFormat 或 outputType 被指定时，Spring AI Alibaba 会自动选择：

  • 当大模型服务支持 “原生结构化输出” 时（目前支持 OpenAiChatModel、DashScopeChatModel），自动使用模型内置的结构化输出能力（这也是目前最稳定、可靠的方式，因为模型服务会自动提供校验支持）。
  • 针对其他没有 “原生结构化输出” 的模型，Spring AI Alibaba 会使用内置的 ToolCall策略，通过一个动态的 ToolCall 来格式化模型输出。

结构化响应将在 Agent 的状态对象 OverAllState 中返回，可通过 structured_output 读取。

模型原生结构化输出

比如，针对 DashScopeChatModel 模型，在配置 outputSchema 或 outputType 后，Spring AI Alibaba 会自动设置如下参数，以启用模型原生结构化输出能力。

ChatOptions options = DashScopeChatOptions.builder()
.withResponseFormat(
	DashScopeResponseFormat.builder()
		.type(DashScopeResponseFormat.Type.JSON_OBJECT)
		.build())
.build();

同时，Spring AI Alibaba 框架会增强系统 Prompt，引导模型输出格式化内容

// In AgentLlmNode.augmentUserMessage() method
public void augmentUserMessage(List<Message> messages, String outputSchema) {
  if (!StringUtils.hasText(outputSchema)) {
      return;
  }

  for (int i = messages.size() - 1; i >= 0; i--) {
      Message message = messages.get(i);
      if (message instanceof UserMessage userMessage) {
          messages.set(i, userMessage.mutate()
              .text(userMessage.getText() + System.lineSeparator() + outputSchema)
              .build());
          break;
      }
  }
}

注意，相比于 DashScope 模型是通过增强 Prompt 提示词实现最终的 JSON 格式，实现的是一个尽最大努力的效果，OpenAI 模型则是在模型 API 层面支持 Json 格式，提供格式的严格保证支持。

ToolCall 结构化输出

对于不支持原生结构化输出的模型，Spring AI Alibaba 支持通过调用工具来实现相同效果。此方法适用于所有支持工具调用的模型，即大多数现代模型。

本文整理自 Spring AI Alibaba 官方文档《Structured Output 结构化输出》：https://java2ai.com/docs/frameworks/agent-framework/tutorials/structured-output

赞(0)
未经允许不得转载：AI项目博客 » Spring AI Alibaba 30｜Structured Output 结构化输出 · 输出 Schema 策略
分享到

admin

相关推荐

评论 抢沙发

取消

AI项目博客

专注 AI 工程化落地 —— 覆盖智能体、大模型、Java AI 与 Python 的学习笔记，以及 AI 平台的项目实战记录。

关于本站文章归档

登录

找回密码

注册