CH 03结构化输出与 Advisors

3.1为什么输出必须是对象

先看一个真实场景。用户输入一段话，你要提取成订单数据：

// 用户输入（一段自由文本，可能来自邮件、聊天记录、OCR 结果）
"你好，我是张三，订单 2024001 在 3 月 5 日下的单，金额 899 元，
 买了一个机械键盘和一个鼠标垫，现在还没发货，麻烦催一下。联系电话 138****8888"

如果用纯文本返回，你拿到的是一段字符串，要写正则去抠订单号、抠金额——模型稍微换个说法（「总计 899 元」/「共 899.00 元」），你的正则就废了。这就是非结构化输出的致命问题：不可靠。

我们的目标类型（用 record，简洁且不可变）：

package com.example.springai.ch03.model;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

/**
 * 订单信息提取结果。
 * 用 record 的好处：字段即构造参数，Jackson 反序列化开箱即用（JDK 17+ / Jackson 2.12+）。
 * 注意字段名要和提示词里的 JSON schema 对应，否则映射不上会得到 null。
 */
public record OrderInfo(
        String orderNo,              // 订单号，如 2024001
        String customerName,         // 客户姓名
        BigDecimal amount,           // 金额。★ 必须用 BigDecimal，绝不能用 double
        String status,               // 状态：未发货/已发货/已完成/已取消
        LocalDate orderDate,         // 下单日期
        List<String> items,          // 商品列表
        String phone                 // 联系电话
) {}

3.2entity()：一行代码拿到对象

Spring AI 把这个过程封装得极其简单——把 .content() 换成 .entity()：

import org.springframework.ai.chat.client.ChatClient;

// 返回单个对象
OrderInfo order = chatClient.prompt()
        .user(userText)
        .call()
        .entity(OrderInfo.class);      // ★ 关键就这一个方法

System.out.println(order.orderNo());   // 2024001
System.out.println(order.amount());    // 899

// 返回集合：泛型需要用 ParameterizedTypeReference 保住类型信息
List<OrderInfo> orders = chatClient.prompt()
        .user("把这段文本里的所有订单都提取出来：\n" + multiOrderText)
        .call()
        .entity(new ParameterizedTypeReference<List<OrderInfo>>() {});

// 返回 Map（字段不固定时用）
Map<String, Object> map = chatClient.prompt()
        .user(userText)
        .call()
        .entity(Map.class);

2.0 重点让它自己纠错：validateSchema()

即使有 schema 约束，模型仍然可能返回不符合要求的 JSON——少字段、类型不对、套了 Markdown 代码块。 2.0 之前你只能自己写重试逻辑（本章 3.4 节后面那种写法）；2.0 把它内置了：

// 1.x 的老写法（仍可用）
OrderInfo order = chatClient.prompt().user(text).call().entity(OrderInfo.class);

// ★ 2.0：给 entity() 传第二个参数，两个开关可以组合
OrderInfo order2 = chatClient.prompt()
        .user(text)
        .call()
        .entity(OrderInfo.class, spec -> spec
                // ① 解析前按 schema 校验；失败时把具体错误回喂给模型并自动重试（默认最多 3 次）
                .validateSchema()
                // ② 把 schema 作为 API 级约束发给厂商（原生结构化输出），而不是靠提示词里写
                .useProviderStructuredOutput()
        );

集合与嵌套结构的写法

// 嵌套对象（订单里有收货地址）
public record OrderDetail(
        String orderNo,
        BigDecimal amount,
        // 嵌套的 record 同样能被 Jackson 处理；
        // 如果模型没识别到地址，这个字段会是 null，调用方必须判空
        Address shippingAddress,
        List<OrderItem> items
) {}

public record Address(String province, String city, String detail) {}
public record OrderItem(String name, int quantity, BigDecimal price) {}

3.3底层原理：手写一遍 converter，才算真懂

如果哪天 entity() 不满足需求（比如你要在系统提示里插入 schema、或者要自定义解析逻辑），就得手动用 StructuredOutputConverter。理解它，你的排查能力会上一个台阶。

