CH 01Spring AI 入门

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

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

为什么必须建立分层心智模型？因为大模型应用的 bug，90% 出在「没搞清楚自己调用的是哪一层」。比如你想换模型，改错了层（去改业务代码）就会事倍功半；你想统一加日志，加错了层（在每处调用里写）就会到处重复。分层图就是用来告诉你：哪些东西该写一次、哪些东西该随场景变、哪些东西永远不用碰。

易混概念对照：ChatModel vs ChatClient

四个必记的核心抽象

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

1.2创建项目与依赖

开始写代码前，要先有一个 Maven 工程。课程提供两种拿到工程的方式：直接用配套 springai-lab，或从零在 Initializr 创建。无论哪种，最终工程里的依赖必须和下面对齐。

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

1. 打开 https://start.spring.io，或 IDEA 的 New Project → Spring Initializr。

2. Project 选 Maven，Language Java，Spring Boot 选 4.1.1（当前默认版），Java 选 17。

3. Group com.example，Artifact springai-lab，Package name com.example.springai。

4. 依赖勾 Spring Web、Lombok（可选，本课程不用），以及 AI 分组里的 OpenAI。 注意：勾「Spring Web」生成出来的坐标是 spring-boot-starter-webmvc —— Boot 4 已把 spring-boot-starter-web 改名（旧名废弃）。

5. 生成后解压到工作目录，用 IDEA 打开 pom.xml。

动手：核对依赖清单（方式二，与配套 lab 一致）

1. 在 IDEA 左侧 Project 面板打开 lab/pom.xml，Ctrl+F 搜索下面四个坐标，确认它们都在文件里：spring-boot-starter-webmvc、spring-boot-starter-validation、spring-ai-starter-model-openai、spring-ai-bom。
2. 确认 spring-ai-bom 在 <dependencyManagement> 段里、与 <dependencies> 平级（不是嵌套在里面）。
3. 确认 没有 spring-boot-starter-web（旧名）——若搜到，说明 Initializr 选成了 Boot 3.x 的写法，要改成 webmvc。

方式二：直接改 pom（本课程采用，与配套 lab 完全一致）

配套 lab/pom.xml 已经是最终形态，下面把最关键的三段抽出来讲。注意第 1 章至少要保证这三个依赖存在：

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

<!-- ★ 参数校验：第 2 章的 @NotBlank 依赖它（Boot 2.3 后 web 不再自带校验）-->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

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

<!-- ★ BOM：统一管理所有 spring-ai-* 的版本，缺了它就要逐个写版本号 -->
<!--   dependencyManagement 是 <project> 直接子元素，和 <dependencies> 平级 -->
<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>

验证依赖是否装配成功

工程打开后，先别急着写代码，先确认依赖真的拉到了。在项目根目录执行：

# 命令行验证 Spring AI 相关依赖树
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

预期输出说明：能看到上面四行、且版本都是 2.0.1，说明 starter 与 BOM 配合正确。如果只看到 spring-ai-bom 而看不到 spring-ai-starter-model-openai，说明 starter 没加进去，回去检查 <dependencies>。

运行验证：先编译一次，确认依赖真的齐了

依赖就位后，先别急着写业务代码——每写完一块就编译一次是本章的纪律。在 lab 工程根目录（pom.xml 所在目录）执行：

mvn -q compile

预期输出：

[INFO] BUILD SUCCESS
[INFO] Total time:  3.456 s

看到什么算通过：最后一行是 BUILD SUCCESS，且没有任何 [ERROR] 或 BUILD FAILURE。如果报 package org.springframework.ai.chat.model does not exist，说明 starter 或 BOM 没配对，回到本节的依赖清单重查。编译通过才继续下一节。

知识卡：starter 与 BOM 到底是什么

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

动手：把配置写进 application.yml

1. 在 IDEA 左侧 Project 面板展开 src → main → resources，找到 application.yml（若不存在，在 resources 目录上右键 → New → File → 输入 application.yml）。
2. 双击打开，Ctrl+A 全选已有内容 → Delete 清空。
3. 把下面这段完整粘贴进去（Ctrl+V），然后 Ctrl+S 保存。
4. 确认 IDEA 没有在 yml 上画红色波浪线——红色说明缩进或层级写错（YAML 对缩进极度敏感，必须用空格、不能用 Tab）。

先写一份第 1 章用的配置：

