WeKnora本地部署实录：知识图谱+RAG构建私有问答系统

WeKnora 本地部署实录：用腾讯微信团队的开源 AI 知识库搭一套问答系统

年初团队内部一直嚷嚷着要搞一个私有知识库，把散落的几十篇技术文档、产品手册和会议纪要统一管起来。我一开始用的是纯 RAG 方案，文档一切块就扔进向量库，结果发现只要问题里带点实体关系——比如"某某模块的依赖组件上线前需要谁审批"——检索回来的片段往往七零八碎，答得牛头不对马嘴。后来读到 WeKnora 这个项目，发现它并不是又一个 Dify 套壳，而是腾讯微信团队开源的一套融合了知识图谱与 RAG 的本地知识库问答系统，核心思路是先在文档里抽取实体和关系，再结合向量检索一起回答用户提问。我把它在自己的服务器上完整部署了一套，跑通了文档上传、图谱生成和自然语言问答，这篇就把实录过程、选型思路和踩坑排查链路全部写下来，给同样想玩本地知识库的人一个参考。

1. 为什么是 WeKnora：从 RAG 的通病到图谱兜底

先说清楚一个背景：知识库问答系统这几年火，但大多数开源项目其实走的是同一条路——RAG。流程很简单，文档切片后做向量化，用户提问时做向量相似度检索，然后把命中的片段拼给大模型生成答案。这套路对"查资料"类需求够用，但一旦问题牵扯到跨段落、跨文档的实体关联，比如"A 服务依赖 B 服务，B 宕机了会影响哪些下游"，纯向量检索的结果就经常让人挠头。

WeKnora 给我的第一感觉就是它没打算只用 RAG 硬扛。这个项目在架构上把两套东西做了融合：一边是常规的向量检索，用来快速召回与问题语义相近的文档片段；另一边是知识图谱构建，系统会从上传的文档里自动抽取实体（人名、系统名、产品名、专业术语等）和它们之间的关系，形成图结构数据。问答阶段，系统既做向量召回，也做图谱检索，两种结果一起交给大模型综合生成答案。

这种设计的价值在垂直领域特别明显。拿我们团队真实碰到过的场景举例：一份历史故障报告里写了"支付服务调用用户服务超时导致订单服务阻塞"，这种一句话里的因果关系，纯 RAG 未必能在检索阶段精确命中，但图谱把"支付服务―调用→用户服务""订单服务―阻塞→支付服务"的关系链提取出来后，后续问"哪些服务会受用户服务影响"时，答案就变得有据可依。

所以如果你是下面这几类人，WeKnora 值得重点看一下：

• 想把公司内部文档做成一个不依赖外部 API 的私有问答库
• 已经在用 Dify、FastGPT、MaxKB 这类纯 RAG 项目，但发现实体关系类问题回答效果不理想
• 有本地大模型（比如通过 Ollama 部署的 DeepSeek、Qwen），想找一个能直接接进来的知识库前端
• 对数据安全敏感，要求所有环节（文档解析、图谱构建、问答生成）都在内网闭环

对了，WeKnora 还带一个"生成图谱"的独立模块，不是传统意义上那种需要人工标注实体的老式知识图谱系统，而是靠 LLM 自动抽取，这一点对非技术团队来说非常友好，后面实操部分我会专门展开。

2. 部署前的"铁三角"：硬件规划、模型选型与组件取舍

任何本地部署项目，动手之前把环境想清楚都能省掉 80% 的后续麻烦。WeKnora 的部署看起来是一套 Web 服务加若干组件，但真正决定成败的其实是三个变量：硬件够不够、模型怎么选、周边组件怎么配。

2.1 硬件的底线和推荐配置

先说结论：如果你没有 NVIDIA 显卡，纯 CPU 也能跑起来，但体验会比较痛苦，尤其是文档解析和图谱生成两个阶段，大模型推理全部压在 CPU 上，速度感人。

我实际部署用的是一台双路 E5 服务器，内存给了 64GB，显卡是一张 16GB 显存的消费级卡。实测下来，一套 20 页的 Markdown 文档，纯 CPU 模式下图谱生成可能要跑十几分钟，上了 GPU 之后能压缩到两三分钟级别。以下是个人实测的硬件参考区间：

