CH 01Spring AI 入门

1.1先建立心智模型：Spring AI 的三层抽象

新手最容易犯的错，是把 Spring AI 当成「一个 HTTP 客户端」。它不是。它是一套把不同厂商大模型的能力抹平成统一接口的抽象层。理解下面这张分层图，你后面 10 章都不会迷路。

四个必记的核心抽象

完整调用时序（建议对照代码看三遍）

1.2创建项目与依赖

方式一：IDEA / start.spring.io 生成（推荐新手）

1. 打开 https://start.spring.io，或 IDEA 的 New Project → Spring Initializr。
2. Project 选 Maven，Language Java，Spring Boot 选 4.1.1（当前默认版）。
3. Group com.example，Artifact springai-lab，JDK 选 21（最低 17）。
4. 依赖勾 Spring Web、Lombok，以及 AI 分组里的 OpenAI。 注意：勾「Spring Web」生成出来的坐标是 spring-boot-starter-webmvc —— Boot 4 已把 spring-boot-starter-web 改名（旧名废弃）。
5. 生成后解压到工作根目录 D:\springai-lab（见 0.4 节的目录约定；放别处也行，后续命令里的路径按实际替换），用 IDEA 打开 pom.xml。

方式二：直接改 pom（本课程采用）

只需在 0.4.7 节的完整 pom 基础上，第 1 章至少要保证下面三个依赖存在：

<!-- Web：提供 HTTP 接口 -->
<!-- ★ 注意是 starter-**webmvc**，不是 3.x 教程里的 starter-web：-->
<!--   Spring Boot 4 已废弃旧名。写成旧名不会报错，但迟早被移除，-->
<!--   详见 index.html 0.4.7 节的完整说明。-->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

<!-- ★ Spring AI 的核心模型接入：OpenAI 协议及其所有兼容实现 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

<!-- ★ BOM：统一管理所有 spring-ai-* 的版本，缺了它就要逐个写版本号 -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

验证依赖是否装配成功

# 命令行验证（在项目根目录）
mvn -q dependency:tree -Dincludes=org.springframework.ai

# 期望能看到类似：
# org.springframework.ai:spring-ai-starter-model-openai:jar:2.0.1
# org.springframework.ai:spring-ai-model:jar:2.0.1
# org.springframework.ai:spring-ai-client-chat:jar:2.0.1
# org.springframework.ai:spring-ai-openai:jar:2.0.1

1.3模型连接配置（换厂商对照表）

先写一份第 1 章用的 application.yml：

spring:
  application:
    name: springai-lab
  ai:
    openai:
      # 从环境变量读；冒号后为空表示"没有也要启动"，避免本地没配就起不来
      api-key: ${OPENAI_API_KEY:}
      # ★ 换厂商的核心开关
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7
          max-tokens: 2048
        # 超时设置：大模型首字延迟经常 2~10 秒，读超时要给足
        connect-timeout: 30s
        read-timeout: 120s

server:
  port: 8080

logging:
  level:
    com.example.springai: debug
    # 打开后能看到发给模型的完整请求体，调提示词时必开
    org.springframework.ai.chat.client: debug

常见厂商配置对照表（可直接抄）

1.4最底层调用：直接使用 ChatModel

先看「不加任何糖」的写法，这样你才知道 ChatClient 帮你做了什么。新建 ch01/ChatModelBasics.java：

package com.example.springai.ch01;

import org.springframework.ai.chat.messages.SystemMessage;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.stereotype.Component;

import java.util.List;

/**
 * 第 1 章 · 最底层的调用方式：只用 ChatModel 接口。
 * 目的：看清一次对话请求到底由哪些部分组成。
 */
@Component
public class ChatModelBasics {

    // 构造器注入。这个 bean 由 spring-ai-starter-model-openai 自动装配，
    // 类型实际是 OpenAiChatModel，但我们只依赖抽象接口，方便日后替换/测试打桩。
    private final ChatModel chatModel;