import org.springframework.ai.converter.BeanOutputConverter;
import org.springframework.ai.converter.MapOutputConverter;
import org.springframework.ai.converter.ListOutputConverter;

// ① 创建转换器，泛型就是目标类型
BeanOutputConverter<OrderInfo> converter = new BeanOutputConverter<>(OrderInfo.class);

// ② 取出"格式说明"——这是一段自动生成的 JSON Schema 文本
String format = converter.getFormat();
System.out.println(format);
// 输出大致如下（这就是 entity() 偷偷帮你加进提示词的东西）：
// Your response should be in JSON format.
// Do not include any explanations, only provide a JSON object.
// The JSON object should conform to the following schema:
// {"type":"object","properties":{"orderNo":{"type":"string"}, ... }}

// ③ 把它作为 {format} 占位符参数写进你的提示词
String template = """
        从下面的文本中提取订单信息。

        文本：
        {input}

        {format}
        """;

Prompt prompt = PromptTemplate.builder()
        .template(template)
        .build()
        .create(Map.of("input", userText, "format", converter.getFormat()));

// ④ 调用模型后，用 converter 解析
String rawJson = chatModel.call(prompt).getResult().getOutput().getText();
OrderInfo order = converter.convert(rawJson);   // 得到对象

三种内置 Converter 对照

3.4输出约束与校验：让脏数据进不来

结构化输出保证了「形状正确」，但不保证「内容合法」。模型完全可能给你一个金额为 -100、或者状态为「随便什么」的订单。所以必须加校验。

用 JSON Schema 描述把约束前置到提示词

// Spring AI 支持在 record 字段上加 @JsonPropertyDescription，
// 这些描述会写进生成的 JSON Schema，等于"写给模型看的字段说明书"
import com.fasterxml.jackson.annotation.JsonPropertyDescription;

public record OrderInfo(

    @JsonPropertyDescription("订单号，纯数字字符串，例如 2024001；找不到则返回 null")
    String orderNo,

    @JsonPropertyDescription("客户姓名；只保留姓名本身，不要带'先生''女士'等称谓")
    String customerName,

    @JsonPropertyDescription("订单总金额，单位元，只输出数字（如 899.00），不要带'元'或'¥'")
    BigDecimal amount,

    @JsonPropertyDescription("订单状态，只能是以下之一：未发货、已发货、已完成、已取消")
    String status
) {}

用 JSR-303 做业务校验

import jakarta.validation.constraints.*;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.Validator;

public record OrderInfo(
    @NotBlank(message = "订单号不能为空") String orderNo,
    @Min(value = 0, message = "金额不能为负") BigDecimal amount,
    @Pattern(regexp = "^(未发货|已发货|已完成|已取消)$", message = "状态非法") String status
) {}

import org.springframework.stereotype.Service;
import java.util.stream.Collectors;

@Service
public class OrderExtractionService {

    private final ChatClient chatClient;
    private final Validator validator;   // Spring Boot 自动装配

    private static final String TEMPLATE = """
            从下面的文本中提取订单信息。

            规则：
            1. 找不到的字段返回 null，禁止猜测。
            2. 金额只输出数字，不带单位和符号。
            3. 只输出 JSON，不要任何解释文字，不要用代码块包裹。

            文本：
            {input}

            {format}
            """;

    public OrderInfo extract(String input) {
        OrderInfo order = chatClient.prompt()
                .user(u -> u.text(TEMPLATE).param("input", input))
                .options(OpenAiChatOptions.builder()
                        .temperature(0.0)      // ★ 抽取类任务温度设为 0，追求确定性
                        .build())
                .call()
                .entity(OrderInfo.class);

        // 业务校验：不合格直接抛，由全局异常处理器翻译成 400
        var violations = validator.validate(order);
        if (!violations.isEmpty()) {
            String msg = violations.stream()
                    .map(ConstraintViolation::getMessage)
                    .collect(Collectors.joining("；"));
            throw new IllegalArgumentException("提取结果校验失败：" + msg);
        }
        return order;
    }
}

