Spring AI 2.0 学习指南
从零到「企业知识问答 + 工单辅助系统」

0.1怎么用这份指南

先明确一条原则：这门课不是「读」出来的，是「跑」出来的。大模型应用开发的特点决定了——你不上手调用一次，永远不知道 API 长什么样；你不亲手把文档灌进向量库，永远理解不了 RAG 为什么检索不到。

0.211 章学习路线

这 11 章不是并列关系，而是层层叠加的：第 1 章拿到「模型能说话」的能力，第 2–3 章把它变成「能按格式说话」，第 4–5 章给它接上「自己的知识」，第 6–8 章给它装上「记忆、工具和外部系统」，第 9 章把它组织成「能自己规划的执行体」，第 10 章保证它「出问题能看得见」，第 11 章把所有东西拼成一个真实系统。

章节依赖关系一览

0.3学时与节奏建议

0.4环境准备（一次性配好，后面 11 章零中断）

这一节是整份指南最容易被跳过、也最不能跳过的部分。请严格按 0.4.1 → 0.4.8 的顺序执行，每一步都有验证命令，验证不通过不要往下走。

0.4.1 JDK 21（2.0 的硬性底线其实是 17）

所以结论是：底线 JDK 17，用 17 运行时完全没问题。 本课程统一用 JDK 21（LTS），这是一个教学选择而非硬性要求，理由有三条： 虚拟线程在 21 已正式化（17 还只是预览）、生态兼容性最稳、IDEA 的静态分析提示更准。 你的团队如果已在用 JDK 25 也完全可以——Spring Boot 4.1.1 支持到 Java 26，AI 场景下虚拟线程的吞吐收益更明显。

1. 下载安装：推荐 Eclipse Temurin 21（https://adoptium.net）或 Oracle JDK 21。
   Windows 选 .msi，安装时勾选 Set JAVA_HOME variable 与 Add to PATH。
2. 验证：

   java -version
   # 期望输出（关键是 21）：
   # openjdk version "21.0.5" 2024-10-15 LTS
   # OpenJDK Runtime Environment Temurin-21.0.5+11 (build 21.0.5+11-LTS)
   
   echo %JAVA_HOME%      # Windows CMD，应指向 JDK 目录（不是 bin，不是 jre）
   echo $JAVA_HOME       # Git Bash / macOS / Linux

3. 为什么课程选 21 而不是 17：
   · 第 9 章 Agent 并行调用多个工具会用 Executors.newVirtualThreadPerTaskExecutor()（JDK 21 才正式化，17 是预览）；
   · 第 3 章结构化输出大量使用 record + 密封接口 + Record Pattern；
   · Spring AI 2.0 全代码库加了 JSpecify 空安全注解，IDEA 的高版本 JDK 对这类静态分析的提示更准。

0.4.2 Maven 3.9+

# 验证
mvn -v
# Apache Maven 3.9.9 (或更高)
# Maven home: D:\dev\apache-maven-3.9.9
# Java version: 21.0.5, vendor: Eclipse Adoptium

接着配置国内镜像，否则拉 Spring AI 依赖会很慢甚至超时。编辑 ~/.m2/settings.xml（没有就新建）：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
  <mirrors>
    <mirror>
      <id>aliyun-central</id>
      <name>Aliyun Public Mirror</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
    <mirror>
      <!-- Spring AI 的里程碑/快照版本需要这条；正式版走 aliyun 即可 -->
      <id>spring-milestones</id>
      <url>https://repo.spring.io/milestone</url>
      <mirrorOf>spring-milestones</mirrorOf>
    </mirror>
  </mirrors>
</settings>

0.4.3 IntelliJ IDEA 与必备插件

0.4.4 Docker 与全套中间件

第 4 章之后要用到 5 个中间件，全部用 Docker 起，不要本机装（本机装 MySQL + PostgreSQL + Redis 是最常见的翻车点）。Windows/macOS 装 Docker Desktop；Linux 装 docker engine + compose 插件。

验证 Docker：

docker version
docker compose version   # 需要 v2，命令是 "docker compose" 而不是 "docker-compose"

在 D:\springai-lab 下创建 docker-compose.yml。这份文件从第 4 章用到第 11 章，请一次配好：

