CH 04嵌入模型与向量数据库

4.1Embedding 到底在做什么：从「关键词匹配」到「语义匹配」

先看一个经典问题。用户问：「怎么把钱退回来？」 而你的知识库里写的是：「退款申请流程说明」。这两句话没有一个字相同，用传统的关键词检索（MySQL 的 LIKE '%退款%' 或 Elasticsearch 的倒排索引）都匹配不到。但人一眼就知道它们讲的是同一件事。

Embedding（嵌入）就是把这种「人知道但机器不知道」的语义关系，变成机器能算的数字关系：

为什么这决定了 RAG 的上限

第 5 章的 RAG 效果好不好，80% 取决于本节这一步。检索错了，后面的大模型再强也只能基于错误的资料胡说八道。所以本章不是「预备知识」，而是整个 RAG 的地基。

4.2向量模型选型与维度对照

4.3相似度算法与索引类型

三种距离度量

索引类型：为什么需要它

假设库里有 100 万条向量。用户查询一次，要对 100 万条逐一算余弦距离——这叫暴力检索（Flat / 精确检索），准确率 100% 但慢得无法接受。

近似最近邻（ANN）索引通过牺牲一点点召回率，把复杂度从 O(n) 降到接近 O(log n)：

4.4EmbeddingModel：把文本变成数字的 API

上一节讲的是「为什么」，这一节动手写出第一段真正可调用的嵌入代码。Spring AI 把各家嵌入模型统一抽象成 EmbeddingModel 接口——你写一遍代码，换供应商只改 yml，不用改 Java。

① 新建包与类（IDEA 手把手）

1. 在 IDEA 左侧 Project 视图，展开 src/main/java → com.example.springai。在 springai 包上右键 → New → Package，输入 ch04，回车（得到 com.example.springai.ch04）。

2. 在 ch04 包上右键 → New → Java Class，名字填 EmbeddingDemoService，回车。

3. 把下面这段「标准答案」整段粘贴进 EmbeddingDemoService.java，Ctrl + S 保存（下面的代码语义不要改，它就是本章的标准答案）：

   import org.springframework.ai.embedding.EmbeddingModel;
   import org.springframework.ai.embedding.EmbeddingResponse;
   
   @Service
   public class EmbeddingDemoService {
   
       private final EmbeddingModel embeddingModel;
   
       public EmbeddingDemoService(EmbeddingModel embeddingModel) {
           this.embeddingModel = embeddingModel;
       }
   
       /** ① 单条文本 → float[] */
       public float[] embedOne(String text) {
           float[] vector = embeddingModel.embed(text);
           System.out.println("维度 = " + vector.length);   // 1536 / 1024 / 768 …
           return vector;
       }
   
       /** ② 批量 → 一次网络往返处理多条，比循环单条快得多（务必用这个） */
       public EmbeddingResponse embedBatch(List<String> texts) {
           // 注意：多数厂商单次批量上限为 10~100 条，超了要自己分片
           return embeddingModel.embedForResponse(texts);
       }
   
       /**
        * ③ 手写一个"语义相似度比较器"，用来验证向量到底有没有用。
        * 这是本章最重要的一个实验，强烈建议自己跑一遍。
        */
       public void compare() {
           String query = "怎么把钱退回来";
           List<String> candidates = List.of(
                   "退款申请流程说明",       // 语义相似，应排第 1
                   "售后服务中心电话",       // 弱相关
                   "如何配置数据库连接池"     // 完全不相关
           );
   
           float[] q = embeddingModel.embed(query);
   
           for (String c : candidates) {
               float[] v = embeddingModel.embed(c);
               // 余弦相似度 = 点积 / (模长乘积)，取值 [-1, 1]，越接近 1 越相似
               double cos = cosine(q, v);
               System.out.printf("%.4f  %s%n", cos, c);
           }
           // 期望看到：退款申请流程说明 的分数明显最高（通常 0.75 以上）
       }
   
       private double cosine(float[] a, float[] b) {
           double dot = 0, na = 0, nb = 0;
           for (int i = 0; i < a.length; i++) {
               dot += a[i] * b[i];
               na  += a[i] * a[i];
               nb  += b[i] * b[i];
           }
           return dot / (Math.sqrt(na) * Math.sqrt(nb));
       }
   }

② 让 compare() 真的跑起来（加一个启动器）

上面的 EmbeddingDemoService 只是个 @Service，需要有人调用它。我们加一个 CommandLineRunner，让应用一启动就打印相似度对比，方便你「亲眼验证向量有用」。

1. 在 ch04 包上右键 → New → Java Class，名字填 EmbeddingDemoRunner。
2. 粘贴下面代码并保存（这是驱动标准答案跑起来的「脚手架」，不属于标准答案本身，可随时删）：

package com.example.springai.ch04;

import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

