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 之后能压缩到两三分钟级别。以下是个人实测的硬件参考区间配置档次内存显卡适用场景最低可行32GB无纯CPU小规模文档试玩、个人学习推荐配置64GB16GB显存如RTX 4090/4090D团队内部知识库、中等文档量舒适配置128GB24GB显存以上大量 PDF 文档、频繁图谱构建内存这块要特别说一下WeKnora 的部署会用 Docker 起多个容器包括后端服务、前端、向量库、图数据库、对象存储等整套下来光容器占用的内存就不少。我最初在 32GB 内存的机器上部署启动后还没跑问答系统就开始内存告急最后不得不把图数据库和向量库的缓存调小。所以32GB 是下限64GB 才属于从容。2.2 大语言模型与 Embedding 模型的选择逻辑WeKnora 的设计有点像BYOMBring Your Own Model模型不内置而是通过配置接入外部大模型服务。这里有两种主流路子接云端 API只要能提供 OpenAI 兼容接口的厂商都行好处是模型能力强、省本地算力坏处是数据要出内网。接本地模型通过 Ollama 跑一个量化版模型再把接口地址指向本地。我本地部署选的是 Ollama 里的 DeepSeek-R1 蒸馏版和 Qwen2.5 系列具体理由后面展开。这里必须先强调一个关键配置问答模型和抽取模型是可以分开设置的。也就是说日常问答你可以用一个偏通用的模型而用来做实体抽取和图谱构建的模型建议选指令跟随能力更强的那款因为抽取任务对格式遵循要求比较高。如果抽取模型不够听话输出格式乱七八糟图谱构建质量会直线下降。Embedding 模型同样值得单独配置。不要贪大求全去选超大参数量的向量模型本地部署场景下 BAAI/bge-large-zh-v1.5 这类中文友好的模型已经够用检索效果比那些偏英文语料的模型稳得多。整体模型规划可以参考我自己用的这个组合用途模型部署方式备注问答生成Qwen2.5 14B / DeepSeek-R1 7B量化Ollama 本地16GB显存可勉强跑图谱抽取Qwen2.5 32B 量化 或 云端强模型Ollama 本地 / 云端API优先保证指令遵循和格式稳定向量嵌入bge-large-zh-v1.5本地起服务中文检索效果好资源占用小2.3 周边组件别照单全收WeKnora 的部署通常依赖向量数据库和图数据库。向量库方面官方推荐里有多种选择我在本地选了 Qdrant主要是它的 Docker 镜像轻量、资源占用相对小而且自带 Web UI 方便查看检索效果。图数据库则是 Neo4j 社区版作为承载实体关系图谱的存储。如果你之前没用过 Neo4j也不用有压力WeKnora 的图谱生成完成后主要是通过接口查询不需要手工去写 Cypher只有排查问题时才需要打开 Neo4j Browser 看一下图结构。还有一个容易忽略的组件是对象存储或文件存储服务用于保存上传的原始文档和解析产物。部署的时候注意给这个存储卷分配足够的磁盘空间因为解析后的中间文件往往比原文档还要大不少。3. 本地化部署完整走一遍从拉取代码到跑通第一轮问答这一节直接进入操作流程。我的部署环境是 Ubuntu 22.04Docker 和 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。排查链路是这样的用docker stats查看各容器的实时内存占用找出内存大户。确认是neo4j和qdrant两个组件的默认缓存上限太高。修改图数据库配置限制堆内存大小修改向量库的缓存上限。重启全部容器观察内存曲线稳定。这种问题很典型本质是默认配置面向生产环境测试环境需要手动收紧。部署前看一眼总内存再按比例分配各组件内存能少走很多弯路。5.2 模型接入Ollama API 地址填错导致问答一直转圈前端页面能正常登录发起对话却一直转圈没有任何报错。这种情况最容易被误判为网络问题其实是后端根本连不上模型服务。排查过程是这样的先检查后端日志发现有请求超时记录。在服务器本地用 curl 测试 Ollama 接口手动请求一次对话补全结果正常返回。对比发现 .env 里填的是http://localhost:11434/v1但 WeKnora 后端跑在 Docker 容器里localhost指向的是容器自身而不是宿主机。把地址改成http://host.docker.internal:11434/v1或直接填宿主机内网 IP问题解决。这是一个 Docker 部署的老坑了凡是容器内访问宿主机服务都不能直接写 localhost要多走一步宿主机地址映射。5.3 图谱生成一直失败模型的 JSON 输出不忍直视图谱生成任务启动后进度条卡在某一篇文档上失败日志显示实体解析异常。打开抽取结果一看模型输出的 JSON 格式乱七八糟有缺少闭合括号的有字段名写错的。我第一反应是提示词的问题后来把同样的文本喂给模型单独测试发现其实是当时选了 7B 的小量化模型指令遵循能力跟不上复杂的抽取要求。最终的解决方案是单独给图谱抽取换了一个更大尺寸、指令跟随更强的模型而不是坚持用问答模型。知识库系统里的问答和抽取是两种完全不同的任务负载别指望一个模型把所有活都干了。我之前图省事所有模型都指向同一个 Ollama 实例这是一个典型的选型失误。5.4 扫描版 PDF 全乱码OCR 没开启的代价传了一个扫描版 PDF 进去解析结果里全是乱码符号图谱生成当然也就无从谈起。这个问题其实在 4.1 里说过但真正想强调的是排查路径打开解析结果预览看到文本是乱码 / 空白直接确认是图片型 PDF。检查 WeKnora 的解析配置确认 OCR 组件未启用或未安装。启用 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 的图谱能力值得投入时间。本地部署的坑确实不少但只要把模型选型、组件内存和文档解析这三关迈过去后面基本就是稳定运行的常态化维护。最后分享一个实操层面的小心得部署知识库系统前先花一小时整理三份不同格式、不同复杂度的测试文档。这三份文档会陪伴你度过后续所有的调试过程每次配置变更都用同一套测试集来验证效果对比才有意义。我现在那三份测试文档还躺在知识库里它们的价值远远超过任何一页官方文档。 
长河君 · 2026/10/27 15:40:24 · 阅读 1.2k 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 之后能压缩到两三分钟级别。以下是个人实测的硬件参考区间配置档次内存显卡适用场景最低可行32GB无纯CPU小规模文档试玩、个人学习推荐配置64GB16GB显存如RTX 4090/4090D团队内部知识库、中等文档量舒适配置128GB24GB显存以上大量 PDF 文档、频繁图谱构建内存这块要特别说一下WeKnora 的部署会用 Docker 起多个容器包括后端服务、前端、向量库、图数据库、对象存储等整套下来光容器占用的内存就不少。我最初在 32GB 内存的机器上部署启动后还没跑问答系统就开始内存告急最后不得不把图数据库和向量库的缓存调小。所以32GB 是下限64GB 才属于从容。2.2 大语言模型与 Embedding 模型的选择逻辑WeKnora 的设计有点像BYOMBring Your Own Model模型不内置而是通过配置接入外部大模型服务。这里有两种主流路子接云端 API只要能提供 OpenAI 兼容接口的厂商都行好处是模型能力强、省本地算力坏处是数据要出内网。接本地模型通过 Ollama 跑一个量化版模型再把接口地址指向本地。我本地部署选的是 Ollama 里的 DeepSeek-R1 蒸馏版和 Qwen2.5 系列具体理由后面展开。这里必须先强调一个关键配置问答模型和抽取模型是可以分开设置的。也就是说日常问答你可以用一个偏通用的模型而用来做实体抽取和图谱构建的模型建议选指令跟随能力更强的那款因为抽取任务对格式遵循要求比较高。如果抽取模型不够听话输出格式乱七八糟图谱构建质量会直线下降。Embedding 模型同样值得单独配置。不要贪大求全去选超大参数量的向量模型本地部署场景下 BAAI/bge-large-zh-v1.5 这类中文友好的模型已经够用检索效果比那些偏英文语料的模型稳得多。整体模型规划可以参考我自己用的这个组合用途模型部署方式备注问答生成Qwen2.5 14B / DeepSeek-R1 7B量化Ollama 本地16GB显存可勉强跑图谱抽取Qwen2.5 32B 量化 或 云端强模型Ollama 本地 / 云端API优先保证指令遵循和格式稳定向量嵌入bge-large-zh-v1.5本地起服务中文检索效果好资源占用小2.3 周边组件别照单全收WeKnora 的部署通常依赖向量数据库和图数据库。向量库方面官方推荐里有多种选择我在本地选了 Qdrant主要是它的 Docker 镜像轻量、资源占用相对小而且自带 Web UI 方便查看检索效果。图数据库则是 Neo4j 社区版作为承载实体关系图谱的存储。如果你之前没用过 Neo4j也不用有压力WeKnora 的图谱生成完成后主要是通过接口查询不需要手工去写 Cypher只有排查问题时才需要打开 Neo4j Browser 看一下图结构。还有一个容易忽略的组件是对象存储或文件存储服务用于保存上传的原始文档和解析产物。部署的时候注意给这个存储卷分配足够的磁盘空间因为解析后的中间文件往往比原文档还要大不少。3. 本地化部署完整走一遍从拉取代码到跑通第一轮问答这一节直接进入操作流程。我的部署环境是 Ubuntu 22.04Docker 和 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。排查链路是这样的用docker stats查看各容器的实时内存占用找出内存大户。确认是neo4j和qdrant两个组件的默认缓存上限太高。修改图数据库配置限制堆内存大小修改向量库的缓存上限。重启全部容器观察内存曲线稳定。这种问题很典型本质是默认配置面向生产环境测试环境需要手动收紧。部署前看一眼总内存再按比例分配各组件内存能少走很多弯路。5.2 模型接入Ollama API 地址填错导致问答一直转圈前端页面能正常登录发起对话却一直转圈没有任何报错。这种情况最容易被误判为网络问题其实是后端根本连不上模型服务。排查过程是这样的先检查后端日志发现有请求超时记录。在服务器本地用 curl 测试 Ollama 接口手动请求一次对话补全结果正常返回。对比发现 .env 里填的是http://localhost:11434/v1但 WeKnora 后端跑在 Docker 容器里localhost指向的是容器自身而不是宿主机。把地址改成http://host.docker.internal:11434/v1或直接填宿主机内网 IP问题解决。这是一个 Docker 部署的老坑了凡是容器内访问宿主机服务都不能直接写 localhost要多走一步宿主机地址映射。5.3 图谱生成一直失败模型的 JSON 输出不忍直视图谱生成任务启动后进度条卡在某一篇文档上失败日志显示实体解析异常。打开抽取结果一看模型输出的 JSON 格式乱七八糟有缺少闭合括号的有字段名写错的。我第一反应是提示词的问题后来把同样的文本喂给模型单独测试发现其实是当时选了 7B 的小量化模型指令遵循能力跟不上复杂的抽取要求。最终的解决方案是单独给图谱抽取换了一个更大尺寸、指令跟随更强的模型而不是坚持用问答模型。知识库系统里的问答和抽取是两种完全不同的任务负载别指望一个模型把所有活都干了。我之前图省事所有模型都指向同一个 Ollama 实例这是一个典型的选型失误。5.4 扫描版 PDF 全乱码OCR 没开启的代价传了一个扫描版 PDF 进去解析结果里全是乱码符号图谱生成当然也就无从谈起。这个问题其实在 4.1 里说过但真正想强调的是排查路径打开解析结果预览看到文本是乱码 / 空白直接确认是图片型 PDF。检查 WeKnora 的解析配置确认 OCR 组件未启用或未安装。启用 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 的图谱能力值得投入时间。本地部署的坑确实不少但只要把模型选型、组件内存和文档解析这三关迈过去后面基本就是稳定运行的常态化维护。最后分享一个实操层面的小心得部署知识库系统前先花一小时整理三份不同格式、不同复杂度的测试文档。这三份文档会陪伴你度过后续所有的调试过程每次配置变更都用同一套测试集来验证效果对比才有意义。我现在那三份测试文档还躺在知识库里它们的价值远远超过任何一页官方文档。