# docker-compose.yml —— Spring AI 课程全套基础设施
services:

  # ---------- 关系型数据库：存业务数据（工单、用户、会话元信息） ----------
  mysql:
    image: mysql:8.4
    container_name: sai-mysql
    ports: ["3306:3306"]
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: springai_lab
      TZ: Asia/Shanghai
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    volumes: ["mysql-data:/var/lib/mysql"]
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-proot123456"]
      interval: 10s
      retries: 10

  # ---------- 缓存：存会话记忆、限流、幂等键 ----------
  redis:
    image: redis:7.4-alpine
    container_name: sai-redis
    ports: ["6379:6379"]
    command: ["redis-server", "--appendonly", "yes", "--requirepass", "redis123456"]
    volumes: ["redis-data:/data"]

  # ---------- 向量数据库方案 A：PostgreSQL + pgvector（轻量，推荐先学这个） ----------
  pgvector:
    image: pgvector/pgvector:pg16
    container_name: sai-pgvector
    ports: ["5432:5432"]
    environment:
      POSTGRES_USER: ai
      POSTGRES_PASSWORD: ai123456
      POSTGRES_DB: vectordb
      TZ: Asia/Shanghai
    volumes:
      - pgvector-data:/var/lib/postgresql/data
      # 首次启动自动执行：创建扩展 + 建表
      - ./init/pgvector-init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  # ---------- 向量数据库方案 B：Milvus 单机版（大规模，第 4/5/11 章用它做对比） ----------
  etcd:
    image: quay.io/coreos/etcd:v3.5.16
    container_name: sai-etcd
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    volumes: ["etcd-data:/etcd"]

  minio:
    image: minio/minio:RELEASE.2024-09-13T20-26-02Z
    container_name: sai-minio
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    command: minio server /minio_data --console-address ":9001"
    ports: ["9000:9000", "9001:9001"]
    volumes: ["minio-data:/minio_data"]

  milvus:
    image: milvusdb/milvus:v2.4.15
    container_name: sai-milvus
    command: ["milvus", "run", "standalone"]
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    ports: ["19530:19530", "9091:9091"]
    depends_on: [etcd, minio]
    volumes: ["milvus-data:/var/lib/milvus"]

  # ---------- 链路追踪后端（第 10 章用来查看 Trace） ----------
  zipkin:
    image: openzipkin/zipkin:3
    container_name: sai-zipkin
    ports: ["9411:9411"]

volumes:
  mysql-data:
  redis-data:
  pgvector-data:
  etcd-data:
  minio-data:
  milvus-data:

创建 pgvector 的初始化脚本 init/pgvector-init.sql：

-- init/pgvector-init.sql
-- 1) 启用向量扩展。没这一步后续建 vector 列会直接报错。
CREATE EXTENSION IF NOT EXISTS vector;

-- 2) 建一张「通用文档向量表」，第 4、5、11 章都复用它。
--    1536 维 = OpenAI text-embedding-3-small 的维度；
--    如果你用 BGE / text-embedding-3-large，要改成 1024 / 3072。
CREATE TABLE IF NOT EXISTS vector_store (
    id        UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
    content   TEXT,
    metadata  JSON,
    embedding VECTOR(1536)
);

-- 3) HNSW 索引：近似最近邻检索，比全表扫描快几个数量级。
--    vector_cosine_ops 对应「余弦距离」，和 Spring AI 默认的 COSINE_DISTANCE 保持一致。
CREATE INDEX IF NOT EXISTS idx_vector_store_hnsw
    ON vector_store USING hnsw (embedding vector_cosine_ops);

启动与验证：

cd D:/springai-lab

# 只起核心服务（推荐配置一般的同学）
docker compose up -d mysql redis pgvector zipkin

# 全部起（含 Milvus）
docker compose up -d

# 看状态，等 STATUS 变成 healthy
docker compose ps

# 逐个连通性验证
docker exec -it sai-mysql mysql -uroot -proot123456 -e "SELECT VERSION();"
docker exec -it sai-redis redis-cli -a redis123456 ping        # 期望 PONG
docker exec -it sai-pgvector psql -U ai -d vectordb -c "\dx"    # 应看到 vector 扩展
curl http://localhost:9411/health                               # Zipkin

0.4.5 大模型服务与密钥

你需要至少一个可用的模型服务。Spring AI 的一大优势是「同一套 API 换模型只改配置」，所以课程里我们会同时配好两三个，用来演示第 6 章的多模型路由。三条路线任选：

方案一：云端 API（以 DeepSeek + 通义千问为例，均兼容 OpenAI 协议）

设置环境变量。Windows 用 PowerShell（永久生效）：

# 用户级环境变量，重启终端后生效
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-你的DeepSeek密钥", "User")
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "sk-你的通义密钥", "User")

# 验证（重开一个终端窗口）
echo $env:OPENAI_API_KEY

macOS / Linux（写入 ~/.zshrc 或 ~/.bashrc，然后 source）：

echo 'export OPENAI_API_KEY="sk-你的DeepSeek密钥"' >> ~/.zshrc
echo 'export DASHSCOPE_API_KEY="sk-你的通义密钥"' >> ~/.zshrc
source ~/.zshrc
echo $OPENAI_API_KEY

方案二：Ollama 本地模型

# 1. 安装：https://ollama.com/download ，装完验证
ollama --version

