说实话，现在大模型是火得一塌糊涂，但真正要把这玩意儿落地到业务里尤其是企业级的客服场景，没点真功夫还真不行。大家dou在聊 RAG，好像搭个架子就Neng跑，可真到了线上，你会发现全是坑：要么是检索出来的东西驴唇不对马嘴，要么是geng新个文档还得重启服务，简直让人头大。

今天咱们就不整那些虚头巴脑的理论了直接来点硬核的。基于 Spring AI Alibaba 框架，我手把手教你如何搭建一个真正“Neng打”的知识库检索模块。这不仅仅是调个 API 的事儿，我们得深入到骨髓里kankan怎么解决语义鸿沟、怎么搞定幂等入库，还有那个让人又爱又恨的混合检索策略。

刚开始搞 RAG 的时候，hen多人dou有个误区：觉得有了 Embedding 向量，就Neng一招鲜吃遍天。确实向量检索在处理语义相似的场景时表现简直惊艳。比如用户问“怎么退款”，系统Neng把“退货流程”给召回来这hen棒。

但是现实往往hen骨感。你想想这种场景：用户问“退款状态是 PENDING 是什么意思”。这时候，纯向量检索就有点“傻”了。它会把语义相近的内容，比如“退款审核中”、“等待处理”dou召回来。这听起来没问题？不问题在于“PENDING”这个词。在hen多业务系统里这是一个精确的枚举值，用户就是盯着这个词问的。向量检索虽然懂语义，但它对这种精确的关键词命中率，反而不如老掉牙的关键词检索。

反过来Ru果你只靠纯关键词检索，那应对近义词、缩写，或者那些语义跨度hen大的问法，立马就不行了。用户问“电脑蓝屏咋整”，关键词检索得匹配到“蓝屏”二字，Ru果用户写的是“屏幕变蓝了没反应”，传统检索可Neng就抓瞎了。

所以结论hen明确：想要构建一个高可用的知识库，这两条路必须dou得走，Zui后还得把它们巧妙地融合在一起。这就是我们常说的混合检索。

在 Spring AI Alibaba 的实战里我们的检索链路被设计成了两条并行的轨道，互不干扰，Zui后汇合。

一条路是“语义路”：用户的问题先经过 Ollama 生成 Embedding，然后去 pgvector Zuo余弦相似度检索，捞出 TopK 的结果，而且每条结果dou得带上 similarity score。

另一条路是“关键词路”：用 jieba 分词把用户的问题切开，去 Redis 的倒排索引里精准匹配，同样捞出 TopK 结果。

这里有个不起眼但超级重要的细节：Spring AI 原生的 VectorStore.similaritySearch 默认是不返回相似度分数的，只给个文档列表。这可不行，因为我们要Zuo融合，没分数怎么排？所以这里必须得Zuo ，让每条检索结果dou带着 similarity 字段。这字段有两个用处：一是给 RRF融合算法用，二是我们Ke以把它塞进 System Prompt 里告诉大模型这条知识的置信度有多高，让它回答的时候心里有数。

Zui后两路结果怎么合体？用 RRF。这公式其实挺简单的，就是kan每个文档在两路结果里的排名，把 1/ 加起来就是Zui终得分。这里的 k=60 是个经验值，Nenghen好地平衡两边的权重差异。这样，既照顾了语义的广泛性，又抓住了关键词的精确性。

光会检索还不行，数据怎么进来的？这涉及到摄入管线。用户上传一个文档，系统得把它切块、生成向量、建索引，这一套流程必须得丝滑。

我们的核心代码在 ai-csr-rag 模块下分成了检索层、入库层、索引层。这种设计的好处是职责清晰，互不耦合，以后维护起来也轻松。

文档上传后第一步是分块。我们用的是 TokenTextSplitter，按 token 切分，默认大小是 1000。这里有个我踩过的血泪坑，一定要听好了：分块时必须给每个 chunk new HashMap<>)，千万别直接复用父文档的 metadata 引用！

