WeKnora 本地部署实战：从零搭建开源知识库问答系统

知识库问答系统这件事，我前前后后搭过不下五套。从最早的纯手工向量检索，到后来用各种框架拼装，每次都在“部署复杂度”和“效果可用性”之间反复横跳。直到最近把 WeKnora 在本地跑通，才算是找到了一个平衡点——它把文档解析、向量化、检索、生成这条链路打包得比较完整，同时又是开源的，数据完全留在自己机器上。这篇文章就把我从零部署到实际跑通问答的完整过程拆开讲，包括中间踩过的坑、参数怎么调、以及为什么某些环节要那样设计。如果你手头有一堆内部文档想做成能问答的知识库，又不想把数据传到别人服务器上，这套方案值得花一个下午试试。

1. 先搞清楚 WeKnora 到底解决了哪几个具体问题

很多人看到“AI 知识库”这个词，第一反应是“不就是把文档扔进去然后问问题吗”。但真正动手做过的人知道，这里面至少藏着四件独立的事：文档得先能读进来、读进来之后得切成合理的片段、片段得变成向量存到某个地方、提问的时候得先找到相关片段再让模型组织答案。这四件事任何一件没处理好，最终问答效果都会打折扣。

WeKnora 是腾讯微信团队开源的一套知识库问答系统，它的定位不是“又一个向量数据库”，也不是“又一个 RAG 框架”，而是把上面这四件事串成一条可用的流水线。你给它一批文档，它负责解析、切片、向量化、存储、检索、生成，最后通过一个接口或者界面把答案吐出来。对于不想从零造轮子的人来说，这个封装程度刚好——既不会像某些商业产品那样完全黑盒，也不会像纯框架那样什么都要自己接。

1.1 它和直接用 Dify 或 FastGPT 有什么区别

热词里出现了“weknora dify”，说明不少人会拿它和 Dify 对比。我两个都实际部署过，说下真实感受。Dify 更像一个 AI 应用开发平台，工作流、Agent、工具调用这些能力很全，知识库只是它其中一个模块。而 WeKnora 是专门为知识库问答这个场景做的，它在文档解析的细粒度、检索策略的调优空间上更聚焦。

具体来说，Dify 的知识库模块在处理复杂格式文档时，切分策略相对固定，你很难针对某类文档做深度定制。WeKnora 在文档解析阶段给了更多可干预的点，比如不同格式走不同的解析器、切片长度和重叠度可以按文档类型分别配置。如果你的场景就是“一堆文档 + 问答”，不需要复杂的工作流编排，WeKnora 的链路更短、更直接。反过来，如果你需要问答之后触发其他动作、或者要接多个工具，那 Dify 的编排能力更合适。

1.2 本地部署的核心价值在哪里

把知识库系统部署在本地，最直接的好处是数据不出内网。对于企业内部文档、技术资料、客户资料这类内容，上传到外部服务总归有合规上的顾虑。本地部署之后，文档解析、向量化、检索全在自己机器上完成，只有最终调用生成模型那一步需要外部 API——而这一步如果你有本地推理环境，也可以完全离线。

另一个价值是可调试性。线上服务出问题你只能看日志，本地部署你可以直接进容器看文件、查数据库、手动调检索接口。我在调试切片策略的时候，就是直接连上向量库看每个片段的内容，才发现某些 PDF 解析出来全是乱码，这种问题在纯黑盒服务里很难定位。

2. 部署前的环境准备：哪些东西必须提前确认

部署这类系统，最怕的就是跑到一半发现某个依赖版本不对。我这次用的是 Docker Compose 方式，整体流程比较顺，但有几个前置条件必须提前确认好，否则后面会卡住。

2.1 硬件与操作系统的最低要求

WeKnora 本身对机器要求不算高，但因为它要跑文档解析和向量化，内存和磁盘要留够。我实测下来，最低配置建议是 4 核 CPU、8GB 内存、50GB 可用磁盘。如果文档量大或者要处理大量 PDF 和图片，内存建议上到 16GB，磁盘按文档总量的三到五倍预留——因为解析过程中会产生中间文件，向量库本身也占空间。