# 2. 拉取模型（按需，注意磁盘占用）
ollama pull qwen2.5:7b            # 通用对话，约 4.7GB
ollama pull llama3.1:8b           # 备选
ollama pull nomic-embed-text      # 向量模型，约 274MB —— 第 4 章要用！

# 3. 验证服务可用
curl http://localhost:11434/api/tags

# 4. 命令行试聊一句
ollama run qwen2.5:7b "用一句话解释什么是向量数据库"

0.4.6 创建项目骨架

用 Spring Initializr 生成，或直接手写 pom.xml。课程统一一个工程，11 章用不同的包名分目录：

0.4.7 一份可以直接用的 pom.xml

这是整个课程通用的依赖清单。你不用一次全打开，注释里标了「第 N 章」的可以到那一章再取消注释——但建议直接全部保留，Maven 会一次性把依赖下好，避免后面反复等下载。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>      <!-- 以 start.spring.io 当前稳定版为准 -->
    <relativePath/>
  </parent>

  <groupId>com.example</groupId>
  <artifactId>springai-lab</artifactId>
  <version>1.0.0</version>
  <name>springai-lab</name>

  <properties>
    <java.version>21</java.version>
    <!-- ★ 版本变量：升级 Spring AI 只改这一行 -->
    <spring-ai.version>2.0.1</spring-ai.version>
  </properties>

  <dependencies>

    <!-- ========== 基础 Web / 工具 ========== -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>  <!-- 第3章：输出校验 -->
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>

    <!-- ========== 第 1 章：核心 + 模型接入 ========== -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-model-openai</artifactId>   <!-- OpenAI 及所有兼容协议 -->
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-model-ollama</artifactId>   <!-- 第6章：本地模型做路由/降级 -->
    </dependency>

    <!-- ========== 第 2、6 章：会话记忆持久化 ========== -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>
    <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-redis</artifactId>  <!-- 第6章：Redis 存记忆 -->
    </dependency>

    <!-- ========== 第 4、5 章：向量库（两种方案，二选一或都留） ========== -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-vector-store-milvus</artifactId>
    </dependency>

    <!-- ========== 第 5 章：RAG 用的 Advisor + 文档解析 ========== -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-vector-store-advisor</artifactId>  <!-- QuestionAnswerAdvisor 等 -->
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-tika-document-reader</artifactId>   <!-- 读 PDF/Word/HTML/PPT -->
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-markdown-document-reader</artifactId>
    </dependency>

    <!-- ========== 第 8 章：MCP（2.0 起 MCP Java SDK 已升到 1.0.x 线） ========== -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-mcp-client</artifactId>     <!-- 作为 MCP 客户端（Host 侧） -->
    </dependency>
    <dependency>
      <!-- 把自己的能力暴露成 MCP Server：WebMVC 版本即可，无需额外引 transport -->
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    </dependency>

    <!-- ========== 2.0 新增：工具很多时用它做渐进式披露（第 7 章） ========== -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-tool-search-advisor</artifactId>
      <!-- 工具数 < 15 时不需要它；接了很多 MCP Server 再打开，能省 34%~64% token -->
    </dependency>

    <!-- ========== 第 10 章：可观测性 ========== -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-tracing-bridge-otel</artifactId>
    </dependency>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-exporter-zipkin</artifactId>
    </dependency>
    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>

    <!-- ========== 测试 ========== -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-spring-boot-testcontainers</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <dependencyManagement>
    <dependencies>
      <!-- ★ 关键：导入 BOM 后，上面所有 spring-ai-* 依赖都不用写版本号 -->
      <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-bom</artifactId>
        <version>${spring-ai.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <release>21</release>
          <annotationProcessorPaths>
            <path>
              <groupId>org.projectlombok</groupId>
              <artifactId>lombok</artifactId>
            </path>
          </annotationProcessorPaths>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

0.4.8 基础 application.yml（第 1–3 章就能跑）

# ============ src/main/resources/application.yml ============
spring:
  application:
    name: springai-lab

  # ---------- 模型：OpenAI 及其兼容协议（DeepSeek / 通义 / Kimi / Groq…） ----------
  ai:
    openai:
      # 密钥从环境变量读取，冒号后是「取不到时的默认空值」，防止未配置时启动直接崩
      api-key: ${OPENAI_API_KEY:}
      # ★ 换厂商只改这一行：DeepSeek=https://api.deepseek.com
      #   通义兼容模式=https://dashscope.aliyuncs.com/compatible-mode
      base-url: https://api.deepseek.com
      chat:
        # ★ 2.0 注意：chat 这层仍然保留 options，只有 embedding/image/audio 等去掉了它
        options:
          model: deepseek-chat          # 通义填 qwen-plus；OpenAI 填 gpt-4o-mini
          temperature: 0.7              # 0=最确定，1=最发散；做结构化输出时建议 0.1~0.3
          max-tokens: 2048
        # 连接超时 / 读取超时，官方接口偶尔抖动，给足余量
        connect-timeout: 30000
        read-timeout: 120000
      embedding:
        # ★★ 2.0 破坏性变更：这里不再有 options 这一层，直接就是 model
        #    1.x 写法：spring.ai.openai.embedding.options.model
        #    2.0 写法：spring.ai.openai.embedding.model
        model: text-embedding-3-small # 第 4 章用；DeepSeek 暂无 embedding，需换厂商或本地模型

    # ---------- 本地模型（第 6 章路由/降级；第 4 章向量化） ----------
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:7b
      embedding:
        model: nomic-embed-text      # 同样去掉了 options 层
      init:
        pull-model-strategy: never     # 不要自动拉模型，否则启动会卡很久

    # ---------- ★ 2.0 自动化工具调用循环（第 7、9 章重点） ----------
    chat:
      client:
        tool-calling:
          # 默认 true：ChatClient 会自动注册 ToolCallingAdvisor 处理工具调用循环。
          # 想做"用户控制的循环"（Agent 场景），把它设成 false，或单次调用时用
          # AdvisorParams.toolCallingAdvisorAutoRegister(false) 关掉。
          enabled: true
          # 自动注册的 ToolCallingAdvisor 在链中的位置，默认 HIGHEST_PRECEDENCE + 300。
          # 想让某个 Advisor 在"每次工具迭代"里都执行，就把它的 order 设得比这个大。
          # advisor-order: 100
        tool-search-advisor:
          # 工具超过 15 个（尤其接了很多 MCP Server）时打开：渐进式工具披露，
          # 模型用内置 toolSearchTool 按需检索工具，官方实测省 34%~64% token。
          enabled: false
          # 索引类型：regex（默认，零依赖）/ lucene（需 lucene-core）/ vector（需 VectorStore）
          tool-index-type: regex

    # ---------- 工具调用保护（2.0 新增，默认值见注释） ----------
    tools:
      limits:
        max-calls-per-tool-default: 40    # 单个工具每轮最多调用次数，-1 关闭
        max-total-tool-calls: 150         # 所有工具合计上限，防止失控循环烧钱
        on-limit-exceeded: THROW          # 或 RETURN_ERROR_RESPONSE（把错误当结果回给模型）
      resolution:
        fallback:
          # 2.0 默认 false：只有本次请求显式附带的工具才允许执行。
          # 打开它意味着"模型报出任何工具名都能执行"，会放大越权风险，生产建议保持 false。
          enabled: false

  # ---------- MySQL：业务数据 ----------
  datasource:
    url: jdbc:mysql://localhost:3306/springai_lab?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false
    username: root
    password: root123456
    driver-class-name: com.mysql.cj.jdbc.Driver

  # ---------- Redis：会话缓存 ----------
  data:
    redis:
      host: localhost
      port: 6379
      password: redis123456

server:
  port: 8080

# ---------- 日志：把 Spring AI 的请求/响应体打出来，调试必备 ----------
logging:
  level:
    root: info
    com.example.springai: debug
    # 想要看到发给模型的完整 JSON（Prompt 和原始返回），把这个打开：
    org.springframework.ai: debug
    # 只看 Advisor 链（含工具调用循环的每次迭代），比全开更清爽：
    org.springframework.ai.chat.client.advisor: debug
    # 想看 HTTP 层面的报文（含请求头、耗时），打开这两个：
    org.springframework.web.client.RestClient: debug
    reactor.netty.http.client: debug

0.4.9 环境验证 Checklist（务必逐条打勾再进第 1 章）

第 11 项——不写一行 Java 直接验证模型是否可用（这一步能帮你把「网络问题」和「代码问题」彻底分开）：

# Windows Git Bash / macOS / Linux
curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role":"user","content":"用一句话说明你是什么模型"}],
    "stream": false
  }'

# 期望：返回 JSON，choices[0].message.content 是一句人话
# 如果返回 401 → 密钥错；404 → base-url 或路径错；超时 → 网络/代理问题

用一个真实的最小集成测试代替「感觉装好了」——这是课程要求的第一个可交付验证：

// src/test/java/com/example/springai/SmokeTest.java
@SpringBootTest
class SmokeTest {

    @Autowired
    // ChatModel 是 Spring AI 最底层、最核心的接口（第 1 章详解）
    ChatModel chatModel;

    @Test
    void 模型应该能正常返回内容() {
        // 注意：必须显式传 key，最后一个参数是 conversationId
        String result = chatModel.call("你好，请回复四个字：环境就绪");
        System.out.println("模型返回：" + result);
        assertThat(result).isNotBlank();
    }
}

开始学习

环境就绪后，按顺序点开下面 11 个章节。每章结尾都有「自测题」和「下一章」按钮。