我要投稿

搭建AI知识库踩了37个坑，血泪总结这套避雷手册

发布日期：2025-06-09 21:08:35 浏览次数： 1526 作者：林生说AI

大家好呀，我是林生。AI落地企业实战的系列文章我终于写完了（可见往期文章），最近准备给自己开个新坑，来写写在实战中遇到的一些具体的坑点，讲讲都是怎么解决的。

想了一下，在企业中用Confluence的人比较多，就从基于Confluence来搭建AI知识库开始吧。

记得老板找我的时候，是这么说的：

"小林，咱们公司这么多年积累了不少技术文档，都在Confluence里躺着。这些都是公司的数字资产，但说实话，除了当时写的人，很少有人会主动去翻这些资料。新人更是不知道从哪开始看。我们得想想怎么盘活这些数字资产。

你看能不能做个基于Confluence的问答平台？嵌入到Confluence中去，大家直接点击就能问问题，或者让它帮忙梳理学习路径。"

我当时第一反应是：这事儿除了我，公司还真没人能干。就答应了。

项目是直接计入绩效考核，KPI定得很明确：响应时间<5秒，用户满意度>90%，并发用户>30人。压力不小，但是技术路线还算清晰：Confluence支持iframe嵌入网页，RAGFlow可以通过API暴露机器人服务。

三个月下来总算交差了，分享下踩过的坑和最终的解决方案。

dify：第一个被淘汰的选择

一开始选了Dify，最初的考虑是它与coze空间类似，而coze我熟悉，用Dify 应该部署验证也快，最主要是它支持私有化部署，界面友好，网上教程多，看起来应该上手难度不大。

结果一测试就发现致命问题：响应时间根本达不到要求。每个问题都要在工作流里转一圈：检索→重排→总结→生成，单个问题10-20秒是常态，完全达不到5秒的KPI要求。

更要命的是回答质量不稳定：

• 明明文档里有的内容，经常检索不到
• 有时候开始胡编乱造，一本正经地瞎说
• 普通问题检索准确率测试下来只有65%左右，复杂问题更是一塌糊涂

Dify直接被pass了。

RAGFlow：一坑又一坑，坑坑不相同

接着从兄弟部门了解到，他们在用 RAGFlow 做 RAG。RAGFlow 是专门做文档理解，API响应也快，于是就决定试试。

部署环节的坑：

那天晚上加班到9点多，整层楼就我一个人。想着赶紧装上测试，结果在Windows上通过源码安装，安装是安装成功了，可是进入UI界面开始就是各种报错，Python环境搞得一团糟。折腾到快10点才放弃，第二天重新用Docker重新搭。

版本敏感性的坑：

这个最要命！同样的配置，不同版本效果天差地别：最开始我花了几天部署的 v0.17.2版本，在检索准确率上可以达到 85%，回答质量还行；后面新版本出来了，是 v0.18.0，看版本说明上RAG准确性上会有提升，结果吭哧吭哧的升级上去，什么配置和模型都不变的情况下，检索准确率竟然掉到70%不到，回答明显下降。吓得我赶紧回退了版本。再测试，看到了基准测试的可靠数据后，才算松了口气。

血泪教训呀，从此一段时间，我版本锁死，非必要绝不随便升级。

模型一致性的坑：

最开始，我从最优化角度利用设备显存的角度出发，设置不同模型在 RAGFlow 的不同阶段，比如资料拆分入知识库的时候选用的大语言模型就与最后问答时设置的大语言模型不同，让前者的上下文长度大于后者，以保证在问答时能有足够的显存支持并发。结果测试答非所问，问了几十个问题，准确率不到40%。

我赶紧将 RAGFlow 各个阶段用到的问答模型设为同一个，这时候回答的准确性才上去了。

后来才知道：知识库构建和问答必须用同一个模型！重新用Qwen构建知识库后，准确率提升到85%。

大模型框架选择：性能对比实测数据

RAGFlow搞定后，还要选择大模型服务框架。我把三个主流框架在我们的硬件环境下都测试了一遍：

Ollama的测试最为简单，其结果如下：

• 并发能力：<10用户，超过就明显开始变慢
• 响应速度：单用户2-3秒，还行，多了就明显耗时变长，回复质量变差
• 资源占用：24GB显存，内存16GB
• 适用场景：开发测试，生产环境不够用

Xinference要进行简单配置，它的测试结果如下：

• 并发能力：20用户左右，还可以接受
• 响应速度：也还行，比ollama 稍快，有2-4秒，有波动
• 资源占用：可以进行动态量化，32GB内存可以跑70B模型
• 配置复杂度：参数太多，光看文档就头晕

VLLM看介绍是当前最好的框架，测试结果如下：

• 并发能力：轻松达到40+用户，完全满足需求
• 响应速度：1-2秒，极快
• 资源占用：48GB显存，太吃显存了，但利用率高
• 唯一问题：动态并发显存占用优化到现在还没完美解决

