1. 为什么我最终从拼接式RAG换成了 WeKnora 这种一站式方案说个真实场景我手头维护的资料库大概有三百多份文档包括产品白皮书、售前方案PPT、扫描版合同、客户FAQ、以及大量带表格和图片的PDF。原本的检索方式就是网盘加文件夹再配一个全文搜索工具真到了去年给某客户报的报价是什么这种问题翻十几分钟是常态。最初我并没有直接上 WeKnora而是走了很多人都会走的路自己拼一套RAG。向量库用 MilvusEmbedding 用 BGELLM 打算先接云端 API文档解析用 PyMuPDF 配合自研规则做切片。折腾了两周能跑通但效果一言难尽——表格被切得粉碎扫描件直接是空文本图片里的关键信息一个都抽不出来问出来的答案驴唇不对马嘴。后来在一个开源社区的讨论帖里看到 WeKnora才知道腾讯微信团队开源了这个项目。它的定位和普通RAG框架不太一样它不是让你自己拼装而是把数据接入、文档理解、切片、索引、混合检索、重排、生成、Agent 编排全部串成一条完整流水线而且对中文场景的处理明显更细致。我把它部署到本地之后第一个感觉是这才是文档该有的待遇。PAW 文档理解流水线能把版面分析、OCR、表格转 Markdown、图表信息提取这些脏活全部接管这在以前是我要写几千行代码去做的事。这套系统适合谁来用我觉得大概是两类人一类是像我一样被各种格式混乱、扫描件居多、表格密布的文档折磨得够呛想搭一个真正能问问题的内部知识库另一类是团队已经有一些 LLM 使用经验但发现通用 RAG 框架对复杂文档的解析和召回精度不够需要一个更完整的开源知识库底座。整篇文章我会把选型理由、模型决策、部署步骤、踩坑过程、调优方法完整记录下来按我实际操作顺序写不是照着官方 README 念后者很多关键弯路根本不会告诉你。先给一个结论如果你现在的痛点只是缺一个工作流编排平台那 Dify 可能更合适但如果痛点在于文档根本进不去、检索不准、表格一塌糊涂WeKnora 这种把文档解析做到极致的开源知识库方案会更能解决问题。2. 部署前的关键决策模型放哪、机器要多大、选哪家Embedding2.1 LLM 选型我用 Ollama 跑 Qwen而不是直接接云端 API标题既然叫本地部署实录那大模型也应该是本地的否则没意义。我最早考虑过直接把 WeKnora 的 LLM 接口指向 OpenAI 兼容的云端 API这样最省事但数据都要出内网在办公场景里过不了安全这一关。所以最后选了 Ollama 作为本地模型运行时。Ollama 的好处是极简一条命令拉模型一条命令起服务而且它提供了 OpenAI 兼容接口WeKnora 配置模型时可以直接走 OpenAI 兼容协议非常方便。模型选择上我对比了三个方向Qwen2.5-7B-Instruct中文理解能力扎实7B 量级在 CPU 上也能勉强跑起来是我最终的主力模型。DeepSeek-R1-Distill-Qwen-7B推理能力强但速度偏慢适合做逐步推理类的复杂问题。热词里也有 deepseek 本地部署说明这条路很多人走通了。Qwen2.5-14B如果你有 16GB 以上显存强烈建议直接上 14B答案质量比 7B 高一个档次尤其是长文档总结场景。量化级别我选的 Q4_K_M。7B 的 Q4_K_M 模型文件大概 4.7GB14B 大概 9GB这是 CPU 推理和显存占用之间的平衡点。再低比如 Q2 就别用了质量衰减肉眼可见。2.2 Embedding 和 Rerank 不能省这是检索精度的真正分水岭很多教程只教你配置 LLMEmbedding 随便选一个Rerank 干脆不配。我在实操中的结论是Rerank 对回答质量的影响甚至大于换一个大模型。Embedding 我用的是 BAAI 的 bge-m3原因很直接它对中文语义的支持明显好于 nomic-embed-text 这类英文为主的模型而且支持 8192 token 的长文本处理整段方案描述不容易被截断。在 Ollama 里拉下来就是一条命令的事。Rerank 也是 BGE 家族的 bge-reranker-v2-m3。它做的事情是先让向量检索和关键词检索各召回一批候选文档比如总共 50 条Rerank 再逐条计算和问题的真实相关性把最相关的 5 到 10 条排到最前面。这一步可以理解为粗筛靠向量精排靠重排。如果你硬件紧张可以先用一小批数据测试确认检索精度成为瓶颈了再补上 Rerank这个优先级是对的。2.3 硬件底线我的实测配置与建议我部署用的是一台旧工作站放在办公网里4 核 8 线程 CPU32GB 内存没有 GPU。这个配置跑 Qwen2.5-7B 的 CPU 推理单轮问答大概 3 到 6 秒能忍但并发一多就明显吃力。文档解析特别是 OCR 阶段非常吃 CPU批量导入 PDF 时整个系统会卡顿。给几个可以参考的档位部署规模内存CPU/GPU模型覆盖场景尝鲜验证16GB4核CPU7B Q4量化单用户少量文档小型团队32GB8核CPU或入门GPU7B~14B5~10人使用生产环境64GB24GB显存GPU14B多并发大量文档一个容易被忽略的点内存不只是给 LLM 用的。文档解析进程、Embedding 模型、向量索引、Rerank 都会常驻内存我实测纯 7B 模型 bge-m3 嵌入 bge-reranker加上 WeKnora 前后端内存占用轻松到 14GB。16GB 的机器跑全套真的很紧张建议至少 32GB。3. 从克隆代码到首次启动环境准备、依赖安装和常见版本坑3.1 环境准备Python 版本是第一个坑WeKnora 的部署方式在仓库 README 里有明确说明但版本更新比较频繁一些细节会变。我按当时实际操作的流程记录你部署时如果发现命令不一致以你拉取到的分支 README 为准。先准备基础环境。我踩的第一个坑就是 Python 版本必须用 3.10 或 3.11太老或太新的版本在装依赖时都可能出编译错误。我一开始用的是系统自带的 Python 3.9安装 requirements 里的某些依赖直接报错换到 3.10 虚拟环境就正常了。sudo apt install python3.10-venv python3.10 -m venv weknora-venv source weknora-venv/bin/activate前端部分需要 Node.js 和 pnpm我用的是 Node 18。WeKnora 的前端是 Vue3 技术栈直接用 pnpm 管理依赖。3.2 后端依赖PaddleOCR 是最大的定时炸弹克隆代码后进入项目目录安装后端依赖git clone https://github.com/Tencent/WeKnora.git cd WeKnora pip install -r requirements.txt这个命令表面上普普通通但里面的雷在 PaddleOCR 相关依赖上。我第一次装的时候直接用默认命令pip 给我装了一堆依赖跑起来才发现 Paddle 的版本和 Python 不兼容进程直接崩掉。正确的姿势是先单独装 CPU 版 PaddlePaddle再装 PaddleOCR装完之后再用 requirements 装其余部分。顺序搞反了就很容易踩到 Paddle 把 numpy 依赖锁上的坑。pip install paddlepaddle # CPU版本别默认装GPU版否则CUDA依赖会卡死你 pip install paddleocr如果你的文档全是文本型 PDF不需要 OCR可以在 WeKnora 的解析配置里把 OCR 模块关掉能省不少 CPU 占用。这个后面会再提。前端构建pnpm install pnpm build第一次构建会拉不少依赖耐心等就好。这个环节倒没遇到太诡异的坑最多是网络问题导致个别包下载超时重试即可。3.3 配置与启动把默认端口和数据库搞清楚WeKnora 的配置文件主要在项目目录下的 config 相关文件里里面涉及数据库地址、服务端口、日志路径等。默认配置可以走 SQLite小规模验证足够如果团队一起用建议换成 MySQL不然并发写入了会锁库。启动方式我按官方命令来后端是一个 Python 服务前端是一个静态站点。开发模式下前端用 dev server 跑生产环境用 build 后的静态文件让后端托管或者单独用 Nginx 代理。首次启动后浏览器访问前端地址它会引导初始化管理员账号。到这里还没接入模型系统能打开但问不了问题因为还没配 LLM。这里有一个值得强调的细节系统默认监听地址如果是 127.0.0.1只有本机能访问如果想让局域网同事用启动时要把 host 改为 0.0.0.0。但是不要把这个服务直接暴露到公网这个我们在最后一章再展开说。4. 接通本地模型让问答系统真正开口说话4.1 管理后台配置 LLM 接口WeKnora 启动后进入管理后台找到模型供应商配置页面。这里支持多种 provider本地部署场景下最常用的是 OpenAI 兼容接口或者 Ollama 直连取决于版本选项。我当时的配置是这样的base_url 填http://127.0.0.1:11434/v1api_key 填任意值比如ollama因为本地 Ollama 不校验 keymodel 名称填qwen2.5:7b-instruct注意必须是 Ollama 里 pull 下来的确切名称多一个冒号少一个 tag 都会报错Embedding 模型同理把模型类型切到 embeddingbase_url 指到 Ollama 的地址模型名填bge-m3。Rerank 如果配了也是同样的思路。4.2 连通性测试先 curl 后页面别一上来就怪系统配置完成后WebUI 里通常有测试按钮。如果提示连接失败不要急着怀疑是 WeKnora 的问题先在本机用 curl 验证 Ollama 接口是否正常curl -X POST http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:7b-instruct,messages:[{role:user,content:你好}]}能正常返回内容说明 Ollama 没问题问题出在 WeKnora 侧的地址或者网络。这里有个非常经典的坑如果你用 Docker 方式跑 WeKnora容器里的 127.0.0.1 指向的是容器自己不是宿主机。这时候要把 base_url 改成http://host.docker.internal:11434/v1Linux 下如果用 docker compose可以加extra_hosts: - host.docker.internal:host-gateway。我在这一步卡了快一个小时。另一个容易踩的是 CORS。浏览器直接访问前端页面发起跨域请求时Ollama 默认对来源有限制。解决办法是给 Ollama 设置环境变量OLLAMA_ORIGINS* ollama serve简单粗暴但本地内网环境这么干问题不大。要注意的是这个环境变量是进程级的设置完要重启 ollama 服务。4.3 第一次真实问答预期管理很重要模型配好之后我先建了一个很小的知识库放了一份 Markdown 格式的 FAQ文档内容是XX 系统如何开通、常见错误码含义。导入成功后做索引然后提问客户反馈登录一直失败错误码 10023怎么处理效果比我预期的好系统能准确引用 FAQ 里的对应条目并且返回了处理建议答案下面还挂了引用来源。但同时我也发现了第一个问题7B 模型对问题的理解过于字面化如果问题里不包含错误码它就不太会联想到相关 FAQ。这说明检索链路本身该做的活已经做完了瓶颈开始转向模型推理能力。所以我建议第一次测试时把预期调低一点不要指望 7B 模型在没有 Rerank、没有调优的情况下就给出惊艳答案。第一步只确认链路通、引用准后面再逐步优化。5. 文档解析和 Agentic RAG 的真实体验PAW 到底强在哪5.1 把一份扫描版方案 PDF 扔给 PAW 之后的对比为了测试 WeKnora 的文档理解能力我专门找了一份旧方案文档一个扫描版的 PDF大概是十几页里面包含彩色封面、目录、带财务数据的表格、几张架构图、还有一些手写批注的痕迹。我将它导入 WeKnora后台任务跑了一阵子打开解析结果一看确实有点东西文字内容被完整 OCR 出来了表格被还原成了 Markdown 表格格式架构图里的文字说明也被单独提取成了图片注释多栏排版的阅读顺序没有被搞乱。这些都是之前我用开源工具自研解析时会崩溃的典型场景。再用对照组来验证同一份 PDF 用 PyMuPDF 直接抽文本结果是一些空行和偶尔乱码因为整个文件本质是图片用单纯的开源 OCR 工具跑文字是出来了但表格结构完全丢了多栏文字串成了一坨。PAW 的价值在于流水线式地把版面分析、OCR、表格结构识别、阅读顺序还原串起来而不是单点工具能比的事。5.2 混合检索和 Rerank 在生产中的真实分工WeKnora 的检索不是单一向量召回而是混合了语义向量、关键词命中、知识图谱关联。这一点在业务文档里非常有用。举个例子文档里经常出现CRM-2024-01这种产品编号。你拿向量去搜CRM-2024-01效果通常不稳定因为向量模型对这个字符串的理解很弱但关键词检索能精准命中。反过来客户关系管理系统的升级方案这种语义描述关键词搜不到向量能轻松召回到相关段落。混合检索就是让这两条路各自发挥优势再合并结果。Rerank 在最终的排序阶段把关。之前我把上下文数量设得很大一次性送三十条检索结果给模型结果上下文爆炸回答质量急剧下降。加上 Rerank 之后先把候选压缩到 top 5模型输入更干净回答质量直接提升。所以我在调优时把 Rerank 的优先级放在很前面。5.3 Agentic RAG 的实际效果什么时候该用什么时候别滥用WeKnora 的 Agentic RAG 模式在管理后台可以开启。它的逻辑是让模型不再做一次检索一次回答而是先拆解用户的复杂问题再决定去哪个知识库检索、调用什么工具、分几步回答。我测试过一个多步骤问题对比新老两版售后服务政策中退换货时效的变化并总结对客户沟通的影响。基础 RAG 模式下模型很容易只找到其中一个版本就开答漏掉对比。切到 Agent 模式后它会先拆成找到两个版本-抽取退换货条款-对比差异-生成结论几步看起来更接近人的检索路径。但我也要泼一盆冷水Agent 模式不是默认开启就万事大吉的。如果知识库范围太大、工具权限没有收敛模型反而会自由发挥检索一些无关的内容甚至凭空生成中间结论。我的做法是在配置里把 Agent 可访问的知识库范围明确限定并给每个知识库加上清晰的角色描述。别让它自由发挥太多。6. 踩坑实录从部署到稳定运行的完整排查链路6.1 症状一模型服务连接超时排查到最后是 localhost 指向问题现象页面测试连接提示 LLM 服务连接超时。这是部署最常遇到的第一个大坑。排查链路先在宿主机执行curl http://127.0.0.1:11434/v1确认 Ollama 服务确实在跑。再确认 WeKnora 的 base_url 是否正确。如果 WeKnora 跑在 Docker 容器里127.0.0.1指容器自己必须改用host.docker.internal。检查 Ollama 是否开启了跨域限制。前端直连时会报 CORS 错误设置OLLAMA_ORIGINS*后重启。最后定位到的根因其实就是第二点容器内外 localhost 的含义不同。这个坑在本地部署里极具代表性属于写配置时看起来完全正确跑起来就是不通的典型。6.2 症状二文档索引成功但答案答非所问现象知识库索引任务显示成功提问后答案和文档内容没有明确关系甚至引用来源都不对。排查链路先打开文档解析结果确认文本内容是否真的被正确提取。结果发现文本在但被切成片段。再检查检索调试页面看输入问题后到底召回了哪些片段。发现召回的段落里只有一半和问题相关另一半是其他主题的内容。进一步查了 chunk 设置默认的切分大小偏大一段话里混了两个主题向量检索时语义就不够聚焦。解决方案是重建索引并把切片策略调小。比如 chunk_size 从默认值调成 512上下文重叠 100。具体要结合文档特点调但方向是让每个切片尽量聚焦单一主题。改完后重新导入或重建索引答案质量明显好转。这个过程让我意识到一个经常被忽视的事情RAG 系统的错误不一定出在模型很多是先出在文档切片环节。切片像切菜切得太大一锅炖不下切得太碎味道就散了。WeKnora 虽然切片策略可配置但默认值未必适合你的文档。6.3 症状三7B 模型回答读不出重点开头啰嗦、结尾敷衍现象Qwen2.5-7B 在长文档问答时答案前半段在复述文档标题后半段直接说请参考文档第X页没有实际内容。排查链路检查送进模型的上下文内容发现一次塞了太多检索片段超出了模型的 32K 上下文窗口被系统自动截断。截断后模型只看到了文档开头的章节信息没看到真正的内容段落。量化模型本身对长文本的归纳能力有限7B 在上下文很长时容易只看见开头和结尾。解决方案有两步第一步是我的老办法启用 Rerank 后把召回数量从 10 降到 5让上下文更精炼第二步是把 max_new_tokens 调大一些给模型更多输出空间。条件允许的情况下换 14B 模型会彻底改善这类问题。6.4 症状四导入文档时解析任务失败日志指向 PaddleOCR现象批量导入 PDF 时部分任务失败日志里有 Paddle 相关的异常。排查链路确认是 GPU 版 Paddle 在没有 CUDA 环境时的兼容问题卸载后安装 CPU 版解决。部分扫描版 PDF 存在旋转页需要开启 OCR 中的自动旋转校正选项。对于双栏排版的扫描件版面分析尤其重要。如果不开版面分析两栏文字会被按行串联上下文语义错乱。最终建议是如果你的文档以扫描件为主先单独跑一轮 OCR 测试任务确认 Paddle 环境没问题再批量导入。批量导入前用小样本试跑能省下不少排查任务失败的时间。7. 部署完之后的日常使用与进阶方向7.1 我的日常操作流从搭好到用好系统稳定运行之后我把日常操作固定成了一套流程。新增文档统一放到一个待处理目录定期上传到 WeKnora 并触发解析每周跑一轮事先准备的问题测试集——大概二十个常见客户问题逐个问答看答案质量有没有波动如果换了模型版本先用这套测试集做 A/B 对比不会直接在生产知识库上开新模型。另外一个容易被忽略的事是索引维护。文档更新后旧索引里的内容不会自动消失需要重新导入或删除。我的做法是给每个知识库设定负责人文档版本更新时同步做索引重建。不然旧版本和新版本的内容混在检索结果里答案可能引用已经作废的政策或报价。7.2 团队权限与 SSOOIDC 和账号体系WeKnora 支持多用户体系而且热词里也有weknora oidc这个检索词说明不少人在问 SSO 集成的问题。我在内网环境里配置了 OIDC 对接企业现有的统一认证这样团队成员不需要单独注册账号直接用公司账号登录。这一块在团队场景里几乎是必须的否则每个人都要手动开账号权限也不好收敛。权限控制的粒度上我的建议是业务敏感的知识库要有独立的访问权限控制不要让所有登录用户都能看全量文档。我们实际就把财务相关规则库和销售产品库分开了不同角色只能检索自己有权限的知识库。7.3 结合 Dify 做更复杂的工作流编排部署完一段时间后我也尝试了把 WeKnora 和 Dify 结合。思路是WeKnora 负责文档解析、知识库管理和精准检索Dify 负责更灵活的对话工作流、外部工具接入、以及和现有业务系统对接。比如客户问题进来自动分类-不同分类走不同知识库-再触发工单创建这类流程Dify 的编排体验比 WeKnora 内置功能更细腻。两个开源项目各司其职反而是比较舒服的组合方式。7.4 进阶功能GraphRAG 和模型微调如果知识库里的实体关系很复杂比如供应链关系、组织架构、人员变动这类数据可以考虑开启 WeKnora 的图增强能力也就是 GraphRAG 方向。它会把文档中的实体和关系抽出来构建知识图谱检索时不光找相似段落还能沿着关系链找答案。我实测在公司上下游关联这类问题上图谱增强明显比纯向量检索强。模型微调这块我没有深入但客观说必要性不大。对大多数团队换更好的基础模型、调好切片和检索参数收益远大于微调。微调是针对模型回答风格或特定领域术语做定制时才需要考虑的选项。整套系统跑了快两个月最直观的感受是开源知识库的差距不在模型而在文档解析和检索链路的成熟度。WeKnora 让我把精力从怎么洗文档、怎么搭索引这类脏活里解放出来集中到真正的调优和场景设计上。如果你手里也有一堆无法直接喂给大模型的文档我建议直接拿 WeKnora 跑一轮最小知识库验证先把链路通起来再逐步加 Rerank、Agent 和 Dify 工作流。后面我还打算把企业微信里的历史消息自动同步进去到时候再更新一篇实践记录。 WeKnora本地部署实战：一站式RAG知识库解决复杂文档解析
1. 为什么我最终从拼接式RAG换成了 WeKnora 这种一站式方案说个真实场景我手头维护的资料库大概有三百多份文档包括产品白皮书、售前方案PPT、扫描版合同、客户FAQ、以及大量带表格和图片的PDF。原本的检索方式就是网盘加文件夹再配一个全文搜索工具真到了去年给某客户报的报价是什么这种问题翻十几分钟是常态。最初我并没有直接上 WeKnora而是走了很多人都会走的路自己拼一套RAG。向量库用 MilvusEmbedding 用 BGELLM 打算先接云端 API文档解析用 PyMuPDF 配合自研规则做切片。折腾了两周能跑通但效果一言难尽——表格被切得粉碎扫描件直接是空文本图片里的关键信息一个都抽不出来问出来的答案驴唇不对马嘴。后来在一个开源社区的讨论帖里看到 WeKnora才知道腾讯微信团队开源了这个项目。它的定位和普通RAG框架不太一样它不是让你自己拼装而是把数据接入、文档理解、切片、索引、混合检索、重排、生成、Agent 编排全部串成一条完整流水线而且对中文场景的处理明显更细致。我把它部署到本地之后第一个感觉是这才是文档该有的待遇。PAW 文档理解流水线能把版面分析、OCR、表格转 Markdown、图表信息提取这些脏活全部接管这在以前是我要写几千行代码去做的事。这套系统适合谁来用我觉得大概是两类人一类是像我一样被各种格式混乱、扫描件居多、表格密布的文档折磨得够呛想搭一个真正能问问题的内部知识库另一类是团队已经有一些 LLM 使用经验但发现通用 RAG 框架对复杂文档的解析和召回精度不够需要一个更完整的开源知识库底座。整篇文章我会把选型理由、模型决策、部署步骤、踩坑过程、调优方法完整记录下来按我实际操作顺序写不是照着官方 README 念后者很多关键弯路根本不会告诉你。先给一个结论如果你现在的痛点只是缺一个工作流编排平台那 Dify 可能更合适但如果痛点在于文档根本进不去、检索不准、表格一塌糊涂WeKnora 这种把文档解析做到极致的开源知识库方案会更能解决问题。2. 部署前的关键决策模型放哪、机器要多大、选哪家Embedding2.1 LLM 选型我用 Ollama 跑 Qwen而不是直接接云端 API标题既然叫本地部署实录那大模型也应该是本地的否则没意义。我最早考虑过直接把 WeKnora 的 LLM 接口指向 OpenAI 兼容的云端 API这样最省事但数据都要出内网在办公场景里过不了安全这一关。所以最后选了 Ollama 作为本地模型运行时。Ollama 的好处是极简一条命令拉模型一条命令起服务而且它提供了 OpenAI 兼容接口WeKnora 配置模型时可以直接走 OpenAI 兼容协议非常方便。模型选择上我对比了三个方向Qwen2.5-7B-Instruct中文理解能力扎实7B 量级在 CPU 上也能勉强跑起来是我最终的主力模型。DeepSeek-R1-Distill-Qwen-7B推理能力强但速度偏慢适合做逐步推理类的复杂问题。热词里也有 deepseek 本地部署说明这条路很多人走通了。Qwen2.5-14B如果你有 16GB 以上显存强烈建议直接上 14B答案质量比 7B 高一个档次尤其是长文档总结场景。量化级别我选的 Q4_K_M。7B 的 Q4_K_M 模型文件大概 4.7GB14B 大概 9GB这是 CPU 推理和显存占用之间的平衡点。再低比如 Q2 就别用了质量衰减肉眼可见。2.2 Embedding 和 Rerank 不能省这是检索精度的真正分水岭很多教程只教你配置 LLMEmbedding 随便选一个Rerank 干脆不配。我在实操中的结论是Rerank 对回答质量的影响甚至大于换一个大模型。Embedding 我用的是 BAAI 的 bge-m3原因很直接它对中文语义的支持明显好于 nomic-embed-text 这类英文为主的模型而且支持 8192 token 的长文本处理整段方案描述不容易被截断。在 Ollama 里拉下来就是一条命令的事。Rerank 也是 BGE 家族的 bge-reranker-v2-m3。它做的事情是先让向量检索和关键词检索各召回一批候选文档比如总共 50 条Rerank 再逐条计算和问题的真实相关性把最相关的 5 到 10 条排到最前面。这一步可以理解为粗筛靠向量精排靠重排。如果你硬件紧张可以先用一小批数据测试确认检索精度成为瓶颈了再补上 Rerank这个优先级是对的。2.3 硬件底线我的实测配置与建议我部署用的是一台旧工作站放在办公网里4 核 8 线程 CPU32GB 内存没有 GPU。这个配置跑 Qwen2.5-7B 的 CPU 推理单轮问答大概 3 到 6 秒能忍但并发一多就明显吃力。文档解析特别是 OCR 阶段非常吃 CPU批量导入 PDF 时整个系统会卡顿。给几个可以参考的档位部署规模内存CPU/GPU模型覆盖场景尝鲜验证16GB4核CPU7B Q4量化单用户少量文档小型团队32GB8核CPU或入门GPU7B~14B5~10人使用生产环境64GB24GB显存GPU14B多并发大量文档一个容易被忽略的点内存不只是给 LLM 用的。文档解析进程、Embedding 模型、向量索引、Rerank 都会常驻内存我实测纯 7B 模型 bge-m3 嵌入 bge-reranker加上 WeKnora 前后端内存占用轻松到 14GB。16GB 的机器跑全套真的很紧张建议至少 32GB。3. 从克隆代码到首次启动环境准备、依赖安装和常见版本坑3.1 环境准备Python 版本是第一个坑WeKnora 的部署方式在仓库 README 里有明确说明但版本更新比较频繁一些细节会变。我按当时实际操作的流程记录你部署时如果发现命令不一致以你拉取到的分支 README 为准。先准备基础环境。我踩的第一个坑就是 Python 版本必须用 3.10 或 3.11太老或太新的版本在装依赖时都可能出编译错误。我一开始用的是系统自带的 Python 3.9安装 requirements 里的某些依赖直接报错换到 3.10 虚拟环境就正常了。sudo apt install python3.10-venv python3.10 -m venv weknora-venv source weknora-venv/bin/activate前端部分需要 Node.js 和 pnpm我用的是 Node 18。WeKnora 的前端是 Vue3 技术栈直接用 pnpm 管理依赖。3.2 后端依赖PaddleOCR 是最大的定时炸弹克隆代码后进入项目目录安装后端依赖git clone https://github.com/Tencent/WeKnora.git cd WeKnora pip install -r requirements.txt这个命令表面上普普通通但里面的雷在 PaddleOCR 相关依赖上。我第一次装的时候直接用默认命令pip 给我装了一堆依赖跑起来才发现 Paddle 的版本和 Python 不兼容进程直接崩掉。正确的姿势是先单独装 CPU 版 PaddlePaddle再装 PaddleOCR装完之后再用 requirements 装其余部分。顺序搞反了就很容易踩到 Paddle 把 numpy 依赖锁上的坑。pip install paddlepaddle # CPU版本别默认装GPU版否则CUDA依赖会卡死你 pip install paddleocr如果你的文档全是文本型 PDF不需要 OCR可以在 WeKnora 的解析配置里把 OCR 模块关掉能省不少 CPU 占用。这个后面会再提。前端构建pnpm install pnpm build第一次构建会拉不少依赖耐心等就好。这个环节倒没遇到太诡异的坑最多是网络问题导致个别包下载超时重试即可。3.3 配置与启动把默认端口和数据库搞清楚WeKnora 的配置文件主要在项目目录下的 config 相关文件里里面涉及数据库地址、服务端口、日志路径等。默认配置可以走 SQLite小规模验证足够如果团队一起用建议换成 MySQL不然并发写入了会锁库。启动方式我按官方命令来后端是一个 Python 服务前端是一个静态站点。开发模式下前端用 dev server 跑生产环境用 build 后的静态文件让后端托管或者单独用 Nginx 代理。首次启动后浏览器访问前端地址它会引导初始化管理员账号。到这里还没接入模型系统能打开但问不了问题因为还没配 LLM。这里有一个值得强调的细节系统默认监听地址如果是 127.0.0.1只有本机能访问如果想让局域网同事用启动时要把 host 改为 0.0.0.0。但是不要把这个服务直接暴露到公网这个我们在最后一章再展开说。4. 接通本地模型让问答系统真正开口说话4.1 管理后台配置 LLM 接口WeKnora 启动后进入管理后台找到模型供应商配置页面。这里支持多种 provider本地部署场景下最常用的是 OpenAI 兼容接口或者 Ollama 直连取决于版本选项。我当时的配置是这样的base_url 填http://127.0.0.1:11434/v1api_key 填任意值比如ollama因为本地 Ollama 不校验 keymodel 名称填qwen2.5:7b-instruct注意必须是 Ollama 里 pull 下来的确切名称多一个冒号少一个 tag 都会报错Embedding 模型同理把模型类型切到 embeddingbase_url 指到 Ollama 的地址模型名填bge-m3。Rerank 如果配了也是同样的思路。4.2 连通性测试先 curl 后页面别一上来就怪系统配置完成后WebUI 里通常有测试按钮。如果提示连接失败不要急着怀疑是 WeKnora 的问题先在本机用 curl 验证 Ollama 接口是否正常curl -X POST http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:7b-instruct,messages:[{role:user,content:你好}]}能正常返回内容说明 Ollama 没问题问题出在 WeKnora 侧的地址或者网络。这里有个非常经典的坑如果你用 Docker 方式跑 WeKnora容器里的 127.0.0.1 指向的是容器自己不是宿主机。这时候要把 base_url 改成http://host.docker.internal:11434/v1Linux 下如果用 docker compose可以加extra_hosts: - host.docker.internal:host-gateway。我在这一步卡了快一个小时。另一个容易踩的是 CORS。浏览器直接访问前端页面发起跨域请求时Ollama 默认对来源有限制。解决办法是给 Ollama 设置环境变量OLLAMA_ORIGINS* ollama serve简单粗暴但本地内网环境这么干问题不大。要注意的是这个环境变量是进程级的设置完要重启 ollama 服务。4.3 第一次真实问答预期管理很重要模型配好之后我先建了一个很小的知识库放了一份 Markdown 格式的 FAQ文档内容是XX 系统如何开通、常见错误码含义。导入成功后做索引然后提问客户反馈登录一直失败错误码 10023怎么处理效果比我预期的好系统能准确引用 FAQ 里的对应条目并且返回了处理建议答案下面还挂了引用来源。但同时我也发现了第一个问题7B 模型对问题的理解过于字面化如果问题里不包含错误码它就不太会联想到相关 FAQ。这说明检索链路本身该做的活已经做完了瓶颈开始转向模型推理能力。所以我建议第一次测试时把预期调低一点不要指望 7B 模型在没有 Rerank、没有调优的情况下就给出惊艳答案。第一步只确认链路通、引用准后面再逐步优化。5. 文档解析和 Agentic RAG 的真实体验PAW 到底强在哪5.1 把一份扫描版方案 PDF 扔给 PAW 之后的对比为了测试 WeKnora 的文档理解能力我专门找了一份旧方案文档一个扫描版的 PDF大概是十几页里面包含彩色封面、目录、带财务数据的表格、几张架构图、还有一些手写批注的痕迹。我将它导入 WeKnora后台任务跑了一阵子打开解析结果一看确实有点东西文字内容被完整 OCR 出来了表格被还原成了 Markdown 表格格式架构图里的文字说明也被单独提取成了图片注释多栏排版的阅读顺序没有被搞乱。这些都是之前我用开源工具自研解析时会崩溃的典型场景。再用对照组来验证同一份 PDF 用 PyMuPDF 直接抽文本结果是一些空行和偶尔乱码因为整个文件本质是图片用单纯的开源 OCR 工具跑文字是出来了但表格结构完全丢了多栏文字串成了一坨。PAW 的价值在于流水线式地把版面分析、OCR、表格结构识别、阅读顺序还原串起来而不是单点工具能比的事。5.2 混合检索和 Rerank 在生产中的真实分工WeKnora 的检索不是单一向量召回而是混合了语义向量、关键词命中、知识图谱关联。这一点在业务文档里非常有用。举个例子文档里经常出现CRM-2024-01这种产品编号。你拿向量去搜CRM-2024-01效果通常不稳定因为向量模型对这个字符串的理解很弱但关键词检索能精准命中。反过来客户关系管理系统的升级方案这种语义描述关键词搜不到向量能轻松召回到相关段落。混合检索就是让这两条路各自发挥优势再合并结果。Rerank 在最终的排序阶段把关。之前我把上下文数量设得很大一次性送三十条检索结果给模型结果上下文爆炸回答质量急剧下降。加上 Rerank 之后先把候选压缩到 top 5模型输入更干净回答质量直接提升。所以我在调优时把 Rerank 的优先级放在很前面。5.3 Agentic RAG 的实际效果什么时候该用什么时候别滥用WeKnora 的 Agentic RAG 模式在管理后台可以开启。它的逻辑是让模型不再做一次检索一次回答而是先拆解用户的复杂问题再决定去哪个知识库检索、调用什么工具、分几步回答。我测试过一个多步骤问题对比新老两版售后服务政策中退换货时效的变化并总结对客户沟通的影响。基础 RAG 模式下模型很容易只找到其中一个版本就开答漏掉对比。切到 Agent 模式后它会先拆成找到两个版本-抽取退换货条款-对比差异-生成结论几步看起来更接近人的检索路径。但我也要泼一盆冷水Agent 模式不是默认开启就万事大吉的。如果知识库范围太大、工具权限没有收敛模型反而会自由发挥检索一些无关的内容甚至凭空生成中间结论。我的做法是在配置里把 Agent 可访问的知识库范围明确限定并给每个知识库加上清晰的角色描述。别让它自由发挥太多。6. 踩坑实录从部署到稳定运行的完整排查链路6.1 症状一模型服务连接超时排查到最后是 localhost 指向问题现象页面测试连接提示 LLM 服务连接超时。这是部署最常遇到的第一个大坑。排查链路先在宿主机执行curl http://127.0.0.1:11434/v1确认 Ollama 服务确实在跑。再确认 WeKnora 的 base_url 是否正确。如果 WeKnora 跑在 Docker 容器里127.0.0.1指容器自己必须改用host.docker.internal。检查 Ollama 是否开启了跨域限制。前端直连时会报 CORS 错误设置OLLAMA_ORIGINS*后重启。最后定位到的根因其实就是第二点容器内外 localhost 的含义不同。这个坑在本地部署里极具代表性属于写配置时看起来完全正确跑起来就是不通的典型。6.2 症状二文档索引成功但答案答非所问现象知识库索引任务显示成功提问后答案和文档内容没有明确关系甚至引用来源都不对。排查链路先打开文档解析结果确认文本内容是否真的被正确提取。结果发现文本在但被切成片段。再检查检索调试页面看输入问题后到底召回了哪些片段。发现召回的段落里只有一半和问题相关另一半是其他主题的内容。进一步查了 chunk 设置默认的切分大小偏大一段话里混了两个主题向量检索时语义就不够聚焦。解决方案是重建索引并把切片策略调小。比如 chunk_size 从默认值调成 512上下文重叠 100。具体要结合文档特点调但方向是让每个切片尽量聚焦单一主题。改完后重新导入或重建索引答案质量明显好转。这个过程让我意识到一个经常被忽视的事情RAG 系统的错误不一定出在模型很多是先出在文档切片环节。切片像切菜切得太大一锅炖不下切得太碎味道就散了。WeKnora 虽然切片策略可配置但默认值未必适合你的文档。6.3 症状三7B 模型回答读不出重点开头啰嗦、结尾敷衍现象Qwen2.5-7B 在长文档问答时答案前半段在复述文档标题后半段直接说请参考文档第X页没有实际内容。排查链路检查送进模型的上下文内容发现一次塞了太多检索片段超出了模型的 32K 上下文窗口被系统自动截断。截断后模型只看到了文档开头的章节信息没看到真正的内容段落。量化模型本身对长文本的归纳能力有限7B 在上下文很长时容易只看见开头和结尾。解决方案有两步第一步是我的老办法启用 Rerank 后把召回数量从 10 降到 5让上下文更精炼第二步是把 max_new_tokens 调大一些给模型更多输出空间。条件允许的情况下换 14B 模型会彻底改善这类问题。6.4 症状四导入文档时解析任务失败日志指向 PaddleOCR现象批量导入 PDF 时部分任务失败日志里有 Paddle 相关的异常。排查链路确认是 GPU 版 Paddle 在没有 CUDA 环境时的兼容问题卸载后安装 CPU 版解决。部分扫描版 PDF 存在旋转页需要开启 OCR 中的自动旋转校正选项。对于双栏排版的扫描件版面分析尤其重要。如果不开版面分析两栏文字会被按行串联上下文语义错乱。最终建议是如果你的文档以扫描件为主先单独跑一轮 OCR 测试任务确认 Paddle 环境没问题再批量导入。批量导入前用小样本试跑能省下不少排查任务失败的时间。7. 部署完之后的日常使用与进阶方向7.1 我的日常操作流从搭好到用好系统稳定运行之后我把日常操作固定成了一套流程。新增文档统一放到一个待处理目录定期上传到 WeKnora 并触发解析每周跑一轮事先准备的问题测试集——大概二十个常见客户问题逐个问答看答案质量有没有波动如果换了模型版本先用这套测试集做 A/B 对比不会直接在生产知识库上开新模型。另外一个容易被忽略的事是索引维护。文档更新后旧索引里的内容不会自动消失需要重新导入或删除。我的做法是给每个知识库设定负责人文档版本更新时同步做索引重建。不然旧版本和新版本的内容混在检索结果里答案可能引用已经作废的政策或报价。7.2 团队权限与 SSOOIDC 和账号体系WeKnora 支持多用户体系而且热词里也有weknora oidc这个检索词说明不少人在问 SSO 集成的问题。我在内网环境里配置了 OIDC 对接企业现有的统一认证这样团队成员不需要单独注册账号直接用公司账号登录。这一块在团队场景里几乎是必须的否则每个人都要手动开账号权限也不好收敛。权限控制的粒度上我的建议是业务敏感的知识库要有独立的访问权限控制不要让所有登录用户都能看全量文档。我们实际就把财务相关规则库和销售产品库分开了不同角色只能检索自己有权限的知识库。7.3 结合 Dify 做更复杂的工作流编排部署完一段时间后我也尝试了把 WeKnora 和 Dify 结合。思路是WeKnora 负责文档解析、知识库管理和精准检索Dify 负责更灵活的对话工作流、外部工具接入、以及和现有业务系统对接。比如客户问题进来自动分类-不同分类走不同知识库-再触发工单创建这类流程Dify 的编排体验比 WeKnora 内置功能更细腻。两个开源项目各司其职反而是比较舒服的组合方式。7.4 进阶功能GraphRAG 和模型微调如果知识库里的实体关系很复杂比如供应链关系、组织架构、人员变动这类数据可以考虑开启 WeKnora 的图增强能力也就是 GraphRAG 方向。它会把文档中的实体和关系抽出来构建知识图谱检索时不光找相似段落还能沿着关系链找答案。我实测在公司上下游关联这类问题上图谱增强明显比纯向量检索强。模型微调这块我没有深入但客观说必要性不大。对大多数团队换更好的基础模型、调好切片和检索参数收益远大于微调。微调是针对模型回答风格或特定领域术语做定制时才需要考虑的选项。整套系统跑了快两个月最直观的感受是开源知识库的差距不在模型而在文档解析和检索链路的成熟度。WeKnora 让我把精力从怎么洗文档、怎么搭索引这类脏活里解放出来集中到真正的调优和场景设计上。如果你手里也有一堆无法直接喂给大模型的文档我建议直接拿 WeKnora 跑一轮最小知识库验证先把链路通起来再逐步加 Rerank、Agent 和 Dify 工作流。后面我还打算把企业微信里的历史消息自动同步进去到时候再更新一篇实践记录。