    public ChatModelBasics(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    /**
     * 最简单的调用：只传一句用户话。
     * 内部会自动包成一个只含 UserMessage 的 Prompt。
     */
    public String simple(String userText) {
        // call(String) 是 ChatModel 的便捷方法，等价于 new Prompt(userText)
        return chatModel.call(userText);
    }

    /**
     * 带系统提示 + 用户消息的标准写法。
     * 这是理解"消息列表"最直观的例子。
     */
    public String withSystemPrompt(String userText) {
        // SystemMessage：设定角色与规则，模型会当作最高优先级的背景指令
        SystemMessage system = new SystemMessage(
                "你是一名严谨的企业知识库助手，回答必须简洁，不确定时明确说不知道，禁止编造。");
        // UserMessage：用户这一轮真正说的话
        UserMessage user = new UserMessage(userText);

        // Prompt 的本质 = 有序的消息列表（+ 可选的模型参数）
        Prompt prompt = new Prompt(List.of(system, user));

        // call 返回的是 ChatResponse，里面不止有文本，还有元数据
        ChatResponse response = chatModel.call(prompt);

        // 逐层取值：response -> generation -> output(AssistantMessage) -> text
        return response.getResult().getOutput().getText();
    }

    /**
     * 取出本次调用的元数据：用了哪个模型、消耗多少 Token。
     * 第 10 章做成本统计时就用这里的数字。
     */
    public String inspectMetadata(String userText) {
        ChatResponse response = chatModel.call(new Prompt(userText));

        String text = response.getResult().getOutput().getText();
        // Usage 里含 promptTokens / completionTokens / totalTokens
        var usage = response.getMetadata().getUsage();
        // 模型名（如 deepseek-chat / gpt-4o-mini）
        String model = response.getMetadata().getModel();

        return """
                模型：%s
                输入Token：%s  输出Token：%s  合计：%s
                回答：%s
                """.formatted(model,
                        usage.getPromptTokens(), usage.getCompletionTokens(),
                        usage.getTotalTokens(), text);
    }
}

1.5推荐用法：ChatClient 门面

实际项目里几乎不会直接调 ChatModel，而是用 ChatClient。它把「默认系统提示、默认 Advisor、参数覆盖、结构化输出」都收进了一套流式 API 里。

第一步：把 ChatClient 做成一等公民（配置类）

package com.example.springai.common;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 全局 ChatClient 配置。
 * 为什么不直接在 Service 里 new？—— 因为默认系统提示、默认 Advisor 应该全应用统一。
 * 注意：容器里已经有一个 ChatClient.Builder（Spring AI 自动装配），
 * 我们注入它再 build，比自己 new Builder 更省事。
 */
@Configuration
public class ChatClientConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                // 全局默认角色设定：所有请求都会自动带上（可在单次调用时覆盖）
                .defaultSystem("""
                        你是"智汇企业助手"，服务于公司内部员工。
                        规则：
                        1. 用简体中文回答，语气专业但不啰嗦。
                        2. 不确定的信息必须说明"我需要更多信息"，禁止编造。
                        3. 涉及金额、日期、人名时，严格使用原文给出的数据。
                        """)
                // 默认 Advisor：打印每次请求/响应，调试期必开（第 3 章会写自定义的）
                .defaultAdvisors(new SimpleLoggerAdvisor())
                // 不在这里写 defaultOptions，留给各场景按需覆盖
                .build();
    }
}

第二步：在 Service 里使用 fluent API

package com.example.springai.ch01;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Flux;

@Service
public class HelloAiService {

    private final ChatClient chatClient;

    public HelloAiService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    /** 最小可用：一句话进，一句话出 */
    public String ask(String question) {
        return chatClient.prompt()      // ① 开启一次请求构建
                .user(question)         // ② 设置用户消息（也可 .system(...) 覆盖默认）
                .call()                 // ③ 同步执行：阻塞等待完整结果
                .content();             // ④ 取出纯文本内容
    }

    /** 流式：一个字一个字往回推，前端体验好，适合聊天框 */
    public Flux<String> askStream(String question) {
        return chatClient.prompt()
                .user(question)
                .stream()               // ③' 换成 stream()，返回 Flux<String>
                .content();
    }

