FDE W7D1 学习手册 · Spring AI 基础（ChatClient、Advisor、Structured Output）

W7 周级拆解 Day1 · A 级（必须掌握，面试核心）· 约 4h · 学完能讲清"Java 侧如何用 Spring AI 统一多模型、做拦截治理、并稳定拿到结构化对象"

一、ChatClient：统一对话入口

1.1 是什么

ChatClient 是 Spring AI 面向应用层的统一对话入口，封装了底层各种模型的 ChatModel 实现（如 QwenChatModel、DeepSeekChatModel、AnthropicChatModel）。业务代码只面向 ChatClient 编程，不直接依赖具体厂商 SDK。

1.2 核心能力

• Prompt 构建：支持 UserMessage / SystemMessage / AssistantMessage / Message 多角色；支持 PromptTemplate 占位符渲染。
• 流式 / 非流式：call() 一次拿到完整结果；stream() 返回 Flux<String> 做打字机效果。
• 链式调用：chatClient.prompt().system(...).user(...).call().content() 流畅 API。
• Advisor 链：调用前后经过 Advisor 拦截（见 s4）。
• 结构化输出：.entity(MyClass.class) 直接拿到 Java 对象（见 s7）。

二、ChatClient 核心 API 与构建

2.1 构建方式

@Bean
public ChatClient chatClient(ChatModel chatModel) {
    return ChatClient.builder(chatModel)
            .defaultSystem("你是医疗保险理赔助手，回答需基于知识库")
            .defaultAdvisors(new LoggingAdvisor(), new RetryAdvisor())
            .build();
}

2.2 调用方式

// 非流式，拿文本
String ans = chatClient.prompt()
        .user("特药理赔需要哪些材料？")
        .call()
        .content();

// 流式
Flux<String> flux = chatClient.prompt()
        .user("解释等待期")
        .stream()
        .content();

// 直接拿结构化对象
ClaimDecision d = chatClient.prompt()
        .user(u -> u.text("判断该理赔是否成立：{0}", claimJson))
        .call()
        .entity(ClaimDecision.class);

2.3 关键方法对照

三、ChatClient 如何统一多模型（Qwen / DeepSeek / Claude）

3.1 靠 ChatModel 抽象 + 自动装配

Spring AI 为每个厂商提供了 ChatModel 实现，并通过 Spring Boot 的 spring-ai-starter-model-* 自动装配。只要换配置（或换 bean），ChatClient 背后就换了模型。

# application.yml 仅改 provider 和 key，业务代码不动
spring:
  ai:
    qwen:
      api-key: ${QWEN_KEY}
      chat.options.model: qwen-max
    # 切换 DeepSeek 时换成 spring.ai.deepseek.*

3.2 多模型路由的两种落地

• 配置切换：一套代码，靠 profile / 环境变量决定注入哪个 ChatModel。适合"测试用便宜模型、生产用强模型"。
• 运行时多 bean + 路由：同时注入多个 ChatModel，上层按场景选（如简单问答走 Qwen、复杂推理走 DeepSeek、长文摘要走 Claude）。这正是 W7D4 AI Gateway 路由要干的事，Spring AI 在应用层、Gateway 在接入层。

四、Advisor：拦截器链（类比 Servlet Filter）

4.1 是什么

Advisor 是 Spring AI 在 ChatClient 调用前后插入的拦截器，概念上完全类比 Servlet Filter / Spring 的 HandlerInterceptor：围绕一次对话请求做横切处理（日志、重试、限流、改写、记忆）。

4.2 执行模型

• around 模式：Advisor 拿到 AdvisedRequest，可改 prompt、加上下文，再 adviseCall/adviseStream 放行到下一环。
• order 控制顺序：@Order 或实现 getOrder()，数字小先执行。
• 可观测点：在 Advisor 里埋 Trace / Metrics 最自然（呼应 W4、W7D3）。

五、内置 Advisor（日志 / 重试 / 限流 / 提示改写）

5.1 常用内置

5.2 重试 Advisor 示例

@Bean
public Advisor retryAdvisor() {
    return new RetryAdvisor(3, Duration.ofSeconds(1)); // 最多3次，间隔1s
}

六、自定义 Advisor（实现 + 顺序）

6.1 实现方式

public class AuditAdvisor implements Advisor {
    private final MeterRegistry meter;
    public AuditAdvisor(MeterRegistry meter){ this.meter = meter; }
    @Override public int getOrder(){ return 1; } // 越早就越靠近入口
    @Override
    public AdvisedResponse adviseCall(AdvisedRequest req, CallAdvisorChain chain) {
        long t0 = System.nanoTime();
        AdvisedResponse resp = chain.nextAroundCall(req); // 放行
        meter.timer("ai.call").record(System.nanoTime()-t0, TimeUnit.NANOSECONDS);
        return resp;
    }
    // adviseStream 类似，注意流式要透传 Flux
}