@Component
public class EmbeddingDemoRunner implements CommandLineRunner {

    private final EmbeddingDemoService demo;

    public EmbeddingDemoRunner(EmbeddingDemoService demo) {
        this.demo = demo;
    }

    @Override
    public void run(String... args) {
        System.out.println("===== 语义相似度实验 start =====");
        demo.compare();
        System.out.println("===== 语义相似度实验 end =====");
    }
}

③ 运行验证

先确认 yml 里已经配好了某个可用的 embedding 供应商（见 4.5，推荐先用 Ollama 本地 nomic-embed-text，零密钥）。然后：

步骤 A：先编译，确保代码写得对（不需要联网、不需要密钥）：

# 在项目根目录（pom.xml 所在目录）执行
mvn -q compile

看到什么算通过：命令结束没有任何 BUILD FAILURE，最后一行是 BUILD SUCCESS（-q 会静默掉下载日志，只留结果）。如果这里报错，通常是包名/import/泛型没敲对，先修编译再往下。

步骤 B：启动应用，触发 compare()：

mvn spring-boot:run

预期输出（控制台）：应用启动后，会打印类似下面的三行（分数随模型不同略有浮动，但顺序一定不变）：

===== 语义相似度实验 start =====
0.7588  退款申请流程说明      ← 课程 lab 实测（智谱 embedding-3，1024 维）
0.30xx  售后服务中心电话
0.10xx  如何配置数据库连接池
===== 语义相似度实验 end =====

看到什么算通过：「退款申请流程说明」的分数（实测 0.7588，用智谱 embedding-3 / 1024 维跑出）明显高于另外两条，且和「如何配置数据库连接池」接近 0.1。这说明：两句没有相同字的话，语义向量确实很近——你对 RAG 的信任从「老师说能行」变成「我亲眼见过」。分数绝对值随模型不同会浮动，但排序不变。

4.5向量数据库选型与配置

向量本身只是一串数字，要能「存得下、查得快、能过滤」，需要一个向量数据库。它和关系库的区别是：除了存字段，还能直接对向量列建索引并算最近邻。

第 0 步：先把 PostgreSQL 与 pgvector 装好（Windows 手把手，约 20 分钟）

pgvector 不是一款独立数据库，它是 PostgreSQL 的一个扩展。所以顺序永远是：① 装 PostgreSQL → ② 把 pgvector 扩展文件放进去 → ③ 建库、建扩展、建表。这一步不先做完，后面遇到的 relation "vector_store" does not exist、extension "vector" is not available、Connection to localhost:5432 refused 全都无从查起——因为你连"数据库在不在"都说不清。

1. 下载并解压 PostgreSQL 17 的 Windows 二进制包（EDB 官网「Binaries」区的 .zip，不要下 Installer）。解压到 D:\pgsql。

   路径纪律：不要放在含中文或空格的目录（如「桌面」「Program Files」），否则后面 initdb 和 pg_ctl 会因为路径解析失败，报的错还看不出跟路径有关。

   解压后自检：确认这三个目录都在——D:\pgsql\bin、D:\pgsql\lib、D:\pgsql\share。

2. 把 pgvector 扩展文件放进去（下载 pgvector 的 Windows 预编译包，解压后按下表放）。放错目录是后面「扩展不可用」的唯一原因：

   pgvector 包里拿到的文件	放到哪里
   vector.dll	D:\pgsql\lib\
   vector.control	D:\pgsql\share\extension\
   全部 vector--*.sql（通常 40 多个）	D:\pgsql\share\extension\

   放完立刻验证（一定要做）：用记事本打开 D:\pgsql\share\extension\vector.control，里面应当有 default_version = '0.8.6'。看到这行，说明扩展文件位置对了；看不到，说明你放错了或没解压完整。

3. 初始化数据目录（只做一次）。打开一个新的 PowerShell 或 CMD 窗口，执行：

   :: 把数据目录建到 D:\pgdata，超级用户 postgres，UTF-8 编码
   D:\pgsql\bin\initdb.exe -D D:\pgdata -U postgres -E UTF8 --locale=C

   预期输出结尾：Success. You can now start the database server using: ... pg_ctl -D "D:\pgdata" -l logfile start

   看到什么算通过：出现 Success.，且 D:\pgdata 下生成了 PG_VERSION（内容为 17）与 postgresql.conf。若报 initdb: error: directory "D:\pgdata" exists but is not empty，说明目录里已有东西——换一个空目录，或确认那是你要复用的旧库。

