知识库问答系统这件事我前前后后搭过不下五套。从最早的纯手工向量检索到后来用各种框架拼装每次都在“部署复杂度”和“效果可用性”之间反复横跳。直到最近把 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 环境变量里必须改的几项配置文件里有一批环境变量大部分可以保持默认但有几项必须改成你自己的值否则服务起不来或者跑不通。变量名作用建议值嵌入模型地址指向本地 BGE-M3 服务http://bge-m3:8080生成模型 API 地址生成模型接口按实际服务填写生成模型 API 密钥调用凭证按实际填写向量库连接串向量存储地址默认即可除非改端口数据挂载路径文档和索引存放位置指向大磁盘分区这里重点说下嵌入模型地址。如果你用 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 的完成度已经相当高了。如果你也在找类似的方案建议先用小批量文档跑通链路确认效果符合预期之后再逐步扩大规模。