6.2 注册

通过 ChatClient.builder().defaultAdvisors(auditAdvisor, retryAdvisor) 注册全局 Advisor，或在单次调用 .advisors(...) 临时叠加。

七、Structured Output 原理（输出绑定 Java 对象）

7.1 是什么

Structured Output 让模型返回的内容自动绑定成 Java 对象，底层靠 JSON Schema 约束 + 解析。Spring AI 用 BeanOutputConverter / StructuredOutputConverter 把 Java 类型信息翻译成 JSON Schema 注入 prompt 或 response_format，再把响应解析回对象。

7.2 与 W1 结构化输出的关系

• W1 我们手动 response_format=json + Pydantic 校验（Python 侧）。
• Spring AI 在 Java 侧用 Jackson + 反射自动生成 schema、自动解析，省去手写 JSON parse 和校验样板。
• 本质一致：仍依赖模型"输出合规 JSON"，解析失败仍需重试/降级。

八、用 BeanOutputConverter / entity() 实现结构化输出

8.1 定义 Bean + 描述

@JsonClassDescription("特药理赔审核结论")
public class ClaimDecision {
    @JsonPropertyDescription("理赔是否成立") boolean approved;
    @JsonPropertyDescription("拒赔原因，成立时为空") String rejectReason;
    @JsonPropertyDescription("风险等级 low/medium/high") String riskLevel;
    @JsonPropertyDescription("引用的知识库条款 id 列表") List<String> clauseIds;
    @JsonPropertyDescription("无法判断时为 true") boolean shouldRefuse;
}

8.2 调用

ClaimDecision d = chatClient.prompt()
        .user(u -> u.text("根据以下理赔材料给出结论：\n{claim}", claim))
        .call()
        .entity(ClaimDecision.class); // 内部用 BeanOutputConverter

// 或显式拿 converter
BeanOutputConverter<ClaimDecision> conv = new BeanOutputConverter<>(ClaimDecision.class);
String schema = conv.getJsonSchema();
Prompt p = new Prompt("按 schema 输出：" + schema + "\n材料：" + claim);
ClaimDecision d2 = conv.convert(chatClient.prompt().user(p.contents()).call().content());

8.3 校验增强

叠加 Bean Validation：validator.validate(d) 校验 @NotNull / 枚举 / 范围，失败则带反馈重试（同 W1 思路）。

九、与 W1 自研 Model Adapter 的对比（框架级 vs 轻量网关）

十、候选人视角：Java 企业 AI 平台能力定位

作为 36 岁、Java + 大数据 + 医疗保险背景的候选人，讲 Spring AI 时要落到企业 AI 平台工程能力，而非"会用 API"：

• 统一接入：用 ChatClient 把医保/保险场景的多个模型（Qwen 做意图识别、DeepSeek 做理赔推理、Claude 做长保单摘要）统一编排。
• 治理内建：把审计、限流、重试、脱敏做成平台级 Advisor，新 Agent 自动继承。
• 结构化兜底：理赔结论、特药适配结果一律 entity(Class) + Bean Validation + 降级，保证下游 Java 系统能稳定消费。
• 可观测：在 Advisor 里埋 Trace（trace_id / model / token / 延迟），对接现有大数据监控（呼应 W4、W7D3）。

十一、学习资源（中文 / 官方）

• B站：Spring AI 全套 84 集（BV1GfyGBqEm6）——系统视频，建议先看"ChatClient 入门""Advisor""结构化输出"几集。
• Spring AI 官方文档（docs.spring.io/spring-ai/reference/）——api/chatclient.html（ChatClient）、api/advisors.html（Advisor）、api/structured-output.html（Structured Output）三章精读。
• Spring AI GitHub samples（spring-projects/spring-ai）——含 chat / advisor / structured-output 可运行示例。

十二、面试达标线①：ChatClient / Advisor / Structured Output 各自作用

十三、面试达标线②：Spring AI 怎么统一多模型、与 W1 自研 Adapter 取舍

1. 统一多模型：业务只写 ChatClient；换模型改 spring.ai.*.api-key/model 配置或注入不同 ChatModel bean，业务零改动；运行时可注入多个 ChatModel 做场景路由。
2. 与 W1 取舍：W1 自研 Adapter 是薄网关、可控性最高，适合做企业 Gateway（限流/成本/审计跨业务线）；Spring AI 是厚框架、开发快，适合业务侧快速搭 AI 能力。两者分层互补：Gateway 在接入层、Spring AI 在应用层，不是二选一。
3. 易踩坑：厂商特有参数要透传、换模型后结构化成功率要重测、统一不等于一个 prompt 通吃。

十四、W7D1 自测清单

十五、高频面试题速记卡