4. 改两处配置。用记事本打开 D:\pgdata\postgresql.conf，把下面两行前面的 # 去掉并改成：

   port = 5432
   listen_addresses = 'localhost'

   再打开 D:\pgdata\pg_hba.conf，在文件最下方追加两行（让本机免密连上，便于排错；生产环境请改用 scram-sha-256）：

   host    all    all    127.0.0.1/32    trust
   host    all    all    ::1/128         trust

   为什么两行都要写：yml 里写的是 localhost，Windows 上它可能被解析成 IPv6 的 ::1。只写 127.0.0.1 那一行时，应用会报 no pg_hba.conf entry for host "::1"——这个错看起来像"没权限"，实际只是少了一行 IPv6 规则。

5. 启动数据库。继续用刚才那个终端：

   D:\pgsql\bin\pg_ctl.exe -D D:\pgdata -l D:\pgdata\pglog.txt start

   预期输出：waiting for server to start.... done 与 server started。

   验证它在监听 5432：

   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "SELECT version();"

   预期输出：形如 PostgreSQL 17.x on x86_64-windows, compiled by ... 的一行。看到它就说明数据库层已经通了。

6. 建业务库、业务账号，并安装 vector 扩展。三条命令，逐条执行：

   :: ① 建库（名字与 application.yml 的 url 一致）
   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "CREATE DATABASE vectordb;"
   
   :: ② 建应用账号（与 yml 的 username / password 一致）
   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "CREATE USER ai WITH PASSWORD 'ai123456';"
   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "GRANT ALL PRIVILEGES ON DATABASE vectordb TO ai;"
   
   :: ③ 装扩展（必须用超级用户 postgres 执行，普通用户没权限）
   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -d vectordb -c "CREATE EXTENSION vector;"

   最终验证（这一步是整个第 0 步的验收动作）：

   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -d vectordb -c "SELECT extname, extversion FROM pg_extension WHERE extname='vector';"

   预期输出：

    extname | extversion
   ---------+------------
    vector  | 0.8.6
   (1 row)

   看到什么算通过：必须出现 vector | 0.8.6 这一行。看不到 extversion 就是扩展没装成，回去看第 2 步的文件位置。到这里，"数据库层"才算准备完毕——接下来配 yml 才有意义。

:: 停止
D:\pgsql\bin\pg_ctl.exe -D D:\pgdata stop

:: 重启（改完 postgresql.conf / pg_hba.conf 后必须重启才生效）
D:\pgsql\bin\pg_ctl.exe -D D:\pgdata restart

:: 看状态
D:\pgsql\bin\pg_ctl.exe -D D:\pgdata status

pgvector 依赖与配置（手把手）

1. 打开项目根目录的 pom.xml，在 <dependencies> 里加入 pgvector starter（它会传递引入 postgresql 驱动）。在 IDEA 里直接粘贴到已有依赖后面：

   <!-- pom.xml：pgvector 的 Spring AI starter（注意它会传递引入 postgresql 驱动） -->
   <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
   </dependency>

2. Ctrl + S 保存，等待右下角 Maven 同步完成（首次会下载依赖）。

3. 打开 src/main/resources/application.yml，按下面「扁平、无 .options、维度匹配」的写法配置。注意：chat 走 DeepSeek，embedding 必须换供应商——下面给两套 embedding 方案，二选一（推荐方案 A 本地 Ollama，零密钥）。

   # application.yml —— pgvector 完整配置（每一项都有注释）
   spring:
     datasource:                              # ★ VectorStore 用的就是这个数据源
       url: jdbc:postgresql://localhost:5432/vectordb
       username: ai
       password: ai123456
       driver-class-name: org.postgresql.Driver
   
     ai:
       # ---- chat 模型：课程默认 DeepSeek（OpenAI 兼容），密钥走环境变量占位符 ----
       openai:
         api-key: ${DEEPSEEK_API_KEY:}
         base-url: https://api.deepseek.com
         chat:
           options:
             model: deepseek-chat
   
       # ---- embedding 模型：★ DeepSeek 不提供 embedding，必须换供应商 ----
       # 方案 A（推荐入门，零密钥）：本地 Ollama 的 nomic-embed-text，输出 768 维
       ollama:
         base-url: http://localhost:11434
         embedding:
           model: nomic-embed-text           # ★ 扁平，无 .options；输出 768 维
   
       # 方案 B（云侧，国内推荐）：通义 text-embedding-v3，输出 1024 维
       # 启用方案 B 时，把上面的 ollama 整段注释掉，取消下面注释，并改 dimensions 为 1024
       # dashscope:
       #   api-key: ${DASHSCOPE_API_KEY:}
       #   embedding:
       #     model: text-embedding-v3
   
       # 方案 C（★ 课程 lab 实测主用）：智谱 embedding-3，输出 1024 维
       # 关键技巧：embedding 在 openai 下单独覆盖 base-url / api-key，chat 仍走上面的 DeepSeek
       # 启用时：把 ollama 整段注释掉，取消下面注释，并把 pgvector 的 dimensions 改为 1024
       # openai:
       #   embedding:
       #     base-url: https://open.bigmodel.cn/api/paas/v4
       #     api-key: ${ZHIPU_API_KEY:}
       #     model: embedding-3
       #     dimensions: 1024
   
       vectorstore:
         pgvector:
           # 是否自动建表 / 建扩展。首次启动 true，后续可设 false 加快启动
           initialize-schema: true
           # 表名。默认为 vector_store，改这里要同步改
           table-name: vector_store
           # 索引类型：HNSW（推荐）/ IVFFlat / NONE（精确检索）
           index-type: HNSW
           # 距离类型，必须与灌库时一致
           distance-type: COSINE_DISTANCE
           # ★★★ 维度必须等于 embedding 模型的输出维度，写错必报错
           #     用 nomic-embed-text → 768；用 text-embedding-v3 → 1024；用 text-embedding-3-small → 1536
           dimensions: 768
           # 单次批量写入上限，文档多时自动分批
           max-document-batch-size: 10000