最终选了VLLM，主要是在大并发情况下，仍然能达到极快的响应速度。缺点也很明显，就是太吃显存了，但是当前一台机器给它独占，还是完全够用的。后续在考虑如何进行显存的优化吧。

小插曲：差点把老板搞放弃的一次汇报

项目进行到一半的时候，我去汇报进度。我说："系统基本跑起来了，但有个问题：不能完全禁止大模型的臆断。就是RAG只查到部分有效信息时，为了让回复链条完整，大模型会自己编一些内容，来保证逻辑的自洽性。"

老板当时就破防了："什么？臆构数据？那开发人员用了虚假信息怎么办？这样大家还会信任这个系统吗？"

我当时也很无奈，大模型就是有这个问题，顿时感觉这问题可能没法解决。

结果下周汇报时，我说："问题解决了。通过三种方法解决的：1是升级大模型，选用更聪明的大模型；2是进行严格的提示词约束；3是要求AI回复时必须带上数据来源链接，用户可以直接跳转查看原文档。通过多种手段，最终实测幻觉率从15%降到了3%以下。"

老板这才放心。

相关提示词如下：

感兴趣的读者朋友可以自行参考。

数据清洗：最耗时耗力的部分

Confluence文档导出有多种格式，我都一一进行了测试，效果最好的是 Markdown,次之的是Word,再次之就是PDF，最差就是图片了。

为了保证数据源被识别的可靠性，我将所有从Confluence上导下来的文档全部转换成立Markdown格式。但是不是Markdown格式就万事大吉了，Markdown还是有很多坑要消除的。比如说：空行问题，如果空行过多的话，在RAGFlow 进行文档分块时，会产生空白块，而RAGFlow在进行分块时有用大模型进行块的初次语义分析，这时候，如果是空的块，会导致文档分块解析直接卡死，你到时候会发现很多莫名其妙的问题，并且也不好排查，所以在数据处理时，最好将多行空格直接删掉，或是只保留一行。

另外类似的问题还有图片链接问题，超链接问题，这在本地部署时，基本不能进行访问，会导致很常见的分块问题。也通常需要进行处理。除此之外还有代码块格式问题，表格问题等等。

为了一次性解决这些问题，我专门写了个小工具，能够一键下Confluence上的指定空间全部文档，然后转换成Markdown格式，然后自动的对其进行数据清洗，来解决这些工作量又大又头痛的问题。

但是你不要以为这样就万事大吉了。后面还有坑么，就非得人工介入审核了。这就是原始文档自身质量的问题。我们发现有些文档写得很随意，甚至是逻辑混乱；有些文档由多个版本并行；有些文档就纯粹是想到什么就记录什么，有些文档就只有一张图片，甚至一句话；更多的是对相同对象的描述，术语也不统一，导致语料极差。这块才是数据清洗的重点，也是人力投入最多的地方。因为数据源头如果质量不高，噪音太多，那么工具再好，效果也不会好到哪去。到头来还会被说工具不好用，真垃圾。

参数调优：纯体力活但必须做

这是最耗时间的环节，每个参数都要反复测试。

最开始是分块大小的测试。最初我采用1024 tokens的长度，觉得块越大，多语义的理解也最准确，回答概念问题应该也最好，事实上也是这样，能检索精度80%，但是对于FAQ问题简短问题上，效果反而不好了，因为太长的块，导致了理解精准数据上的泛化。
接着我采用512 tokens的块，这时候在语义理解上和简短问题理解上的能力达到了个平衡：检索精度达到85%，答案完整度也在95%左右，测试OK。
我接着试了更小的256 tokens，确实他在FAQ类问题上表现很好，但是对于需要回复很长的问题，往往需要跨几个块来拼接知识时，效果就变差了，答案经常不完整。PASS

同样的我有对其他的参数，比如提示引擎、模型参数等都进行了定变量，单点测试，直到得出自己满意的数据。

最终我的配置方案是：

- 提示引擎:
  - 相似度阈值: ~0.5
  - 关键字相似度权重: ~0.6
  - Top N: ~8
- 模型设置:
  - 温度: 0.1
  - Top P: 0.3
  - 存在处罚: 0.2
  - 频率惩罚: 0.3

这套配置在我们场景下效果最好，响应时间基本能做到秒回，调研的用户满意度达到85%，用户检索的准确率达到83%，并发也能达到预期，又不占用太多的显存。

还没完全解决的问题

说实话，到目前上线为止，还有些问题，我还没完美的进行解决：1是VLLM动态并发调优，2是知识库更新同步。

对于VLLM动态并发调优，通常启动VLLM时，他就会预先分配一大块显存用于KVCache的预空间，一旦有用户询问时，其能保证大模型的即时回复，但是弊端也很明显，就是不管人多人少，这块显存它一直占着，不能被释放，导致事实上的空余显存不能给其它应用用。这块也始终没找到完美的动态调节方案。如果有朋友知道怎么搞，求指教。

其次是知识库更新同步，当前采用的是手动更新，还没实现Confluence文档变更的自动同步。这块还需要进一步的开发。