内存这块要特别说一下，WeKnora 的部署会用 Docker 起多个容器，包括后端服务、前端、向量库、图数据库、对象存储等，整套下来光容器占用的内存就不少。我最初在 32GB 内存的机器上部署，启动后还没跑问答，系统就开始内存告急，最后不得不把图数据库和向量库的缓存调小。所以32GB 是下限，64GB 才属于从容。

2.2 大语言模型与 Embedding 模型的选择逻辑

WeKnora 的设计有点像"BYOM"（Bring Your Own Model），模型不内置，而是通过配置接入外部大模型服务。这里有两种主流路子：

• 接云端 API：只要能提供 OpenAI 兼容接口的厂商都行，好处是模型能力强、省本地算力，坏处是数据要出内网。
• 接本地模型：通过 Ollama 跑一个量化版模型，再把接口地址指向本地。

我本地部署选的是 Ollama 里的 DeepSeek-R1 蒸馏版和 Qwen2.5 系列，具体理由后面展开。这里必须先强调一个关键配置：问答模型和抽取模型是可以分开设置的。也就是说，日常问答你可以用一个偏通用的模型，而用来做实体抽取和图谱构建的模型，建议选指令跟随能力更强的那款，因为抽取任务对格式遵循要求比较高。如果抽取模型不够听话，输出格式乱七八糟，图谱构建质量会直线下降。

Embedding 模型同样值得单独配置。不要贪大求全去选超大参数量的向量模型，本地部署场景下 BAAI/bge-large-zh-v1.5 这类中文友好的模型已经够用，检索效果比那些偏英文语料的模型稳得多。整体模型规划可以参考我自己用的这个组合：

2.3 周边组件别照单全收

WeKnora 的部署通常依赖向量数据库和图数据库。向量库方面，官方推荐里有多种选择，我在本地选了 Qdrant，主要是它的 Docker 镜像轻量、资源占用相对小，而且自带 Web UI 方便查看检索效果。图数据库则是 Neo4j 社区版，作为承载实体关系图谱的存储。如果你之前没用过 Neo4j，也不用有压力，WeKnora 的图谱生成完成后主要是通过接口查询，不需要手工去写 Cypher，只有排查问题时才需要打开 Neo4j Browser 看一下图结构。

还有一个容易忽略的组件是对象存储或文件存储服务，用于保存上传的原始文档和解析产物。部署的时候注意给这个存储卷分配足够的磁盘空间，因为解析后的中间文件往往比原文档还要大不少。

3. 本地化部署完整走一遍：从拉取代码到跑通第一轮问答

这一节直接进入操作流程。我的部署环境是 Ubuntu 22.04，Docker 和 Docker Compose 已经提前装好。具体命令和文件内容可能随项目版本更新有所调整，但整体操作思路是一样的，建议边看边对照官方仓库的 README。

3.1 第一步：获取部署文件和配置模板

WeKnora 的仓库结构比较清晰，部署相关的文件一般放在项目的 deploy 或 docker 目录下，提供了 docker-compose.yml 以及 .env 配置模板。我的操作是先 clone 一份代码到服务器，再进入部署目录查看配置模板：

git clone https://github.com/tencent/weknora.git cd weknora/deploy cp .env.example .env

然后打开 .env 文件，把关键配置项逐个填好。这里可以来个清单帮助对照：

• 后端服务端口和前端服务端口：默认值一般不需要改，但如果你服务器上 80 端口被占，建议改成不冲突的端口。
• 向量库连接信息：Qdrant 的地址、端口、API Key，注意不要在配置文件里用明文密码，至少用 Docker Secret 方案管理。
• 图数据库连接信息：Neo4j 的地址、账号、密码，记得修改默认密码。
• 模型接入配置：包括 API 地址、API Key、模型名称。我用 Ollama 时，填的是类似http://<服务器IP>:11434/v1这样的 OpenAI 兼容地址。
• 存储路径：本地文件存储的挂载目录，确保磁盘空间充足。

3.2 第二步：用 Docker Compose 拉起整套服务

配置好 .env 后，直接执行启动命令：

docker compose up -d