操作系统方面，Linux 是最顺的，Ubuntu 22.04 和 Debian 12 我都试过，没遇到系统层面的问题。Windows 下用 WSL2 也可以，但文件挂载的性能会差一些，文档量大时解析速度明显变慢。macOS 上 Docker Desktop 跑起来没问题，但要注意 Apple Silicon 和 x86 的镜像架构差异，部分依赖镜像可能需要指定平台。

2.2 Docker 与 Docker Compose 的版本坑

热词里有“docker compose 安装”和“cannot start docker compose application”，说明不少人在这一步卡住。我用的版本是 Docker 26.x 配合 Docker Compose v2，这是目前比较稳的组合。需要注意的是，Compose 有 v1 和 v2 两个大版本，命令从docker-compose变成了docker compose（中间是空格不是横杠）。如果你照着老教程敲命令发现找不到，大概率是版本对不上。

安装完之后一定要验证：

docker --version docker compose version

两条命令都能正常输出版本号才算准备好。另外，当前用户要能直接执行 docker 命令，不需要 sudo。如果没有加入 docker 用户组，后面 Compose 启动时会报权限错误。加组的命令是：

sudo usermod -aG docker $USER

执行完要重新登录一次才生效。这个细节很多人会忽略，然后对着权限报错排查半天。

2.3 模型服务的准备：嵌入模型和生成模型

WeKnora 的流水线里有两个模型位置：一个是嵌入模型，负责把文本片段变成向量；另一个是生成模型，负责根据检索到的片段组织答案。嵌入模型我推荐用 BGE-M3，热词里也出现了“bge-m3 docker compose 部署”，说明这个组合比较常见。BGE-M3 对中文支持好，而且能同时处理稠密向量和稀疏向量，检索效果比单一向量模式更稳。

生成模型可以用外部 API，也可以用本地推理。如果走 API，需要提前准备好对应的密钥和接口地址。如果本地跑，显存至少要 8GB 以上才能跑得动 7B 级别的模型。我这次为了验证完整链路，生成模型用的是外部 API，嵌入模型用本地部署的 BGE-M3，这样既保证了检索效果，又降低了本地资源压力。

3. 拉取代码与配置文件的关键改动

环境准备好之后，就可以拉代码了。WeKnora 的仓库结构比较清晰，配置集中在几个文件里，改完之后用 Compose 一把启动。

3.1 代码拉取与目录结构速览

git clone <仓库地址> cd weknora

拉下来之后先别急着启动，花两分钟看一下目录结构。核心的几个目录是：docker下面放的是 Compose 文件和各个服务的配置，config下面是应用层的配置模板，data是运行时数据挂载点。理解这个结构之后，后面改配置就知道该动哪个文件。

我建议先把config目录下的示例配置复制一份改成实际配置，而不是直接改示例文件。这样后面升级或者重新部署的时候，原始示例还在，方便对比。

3.2 环境变量里必须改的几项

配置文件里有一批环境变量，大部分可以保持默认，但有几项必须改成你自己的值，否则服务起不来或者跑不通。

这里重点说下嵌入模型地址。如果你用 Compose 一起启动 BGE-M3，服务名就是容器名，直接用服务名做主机名即可，Docker 内部网络会自动解析。如果你把 BGE-M3 部署在宿主机上，那地址要写成宿主机的内网 IP，不能用 localhost——因为容器里的 localhost 指向容器自己。

3.3 Compose 文件里我调整过的两处

默认的 Compose 文件基本能用，但我根据自己机器的情况调了两处。第一处是资源限制，给解析服务和向量化服务分别加了内存上限，防止某个文档解析卡死把整机内存吃满。第二处是数据卷映射，把数据目录映射到了一个大容量磁盘上，而不是默认的项目目录。

services: parser: deploy: resources: limits: memory: 4G embedding: volumes: - /data/weknora/models:/models

资源限制这个事，机器配置高的时候感觉不到，但一旦遇到一个几百页的 PDF，解析进程内存飙升，没有限制的话可能触发系统 OOM，把其他服务也带崩。加个上限，最坏情况只是这个文档解析失败，不影响整体服务。

4. 启动服务与验证链路是否真正跑通