    /** 想看完整响应对象（含 Token 用量），用 chatResponse() 而不是 content() */
    public String askWithUsage(String question) {
        var response = chatClient.prompt()
                .user(question)
                .call()
                .chatResponse();        // ④' 拿到 ChatResponse
        var usage = response.getMetadata().getUsage();
        return "用量：" + usage.getTotalTokens() + " tokens\n"
                + response.getResult().getOutput().getText();
    }
}

ChatClient fluent API 速查

1.6流式输出（SSE）—— 让前端"打字机"效果

非流式的问题：模型生成 500 字要 8 秒，用户盯着白屏 8 秒，体验极差。流式的价值是把首字延迟从 8 秒降到 0.5 秒。

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("/api/v1/chat")
public class ChatController {

    private final HelloAiService service;

    public ChatController(HelloAiService service) {
        this.service = service;
    }

    /** 同步：适合后台任务、脚本调用 */
    @PostMapping("/ask")
    public String ask(@RequestBody AskRequest req) {
        return service.ask(req.question());
    }

    /**
     * 流式：produces 必须是 text/event-stream（SSE 协议），
     * 前端用 EventSource 或 fetch + ReadableStream 接收。
     */
    @PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestBody AskRequest req) {
        return service.askStream(req.question());
    }

    /** 用 record 接收请求体，比 Map 更安全 */
    public record AskRequest(String question) {}
}

前端怎么接（可以直接贴进浏览器控制台验证）：

// 浏览器端：fetch + 流式读取（比 EventSource 更灵活，因为要 POST）
const res = await fetch('http://localhost:8080/api/v1/chat/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ question: '用三句话介绍 Spring AI' })
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let full = '';
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  // SSE 每行形如 "data:xxx\n\n"，这里做最简解析
  const chunk = decoder.decode(value, { stream: true });
  chunk.split('\n').forEach(line => {
    if (line.startsWith('data:')) {
      full += line.slice(5);
      document.title = full.slice(-30);   // 快速验证：看标签页标题在变
    }
  });
}
console.log(full);

1.7完整可运行示例：Hello AI 服务

还差一个统一异常处理——模型调用是最容易抛异常的地方（超时、限流、余额不足），不兜住会把 500 堆栈直接暴露给前端：

package com.example.springai.common;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.client.ResourceAccessException;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

    /** 网络层：连不上 / 读超时。99% 是网络或 base-url 写错 */
    @ExceptionHandler(ResourceAccessException.class)
    public ResponseEntity<Map<String, Object>> onNetwork(ResourceAccessException e) {
        return ResponseEntity.status(HttpStatus.GATEWAY_TIMEOUT)
                .body(Map.of("code", 504,
                             "message", "模型服务不可达，请检查网络或 base-url 配置",
                             "detail", e.getMessage()));
    }

    /** 业务层：模型返回了错误码（401 密钥错、429 限流、402 余额不足） */
    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<Map<String, Object>> onRuntime(RuntimeException e) {
        // 生产环境应打日志 + 上报，不要把原始堆栈返回给前端
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Map.of("code", 500,
                             "message", "AI 服务调用失败：" + e.getMessage()));
    }
}

1.8运行与验证

# 1) 起数据库（本章其实还用不到，但保持习惯）
cd D:/springai-lab && docker compose up -d mysql redis pgvector

# 2) 起应用
mvn spring-boot:run
# 或者 IDEA 里运行 SpringAiLabApplication

# 3) 同步接口
curl -X POST http://localhost:8080/api/v1/chat/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"用一句话解释 Spring AI 是什么"}'

# 期望输出：一段中文回答

# 4) 流式接口（-N 关闭 curl 缓冲，才能看到逐字输出）
curl -N -X POST http://localhost:8080/api/v1/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"question":"从 1 数到 10，每个数字换一行"}'

1.9常见坑排错对照表

1.10自测题（先自己想，再点开）