spring:
  application:
    name: springai-lab
  ai:
    openai:
      # 从环境变量读；冒号后为空表示"没有也要启动"，避免本地没配就起不来
      # ★ 本课程统一约定用 DEEPSEEK_API_KEY 这个环境变量名
      api-key: ${DEEPSEEK_API_KEY:}
      # ★ 换厂商的核心开关：只改这一行 + model，Java 代码一行不动
      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

运行验证：配置能编译、层级正确

光写对还不够，先确认它不报错。在 lab 根目录执行：

mvn -q compile

预期输出：

[INFO] BUILD SUCCESS

看到什么算通过：BUILD SUCCESS 即说明 YAML 层级、缩进、属性名都没问题（真正的连通性要到 1.8 节启动后调接口才验证）。如果报 Failed to bind properties under 'spring.ai.openai' ... 之类，通常是缩进错位，回到上一步检查 ai: 下 openai: 的缩进是否对齐。

知识卡：${DEEPSEEK_API_KEY:} 占位符

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

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

先看「不加任何糖」的写法，这样你才知道 ChatClient 帮你做了什么。为什么先讲底层？因为底层最容易出错也最容易理解——它能让你看清一次对话请求到底由「消息列表」组成。

动手：在 ch01 包创建 ChatModelBasics.java

1. 在 IDEA 左侧 Project 面板，展开 java → com → example → springai。确认能看到 ch01 包（配套 lab 已建好；若没有，在 springai 目录上右键 → New → Package → 输入 com.example.springai.ch01）。
2. 在 ch01 包上右键 → New → Java Class。
3. 在弹出的输入框里精确输入 ChatModelBasics（注意大小写：首字母大写、其余驼峰；不要带 .java 后缀）。回车。
4. IDEA 会自动生成 package com.example.springai.ch01; 和空的类骨架。把下面整段代码全选粘贴覆盖进去（Ctrl+A 再 Ctrl+V），然后 Ctrl+S 保存。

下面这份代码与配套 lab 逐字一致，是本章第一个要落盘的文件：

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 -> getResult() -> getOutput()(AssistantMessage) -> getText()
        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);
    }
}

mvn -q compile

[INFO] BUILD SUCCESS

1.5推荐用法：ChatClient 门面

实际项目里几乎不会直接调 ChatModel，而是用 ChatClient。它把「默认系统提示、默认 Advisor、参数覆盖、结构化输出」都收进了一套流式 API 里。为什么推荐门面？因为它把「每次都要重复写的系统提示、日志 Advisor、异常处理」统一收口——你只关心业务逻辑，重复的脚手架交给它。

动手：在 common 包创建 ChatClientConfig.java

1. 在 Project 面板找到 com.example.springai.common 包（配套 lab 已建好；若没有，在 springai 上右键 → New → Package → 输入 com.example.springai.common）。
2. 在 common 包上右键 → New → Java Class，精确输入 ChatClientConfig，回车。
3. 把下面整段配置代码粘贴覆盖，Ctrl+S 保存。

为什么放 common 包？它是全应用共享的全局配置，必须放在 com.example.springai.common（在主启动类的组件扫描范围内），才能被 Spring 自动发现并注册为 bean。若放在 ch01 之外的未扫描路径，全局 ChatClient 就注入不进来。

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

配套 common/ChatClientConfig.java 与下面逐字一致。注意它比 1.x 旧写法多了一个 @Primary——1.x 那种不区分默认人选的写法已经过时；因为第 2 章会再建一个客服专用 ChatClient，容器里就有两个同类型的 bean，必须有一个被标记为「默认人选」。

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;
import org.springframework.context.annotation.Primary;

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

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

动手：在 ch01 包创建 HelloAiService.java

1. 在 ch01 包上右键 → New → Java Class，精确输入 HelloAiService，回车。
2. 把下面整段 Service 代码粘贴覆盖，Ctrl+S 保存。

运行验证：写完两个文件再编译一次

此时项目里有 ChatModelBasics、ChatClientConfig、HelloAiService 三个类。再编译一次，确认它们能一起通过：

mvn -q compile

预期输出：

[INFO] BUILD SUCCESS

看到什么算通过：BUILD SUCCESS。注意此刻还没写 Controller，应用还不能对外提供接口，但三个类已经能互相注入（编译期就检查了类型匹配）。

第二步：在 Service 里使用 fluent API

配套 ch01/HelloAiService.java。注意构造器注入的是 ChatClient（拿到的就是上面 @Primary 那个全局 bean）。

package com.example.springai.ch01;

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

