Spring AI Alibaba + RAG 实战：知识库检索模块从设计到落地

Spring AI Alibaba RAG 实战知识库检索模块从设计到落地混合检索 幂等入库 动态权重这是 AI 客服知识库能跑稳的核心与上一篇的关系上一篇讲了 AI 客服系统的整体架构——情绪感知、意图识别、Agent 工具链。这篇是那篇的续集专门讲RAG 知识库模块的设计与实现。如果你没看过上一篇这里先补一张对比表让你知道 RAG 模块在整个系统里处于什么位置上一篇已有的本篇新增的情绪感知EmotionAnalyzer文档摄入管线Ingest Pipeline意图识别IntentClassifier多格式文档解析PDF / MD / TXT / WordAgent 工具链订单退款向量检索 关键词倒排双路并行Redis 会话缓存RRF 混合检索融合排序MyBatis-Plus 数据访问searchWithScore()相似度评分扩展多模块 Maven 架构动态检索权重system_config 表控制一、RAG 模块在整体架构中的位置先回顾一下整体请求链路RAG 是其中的一个分支用户问题 → ChatController → ConversationService会话管理 → 意图识别 → 命中 RAG 意图 → HybridSearchService混合检索 ├── PgVectorKnowledgeStore向量检索语义相似度 └── RedisKeywordIndex关键词倒排索引jieba 中文分词 → 构建 System Prompt含检索到的 context → ZhipuAI / Ollama 生成回答核心代码在ai-csr-rag模块下检索层 入库层 索引层三个组件各自独立、职责清晰互不耦合。二、文档摄入管线Ingest Pipeline用户上传知识库文档之后系统需要把它切块、生成向量、建索引这一套流程就是摄入管线。2.1 整体流程文档上传 → MultiFormatDocumentLoader支持 PDF / TXT / Markdown / Word → TokenTextSplitter按 token 分块默认 500 → PgVectorKnowledgeStoreOllama 生成 embedding写 pgvector → RedisKeywordIndexjieba 分词建立 Redis 倒排索引 → KnowledgeDocument 状态更新为 READY2.2 几个关键的设计决策多格式统一入口不同格式文档的解析逻辑差异很大——PDF 要提取正文并清洗特殊字符Markdown 要去掉语法标记Word 要处理样式嵌套。MultiFormatDocumentLoader统一对外暴露一个接口内部按文件类型分派具体解析器上层调用方不用关心格式细节。每个 Chunk 独立持有 metadata这里有个不起眼但很重要的细节分块时必须给每个 chunknew HashMap(doc.getMetadata())而不是直接复用父文档的 metadata 引用。为什么因为如果共享同一个 Map多个 chunk 写chunk_index时会互相覆盖最后所有 chunk 的chunk_index都变成同一个值入库触发唯一约束冲突。这个坑我踩过留到踩坑篇细讲。幂等写入PgVectorKnowledgeStore.add()在入库前先按document_idDELETE 旧数据再配合ON CONFLICT DO NOTHING写入。这样重复 ingest 同一份文档不会报错也不会留下重复数据。线上知识库更新文档是高频操作幂等是必须的。三、混合检索Hybrid Search这是整个 RAG 模块最核心的部分。3.1 为什么要混合而不是单纯向量检索纯向量检索在语义相似的场景很好用但有个明显短板用户问退款状态是 PENDING 是什么意思向量检索会把语义相近的内容都召回来但PENDING 是精确词——这种场景关键词检索命中率反而更高。反过来纯关键词检索应对近义词、缩写、语义跨度大的问法就不行了。所以两条路都要走再融合排序这就是混合检索的出发点。3.2 检索流程查询请求 ├── 语义路Ollama embedding → pgvector cosine 检索 → TopK 结果 similarity score └── 关键词路jieba 分词 → Redis 倒排索引命中 → TopK 结果 → RRF 融合k60→ 统一排名列表两路并行互不阻塞最后用RRFReciprocal Rank Fusion做融合排序。RRF 的公式很简单每个文档在两路结果里分别有排名把1/(k rank)加起来就是最终得分k60 是经验值能平衡两路结果的权重差异。3.3 动态权重配置# 不在 yml 里写死在 system_config 表里动态控制rag.keyword_weight 0.4 rag.vector_weight 0.6keyword_weight和vector_weight从system_config表里读不重启服务就能调整检索策略。这个设计在灰度调参时非常好用——先把 keyword_weight 调高跑几天看召回质量不满意再往回调不用打包发版。配置项说明推荐起始值rag.keyword_weight关键词检索在融合中的权重0.4rag.vector_weight语义检索在融合中的权重0.6rag.top_k每路各取 TopK 结果5rag.similarity_threshold语义相似度过滤阈值0.53.4 相似度评分扩展Spring AI 的VectorStore.similaritySearch()默认不返回相似度分数只返回文档列表。但 RRF 融合需要分数来排序所以这里做了扩展新建SearchHitDTO包含document和score两个字段在PgVectorKnowledgeStore里新增searchWithScore()方法通过向量内积计算余弦相似度回填到SearchHit.score扩展之后每条检索结果都带着similarity字段既能用于 RRF 融合也能在 System Prompt 里标注置信度让大模型知道这条知识的可靠程度。四、Session 会话管理多轮对话不是独立的前几轮的上下文要带进来大模型才能理解你刚才说的那个订单指的是哪一个。SessionService维护USER / ASSISTANT / SYSTEM三种角色消息记录每轮对话结束后追加写入下一轮检索时一并注入 System Prompt。支持历史回溯和滑动窗口截断避免上下文过长撑爆 token 限制。五、当前系统状态模块状态备注文档摄入PDF / TXT / MD✅ 正常12 个 chunkembeddings 全入库向量语义检索✅ 正常相似度 0.55–0.63 区间命中关键词倒排检索✅ 正常jieba NPE 已修复fallback 兜底混合检索 RRF 融合✅ 正常双路召回k60 融合会话管理✅ 正常USER / ASSISTANT 消息写入正常Ollama 本地模型✅ 正常bge-large-zh-v1.5 向量模型就绪六、后续计划已完成Spring AI Alibaba 集成智谱 GLM-4情绪感知模块意图识别模块Agent 工具链订单查询、退款申请订单查询服务MyBatis-Plus退款申请服务RAG 知识库模块文档上传 → 向量入库 → 检索问答正在做多轮对话记忆优化转人工功能自动转接 手动转接后面要做知识库运营后台客服工作台人工接待数据统计与监控大屏源码怎么拿公众号「亦暖筑序」底部菜单【获取源码】完整的 Gitee 仓库直接拉。源码里除了文章提到的这些还有几个文章没展开的数据库初始化脚本5 张表带模拟数据跑起来就能测完整的多模块 pom 依赖配置不用自己一个个试版本了情绪分析 / 意图识别的完整 Prompt 模板文章里只是核心片段源码里是完整可运行的说白了吧看完文章理解思路拿到源码照着跑这才是最省时间的路径。不拿源码硬看你会卡在这行代码放哪个模块这种低级问题上浪费半天。 想继续聊的你在项目里有没有遇到过检索能命中但回答驴唇不对马嘴的情况大概率是 Prompt 里的 context 注入方式有问题或者 chunk 切分粒度没调好。评论区说一句下篇可以专门讲这个。RAG 知识库踩坑复盘五个真实 Bug已经写好了关注等更新。