1. 为什么我盯上了 WeKnora 这套开源知识库第一次看到 WeKnora 这个名字是在一个做企业内训的朋友群里。他丢了一句“腾讯微信团队开源了个 AI 知识库能本地部署”群里瞬间炸出一堆人问“真的假的”“吃不吃配置”“跟 Dify 比怎么样”。我当时没吭声转头就去把仓库拉下来读了一遍 README 和目录结构越看越觉得这东西值得写一篇完整的部署实录——因为它踩中了一个非常具体的痛点很多团队手里有一堆内部文档、FAQ、产品手册想搭一套能问答的知识库但既不想把资料传到别人的服务器上又不想从零写 RAG 链路。WeKnora 解决的正是这件事。它是一套开源的 AI 知识库问答系统核心能力是把文档切片、向量化、存进向量库再通过检索增强生成的方式回答用户提问。你可以把它理解成“一个能自己部署的、带管理后台的文档问答引擎”。它适合谁我梳理了三类人一是中小团队里负责内部工具的技术同学二是想把公司资料做成智能客服的产品同学三是像我这样喜欢折腾本地 AI 应用的爱好者。哪怕你之前只跑过 Docker 的基本命令跟着这篇实录也能把整套系统在本机跑起来。我特别想强调“本地部署”这四个字的分量。市面上做知识库问答的产品不少但大多数要么是纯云服务要么是开源但部署链路极其复杂光依赖就能劝退一半人。WeKnora 用的是 Docker Compose 编排把后端服务、前端界面、向量库、数据库这些组件打包成一套可以一键拉起的组合这对没有专职运维的团队来说友好度直接拉满。接下来我会从整体设计思路讲起再一步步拆解部署过程最后把我踩过的坑和排查经验全部摊开讲。2. 整体架构与方案选型拆解2.1 这套系统到底由哪些部件组成在动手之前我习惯先把一个项目的组件关系画清楚不然部署到一半报错都不知道是哪个环节出的问题。WeKnora 的整体结构可以拆成四层来看我用一张表把每层的职责和常见实现列出来方便你对照理解。层级职责常见实现接入层提供 Web 管理界面和问答入口前端静态资源 反向代理应用层处理文档解析、切片、检索、生成后端服务API 业务逻辑存储层存向量、存元数据、存原始文件向量库 关系型数据库 对象存储模型层提供向量化和文本生成能力嵌入模型 大语言模型接入层就是你浏览器里看到的那个管理后台用来上传文档、管理知识库、测试问答效果。应用层是真正干活的部分它要负责把上传的 PDF、Word、Markdown 解析成纯文本再按策略切成一段段 chunk调嵌入模型把每段转成向量。存储层里向量库存的是 chunk 的向量表示关系型数据库存的是知识库、文档、会话这些结构化信息原始文件一般放在本地磁盘或对象存储里。模型层是整套系统的“大脑”嵌入模型决定检索准不准生成模型决定回答顺不顺。2.2 为什么选 Docker Compose 而不是别的编排方式这个问题我在部署前认真想过。可选方案其实有三种手动装依赖逐个启动、用 Docker Compose 编排、上 Kubernetes。手动装的问题在于环境差异太大Python 版本、系统库、CUDA 驱动稍有不同就报错复现成本极高。Kubernetes 对个人和小团队来说太重了为了跑一个知识库去维护一套集群性价比太低。Docker Compose 刚好卡在中间它把每个组件封装成独立容器容器之间通过内部网络通信你只需要一条docker compose up就能把整套系统拉起来。更重要的是Compose 文件本身就是一份可读的部署文档哪个服务依赖哪个服务、暴露哪些端口、挂载哪些卷全都写得清清楚楚。我实测下来只要宿主机装好了 Docker 和 Compose 插件从零到能访问后台顺利的话二十分钟以内能搞定。这也是我推荐绝大多数人首选 Compose 的原因——它不是最强大的但对这个场景是最合适的。2.3 向量库和模型的选择逻辑向量库这块WeKnora 支持对接多种后端其中比较常见的是本地向量库和云上的向量数据库服务。我的建议是如果你只是本地测试或者数据量在几万条 chunk 以内直接用本地向量库就够了省去申请云服务、配置网络白名单的麻烦。等数据量上来了、或者需要多实例共享向量数据再考虑换成云上的向量数据库。模型选择是另一个关键决策点。嵌入模型我强烈推荐用 BGE-M3 这类多语言模型它对中文的支持明显好于很多英文为主的模型而且能同时处理稠密检索和稀疏检索检索召回率提升很直观。生成模型的选择就灵活多了本地跑可以用量化后的小参数模型追求效果就接一个能力更强的模型服务。这里有个经验嵌入模型一旦选定中途不要随便换因为换模型意味着所有已入库的向量都要重新生成数据量大的时候这个成本很高。所以部署前就要想清楚用哪个嵌入模型一次定下来。3. 部署前的环境准备与关键检查3.1 硬件和系统的最低门槛在正式动手前我先把硬件要求说清楚免得你跑到一半发现机器扛不住。纯 CPU 环境也能跑但生成速度会比较慢适合功能验证如果想让问答响应在可接受范围内建议至少有一块显存 8GB 以上的显卡。内存方面我建议不低于 16GB因为向量库、数据库、后端服务加起来本身就吃内存再叠加模型推理8GB 的机器很容易被 OOM 杀掉进程。系统层面Linux 是最省心的选择Ubuntu 22.04 和 Debian 12 我都实测过没遇到系统级坑。Windows 用户建议走 WSL2直接在 Windows 原生环境跑 Docker 会有路径挂载和网络转发的小问题。macOS 用户注意Apple Silicon 芯片在跑某些镜像时需要指定 arm64 架构这个后面会讲到。磁盘空间至少留 50GB因为镜像、模型权重、上传的文档加起来占用不小模型权重动辄几个 GB。3.2 Docker 与 Compose 的安装要点安装 Docker 这件事本身不难但有几个细节值得提醒。第一一定要装 Compose V2 插件也就是用docker compose而不是老的docker-compose命令很多新项目的编排文件用了 V2 才支持的语法。第二安装完记得把当前用户加入 docker 组否则每条命令都要加 sudo很烦。第三国内网络环境下拉镜像可能很慢建议提前配置好镜像加速地址这个能省下大量等待时间。验证安装是否到位跑这两条命令就够了docker --version docker compose version两条都能正常输出版本号说明环境没问题。如果第二条报“command not found”说明 Compose 插件没装上需要单独安装。我见过不少人卡在这一步以为是项目的问题其实是环境没配好。3.3 部署前必须确认的三件事在拉代码之前我建议你先确认三件事能避免后面大量返工。第一确认端口没被占用。WeKnora 默认会用到几个端口如果宿主机上已经有服务占了这些端口容器起不来。用ss -tlnp看一眼当前监听情况。第二确认磁盘挂载路径有写权限容器里的数据要持久化到宿主机路径权限不对会导致数据库初始化失败。第三确认模型文件的存放位置如果你打算用本地模型提前把权重下载好放到指定目录别等部署到一半再去下。提示部署前把这几项检查做成一个清单逐项打勾再往下走比出了问题再回头排查效率高得多。4. 一步步把 WeKnora 跑起来4.1 获取代码与目录结构速览第一步是把项目代码拉到本地。用 git clone 就行拉下来之后先别急着启动花两分钟看一眼目录结构心里有个数。通常这类项目会有几个关键目录存放编排文件的根目录、后端服务代码、前端代码、以及配置和脚本目录。编排文件是整个部署的核心它定义了所有服务、网络、卷的关系。我建议你打开编排文件通读一遍重点看三样东西每个服务用的镜像、暴露的端口映射、以及挂载的卷。读懂了这三样后面出问题你就能快速定位是哪个服务的事。这一步很多人跳过结果一报错就懵其实答案全在编排文件里写着。4.2 环境变量的配置与参数计算绝大多数这类项目都会提供一个环境变量示例文件你需要复制一份改成实际配置。这里面有几个参数必须认真填。数据库密码要改成强密码别用默认值。模型相关的配置要填对包括模型名称、服务地址、API 密钥如果用云服务的话。向量库的连接信息也要和编排文件里的服务名对应上。这里有个容易踩的坑容器之间通信用的是服务名而不是 localhost。比如后端要连向量库地址应该写向量库的服务名而不是 127.0.0.1。因为每个容器有自己独立的网络命名空间localhost 指向的是容器自己。这个原理搞懂了很多“连接被拒绝”的报错就迎刃而解了。关于 chunk 大小这个参数我补充一下计算思路。chunk 太大检索时召回的内容太杂生成模型容易被无关信息干扰chunk 太小单段信息不完整回答容易断章取义。我的经验值是中文文档切 300 到 500 字比较合适同时设置一定的重叠长度比如 50 字保证跨 chunk 的语义不被切断。这个值不是固定的要结合你的文档类型调技术文档可以小一点叙述性文档可以大一点。4.3 启动服务与验证运行状态配置改好之后就可以启动了。在编排文件所在目录执行docker compose up -d-d表示后台运行。第一次执行会拉取镜像耗时取决于网络。启动完成后用下面这条命令看所有容器的状态docker compose ps正常情况下所有服务都应该是 running 或 healthy 状态。如果有服务反复重启用docker compose logs 服务名看日志。我实测时遇到过一次向量库启动慢导致后端连不上后端就不断重试等向量库起来之后自动恢复了这种情况不用慌等一两分钟再看。服务都起来之后浏览器访问配置的端口应该能看到管理后台的登录界面。第一次登录用默认账号进去后第一件事就是改密码。到这里部署的主体工作就完成了。4.4 上传文档与验证问答效果系统跑起来只是第一步真正验证它好不好用得喂点文档进去测。我建议先传一份结构清晰的 Markdown 或 PDF等解析和向量化完成然后在问答界面提几个问题。测试的时候要分两类问题一类是文档里明确写了答案的看它能不能准确检索到另一类是文档里没有的看它会不会胡编。一个合格的知识库系统对不知道的问题应该明确说不知道而不是硬编一个答案。如果检索不准先别急着换模型检查一下文档解析是否正常。有些 PDF 是扫描件纯文本解析出来是空的这种情况需要先做 OCR。还有些文档排版复杂表格和正文混在一起解析后顺序乱了也会影响检索。我一般会先看解析后的文本内容确认没问题再排查检索环节。5. 实操中踩过的坑与排查技巧5.1 容器启动失败的常见原因部署过程中最容易遇到的就是容器起不来。我把遇到过的情况整理成一张速查表方便你对照排查。现象可能原因排查方向容器反复重启配置错误或依赖未就绪看容器日志最后几十行端口被占用宿主机已有服务监听换端口或停掉冲突服务数据库初始化失败挂载目录权限不足检查宿主机目录属主和权限镜像拉取超时网络问题配置镜像加速或重试内存不足被杀宿主机内存不够加内存或减少并发服务排查的核心思路永远是先看日志。docker compose logs能解决八成以上的问题日志里通常会直接告诉你哪一行配置错了、哪个依赖连不上。我见过太多人一报错就去搜其实日志第一行就写明了原因。5.2 模型连接与推理相关的坑模型这块的坑主要集中在连接和性能两方面。连接问题多半是地址填错记住容器间用服务名。如果用的是外部模型服务要确认网络能通、密钥有效。性能问题则表现为回答特别慢这时候先看是不是在用 CPU 推理如果是换成 GPU 或者换更小的模型。还有一个隐蔽的坑嵌入模型和生成模型如果部署在同一个 GPU 上显存可能不够。我建议要么分卡部署要么把嵌入模型跑在 CPU 上嵌入对延迟没那么敏感把宝贵的显存留给生成模型。这个取舍在实际部署中很关键直接决定系统能不能稳定跑起来。5.3 检索效果不佳的调优思路检索效果差是问得最多的问题。我的调优顺序是这样的先确认文档解析质量再看 chunk 切分是否合理然后检查嵌入模型是否适合中文最后才考虑调整检索参数。很多人一上来就调参数其实前面的基础没打好怎么调都白搭。如果文档里有大量专有名词、产品代号纯向量检索可能召回不准这时候可以开启混合检索把关键词匹配和向量检索结合起来。BGE-M3 这类模型本身就支持混合检索能力配置里打开对应开关就行。我实测下来对于术语密集的技术文档混合检索的召回率比纯向量检索有明显提升。注意调优是个迭代过程每次只改一个变量改完测一组固定问题对比效果。一次改好几个参数最后根本不知道是哪个起了作用。6. 关于这套系统后续能怎么用跑通之后我陆陆续续试了几个扩展方向这里分享两个我觉得最有价值的。第一个是把它接到团队内部的聊天工具上做成一个随时能问的助手同事不用打开网页就能查资料。第二个是给不同的知识库设置不同的权限比如产品文档全员可见财务制度只有特定角色能问这在管理后台里配置一下就能实现。我个人在实际操作中的体会是本地部署知识库这件事部署本身只占两成工作量剩下八成都在文档治理和效果调优上。文档质量差、结构乱再好的模型也救不回来。所以如果你打算长期用从一开始就规范文档的格式和命名后面会省下大量精力。另外定期把问答日志翻出来看看哪些问题答得不好针对性地补充文档这套系统才会越用越聪明。