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

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));
    }
}

4.5向量数据库选型与配置

pgvector 依赖与配置

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

# application.yml —— pgvector 完整配置（每一项都有注释）
spring:
  datasource:                              # ★ VectorStore 用的就是这个数据源
    url: jdbc:postgresql://localhost:5432/vectordb
    username: ai
    password: ai123456
    driver-class-name: org.postgresql.Driver

  ai:
    vectorstore:
      pgvector:
        # 是否自动建表 / 建扩展。首次启动 true，后续可设 false 加快启动
        initialize-schema: true
        # 表名。默认为 vector_store，改这里要同步改 
        table-name: vector_store
        # 索引类型：HNSW（推荐）/ IVFFlat / NONE（精确检索）
        index-type: HNSW
        # 距离类型，必须与灌库时一致
        distance-type: COSINE_DISTANCE
        # ★★★ 维度必须等于 embedding 模型的输出维度，写错必报错
        dimensions: 1536
        # 单次批量写入上限，文档多时自动分批
        max-document-batch-size: 10000
        # 搜索时默认返回条数（可被 SearchRequest 覆盖）
        # 若使用外部已建好的库，可关掉自动初始化：
        # schema-validation: true
      # 同时启用了 OpenAI embedding 时，会自动用 OpenAI 生成向量
    openai:
      api-key: ${OPENAI_API_KEY:}
      base-url: https://api.openai.com         # embedding 建议用 OpenAI 或通义，DeepSeek 无此能力
      embedding:
        options:
          model: text-embedding-3-small        # 输出 1536 维，与上面 dimensions 对应

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: 1536
        # 索引类型：IVF_FLAT / HNSW / FLAT
        index-type: IVF_FLAT
        # 距离度量：COSINE / L2 / IP
        metric-type: COSINE
        # 是否自动创建 collection
        initialize-schema: true

4.6VectorStore：写入、删除、检索

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

写入与删除

@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 详解（本章最重要的一段）

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 章会直接复用。

① 灌库服务

package com.example.springai.ch04;

import lombok.extern.slf4j.Slf4j;
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;

@Slf4j
@Service
public class DocumentIndexService {

    /** 单批写入条数。太大易触发厂商限流，太小效率低。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());
        }
    }
}

② 检索服务

@Slf4j
@Service
public class VectorSearchService {

    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 接口与验证

@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);
    }

    public record IndexRequest(String source, String category, List<String> chunks) {}
    public record SearchResult(String content, Double score, String source, String category) {}
}

验证步骤（三条命令走完整个闭环）：

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

# ② 灌库：三条技术文档（用来验证"不串味"）
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。"
    ]}'

# ③ 语义检索：故意用"没有一个字相同"的问法
curl "http://localhost:8080/api/v1/vector/search?q=钱什么时候能到账&topK=3&threshold=0.4"

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

# ④ 加分类过滤，验证元数据过滤生效
curl "http://localhost:8080/api/v1/vector/search?q=钱什么时候能到账&topK=3&category=技术"

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

4.9常见坑排错

4.10自测题