第一次启动会拉取镜像，耗时取决于网络环境，耐心等就行。启动完成后，用docker compose ps查看各服务状态，确保所有容器都处于 running 状态。前端一般默认跑在 8088 或 3000 端口，浏览器打开就能看到登录页面。

首次登录后第一件事不是去创建知识库，而是去系统设置里检查模型配置是否生效。我之前的教训是：容器起来了不代表模型接好了，一定要在页面上发起一次对话测试，确认后端能成功调用 Ollama 接口。

3.3 第三步：创建知识库，上传第一批文档

模型打通后，就可以开始建知识库了。WeKnora 的知识库管理界面支持创建多个知识库，每个知识库可以设置独立的文档解析策略和模型配置，这对有多套文档体系（比如一套技术文档、一套行政制度）的团队非常有用。

我在创建"产品技术知识库"后，先传了几份混淆度比较高的文档来测试：一份 PDF 格式的产品白皮书、一份 Markdown 格式的接口文档、一份带表格的 Word 文档。上传完成后，系统会自动进入解析流程。这一步可以在任务中心里跟踪进度。

解析完成后，真正的重头戏来了——生成知识图谱。这个动作需要在知识库详情页里手动触发，触发后系统会读取已经解析好的文本内容，调用配置好的大模型抽取实体和关系，然后写入图数据库。首次生成图谱的耗时比较久，建议在非工作时间触发。生成完成后，可以到图数据库的管理界面看一眼，满屏的节点和边会很有成就感。

3.4 第四步：跑通第一轮问答

图谱生成完毕，问答才有完整的样子。我在测试时问了一个跨文档问题："支付服务超时会影响哪些下游系统？"系统返回的不再是某一段文档的原文复制，而是结合了图谱路径和向量片段综合生成的一段回答，同时标注了答案来源文档。这个体验比纯 RAG 好了不止一个档次，因为图谱把两个文档里的实体真正连了起来。

到这一步，一套基础可用的 WeKnora 本地问答系统就算跑通了。但"能跑"和"好用"之间还有不少距离，接下来聊细节配置和踩坑。

4. 让问答效果真正靠谱的配置细节：解析、图谱与检索调优

很多人在知识库部署完、上传几篇文档跑通问答后，就以为大功告成了。实际上这时候的效果往往只是"能回答"，离"回答得靠谱"还差得远。这里分享三个决定问答质量的配置方向。

4.1 文档解析质量决定天花板

知识库问答的上限不在大模型，在文档解析。WeKnora 对文档的处理不是简单把 PDF 转成文本就完事，而是需要做版面分析、标题层级识别、表格抽取等。我自己实测的结论是：

• PDF 扫描件必须开启 OCR 能力，否则文本全部是空白的。WeKnora 生态里常见的做法是接 PaddleOCR 或 MinerU 这类开源解析工具。我一开始没配 OCR，传了一份扫描版合同进去，解析结果全是乱码，图谱也抽了个寂寞。
• Word 文档里的表格是重灾区。很多 RAG 系统的表格解析直接翻车，WeKnora 在这块处理得相对好些，但表格结构特别复杂的文档，建议先转成 Markdown 再上传。
• Markdown 格式是最友好的，解析几乎零损耗，标题结构和列表层级能完整保留。个人建议团队内部文档优先用 Markdown 沉淀，PDF 只用来做历史资料归档。

这个方向给到的实用建议是：上传文档后不要急着触发图谱生成，先打开后台的解析结果预览，确认文本内容是完整的、结构是可读的，再进入下一步。宁可多花一分钟检查，也不要在一堆垃圾文本上构建知识图谱。

4.2 图谱生成配置：模型选得好，图才建得准

图谱生成是 WeKnora 最耗时的环节，也是差异化价值最大的环节。这个阶段的核心是把非结构化文本转换成结构化的三元组（实体—关系—实体），质量完全取决于抽取模型的能力。

我在调参过程中的几个实测体会如下：

• 上下文长度是关键参数。抽取模型如果上下文窗口太小，遇到长文档时只能截断，导致实体关系断裂。建议选择上下文窗口至少 32K 以上的模型，或者提前调整文档切块策略，让送入模型的文本片段保持合理长度。
• 提示词里的抽取Schema不要随意改。WeKnora 预置了一套实体类型和关系类型，如果乱加实体类型，模型输出就会不稳定，图谱也会变得杂乱无章。先跑一套默认配置，出问题再考虑细调。
• 图数据库的写入是分批的，图谱生成过程中如果出现任务失败，不用整库重跑，可以先查看失败原因，修复配置后对失败文档单独重试，省时省力。