配置改完之后，就可以启动了。但“启动成功”和“链路跑通”是两回事，很多人看到容器都起来了就以为完事了，结果一问问题就报错。这一节把启动和验证分开讲。

4.1 启动顺序与日志观察

docker compose up -d

加-d是后台启动。启动之后不要马上就去访问界面，先看日志：

docker compose logs -f

重点观察三个服务的日志：向量库是否正常初始化、嵌入模型是否加载完成、应用服务是否连上了向量库和嵌入模型。嵌入模型加载比较慢，尤其是第一次启动要下载模型文件，可能要等几分钟。日志里出现类似“model loaded”或者“server started”的字样才算就绪。

如果某个服务反复重启，先看它的日志最后几行。常见的问题是端口冲突、挂载路径权限不对、或者环境变量里地址写错。我遇到过一次是数据目录权限问题，容器里的进程没有写权限，导致向量库初始化失败。解决办法是把宿主机上对应目录的权限放开，或者指定容器内运行的用户 ID。

4.2 用一条真实文档验证完整链路

服务都起来之后，先别急着灌大量文档。找一篇结构清晰的文档，比如一份产品说明或者技术文档，先走一遍完整流程。上传之后观察几个点：文档是否被正确解析成文本、切片数量是否合理、向量是否成功写入。

我一般会先传一篇 Markdown 文档，因为它的结构最清晰，解析出问题的概率最低。确认 Markdown 能跑通之后，再传 PDF 和 Word，逐步增加复杂度。如果一上来就传扫描版 PDF，解析出问题你很难判断是解析器的问题还是切片的问题。

验证检索是否正常，可以直接调检索接口，给一个关键词，看返回的片段是否相关。这一步很关键，因为如果检索返回的片段不相关，后面生成模型再强也答不对。我调试的时候就是先确保检索命中率，再去看生成质量。

4.3 问答效果不理想时的排查顺序

问答效果差，原因可能出在链路的任何一个环节。我的排查顺序是这样的：先看检索返回的片段是否包含答案，如果不包含，问题在解析或切片或向量化；如果包含但生成答案不对，问题在生成模型的提示词或参数。

检索不相关，最常见的原因是切片太长或太短。切片太长，一个片段里混了多个主题，向量表示不聚焦；切片太短，上下文丢失，检索到的片段缺少必要信息。我一般会把切片长度设在 300 到 500 字之间，重叠 50 到 100 字，具体根据文档类型微调。技术文档可以短一些，叙述性文档可以长一些。

生成答案不对，先检查提示词里有没有明确要求“只根据提供的片段回答”。如果不加这个约束，模型可能会用自己的知识编答案，看起来合理但实际是错的。另外，生成模型的温度参数建议调低，知识库问答场景不需要创造性，稳定准确更重要。

5. 文档解析与切片策略的实战调优

链路跑通只是第一步，真正决定问答质量的是文档解析和切片这两个环节。这部分没有一劳永逸的配置，必须根据你的文档类型来调。

5.1 不同格式文档的解析差异

Markdown 和纯文本最好处理，结构清晰，解析基本不会丢信息。Word 文档要注意表格和图片，表格如果被当成普通文本解析，结构会乱掉，检索时很难命中。PDF 是最麻烦的，文字版 PDF 还好，扫描版 PDF 必须走 OCR，而 OCR 的准确率直接影响后续所有环节。

我的做法是先把文档按格式分类，文字版 PDF 和 Word 走常规解析，扫描版 PDF 单独走 OCR 流程。WeKnora 的解析配置里可以针对不同格式指定不同的解析器，这个灵活性比很多同类系统要好。如果某类文档解析效果一直不好，可以考虑在入库前先人工转成 Markdown，虽然多了一步，但后续检索质量会明显提升。

5.2 切片长度与重叠度的取舍逻辑

切片策略的核心矛盾是：切片越长，上下文越完整，但向量表示越不聚焦；切片越短，向量表示越精准，但可能丢失上下文。我实测下来，对于技术文档和产品说明，400 字左右的切片配合 80 字重叠效果比较均衡。对于叙述性强的文档，比如会议纪要，可以放宽到 600 字。