/**
 * 第 1 章 · 推荐的日常写法：通过 ChatClient 调用。
 * ChatClient 是高层封装：链式 API + 自动带上全局系统提示 + Advisor 链。
 * 业务代码 95% 的情况只面向 ChatClient 写。
 */
@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();
    }
}

知识卡：@Primary 与「多个同类型 bean」

知识卡：ChatClient fluent API 的「链式契约」

ChatClient fluent API 速查

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

非流式的问题：模型生成 500 字要 8 秒，用户盯着白屏 8 秒，体验极差。流式的价值是把首字延迟从 8 秒降到 0.5 秒。为什么用 SSE（Server-Sent Events）？因为它基于 HTTP、天然单向推送、浏览器原生支持 EventSource，比 WebSocket 轻得多——而 AI 回答恰恰只需要「服务端推给前端」，不需要前端回推。

动手：在 ch01 包创建 ChatController.java

1. 在 ch01 包上右键 → New → Java Class，精确输入 ChatController，回车。
2. 把下面整段 Controller 代码粘贴覆盖，Ctrl+S 保存。
3. 重点确认：/stream 那个方法上有 produces = MediaType.TEXT_EVENT_STREAM_VALUE——这是流式能否生效的关键，漏写前端就看不到打字机效果（见下方坑 ①）。

下面是完整代码：

package com.example.springai.ch01;

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

/**
 * 第 1 章 · 对外 HTTP 接口。
 * Controller 只做三件事：接参数 → 调 Service → 返回结果。
 * 不要在 Controller 里写业务逻辑，也不要直接注入 ChatClient。
 */
@RestController
@RequestMapping("/api/v1/chat")
public class ChatController {

    private final HelloAiService service;

    // 构造器注入（推荐）：字段少一个 @Autowired，还便于单元测试时手工构造
    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) {}
}

运行验证：写完 Controller 再编译一次

现在 ch01 包已经有三个类、common 包有一个配置类。编译确认它们整体能通过：

mvn -q compile

预期输出：

[INFO] BUILD SUCCESS

看到什么算通过：BUILD SUCCESS，且 IDEA 里 ChatController 的 @PostMapping 没有红色波浪线。至此全部代码已就位，下一步（1.8 节）就是真正启动应用、调接口验证。

知识卡：SSE 与 produces 的关系

易混概念对照：WebMVC vs WebFlux（跨域写法）

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

// 浏览器端：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);

package com.example.springai.common;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * 全局跨域配置（WebMVC 写法）。
 * 原理：addCorsMappings 注册的规则会在浏览器发 OPTIONS 预检时
 * 自动返回 Access-Control-Allow-Origin 等响应头，预检通过后真正请求才被放行。
 */
@Configuration
public class WebCorsConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")          // 对哪些接口生效
                .allowedOriginPatterns("*")      // 允许哪些来源（课程演示放开，生产要收紧为具体域名）
                .allowedMethods("GET", "POST", "OPTIONS")
                .allowedHeaders("*");
    }
}

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

把前面三块拼起来，第 1 章的包结构如下。这三份文件与 1.4、1.5、1.6 节逐个对应，是本章唯一需要落盘的代码：

运行验证：确认文件都落在正确的包

1. 在 IDEA 的 Project 面板展开 com.example.springai，确认结构如下（包名、文件名一个字都不能差）：
   • common/ChatClientConfig.java
   • ch01/ChatModelBasics.java
   • ch01/HelloAiService.java
   • ch01/ChatController.java
2. 再编译一次兜底：mvn -q compile → BUILD SUCCESS。

看到什么算通过：四个文件都在对应包下、编译通过。文件若建错包（比如 ChatClientConfig 放在 ch01 而非 common），启动时全局 ChatClient 注入会失败——所以这一步的「包名核对」不是走过场。

1.8运行与验证

代码写完，现在让它在本地真正跑起来。第 1 章不需要任何数据库（向量库、记忆库都是后面章节才用），所以直接启动应用即可。

1. 确认环境变量已设好（重开终端后执行）：

   # Windows PowerShell
   echo $env:DEEPSEEK_API_KEY
   # macOS / Linux
   echo $DEEPSEEK_API_KEY
   # 期望：打印出 sk- 开头的 key，而不是空

2. 启动应用（任选其一）：

   # 方式 A：Maven 插件
   mvn spring-boot:run
   
   # 方式 B：IDEA 直接运行 SpringaiLabApplication 的 main 方法

   预期输出：控制台出现 Started SpringaiLabApplication in X.XXX seconds，且没有任何 APPLICATION FAILED TO START。