4. Ctrl + S 保存 yml。记住一条：只要改了 embedding 模型（维度变了），就必须把 dimensions 改成对应值，并且把 pgvector 表删掉重建（drop table if exists vector_store; 后重启让 initialize-schema: true 重新建表）。

# 1) 启动 Ollama（默认监听 11434）
# 2) 拉取嵌入模型（只需一次）
ollama pull nomic-embed-text
# 3) 验证模型在本地已就绪
curl http://localhost:11434/api/tags

方案 C 全程手把手：接入智谱 embedding-3（课程 lab 实测，推荐）

这套配置在课程 lab 里真实跑通过：中文语义检索效果好（「钱什么时候能到账」能命中「3 个工作日内退回原支付账户」），国内直连不需要任何网络工具，花费按 token 计费（0.5 元/百万 tokens，跑完本章全部实验通常 不到 1 元）。跟着下面 8 步做，每一步都有「看到什么算通过」。

1. 注册并生成 API Key。打开 https://open.bigmodel.cn（智谱开放平台），用手机号注册并完成实名认证。进入控制台 → 「API Keys」→ 新建一个 Key，它会形如 a5081a84....zJW75k（id.secret 两段式，整串复制）。这一步只需要做一次。

2. 确认账户有可用额度。embedding-3 按量计费：0.5 元 / 百万 Tokens。如果调用时收到 HTTP 429 且错误码 1113、提示「余额不足或无可用资源包」，去控制台「财务中心」充值最低档（10 元够整个学期）或在「资源包」页领免费额度。

3. 把 Key 配置成环境变量（不要写进代码）。以 PowerShell 为例（永久生效，写入用户级）：

   # 永久写入用户环境变量（推荐）
   [Environment]::SetEnvironmentVariable("ZHIPU_API_KEY", "你的key", "User")
   
   # 验证：必须新开一个终端/重启 IDEA 后执行
   echo $env:ZHIPU_API_KEY

   看到什么算通过：新开的终端里 echo 能打印出你的 key。已经开着的 IDEA 读不到新环境变量，必须整个重启 IDEA（不是重启运行窗口）——这是环境变量「进程继承」规则，没重启就配好了也白配。

4. 改 yml：embedding 在 openai 下单独覆盖 base-url / api-key。核心认知：智谱的 API 是 OpenAI 兼容的，所以不用换 starter，只要在 spring.ai.openai.embedding 下覆盖三个值，chat 层完全不受影响（chat 继续走 DeepSeek）：

   # application.yml —— 在 spring.ai 下，把原来 ollama 的 embedding 整段注释/删除，改为：
   spring:
     ai:
       openai:
         api-key: ${DEEPSEEK_API_KEY:}          # chat 用，保持不动
         base-url: https://api.deepseek.com     # chat 用，保持不动
         chat:
           options:
             model: deepseek-chat               # chat 用，保持不动
         # ★ embedding 三件套：只影响向量化，chat 不受影响。扁平结构，没有 .options
         embedding:
           base-url: https://open.bigmodel.cn/api/paas/v4
           api-key: ${ZHIPU_API_KEY:}
           model: embedding-3
           dimensions: 1024                     # 主动声明 1024 维（省一半存储）
   
       vectorstore:
         pgvector:
           dimensions: 1024                     # ★ 必须与上面一致
           # 其余 initialize-schema / index-type / distance-type 保持原样

   两处易错：① embedding 下没有 .options 层级，写 embedding.options.model 是 1.x 的错误写法，2.0 不生效；② base-url 必须带 /api/paas/v4，少了版本段会 404。

5. 改了模型就要删表重建。如果你之前用 Ollama/通义灌过数据，向量维度是旧的 768/1536，必须先清库：

   -- 在 psql（或 IDEA Database 面板）里对 vectordb 执行
   drop table if exists vector_store;

   然后保持 initialize-schema: true 重启应用，它会按新的 1024 维重建表。建库后 dimensions 就锁死了——这是 pgvector 列类型 vector(1024) 决定的，改维度只能删表重建。