还有一点容易被忽略：图谱并不是"生成一次就永久有效"。文档更新后，旧图谱里的实体关系会过期，这时候需要做增量更新或整体重建，具体看项目版本的更新策略。我的习惯是每周更新一次文档后再重建一次图谱，保持问答口径的鲜活度。

4.3 检索参数：向量召回与图谱查证的平衡

问答阶段的核心逻辑，是把向量检索结果和图谱查询结果合并交给大模型。涉及的关键参数一般有以下几项：

• 检索 TopK：向量召回返回多少个相关片段。调太大会往上下文里塞入无关内容，调太小则容易漏掉关键信息。我一般先设 5，观察效果再微调。
• 重排序开关：如果部署了跨编码器重排序模型，可以打开重排序，让召回的片段按真实相关性重新排序，效果提升明显，代价是响应时间变长。
• 图谱查询深度：这是和纯 RAG 差异最大的参数。图谱查询可以设定遍历路径的跳数，跳数越大越能发现间接关系，但可能引入噪声。默认 1~2 跳通常就够用。

这类参数没有绝对的最佳值，跟你文档体系的复杂度强相关。一个可参考的建议是：先准备 10 道难度不同的问题作为"测试集"，每次调参后跑一遍，看答案质量变化，而不是靠感觉反复横跳。

5. 踩坑实录：五次翻车和完整的排查链路

本地部署 WeKnora 的过程中，我前前后后踩了不少坑，有些问题花了大半天才定位到根因。这一段不是直接给答案，而是把排查思路写出来，方便你以后遇到类似问题能快速下手。

5.1 容器启动就崩：内存分配引发的连锁反应

第一次执行docker compose up时，前端服务起来后很快自动退出，docker compose logs里提示内存不足。查了下才知道是服务器同时运行了多个容器，内存一下子被占满，后端服务持续 OOM。

排查链路是这样的：

1. 用docker stats查看各容器的实时内存占用，找出内存大户。
2. 确认是neo4j和qdrant两个组件的默认缓存上限太高。
3. 修改图数据库配置，限制堆内存大小；修改向量库的缓存上限。
4. 重启全部容器，观察内存曲线稳定。

这种问题很典型，本质是默认配置面向生产环境，测试环境需要手动收紧。部署前看一眼总内存，再按比例分配各组件内存，能少走很多弯路。

5.2 模型接入：Ollama API 地址填错导致问答一直转圈

前端页面能正常登录，发起对话却一直转圈，没有任何报错。这种情况最容易被误判为网络问题，其实是后端根本连不上模型服务。

排查过程是这样的：

1. 先检查后端日志，发现有请求超时记录。
2. 在服务器本地用 curl 测试 Ollama 接口，手动请求一次对话补全，结果正常返回。
3. 对比发现 .env 里填的是http://localhost:11434/v1，但 WeKnora 后端跑在 Docker 容器里，localhost指向的是容器自身，而不是宿主机。
4. 把地址改成http://host.docker.internal:11434/v1或直接填宿主机内网 IP，问题解决。

这是一个 Docker 部署的老坑了，凡是"容器内访问宿主机服务"，都不能直接写 localhost，要多走一步宿主机地址映射。

5.3 图谱生成一直失败：模型的 JSON 输出不忍直视

图谱生成任务启动后，进度条卡在某一篇文档上，失败日志显示实体解析异常。打开抽取结果一看，模型输出的 JSON 格式乱七八糟，有缺少闭合括号的，有字段名写错的。

我第一反应是提示词的问题，后来把同样的文本喂给模型单独测试，发现其实是当时选了 7B 的小量化模型，指令遵循能力跟不上复杂的抽取要求。

最终的解决方案是：单独给图谱抽取换了一个更大尺寸、指令跟随更强的模型，而不是坚持用问答模型。知识库系统里的"问答"和"抽取"是两种完全不同的任务负载，别指望一个模型把所有活都干了。我之前图省事，所有模型都指向同一个 Ollama 实例，这是一个典型的选型失误。

