SpringAI实战-7-RAG之R(Retrieval)语义检索

定位: 基于前面Embedding和PGVector的基础,本文聚焦语义检索的实际应用

一、从Embedding到语义检索

1.1 知识回顾

前面我们学了:文本 → Embedding → 向量向量存储到 PGVector余弦相似度计算现在我们要做的是:批量向量化100条文档实现语义搜索接口理解不同的距离度量方式

1.2 语义检索在RAG中的位置

RAG = Retrieval + Augmented + GenerationRetrieval (检索) ← 本文重点   ↓Augmented (增强) ← 下一篇   ↓  Generation (生成) ← 已有ChatModel

二、完整实现

2.1 技术栈

数据层: MyBatis Plus + PGVector服务层: VectorService (批量向量化)接口层: VectorController (REST API)

2.2 核心代码结构

src/main/java/com/springailearn/├── mapper/│   └── DocumentMapper.java          # MyBatis Mapper接口├── model/│   └── Document.java                # 文档实体├── service/│   └── VectorService.java           # 向量化服务└── controller/    └── VectorController.java        # REST接口src/main/resources/└── mapper/    └── DocumentMapper.xml           # SQL映射文件

2.3 批量向量化流程

第1步: 查询未向量化的文档

<!-- DocumentMapper.xml --><selectid="selectDocumentsWithoutEmbedding"resultType="Document">    <![CDATA[    SELECT id, content, metadata, embedding    FROM documents    WHERE embedding IS NULL OR LENGTH(embedding::text) = 0    ORDER BY id    ]]></select>

注意: PGVector字段不能用 = '' 判断,会触发类型校验错误,必须用 LENGTH(::text) = 0

第2步: 调用Embedding API生成向量

// VectorService.javaprivate float[] generateEmbedding(String text) {    // Spring AI封装,一行搞定    return embeddingModel.embed(text);}

第3步: 格式化并更新数据库

// float[] → "[0.1, -0.2, 0.3, ...]"private String formatEmbedding(float[] embedding) {    StringBuilder sb = new StringBuilder("[");    for (int i = 0; i < embedding.length; i++) {        sb.append(embedding[i]);        if (i < embedding.length - 1) {            sb.append(", ");        }    }    sb.append("]");    return sb.toString();}

第4步: 更新到PGVector

<update id="updateEmbedding">    UPDATE documents    SET embedding = #{embedding}::vector    WHERE id = #{id}</update>

关键: ::vector 是PostgreSQL的类型转换语法,将字符串转为pgvector类型

三、语义搜索实现

3.1 搜索接口