6. 启动前先确认 PostgreSQL 在跑。本章最常见的启动失败就是下面这个（JDBC 连不上）：

   PgVectorStoreAutoConfiguration ... Failed to obtain JDBC Connection
   Caused by: PSQLException: Connection to localhost:5432 refused.

   这不是 Spring AI 的错，是 postgres 进程根本没在跑。先把数据库拉起来（本项目 lab 用绿色版：前台运行 postgres.exe -D 数据目录 的那个终端窗口别关），看到日志出现 database system is ready to accept connections 再启动应用。

7. 验证 ①：跑 4.4 的 compare() 实验。启动应用，控制台应打印三行分数，其中「退款申请流程说明」明显最高（实测 0.7588，智谱 embedding-3 / 1024 维）。

8. 验证 ②：确认表结构真的是 1024 维。psql 连上 vectordb：

   \d vector_store
   -- 应看到：embedding | vector(1024)，以及 hnsw (embedding vector_cosine_ops) 索引

   看到什么算通过：维度是 1024、索引是 HNSW cosine。到这里，智谱链路（注册 → 充值 → 环境变量 → yml 覆盖 → 建表 → 语义实验）全部打通。

运行验证：确认表真的建出来了

# 编译
mvn -q compile
# 启动（确保 PostgreSQL/pgvector 已运行、datasource 可达）
mvn spring-boot:run

看到什么算通过：启动日志里出现 pgvector 建表/建扩展相关 INFO，且没有 expected N dimensions 或 extension "vector" is not available 之类报错。再用 psql / IDEA Database 工具连上 vectordb，执行：

:: 用 psql 连上业务库（psql 已加 PATH 就直接写 psql，否则用全路径）
D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -d vectordb

-- 连上后执行：能看到这张表，说明自动建表成功
\d vector_store
-- 应看到一列类型为 vector(N)，N = 你配置的 dimensions（如 768）
-- 以及一条 hnsw (embedding vector_cosine_ops) 索引

Milvus 配置（做对比实验时用）

<!-- 依赖：与 pgvector 可以同时存在，但要靠 @Qualifier 或 spring.ai.vectorstore.type 指定主用 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-vector-store-milvus</artifactId>
</dependency>

spring:
  ai:
    vectorstore:
      milvus:
        client:
          host: localhost
          port: 19530
          # 用户名密码（未开启鉴权可留空）
          username: root
          password: milvus
        database-name: default
        collection-name: vector_store
        # ★ 同样必须与 embedding 维度一致
        embedding-dimension: 768
        # 索引类型：IVF_FLAT / HNSW / FLAT
        index-type: IVF_FLAT
        # 距离度量：COSINE / L2 / IP
        metric-type: COSINE
        # 是否自动创建 collection
        initialize-schema: true

4.6VectorStore：写入、删除、检索

VectorStore 是 Spring AI 对「向量库读写」的统一抽象。你不用手写 SQL 或向量距离计算，add() 时它内部自动调用 EmbeddingModel 把文本变成向量再入库，similaritySearch() 时自动把查询文本向量化再去比。

Document 与 metadata（先认识数据单位）

import org.springframework.ai.document.Document;

// Document = 文本内容 + 元数据 + 向量（向量由 VectorStore 自动生成，你不用管）
Document doc = new Document(
        "退款申请需在订单完成后 7 天内提交，超期需联系客服人工审核。",   // ① content：会被向量化的文本
        Map.of(                                                     // ② metadata：不会向量化，但可用来过滤
                "source", "refund-policy.pdf",
                "page", 3,
                "category", "售后",
                "version", "v2"
        )
);

// 也可以自己生成文档 ID（默认是随机 UUID）
Document withId = new Document(
        "doc-001",                  // 显式指定 id，便于幂等更新
        "退款申请需在订单完成后 7 天内提交。",
        Map.of("category", "售后"));

// 读取
doc.getText();          // 正文
doc.getMetadata();      // 元数据 Map
doc.getId();            // id
doc.getScore();         // ★ 检索返回的文档会带相似度分数，写入时为 null

写入与删除（手把手建类）

1. 在 ch04 包上右键 → New → Java Class，名字填 VectorStoreBasics。
2. 粘贴下面「标准答案」并保存（语义不要改）：

@Service
public class VectorStoreBasics {

    private final VectorStore vectorStore;