校验失败怎么办：重试 with 错误反馈

/**
 * 带自动重试的提取：把校验失败的原因回传给模型，让它自己修正。
 * 这是生产环境的标准做法——重试 1~2 次能解决绝大部分格式问题。
 */
public OrderInfo extractWithRetry(String input, int maxAttempts) {
    String lastError = null;

    for (int attempt = 1; attempt <= maxAttempts; attempt++) {
        String userText = TEMPLATE.replace("{input}", input);
        if (lastError != null) {
            // ★ 关键：把上次的错误当成新指令喂回去
            userText += "\n\n注意：上一次的输出存在问题（" + lastError
                      + "），请修正后重新输出。";
        }
        try {
            OrderInfo order = chatClient.prompt()
                    .user(userText)
                    .options(OpenAiChatOptions.builder().temperature(0.0).build())
                    .call()
                    .entity(OrderInfo.class);

            var violations = validator.validate(order);
            if (violations.isEmpty()) {
                return order;                    // 成功
            }
            lastError = violations.iterator().next().getMessage();
        } catch (Exception e) {
            // 解析失败（返回的不是合法 JSON），同样记为错误重试
            lastError = "返回内容不是合法 JSON：" + e.getMessage();
        }
        log.warn("第 {} 次提取失败：{}", attempt, lastError);
    }
    // 全部失败：返回 null 或抛业务异常，让上游决定降级策略（如转人工）
    throw new IllegalStateException("订单信息提取失败，已重试 " + maxAttempts + " 次");
}

3.5Advisor 机制：把横切逻辑从业务里抽出来

假设现在有 30 个 AI 接口，你希望每个接口都：打印请求日志、统计 Token 消耗、做敏感词过滤、失败自动重试。 如果写在每个 Service 里，就是 30 份复制粘贴——这正是 Spring AOP 要解决的问题，而 Spring AI 给出的答案是 Advisor。

Advisor 的执行模型

内置 Advisor 一览（课程会逐步用到）

3.6自定义 Advisor 实战：Token 统计 + 内容安全

我们一次写两个，覆盖「后置读取元数据」和「前置拦截改写」两类典型需求。

① Token 用量与耗时统计 Advisor

package com.example.springai.common.advisor;

import io.micrometer.core.instrument.MeterRegistry;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.chat.client.ChatClientRequest;
import org.springframework.ai.chat.client.ChatClientResponse;
import org.springframework.ai.chat.client.advisor.api.CallAdvisor;
import org.springframework.ai.chat.client.advisor.api.CallAdvisorChain;

/**
 * 统计每次模型调用的输入/输出 Token 与耗时。
 * 同时把指标写进 Micrometer，第 10 章可在 Prometheus/Grafana 里看趋势。
 */
@Slf4j
@Component
public class TokenUsageAdvisor implements CallAdvisor {

    private final MeterRegistry meterRegistry;

    public TokenUsageAdvisor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request,
                                          CallAdvisorChain chain) {
        long start = System.currentTimeMillis();

        // ★ 前置逻辑：在调用模型之前
        // ...（这里可以改写 request、记录开始时间、打日志）

        // ★ 交给链上的下一个 Advisor / 最终交给模型
        ChatClientResponse response = chain.nextCall(request);

        // ★ 后置逻辑：拿到响应之后
        long cost = System.currentTimeMillis() - start;
        var usage = response.chatResponse() == null ? null
                : response.chatResponse().getMetadata().getUsage();

        if (usage != null) {
            log.info("[AI用量] 耗时={}ms 输入={} 输出={} 合计={}",
                    cost, usage.getPromptTokens(),
                    usage.getCompletionTokens(), usage.getTotalTokens());

            // 埋点：第 10 章用 Grafana 画"每日 Token 成本"曲线
            meterRegistry.counter("ai.tokens.prompt")
                    .increment(usage.getPromptTokens());
            meterRegistry.counter("ai.tokens.completion")
                    .increment(usage.getCompletionTokens());
        }
        meterRegistry.timer("ai.call.duration").record(cost, java.util.concurrent.TimeUnit.MILLISECONDS);

        return response;
    }

    /**
     * 顺序：设成最小，尽量包在最外层，这样能统计到包含其他 Advisor 在内的总耗时。
     */
    @Override
    public int getOrder() {
        return 0;
    }

    @Override
    public String getName() {
        return "TokenUsageAdvisor";
    }
}