重叠度的作用是防止答案刚好被切在边界上。比如一个关键句子被切成两半，前半段在一个片段末尾，后半段在下一个片段开头，检索时可能两个片段都命中但都不完整。有了重叠，边界处的信息会在两个片段里都出现，降低漏检概率。重叠度一般设成切片长度的 15% 到 20% 比较合适。

5.3 元数据标注对检索的隐性提升

这是一个很多人会忽略的点：给文档片段加上元数据，比如来源文件名、章节标题、文档类型，检索时可以结合这些信息做过滤或加权。比如你问一个关于“部署”的问题，如果片段带有“部署”相关的章节标题，它的相关性得分可以适当提高。

WeKnora 支持在入库时保留文档的结构信息，我在配置里开启了章节标题提取，这样每个片段都知道自己来自哪个章节。实测下来，对于结构清晰的文档，这个功能对检索准确率的提升比较明显。尤其是当文档里有多个相似主题时，章节信息能帮助区分。

6. 检索策略与生成环节的配合调参

检索和生成是问答系统的最后两环，也是最直接影响用户体验的两环。这两环的参数需要配合调整，单独调一个往往效果有限。

6.1 向量检索与关键词检索的混合模式

纯向量检索的优点是语义匹配能力强，你问“怎么部署”它能找到“安装步骤”相关的片段。但它的缺点是对精确匹配不敏感，比如你问一个具体的错误码，向量检索可能找不到包含这个错误码的片段。这时候就需要关键词检索来补充。

BGE-M3 的一个优势是它同时输出稠密向量和稀疏向量，稠密向量负责语义匹配，稀疏向量负责关键词匹配。WeKnora 的检索配置里可以开启混合模式，把两种检索的结果融合。我实测下来，混合模式在技术文档场景下比纯向量模式命中率高不少，尤其是涉及具体名词和编号的问题。

融合的时候有个权重参数，控制语义匹配和关键词匹配的占比。默认值一般是各占一半，但如果你的文档里专业术语多，可以适当提高关键词匹配的权重。这个参数需要根据实际问答效果来调，没有固定最优值。

6.2 重排序模型要不要加

检索返回一批候选片段之后，可以再加一个重排序模型，对候选片段做更精细的相关性打分。重排序模型比向量检索慢，但准确率更高。加不加取决于你的场景：如果候选片段数量不多，比如只取前 5 个，那重排序的提升有限；如果取前 20 个再重排取前 5 个，效果会更好。

我的做法是候选取 15 到 20 个，重排序之后取前 5 个送给生成模型。这样既保证了召回率，又控制了送给生成模型的上下文长度。重排序模型我用的也是 BGE 系列的，和嵌入模型同源，配合起来比较顺。

6.3 生成模型的提示词模板设计

提示词模板决定了生成模型怎么利用检索到的片段。一个基本的模板包含三部分：角色设定、上下文片段、用户问题。角色设定告诉模型它是知识库助手，上下文片段是检索结果，用户问题是原始提问。

关键约束是要求模型“只根据提供的片段回答，如果片段中没有相关信息，明确说不知道”。这个约束能大幅降低幻觉。另外，可以在模板里要求模型引用来源，比如“根据文档 X 的第 Y 节”，这样用户能验证答案的可靠性。

温度参数建议设在 0.1 到 0.3 之间，太低会显得死板，太高会引入不确定性。知识库问答场景下，稳定比创意重要，我一般设 0.2。

7. 实际运行中遇到的几个典型问题与处理

部署和调优过程中总会遇到各种意外，这一节记录几个我实际碰到的问题和处理方式，供参考。

7.1 容器启动后端口访问不通

服务起来了但浏览器访问不了，先检查端口映射。Compose 文件里每个服务都有端口映射配置，格式是“宿主机端口:容器端口”。如果宿主机端口被占用，Compose 启动时会报错，但有时候不报错只是映射失败。用docker compose ps看服务状态，用netstat或ss看端口监听情况。

另一个常见原因是防火墙。如果机器开了防火墙，宿主机端口没有放行，外部访问就会被拦。本地测试的话可以先临时关闭防火墙验证，确认是防火墙问题之后再按需放行端口。

7.2 嵌入模型加载慢或超时