    public VectorStoreBasics(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    /** 写入：内部会自动调用 EmbeddingModel 生成向量，再批量入库 */
    public void add(List<Document> docs) {
        vectorStore.add(docs);
        // 注意：add 是"只增不改"。同一个 id 再 add 一次会怎样？
        // 取决于实现：pgvector 用主键冲突会更新（upsert 行为），Milvus 可能抛错。
        // 生产上建议：更新前先 delete(ids)，再 add，语义更清晰。
    }

    /** 按 id 删除 */
    public void deleteByIds(List<String> ids) {
        vectorStore.delete(ids);
    }

    /** 按条件删除：例如删除某个文档来源的全部向量（重建索引时用） */
    public void deleteBySource(String source) {
        vectorStore.delete("source == '" + source + "'");
    }

    /** 向量库的名字，多库共存时用于区分 */
    public String name() {
        return vectorStore.getName();
    }
}

检索：SearchRequest 详解（本章最重要的一段）

1. 继续在 ch04 包新建类 VectorSearchDemo（或把下面代码并入你已有的检索服务），粘贴标准答案并保存：

import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;

// 最简写法：默认 topK，无阈值过滤
List<Document> simple = vectorStore.similaritySearch("退款要几天");

// 完整写法：所有参数都显式控制（推荐）
SearchRequest request = SearchRequest.builder()
        .query("退款要几天")              // 查询文本，会被向量化后去比对
        .topK(5)                              // 返回最相似的 5 条
        .similarityThreshold(0.5)             // ★ 相似度低于 0.5 的直接丢弃（余弦下 0.5 约等于"弱相关"）
        .filterExpression("category == '售后'")  // 元数据过滤，见 4.7
        .build();

List<Document> docs = vectorStore.similaritySearch(request);

for (Document d : docs) {
    System.out.printf("分数=%.4f  来源=%s  内容=%s%n",
            d.getScore(), d.getMetadata().get("source"), d.getText());
}

4.7元数据过滤：把检索范围先缩小，再算相似度

这是提升 RAG 准确率性价比最高的一招。举例：公司有 5 个部门的知识库，用户是财务部的，问「报销标准是多少」。如果不加过滤，向量检索会在全公司 10 万条文档里找，很可能把销售部的差旅标准捞出来——语义上极其相似，但答案是错的。

// ---------- 支持的运算符（Spring AI 的过滤表达式 DSL）----------
// 比较：  ==  !=  >  >=  <  <=
// 逻辑：  and  or  ( )
// 集合：  in

// 精确匹配
"category == '售后'"

// 数值比较（注意：数值型元数据不要加引号）
"page >= 10"

// 组合条件
"category == '售后' and version == 'v2'"

// 集合包含
"source in ['refund-policy.pdf', 'aftersale.pdf']"

// 实际用法
SearchRequest req = SearchRequest.builder()
        .query("报销标准是多少")
        .topK(5)
        .similarityThreshold(0.5)
        .filterExpression("dept == '财务部' and docType == '制度'")
        .build();

4.8完整示例：文档向量索引服务

目标：一个能「灌库 + 检索 + 统计」的最小可用服务。本节的代码第 5 章会直接复用。注意：本课程不使用 Lombok，日志用显式 LoggerFactory。下面 4 个文件请逐一按步骤新建，每个文件都是标准答案，语义不要改。

① 灌库服务

1. 在 ch04 包上右键 → New → Package，输入 dto，回车。
2. 在 ch04 包（不是 dto）上右键 → New → Java Class，名字填 DocumentIndexService，粘贴下面标准答案并保存：

package com.example.springai.ch04;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.stereotype.Service;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

@Service
public class DocumentIndexService {

    private static final Logger log = LoggerFactory.getLogger(DocumentIndexService.class);
    /** 单批写入条数。太大易触发厂商限流，太小效率低。10~50 是常见区间 */
    private static final int BATCH_SIZE = 20;

    private final VectorStore vectorStore;

    public DocumentIndexService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    /**
     * 把一批文本（已切分好的片段）灌入向量库。
     * @param source 来源标识（如文件路径），用于后续按来源删除/过滤
     * @param chunks 已切分的文本片段，每个片段会成为一条向量
     */
    public int index(String source, String category, List<String> chunks) {
        // ★ 幂等：先删掉这个来源的旧数据，避免重复灌导致结果重复
        //   这是"重建索引"最常见的做法
        deleteBySource(source);

        int seq = 0;
        int total = 0;

        for (int i = 0; i < chunks.size(); i += BATCH_SIZE) {
            List<String> batch = chunks.subList(i, Math.min(i + BATCH_SIZE, chunks.size()));

            List<Document> docs = batch.stream()
                    .map(text -> new Document(text, buildMetadata(source, category, chunks.indexOf(text))))
                    .toList();

            vectorStore.add(docs);          // 内部自动批量向量化 + 入库
            total += docs.size();
            log.info("已灌入 {}/{} 条", total, chunks.size());
        }
        return total;
    }