为啥？因为Ru果你共享同一个 Map，当多个 chunk 写 chunk_index 这种元数据时它们会互相覆盖。结果就是所有 chunk 的 chunk_index dou变成了同一个值。等你入库的时候，唯一约束冲突直接报错，让你怀疑人生。这个坑我之前专门写过复盘，真的太隐蔽了。

线上知识库geng新文档是高频操作。运营同学手抖点了两下上传，或者系统重试，怎么办？Ru果我们的入库逻辑不支持幂等，那库里全是重复数据，检索质量直接爆炸。

kankan PgVectorKnowledgeStore.add 的实现，它在入库前会先按 document_id DELETE 旧数据，然后再配合 ON CONFLICT DO NOTHING 写入。这招太稳了。这样重复 ingest 同一份文档既不会报错，也不会留下垃圾数据。这就是企业级代码该有的严谨。

为了方便使用，我们还设计了多格式统一入口。不管是 PDF、Word 还是 Markdown，dou走这一套逻辑。提取文档的文件名作为元信息，这样后续检索的时候，Nenggeng精确地定位到来源文件，排查问题也方便。

系统上线了不代表就完事了。我们得根据用户的反馈不断调优。比如发现关键词检索效果不好，想提高向量检索的权重，怎么办？

传统的Zuo法是改 application.yml，然后重新打包、发版、重启服务。这在互联网公司简直是不可接受的慢。

我们的设计是：把 keyword_weight 和 vector_weight 放到 system_config 表里。代码里直接读数据库配置，而不是读死文件。这效果立竿见影——不重启服务就Neng调整检索策略。灰度调参的时候特别好使：先把 keyword_weight 调高跑几天观察召回质量，不满意再往回调，整个过程对用户无感。

# 不在 yml 里写死，在 system_config 表里动态控制
rag.keyword_weight = 0.5
rag.vector_weight = 0.5

单轮问答好Zuo，多轮对话难搞。用户说“那个订单怎么还没到？”，AI 得知道“那个订单”指的是上一轮对话里的 ID。

这就需要 SessionService 出场了。它维护着 USER / ASSISTANT / SYSTEM 三种角色的消息记录。每轮对话结束后我们会把记录追加写入。下一轮检索的时候，把这些历史信息一并注入到 System Prompt 里。

当然也不Neng无限制地往里塞，不然 token 撑爆了谁也受不了。所以这里用了滑动窗口截断机制，保证上下文在可控范围内，既Neng让大模型理解“你刚才说的那个订单”，又不会因为上下文过长导致响应变慢。

回顾一下构建一个靠谱的 RAG 知识库，真的不仅仅是调个 similaritySearch 那么简单。从混合检索与 RRF 融合，到分块时的元数据深坑，再到入库的幂等性设计和动态权重调优，每一个环节dou藏着细节。

说白了吧，kan完文章理解思路，拿到源码照着跑，这才是Zui省时间的路径。不拿源码硬kan，你可Neng会卡在“这行代码放哪个模块”这种低级问题上浪费半天。

这套方案——混合检索 + 幂等入库 + 动态权重，就是 AI 客服知识库Neng跑稳的核心。Ru果你在项目里遇到过“检索Neng命中，但回答驴唇不对马嘴”的情况，大概率是 Prompt 里的 context 注入方式有问题，或者 chunk 切分粒度没调好。

技术这条路，坑总是踩不完的，但填坑的过程就是成长的过程。希望这篇实战经验Neng帮你少走点弯路，让你的 AI 助手早日成为业务上的得力干将。

💬 想继续聊的

关于 RAG 知识库踩坑复盘我Yi经整理好了里面还有geng多关于 PgVector 和 Redis 配合的细节。Ru果你对 Spring AI Alibaba 感兴趣，或者正在搭建自己的私有知识库，不妨关注一下咱们下期继续深挖。