@PostMapping("/search")public List<Document> search(        @RequestParam String query,        @RequestParam(defaultValue = "5") int limit) {    // 1. 查询文本转矢量 (必须用同一个Embedding模型!)    float[] queryEmbedding = embeddingModel.embed(query);    String embeddingStr = formatEmbedding(queryEmbedding);    // 2. 向量相似度搜索    return documentMapper.selectSimilarDocuments(embeddingStr, limit);}

3.2 SQL实现

<selectid="selectSimilarDocuments"resultType="Document">    <![CDATA[    SELECT         id, content, metadata, embedding,        (embedding <=> #{embedding}::vector) AS similarity_distance    FROM documents    WHERE embedding IS NOT NULL AND LENGTH(embedding::text) > 0    ORDER BY similarity_distance ASC    LIMIT #{limit}    ]]></select>

说明: <=> 是PGVector的余弦距离运算符,值越小越相似

四、PGVector的距离度量方式

4.1 三种运算符对比

PGVector支持3种向量距离计算:

运算符	名称	排序方式	适用场景
`<=>`	余弦距离	ASC (越小越相似)	✅ 文本语义搜索
`<->`	欧氏距离	ASC (越小越相似)	图像、物理量
`<#>`	负内积	DESC (越大越相似)	推荐系统

4.2 余弦距离 vs 欧氏距离

场景演示:

文本A: "Java编程"        → 向量 [0.5, 0.5, 0.5]  (模长0.87)文本B: "Java编程教程"     → 向量 [0.8, 0.8, 0.8]  (模长1.39)语义分析: 两者非常相似,B只是多了"教程"两字

欧氏距离的结果 ❌:

distance = √[(0.8-0.5)² + (0.8-0.5)² + (0.8-0.5)²] = 0.52

问题: 虽然语义相似,但因为向量长度不同,距离较大,误判为不相似!

余弦距离的结果 ✅:

cos = (0.5×0.8 + 0.5×0.8 + 0.5×0.8) / (0.87 × 1.39) = 0.99

优势: 忽略长度,只看方向,正确判断为高度相似!

4.3 实际应用建议

场景	推荐运算符	原因
文本语义搜索	`<=>` 余弦距离	忽略文本长度差异
图像相似度	`<->` 欧氏距离	关心绝对差异
用户推荐	`<#>` 负内积	综合考虑方向和强度
地理位置	`<->` 欧氏距离	物理距离就是直线距离

4.4 SQL示例

-- 余弦距离 (文本搜索推荐)SELECT * FROM documents ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector LIMIT 5;-- 欧氏距离 (图像/物理量)SELECT * FROM documents ORDER BY embedding <-> '[0.1, 0.2, ...]'::vector LIMIT 5;-- 负内积 (推荐系统)SELECT * FROM documents ORDER BY embedding <#> '[0.1, 0.2, ...]'::vector DESC LIMIT 5;

五、测试验证

5.1 准备测试数据

# 1. 创建表和索引psql -U postgres -d spring_ai_learn -f script/vector.sql# 2. 导入100条测试数据psql -U postgres -d spring_ai_learn -f script/generate_100_data.sql

5.2 批量向量化

# 启动项目后调用接口curl -X POST http://localhost:8080/api/vector/batch-vectorize

预期输出:

{  "total": 100,  "success": 100,  "message": "总计:100, 成功:100, 失败:0"}

5.3 语义搜索测试

# 搜索"编程语言"相关文档curl -X POST "http://localhost:8080/api/vector/search?query=编程语言&limit=5"

预期结果:

[  {    "id": 1,    "content": "Python是一种高级编程语言,广泛用于数据科学...",    "metadata": "{\"category\": \"programming\"}",    "embedding": "[0.123, -0.456, ...]"  },  {    "id": 2,    "content": "Spring Boot是Java生态系统中最流行的微服务框架...",    "metadata": "{\"category\": \"programming\"}",    "embedding": "[0.234, -0.567, ...]"  }]

5.4 Swagger测试

访问: http://localhost:8080/doc.html^[3]

接口1: 批量向量化

•POST /api/vector/batch-vectorize

接口2: 语义搜索

•POST /api/vector/search?query=Python&limit=5

六、关键注意事项

6.1 必须使用同一个Embedding模型

错误做法:文档用阿里云Embedding → 向量A查询用OpenAI Embedding  → 向量B比较A和B的相似度       → 无意义!正确做法:文档用阿里云Embedding → 向量A查询用阿里云Embedding  → 向量B  比较A和B的相似度       → 有效!

6.2 性能优化方向

当前实现: 逐条处理 (学习用)生产优化:1. 批量调用Embedding API (减少网络开销)2. 添加向量缓存 (避免重复计算)3. 异步处理 (大批量数据不阻塞)4. 创建IVFFlat索引 (加速检索)

6.3 常见问题

问题	原因	解决方案
`invalid input syntax for type vector`	空字符串无法转vector	用 `LENGTH(::text) = 0` 判断
XML解析错误	`<=>` 被XML解析为标签	用 `<![CDATA[]]>` 包裹SQL
相似度不准确	混用了不同Embedding模型	统一使用同一个模型

七、下一步: 完整的RAG

当前我们完成了 Retrieval (检索),接下来要补充:

✅ Retrieval: 语义搜索 (本文)⬜ Augmented: 构建增强Prompt (下一篇)✅ Generation: AI对话 (已有)

完整RAG流程:

用户问题: "Python适合做什么?"     ↓1. 检索相关文档 (本文已完成)     ↓2. 构建Prompt:   """   请根据参考资料回答问题:   参考资料:   - Python是一种高级编程语言,广泛用于数据科学...   - Django是高级Python Web框架...   用户问题: Python适合做什么?   """     ↓3. 调用DeepSeek生成答案 (已有ChatModel)     ↓4. 返回完整回答 + 引用来源

八、总结

核心要点

1.语义检索流程: 文本 → Embedding → 向量匹配 → 返回结果2.PGVector运算符: <=> 余弦距离最适合文本搜索3.关键技术点:

•统一Embedding模型•正确的空值判断•XML特殊字符转义

技术栈总结

MyBatis Plus: 数据访问层PGVector: 向量存储和检索阿里云Embedding: 文本向量化Spring AI: 统一封装

学习建议: 动手执行批量向量化,用不同查询词测试搜索效果,直观感受语义检索的魅力!

References

[1] SpringAI实战-6-Embedding向量基础: ./SpringAI实战-6-Embedding向量基础.md[2] SpringAI实战-6.2-安装pgVector: ./SpringAI实战-6.2-安装pgVector.md[3]: http://localhost:8080/doc.html