    /** 元数据必须在灌库时一次性写全，后面补字段要整库重灌 */
    private Map<String, Object> buildMetadata(String source, String category, int chunkIndex) {
        return Map.of(
                "source",      source,
                "category",    category,
                "chunkIndex",  chunkIndex,
                // 注意：pgvector 的 JSON 元数据对 LocalDateTime 支持不一，
                // 统一转成字符串更稳妥
                "indexedAt",   LocalDateTime.now().toString()
        );
    }

    /** 按来源删除：重建索引时先调它 */
    public void deleteBySource(String source) {
        try {
            vectorStore.delete("source == '" + source + "'");
        } catch (Exception e) {
            // 表为空或字段不存在时可能抛异常，降级为打日志，不阻断主流程
            log.debug("按来源删除失败（可能是首次灌库）：{}", e.getMessage());
        }
    }
}

② 检索服务

1. 在 ch04 包上右键 → New → Java Class，名字填 VectorSearchService，粘贴标准答案并保存：

@Service
public class VectorSearchService {

    private static final Logger log = LoggerFactory.getLogger(VectorSearchService.class);
    private final VectorStore vectorStore;

    public VectorSearchService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    /**
     * 语义检索。
     * @param query     用户问题
     * @param topK      返回条数
     * @param threshold 相似度阈值，低于它的结果丢弃
     * @param category  分类过滤，可为 null
     */
    public List<SearchResult> search(String query, int topK,
                                      double threshold, String category) {

        // 过滤表达式按需拼接。注意：字符串值必须单引号
        String filter = (category == null || category.isBlank())
                ? null
                : "category == '" + category + "'";

        var builder = SearchRequest.builder()
                .query(query)
                .topK(topK)
                .similarityThreshold(threshold);
        if (filter != null) {
            builder.filterExpression(filter);
        }

        List<Document> docs = vectorStore.similaritySearch(builder.build());
        log.info("检索「{}」命中 {} 条", query, docs.size());

        // 转成对外的 DTO，不要把 Document 直接暴露给前端（会带上内部元数据）
        return docs.stream()
                .map(d -> new SearchResult(
                        d.getText(),
                        d.getScore(),
                        String.valueOf(d.getMetadata().get("source")),
                        String.valueOf(d.getMetadata().get("category"))))
                .toList();
    }
}

③ HTTP 接口与验证

1. 在 ch04.dto 包上右键 → New → Java Class，名字填 IndexRequest，粘贴下面两个 record（可放同一文件或各建一个）并保存：

package com.example.springai.ch04.dto;

// 灌库入参
public record IndexRequest(String source, String category, List<String> chunks) {}

// 检索出参
public record SearchResult(String content, Double score, String source, String category) {}

2. 在 ch04 包上右键 → New → Java Class，名字填 VectorApiController，粘贴下面标准答案并保存：

@RestController
@RequestMapping("/api/v1/vector")
public class VectorApiController {

    private final DocumentIndexService indexService;
    private final VectorSearchService searchService;

    public VectorApiController(DocumentIndexService i, VectorSearchService s) {
        this.indexService = i;
        this.searchService = s;
    }

    /** 灌库：先手工传几段文本，验证链路 */
    @PostMapping("/index")
    public Map<String, Object> index(@RequestBody IndexRequest req) {
        int n = indexService.index(req.source(), req.category(), req.chunks());
        return Map.of("indexed", n, "source", req.source());
    }

    /** 检索 */
    @GetMapping("/search")
    public List<SearchResult> search(@RequestParam String q,
                                   @RequestParam(defaultValue = "5") int topK,
                                   @RequestParam(defaultValue = "0.5") double threshold,
                                   @RequestParam(required = false) String category) {
        return searchService.search(q, topK, threshold, category);
    }
}

④ 运行验证：三条命令走完整个闭环

先编译并启动（确保 embedding 供应商可达、pgvector 表已建）：

mvn -q compile
mvn spring-boot:run

看到什么算通过：BUILD SUCCESS 且应用监听 8080，日志无维度/扩展报错。然后依次发下面四条请求。

1. ① 灌库：先灌三条售后知识。

   curl -X POST http://localhost:8080/api/v1/vector/index \
     -H "Content-Type: application/json" \
     -d '{
       "source":"refund-policy.md",
       "category":"售后",
       "chunks":[
         "退款申请需在订单完成后 7 天内提交，超期需联系客服人工审核。",
         "退款将在审核通过后 3 个工作日内退回原支付账户。",
         "生鲜类商品一经签收不支持无理由退款。"
       ]}'

   预期输出：{"indexed":3,"source":"refund-policy.md"}，日志出现「已灌入 3/3 条」。