3. 测试同步接口：

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

   预期输出：一段中文回答，例如「Spring AI 是 Spring 官方提供的大模型应用开发抽象层……」。

4. 测试流式接口（-N 关闭 curl 缓冲，才能看到逐字输出）：

   curl -N -X POST http://localhost:8080/api/v1/chat/stream \
     -H "Content-Type: application/json" \
     -d '{"question":"从 1 数到 10，每个数字换一行"}'

   预期输出：数字一个一个蹦出来，而不是等 8 秒后一次性出现。

Invoke-RestMethod -Uri http://localhost:8080/api/v1/chat/ask `
  -Method Post -ContentType "application/json" `
  -Body '{"question":"用一句话解释 Spring AI"}'

1.9常见坑排错对照表

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

1.11实操作业与本章验收

• 能口头说出 Spring AI 三层抽象（应用/门面/模型/厂商）各自的职责，并在白板上画出 1.1 节的调用时序。
• /ask 与 /stream 两个接口都通过 curl 验证：同步返回完整文本、流式可见逐字输出。
• 能独立把模型从 DeepSeek 切换到通义千问或本地 Ollama，且业务代码零改动。
• 能读懂 getMetadata().getUsage() 里的 Token 数字，说清 promptTokens / completionTokens / totalTokens 含义。

1.12动手清单与自查表（照着核对）

这一节只回答三个问题：本章到底要建哪些文件、怎么一步步确认做对了、卡住时去哪一节的哪张表查。建议每完成一步就回来打个勾——全部过完，第 1 章才算真的跑通，而不是"看着像跑通了"。

① 你要建的文件（建一个，勾一个）

② 分步验收：从零到跑通（每步都有预期输出）

1. 先确认密钥在当前终端可见（不通过就别往下走）：

   # Git Bash / macOS / Linux
   echo $DEEPSEEK_API_KEY
   # PowerShell
   echo $env:DEEPSEEK_API_KEY

   预期：打印出 sk- 开头的一长串。打印为空 → 停下，回第 0 章 0.6 节重设环境变量并重开终端，否则后面必然报"找不到 ChatModel"。

2. 确保 8080 没被占用（不先做这步，第 4 步一定失败）：

   # 推荐：用第 0 章的一键脚本
   powershell -ExecutionPolicy Bypass -File .\stop-app.ps1
   # 或手工查一下有没有 LISTENING
   netstat -ano | findstr :8080

   预期：提示「未被占用」，或列出被清掉的 PID。看到什么算通过：再执行一次 netstat，8080 上已无 LISTENING。

3. 编译（在 pom.xml 所在目录执行）：

   mvn -q compile

   预期：BUILD SUCCESS，且没有任何 [ERROR]。报 package org.springframework.ai... does not exist → 回 1.2 节查依赖，不是代码问题。

4. 启动应用：mvn spring-boot:run，或 IDEA 里直接运行启动类。

   预期：控制台出现 Tomcat started on port 8080 与 Started SpringaiLabApplication in X.XXX seconds，没有 APPLICATION FAILED TO START。

5. 打同步接口（新开一个终端，别把启动的那个关掉）：

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

   预期：首行 HTTP/1.1 200，随后是一段中文回答。

   看到什么算通过：状态码是 200 且回答与问题相关（出现「Spring」「AI」等字样）。若返回 401 / 404 / 400 → 见 1.9 排错表与第 0 章终端差异表。

   PowerShell 用户注意：这句会踩引号坑，先读第 0 章 0.2 节，改用 Apifox 或 Invoke-RestMethod。

6. 打流式接口（验证 SSE 真的通了）：

   curl -N -X POST http://localhost:8080/api/v1/chat/stream \
     -H "Content-Type: application/json" \
     -d '{"question":"从 1 数到 10，每个数字换一行"}'

   预期：数字一个一个蹦出来。

   看到什么算通过：盯着屏幕能看到中间态；若"唰"地一次性全出来，说明少了 -N，或中间有缓冲层。

7. 做一次反例实验（最能检验你是否真懂这一章）：把 application.yml 里 api-key 临时改成空串，重启。

   预期：启动失败，报 Parameter 0 of constructor ... required a bean of type 'ChatModel' that could not be found。

   为什么值得做：这条报错看起来像"依赖没配好"，实际是"密钥为空导致自动配置整体没生效"。亲手制造一次，下次见到就不会往错方向查。实验完记得改回去并重启。

③ 卡住了去哪查（症状 → 定位）