② 内容安全 Advisor（前置拦截 + 改写）

@Slf4j
@Component
public class SafeGuardAdvisor implements CallAdvisor {

    /** 简化版敏感词表；生产环境应放数据库或接入内容安全服务 */
    private static final List<String> BLOCKED = List.of(
            "身份证号", "银行卡密码", "内部机密");

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request,
                                          CallAdvisorChain chain) {

        // 取出本次请求的用户文本。Prompt 里最后一条通常是当前用户消息
        String userText = extractUserText(request);

        for (String word : BLOCKED) {
            if (userText.contains(word)) {
                log.warn("命中敏感词：{}，已拦截", word);
                // ★ 关键：直接返回构造好的响应，不再调用 chain.nextCall()，
                //   这样请求根本不会打到模型，既省钱又安全
                return blockedResponse(request, "抱歉，您的请求包含不允许的内容。");
            }
        }
        return chain.nextCall(request);
    }

    private String extractUserText(ChatClientRequest request) {
        return request.prompt().getInstructions().stream()
                .filter(m -> m.getMessageType() == MessageType.USER)
                .map(m -> m.getText() == null ? "" : m.getText())
                .reduce("", (a, b) -> a + "\n" + b);
    }

    private ChatClientResponse blockedResponse(ChatClientRequest request, String msg) {
        // 构造一个"假的"模型响应，字段结构与真实响应一致
        AssistantMessage message = new AssistantMessage(msg);
        ChatResponse chatResponse = new ChatResponse(
                List.of(new Generation(message)));
        return ChatClientResponse.builder()
                .chatResponse(chatResponse)
                .context(request.context())
                .build();
    }

    @Override
    public int getOrder() {
        // ★ 必须比其他 Advisor 小，保证最先检查用户输入
        return Ordered.HIGHEST_PRECEDENCE;
    }

    @Override
    public String getName() { return "SafeGuardAdvisor"; }
}

③ 挂载 Advisor

// 全局挂载：所有请求都生效
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(safeGuardAdvisor, tokenUsageAdvisor)
        .build();

// 单次请求挂载：只对这次生效（临时调试很方便）
chatClient.prompt()
        .user("...")
        .advisors(new SimpleLoggerAdvisor())
        .call()
        .content();

// 通过上下文给 Advisor 传参（Advisor 里用 request.context().get("key") 取）
chatClient.prompt()
        .user("...")
        .advisors(a -> a.param("tenantId", "t001"))
        .call()
        .content();

3.7完整示例：订单信息提取服务

把本章能力组装成完整可运行的服务：结构化输出 + 校验 + 重试 + Advisor 治理。

package com.example.springai.ch03.model;

import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import jakarta.validation.constraints.*;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

public record OrderInfo(

    @JsonPropertyDescription("订单号，纯数字字符串，例如 2024001；找不到则返回 null")
    String orderNo,

    @JsonPropertyDescription("客户姓名，不含称谓")
    String customerName,

    @NotNull(message = "金额缺失")
    @DecimalMin(value = "0", message = "金额不能为负")
    @JsonPropertyDescription("订单总金额，只输出数字如 899.00，不带单位")
    BigDecimal amount,

    @Pattern(regexp = "^(未发货|已发货|已完成|已取消)$",
             message = "状态必须是：未发货/已发货/已完成/已取消")
    @JsonPropertyDescription("订单状态，四选一")
    String status,

    @JsonPropertyDescription("下单日期，格式 yyyy-MM-dd；无法确定则 null")
    LocalDate orderDate,

    @JsonPropertyDescription("商品名称列表；没有则返回空数组 []")
    List<String> items,

    @JsonPropertyDescription("联系电话原文，保持原样不做脱敏")
    String phone
) {}