BGE-M3 模型文件有几个 G，第一次启动要下载，如果网络不好会非常慢。我的做法是提前把模型文件下载好，挂载到容器里，而不是让容器启动时去下载。这样启动速度快，而且不受网络波动影响。

如果模型已经加载但检索请求超时，检查嵌入服务的并发配置。默认并发数可能比较低，文档批量入库时会排队。适当调高并发数可以加快入库速度，但要注意别超过机器承载能力，否则反而会拖慢整体响应。

7.3 检索结果相关性突然下降

如果之前检索效果正常，某天突然变差，先检查最近有没有新文档入库。新文档的解析或切片如果出了问题，可能会污染整个向量库。比如某个文档解析出大量乱码片段，这些片段在检索时可能被命中，挤掉了原本相关的片段。

处理方式是先定位问题文档，把它从库里删掉，重新解析入库。WeKnora 支持按文档删除对应的向量，这个功能在排查问题时很有用。另外，建议定期检查向量库的片段质量，抽样看一些片段的内容是否正常。

8. 从单机部署到多人使用的扩展思路

单机跑通之后，如果想让团队里其他人也能用，需要考虑一些扩展问题。这部分不是必须的，但如果你打算长期使用，提前规划会省很多事。

8.1 接入统一身份认证的考虑

热词里出现了“weknora oidc”，说明有人已经在做身份认证集成。如果团队规模不大，用系统自带的账号体系就够了。但如果要和公司现有的账号系统打通，OIDC 是比较通用的方案。WeKnora 的配置里预留了 OIDC 相关参数，填入身份提供方的地址和凭证即可。

接入 OIDC 的好处是用户不用单独记一套账号密码，权限管理也统一了。配置的时候注意回调地址要填对，否则认证跳转会失败。这个地址必须是外部可访问的地址，不能用 localhost。

8.2 多用户并发时的资源分配

多人同时使用时，嵌入模型和向量库的压力会明显上升。如果发现响应变慢，可以考虑把嵌入服务单独部署到一台机器上，通过内网调用。向量库如果支持集群模式，也可以做水平扩展。

另一个优化点是缓存。对于高频问题，可以把检索结果缓存起来，下次同样的问题直接返回缓存结果，不用重新走检索流程。这个优化在问答场景下效果很明显，因为很多问题是重复的。

8.3 数据备份与迁移的注意事项

向量库和原始文档都要定期备份。向量库的备份相对简单，直接备份数据目录即可，但要注意备份时服务最好暂停，否则可能备份到不一致的状态。原始文档的备份按常规文件备份流程走就行。

迁移的时候，把数据目录和配置文件一起迁过去，在新机器上改一下环境变量里的地址和路径，重新启动即可。注意嵌入模型如果换了机器，模型文件也要一起迁，或者在新机器上重新下载。

9. 一些让系统更稳的运维小习惯

最后分享几个我在长期运行中养成的习惯，都是些不起眼的细节，但能省不少排查时间。

第一，给 Compose 服务配置日志轮转。默认情况下 Docker 日志会一直增长，时间长了能把磁盘占满。在 Compose 文件里加上日志配置，限制单个日志文件大小和保留数量。

logging: driver: json-file options: max-size: "10m" max-file: "3"

第二，定期检查磁盘使用情况。向量库和解析中间文件会持续占用空间，尤其是文档量大或者频繁更新的时候。设个监控或者定时任务，磁盘使用超过阈值就告警。

第三，文档入库前先做一轮格式检查。把明显有问题的文档挑出来，比如加密的 PDF、损坏的 Word 文件，这些文档入库只会产生垃圾片段，不如提前过滤掉。

第四，保留一份最小可用的配置备份。调参过程中改来改去，有时候改坏了想回退，如果没有备份就得从头再来。我习惯在每次大改之前把配置文件复制一份，加上日期后缀，出问题随时能对比。

这套系统我目前跑了一段时间，日常问答的准确率能满足内部使用需求。它不是什么万能方案，文档质量差、问题太模糊的时候效果也会打折扣，但对于“把内部文档变成可问答的知识库”这个需求来说，WeKnora 的完成度已经相当高了。如果你也在找类似的方案，建议先用小批量文档跑通链路，确认效果符合预期之后再逐步扩大规模。