5.4 扫描版 PDF 全乱码：OCR 没开启的代价

传了一个扫描版 PDF 进去，解析结果里全是乱码符号，图谱生成当然也就无从谈起。这个问题其实在 4.1 里说过，但真正想强调的是排查路径：

1. 打开解析结果预览，看到文本是乱码 / 空白，直接确认是图片型 PDF。
2. 检查 WeKnora 的解析配置，确认 OCR 组件未启用或未安装。
3. 启用 OCR 支持并安装对应依赖，重新上传文档。

有一种情况特别容易迷惑人：扫码文档里的英文能正确识别，中文全乱码。那时候别先怀疑系统，多半是 OCR 组件里缺少中文语言包，安装对应语言包就能解决。

5.5 问答答案明明有但出处飘忽：图谱过期在作祟

有一阵子问答的答案虽然正确，但引用文档明显是旧版本的内容。排查到最后发现文档已经更新过，但图谱仍是旧版。这一步让我彻底养成了"更新文档后重建图谱"的习惯。

排查思路很简单：打开图数据库界面，搜索某个实体，发现它关联的文档 ID 已经不存在于当前文档列表。这个现象基本就能确认是图谱过期。处理方式是删除该知识库的图谱数据，重新触发生成。

6. 进阶玩法：把 WeKnora 真正用成团队的私有问答底座

一个知识库系统跑通、调好，只算完成了第一步。真正让它发挥价值，还需要在团队协作和使用方式上做更多扩展。这里分享几个我认为值得尝试的方向。

6.1 多模型协作：让不同模型各干各的

刚才聊过问答和抽取可以分模型，更进一步的是可以在问答阶段做模型策略切换。比如：日常通用型问题用一个轻量模型快速响应，复杂推理问题让更强模型接管；或者接一路云端强模型作为"疑难杂症专属"，只在向量检索置信度低时触发。WeKnora 支持对接多个模型服务端点，这给了团队很大的调度自由度。

6.2 与 Obsidian、Trae 这类工具联动

很多人平时用 Obsidian 做个人知识管理，用 Trae 这类 AI 编程工具写代码、维护技术文档。这些工具产生的 Markdown 文件天然适合作为知识库的粮仓。我之前尝试过把 Obsidian 的仓库目录作为知识库文档源，通过定时同步脚本把新增的 Markdown 文件推送进 WeKnora，实现了"写笔记自动进知识库"的闭环。Trae 里的项目文档也可以采取同样策略，让 AI 编程时能参考到完整的项目知识沉淀。

6.3 多人协作：权限、审核与问答日志

知识库不是单机玩具，团队用起来之后，权限管理和内容审核就会浮上水面。正式启用前建议规划好定期整理文档、设置管理员账号、随时检查问答日志中出现的明显错误。问答日志是知识库系统的宝藏，里面记录着用户最真实的痛点，定期分析日志可以把知识库内容调整得越来越贴合团队的提问习惯。

7. 写在最后：部署之后的几点真实感受

整套 WeKnora 从部署到调优，给我最大的感受是知识库问答系统的核心竞争点并不在大模型本身，而在于"内容怎么被理解和组织"。纯 RAG 方案可以快速响应"这篇文章讲了什么"这类问题，而我们在实际工作中碰到的大量问题都是"这些文档之间是什么关系"，这恰恰是图谱的用武之地。

如果你正在 Dify 和 WeKnora 之间纠结，我的建议是看你的核心场景：如果主要是把文档变成可检索的资料库，Dify 的成熟度和生态会让人更省心；如果你的问题天然带着实体关系和跨文档链路，那 WeKnora 的图谱能力值得投入时间。本地部署的坑确实不少，但只要把模型选型、组件内存和文档解析这三关迈过去，后面基本就是稳定运行的常态化维护。

最后分享一个实操层面的小心得：部署知识库系统前，先花一小时整理三份不同格式、不同复杂度的测试文档。这三份文档会陪伴你度过后续所有的调试过程，每次配置变更都用同一套测试集来验证效果，对比才有意义。我现在那三份测试文档还躺在知识库里，它们的价值远远超过任何一页官方文档。