package com.example.springai.ch03;

/** 提取结果包装：让上游知道"这是几次尝试拿到的、可靠性如何" */
public record ExtractResult(OrderInfo data, int attempts, boolean success, String message) {}

@Slf4j
@Service
public class OrderExtractionService {

    private final ChatClient chatClient;
    private final Validator validator;

    public OrderExtractionService(ChatClient chatClient, Validator validator) {
        this.chatClient = chatClient;
        this.validator = validator;
    }

    private static final String TEMPLATE = """
            你是一名订单信息抽取助手。请从下面的文本中提取订单结构。

            抽取规则：
            1. 找不到的字段返回 null（列表返回 []），严禁编造或推测。
            2. 金额只输出数字，不带"元""¥"等符号。
            3. 状态只能从四个值里选，无法判断时返回 null。
            4. 只输出 JSON 对象本身，不要解释、不要代码块标记。

            待抽取文本：
            {input}

            {format}
            """;

    public ExtractResult extract(String input) {
        final int MAX = 3;
        String lastError = null;

        for (int attempt = 1; attempt <= MAX; attempt++) {
            String userText = TEMPLATE
                    .replace("{input}", input)
                    .replace("{format}", "");  // format 由 entity() 自动注入

            if (lastError != null) {
                userText += "\n\n【重要】上次输出有问题：" + lastError + "，请修正。";
            }

            try {
                OrderInfo order = chatClient.prompt()
                        .user(userText)
                        // 抽取类任务：温度必须为 0，追求可复现
                        .options(OpenAiChatOptions.builder().temperature(0.0).build())
                        .call()
                        .entity(OrderInfo.class);

                var violations = validator.validate(order);
                if (violations.isEmpty()) {
                    return new ExtractResult(order, attempt, true, "OK");
                }
                lastError = violations.stream()
                        .map(ConstraintViolation::getMessage)
                        .collect(Collectors.joining("；"));

            } catch (Exception e) {
                // 常见：模型输出了非 JSON（含解释文字 / 代码块包裹）
                lastError = "输出不是合法 JSON（" + e.getClass().getSimpleName() + "）";
                log.warn("第 {} 次提取失败：{}", attempt, lastError);
            }
        }
        // 三次都失败：不抛异常，返回失败标记，让上游走人工/降级流程
        return new ExtractResult(null, MAX, false,
                "自动提取失败，请转人工处理。最后错误：" + lastError);
    }
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderExtractionController {

    private final OrderExtractionService service;

    public OrderExtractionController(OrderExtractionService service) {
        this.service = service;
    }

    @PostMapping("/extract")
    public ExtractResult extract(@RequestBody Map<String, String> body) {
        return service.extract(body.get("text"));
    }
}

验证

curl -X POST http://localhost:8080/api/v1/orders/extract \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，我是张三，订单 2024001 在 3 月 5 日下的单，金额 899 元，买了一个机械键盘和一个鼠标垫，现在还没发货，联系电话 13800008888"}'

# 期望输出（字段名与 record 完全一致）：
# {"data":{"orderNo":"2024001","customerName":"张三","amount":899.00,
#          "status":"未发货","orderDate":"2024-03-05",
#          "items":["机械键盘","鼠标垫"],"phone":"13800008888"},
#  "attempts":1,"success":true,"message":"OK"}

# 故意给一段信息不全的文本，验证"不编造"规则
curl -X POST http://localhost:8080/api/v1/orders/extract \
  -H "Content-Type: application/json" \
  -d '{"text":"帮我看看那个订单发货了没有"}'

# 期望：orderNo/amount 为 null，success=false（因为 amount 有 @NotNull），
#       最终返回"请转人工处理" —— 这正是一个"不瞎编"的正确表现

3.8常见坑排错

3.9自测题