1. 为什么我盯上了 WeKnora 这套开源知识库第一次看到 WeKnora 这个项目是在一个做企业内训的朋友群里。他当时吐槽说公司攒了七八年的产品文档、售后 FAQ、培训手册全躺在共享盘里吃灰新来的客服遇到问题还是靠老员工口口相传。他试过几个商业知识库方案要么按席位收费贵得离谱要么数据必须传到别人服务器上法务那边过不了。后来有人甩了个链接给他说是腾讯微信团队开源的一套 AI 知识库工具能本地部署支持文档解析、向量检索、大模型问答一条龙。他折腾了一个周末跑通之后在群里发了一句“真香”。我这个人有个毛病看到“本地部署”加“开源”这两个词凑一块儿手就痒。更何况还挂着腾讯微信团队的名头——这帮人做工程化落地的能力业内是有共识的。于是我也拉了一份代码在自己那台闲置的迷你主机上从头到尾搭了一遍。整个过程踩了不少坑也积累了一些官方文档里没写的经验索性整理成这篇实录给同样想自己搭一套问答系统的朋友做个参考。WeKnora 本质上是一个检索增强生成RAG的知识库系统。说人话就是你把 PDF、Word、Markdown 这些文档丢进去它帮你切碎、向量化、存进数据库你提问的时候它先从数据库里捞出最相关的几段内容再交给大模型组织成通顺的回答。整套东西可以完全跑在你自己的机器上数据不出内网模型可以接本地的也可以接云端 API。适合谁呢我总结下来是三类人一是手里有一堆私有文档、又不想把数据交出去的小团队二是想学习 RAG 系统完整工程实现的技术爱好者三是需要给内部系统加一个智能问答入口的开发者。下面我就按实际操作的顺序把整个部署过程、关键决策点和踩坑记录拆开来讲。2. 部署前的整体设计与选型考量2.1 为什么选 Docker Compose 而不是裸机安装WeKnora 官方提供了两种部署方式一种是手动装 Python 环境、数据库、向量库逐个配置另一种是直接用 Docker Compose 一把梭。我毫不犹豫选了后者原因有三。第一依赖隔离。这套系统涉及 Python 运行时、PostgreSQL带 pgvector 扩展、Redis、对象存储MinIO等一堆组件裸机装的话版本冲突能把你折腾到怀疑人生。Docker Compose 把每个组件关进自己的容器里互不干扰删起来也干净。第二可复现性。Compose 文件本身就是一份部署文档换台机器把文件一拷docker compose up -d就完事。我后来在另一台机器上复现前后不到十分钟。第三资源可控。Compose 里可以给每个服务限制 CPU 和内存避免某个组件把整机资源吃光。我那台迷你主机只有 16G 内存不限制的话 PostgreSQL 和向量检索服务能把内存撑爆。注意Docker Compose 有两个大版本v1 是docker-compose带横杠v2 是docker compose空格。现在新装的基本都是 v2命令别写错了否则会报cannot start docker compose application之类的错。2.2 向量数据库和嵌入模型怎么选这是整个部署里最关键的决策点直接决定了检索效果和硬件开销。WeKnora 默认支持多种向量存储后端我实测下来PostgreSQL pgvector是最省心的组合。原因很简单它跟业务数据共用一个数据库实例少维护一个组件备份也方便。如果你追求极致检索性能可以换成专门的向量库但对中小规模知识库几万到几十万条切片来说pgvector 完全够用没必要给自己加运维负担。嵌入模型这块我强烈推荐BGE-M3。这个模型在中文语义检索上的表现相当扎实而且支持多语言、支持长文本最关键的是它能在消费级显卡甚至纯 CPU 上跑。我一开始用的是某个更小的模型检索召回率明显不行换成 BGE-M3 之后同一个问题的命中率肉眼可见地提升。部署 BGE-M3 也有现成的 Docker 镜像Compose 里加一个服务就行。至于大模型看你手头有什么。有显卡的可以本地跑量化版模型没显卡的就接云端 API。WeKnora 的模型接入层做得比较灵活改配置文件就能切换。2.3 硬件配置的底线在哪里我把实测的配置需求整理成了一张表供你参考组件最低配置推荐配置说明CPU4 核8 核以上文档解析和向量化吃 CPU内存8 GB16 GB 以上pgvector 和嵌入模型是大头硬盘20 GB50 GB 以上模型文件加文档存储显卡无纯 CPU8 GB 显存以上有显卡可本地跑大模型纯 CPU 也能跑就是文档入库慢一些问答响应大概在几秒到十几秒。如果你只是自己用或者小团队内部用这个延迟完全可以接受。3. 核心组件拆解与实操要点3.1 目录结构规划别等数据丢了才后悔很多人上来就git clone然后docker compose up跑是能跑起来但数据卷全在默认位置哪天容器重建或者系统重装几年的文档就没了。我建议在部署前先把目录规划好。我的做法是在数据盘上建一个总目录比如/data/weknora下面再分几个子目录/data/weknora/ ├── docker-compose.yml ├── .env ├── data/ │ ├── postgres/ # 数据库数据 │ ├── redis/ # 缓存数据 │ ├── minio/ # 对象存储 │ └── models/ # 本地模型文件 └── logs/ # 各服务日志然后在 Compose 文件里把这些目录挂载进容器。这样做的好处是所有持久化数据集中在一处备份的时候直接打包整个data目录就行。我吃过亏——之前有个项目数据卷散落在 Docker 默认路径下迁移的时候找都找不全。3.2 环境变量配置那些容易填错的参数WeKnora 用.env文件管理配置里面有几个参数特别容易踩坑我逐个说。数据库连接串。格式是postgresql://用户名:密码主机:端口/库名。注意主机名要填 Compose 里的服务名不是localhost。因为容器之间通过内部网络通信填localhost会指向容器自己连不上数据库。我第一次就栽在这儿日志里报连接拒绝排查了半天。嵌入模型地址。如果你用独立的嵌入模型服务地址要填那个服务的容器名加端口。比如嵌入服务叫embedding端口 80那就填http://embedding:80。同样别填localhost。大模型 API Key。如果用云端模型Key 直接写在.env里。这里有个安全建议.env文件权限设成600别让其他用户读到。另外.env千万别提交到 Git 仓库.gitignore里加上。文件上传大小限制。默认值可能偏小如果你要传大 PDF记得调大。这个参数在不同版本里名字可能不一样一般在应用服务的环境变量里找带MAX或SIZE字样的。3.3 文档解析与切片策略决定问答质量的关键文档丢进去之后系统要把它切成一段一段的“切片”再向量化。切片策略直接决定了检索质量这是很多人忽略的地方。WeKnora 默认的切片是按固定字符数切的比如每 500 字一段段之间留 50 字重叠。这个策略对结构规整的文档还行但遇到表格、代码块、多级标题的文档就容易切碎语义。我的经验是按文档类型分别设置切片参数。纯文本类文档切片可以大一些800 到 1000 字重叠 100 字技术文档和 FAQ切片小一些300 到 500 字因为问答对本身就很短表格密集的文档最好先转成 Markdown 再入库让解析器能识别表格结构。提示切片重叠overlap这个参数别省。它保证相邻切片之间有内容交叠避免一个完整的语义被硬生生切断。我一般设成切片长度的 10% 到 20%。3.4 检索参数调优召回率和准确率的平衡检索环节有几个参数值得调Top K每次检索返回多少个切片。设太小可能漏掉关键信息设太大会引入噪声还会拖慢大模型的处理速度。我一般设 5 到 8。相似度阈值低于这个阈值的切片直接丢弃。设太高可能什么都召不回设太低会混进不相关的内容。建议从 0.5 开始试根据实际效果微调。重排序Rerank如果系统支持强烈建议开启。它会对初步召回的切片做二次精排把最相关的排到前面。开了之后回答准确率提升很明显。这些参数在 WeKnora 的配置文件里都能找到改完重启服务生效。调参是个细活建议准备一组测试问题每次改完跑一遍对比效果。4. 完整部署流程与关键环节实现4.1 环境准备Docker 和 Compose 的安装先确认你的系统里有没有 Docker。终端里敲docker --version docker compose version如果两条命令都能输出版本号说明环境 OK。如果提示找不到命令就得先装。Linux 上装 Docker 最省事的方式是用官方脚本但有些发行版的软件源里版本太老建议直接参考 Docker 官方文档添加软件源安装。装完之后记得把当前用户加进docker组否则每次敲 docker 命令都要加sudosudo usermod -aG docker $USER执行完这条命令要重新登录才生效别问我怎么知道的。Windows 和 macOS 用户直接装 Docker Desktop 就行里面自带 Compose。注意 Windows 上要开启 WSL2 后端性能会好很多。4.2 拉取代码与配置文件准备从代码仓库把 WeKnora 拉下来git clone 仓库地址 weknora cd weknora然后找到.env.example或者类似的模板文件复制一份改名为.envcp .env.example .env接下来就是编辑.env把前面说的那些参数填进去。我建议用vim或者nano直接改改完保存。4.3 启动服务与验证一切就绪后在项目根目录执行docker compose up -d-d表示后台运行。第一次执行会拉取镜像视网速而定可能要等几分钟到十几分钟。拉完之后容器会依次启动。用下面这条命令看容器状态docker compose ps正常情况下所有服务的状态应该是running或者healthy。如果有服务显示restarting或者exited说明启动失败了得看日志排查docker compose logs -f 服务名-f是持续输出日志按CtrlC退出。重点看报错信息一般是配置填错或者端口被占用。所有服务正常后打开浏览器访问http://你的机器IP:端口应该能看到 WeKnora 的登录界面。默认端口在.env里配置一般是 8080 或者 3000 之类。第一次登录用默认管理员账号登录后第一件事就是改密码。4.4 上传文档与构建知识库登录进去之后创建一个知识库然后把文档拖进去。系统会自动解析、切片、向量化。这个过程的时间取决于文档数量和硬件性能。我传了大概 200 个 PDF纯 CPU 环境下跑了将近一个小时。入库完成后可以在知识库里看到每个文档被切成了多少片。这时候建议抽查几个切片看看切得合不合理。如果发现切片把表格切得七零八落就得回去调整切片策略删掉重新入库。4.5 问答测试与效果评估知识库建好后就可以提问了。我建议准备一组“标准问题”覆盖不同难度有直接答案在文档里的有需要跨文档综合的还有文档里根本没提的测试它会不会胡编。实测下来BGE-M3 加 pgvector 的组合在中文技术文档上的召回效果相当不错。问一个产品参数问题它能把相关的几个切片都捞出来大模型组织出来的回答也基本准确。但遇到需要多跳推理的问题比如“A 产品的某个功能在 B 场景下怎么配置”效果就一般了这跟切片策略和检索深度都有关系。5. 常见问题与排查技巧实录5.1 容器起不来怎么办这是最常见的问题我整理了一张速查表现象可能原因排查方法容器反复重启配置错误或依赖未就绪docker compose logs 服务名看报错端口被占用宿主机已有服务占用端口netstat -tlnp查端口改.env里的端口数据库连接失败主机名填错或密码不对检查.env里的连接串确认服务名一致内存不足被 kill容器内存超限docker stats看资源占用调大限制或加内存镜像拉取失败网络问题配置镜像加速器或手动docker pull我遇到最多的是数据库连接失败十有八九是主机名填了localhost。记住容器之间通信要用服务名。5.2 文档入库卡住或失败如果文档传上去一直显示“处理中”或者直接报错先看应用服务的日志。常见原因有几个一是文档格式不支持比如加密的 PDF 或者扫描件没有文字层二是文件太大超过了配置的上限三是嵌入模型服务挂了导致向量化步骤失败。扫描件这个问题特别常见。很多人以为 PDF 都能解析其实扫描件本质是图片得先做 OCR。WeKnora 是否内置 OCR 要看版本如果没有就得自己先用 OCR 工具处理一遍再入库。5.3 问答答非所问或胡编乱造这个问题分两种情况。一种是检索没召回到正确内容那就要调检索参数或者检查切片策略。另一种是召回了正确内容但大模型没用好那就是提示词Prompt的问题。WeKnora 的问答提示词模板一般可以在配置文件里改。核心思路是明确告诉模型“只根据下面提供的资料回答资料里没有的就说不知道。”这句话能大幅降低胡编的概率。另外可以在提示词里要求模型引用来源这样你还能追溯它是根据哪段内容回答的。5.4 性能优化的一些实操心得跑了一段时间之后我做了几项优化效果比较明显给 PostgreSQL 调参默认配置偏保守适当调大共享缓冲区和工作内存检索速度能快不少。嵌入模型用 GPU如果有显卡把嵌入模型跑在 GPU 上入库速度能提升好几倍。开启 Redis 缓存重复问题的检索结果可以缓存减少数据库压力。定期清理日志容器日志不清理会越积越多占满硬盘。可以配置日志轮转。注意调 PostgreSQL 参数前先备份数据改错了可能导致服务起不来。不确定的参数就保持默认别乱动。5.5 数据备份与迁移前面强调过目录规划这里说备份的具体操作。最简单的办法是停掉服务然后打包整个data目录docker compose down tar -czvf weknora-backup-$(date %Y%m%d).tar.gz /data/weknora/data docker compose up -d迁移到新机器时把备份包解压到相同路径再把 Compose 文件和.env拷过去docker compose up -d就能恢复。注意.env里的路径配置要跟新机器一致。6. 我踩过的坑和最后想说的回过头看整个部署过程最耗时间的不是技术难点而是那些“想当然”的地方。比如以为localhost万能结果在容器网络里栽了跟头比如没规划目录数据卷散落各处迁移时手忙脚乱比如切片参数用默认值导致检索效果一直上不去还以为是模型不行。还有一个体会是别追求一步到位。我一开始想把所有参数都调到最优结果改来改去把自己绕晕了。后来学乖了先用默认配置跑通确保整个链路没问题然后再针对具体问题逐个调优。这样每改一个参数都能清楚知道它带来了什么变化。WeKnora 这套东西工程完成度确实对得起“微信团队出品”这几个字。Compose 文件写得规整配置项注释清楚日志输出也够详细。但它毕竟是个开源项目不是开箱即用的商业产品很多地方需要你根据自己的场景去调。如果你只是想快速体验一下 RAG 问答那跑通默认配置就够了如果你想把它用在生产环境那切片策略、检索参数、提示词模板这几块值得花时间好好打磨。最后分享一个小技巧建知识库的时候先拿一小批有代表性的文档做测试把切片和检索参数调满意了再批量导入全部文档。这样能省下大量反复入库的时间。我一开始就是一股脑全传进去结果参数不对删了重来白白等了好几个小时。