2. ② 再灌三条技术文档（用来验证「不串味」）。

   curl -X POST http://localhost:8080/api/v1/vector/index \
     -H "Content-Type: application/json" \
     -d '{
       "source":"db-guide.md",
       "category":"技术",
       "chunks":[
         "PostgreSQL 连接池建议 max_connections 不超过 200。",
         "pgvector 的 HNSW 索引构建参数 m 默认为 16。"
       ]}'

   预期输出：{"indexed":2,"source":"db-guide.md"}。

3. ③ 语义检索：故意用「没有一个字相同」的问法。

   curl "http://localhost:8080/api/v1/vector/search?q=钱什么时候能到账&topK=3&threshold=0.4"

   预期输出：第一条命中「退款将在审核通过后 3 个工作日内退回原支付账户」——说明语义检索生效（关键词匹配绝对做不到）。

4. ④ 加分类过滤，验证元数据过滤生效。

   curl "http://localhost:8080/api/v1/vector/search?q=钱什么时候能到账&topK=3&category=技术"

   预期输出：结果全部来自 category=技术（很可能为空），证明过滤条件真的缩小了检索范围。

4.9常见坑排错

4.10自测题

4.11实操作业与本章验收

• 能用自己的话说清 Embedding 在做什么，并解释「为什么关键词匹配做不到、语义匹配可以」（4.1 实验截图为证）。
• 能说出维度、距离算法、索引类型三个配置项的作用和相互约束，并确认自己库的维度与模型一致。
• 三个 curl 实验全部通过，特别是「钱什么时候能到账」能命中退款条款。
• 能设计一份合格的元数据 schema（含 source / page / category / tenantId），并知道「换模型必须重灌库」「阈值必须调」两条铁律。

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

本章是第一次引入外部依赖（数据库），失败面比前三章大得多：一半的报错来自"数据库没弄好"，另一半来自"维度/阈值配错"。下面把三类事情分开列清楚。

① 前置：数据库层必须先过关（不过关别往下走）

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

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

1. 编译并启动。启动日志里应有 pgvector 建表/建扩展的 INFO，且没有 expected N dimensions、extension "vector" is not available、Connection refused。

2. 确认表真的建出来了（自动建表成功的唯一证据）：

   D:\pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -d vectordb -c "\d vector_store"

   预期：看到 id uuid / content text / metadata json / embedding vector(N)，以及一条 hnsw (embedding vector_cosine_ops) 索引。

   看到什么算通过：vector(N) 里的 N 必须等于你 yml 里配的 dimensions（用 nomic-embed-text 就是 768，用智谱 embedding-3 就是 1024）。N 不对，后面灌库必报错。

3. 先跑 4.4 的相似度实验（验证"向量真的有用"，这一步不需要数据库）：运行 EmbeddingDemoService 的 compare()（或 Ch04DemoRunner 的日志输出）。

   预期：「怎么把钱退回来」与「退款申请流程说明」的余弦分明显最高（0.7 以上量级），与无关句子的分数明显更低。

   看到什么算通过：语义相近的那条排第一。这一条是整章的直觉基础——它证明了"语义匹配"这件事真的成立。

4. 灌库（先清后灌，幂等）：

   curl -s -X POST http://localhost:8080/api/v1/vector/index \
     -H "Content-Type: application/json" \
     --data-binary "@test-index-refund.json"

   预期：返回写入条数（如 {"indexed":8} 之类）。

   重复执行一次，条数应不变——这是幂等生效的证据。条数翻倍说明没做 deleteBySource，先修再往下。

5. 语义检索（第 ③ 项验收动作，也是本章最漂亮的一次实验）：用一句不含原文关键词的口语去查：

   :: 中文参数必须 URL 编码，否则乱码
   curl -s -G http://localhost:8080/api/v1/vector/search \
     --data-urlencode "q=钱什么时候能到账" \
     --data-urlencode "topK=5"

   预期：命中 refund-policy.md 里的退款到账条款，score 在 0.5 以上。

   看到什么算通过（可精确断言）：结果里必须出现「3 个工作日内退回原支付账户」这类内容——注意原文里根本没有"到账"两个字，能命中就说明走的是语义而非关键词。这一条过不了，后面第 5 章整章都会塌。

6. 加元数据过滤，看结果被收紧：

   curl -s -G http://localhost:8080/api/v1/vector/search \
     --data-urlencode "q=报销标准是多少" \
     --data-urlencode "category=财务"

   预期：结果里不再出现"销售部差旅标准"之类归属错误的文档。

   对照实验（推荐做）：把 category 参数去掉再查一次，你会看到它混进第 2 名——一加一减，元数据过滤的价值立刻可见。

7. 做一个"阈值"反例：把 similarityThreshold 从 0.4 改成 0.95，重发检索。

   预期：结果几乎变空。再改回 0.5 左右，恢复正常。

   为什么要做：让"阈值过低会进噪声、过高会检索为空"这两件事变成身体记忆——这是后面调 RAG 效果时最常动的两个旋钮之一。

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