★ FEATURED ARTICLE 1. 为什么我要认真聊聊 WeKnora 这个项目第一次看到 WeKnora 这个名字是在一个做企业知识管理的群里。有人甩了句“腾讯微信团队开源了个 RAG 知识库叫 WeKnora”群里瞬间炸了。做 RAG 的人都知道2024 到 2025 这两年RAG 项目多如牛毛但真正能落地、能扛住企业级文档解析、还能把 Agent 和沙箱串起来的屈指可数。WeKnora 吸引我的点很直接它不是又一个“上传 PDF 然后问答”的玩具而是把文档解析、向量检索、Agent 编排、代码沙箱执行这几件事捏在了一起。我花了大概两周时间在 Windows 11 和 Linux 两个环境下分别部署了 WeKnora拿它跑了技术文档、合同模板、内部 Wiki 三类语料也对比了 Dify、RAGFlow 这些同类开源方案。这篇文章不打算写成官方文档的复述而是把我踩过的坑、调参的逻辑、以及“为什么这么设计”的思考摊开来讲。如果你正在选型 RAG 知识库或者想搞清楚 Agentic RAG 到底怎么落地这篇内容应该能帮你省下不少试错时间。WeKnora 的核心价值我总结成一句话它把 RAG 从“检索增强生成”推进到了“检索增强执行”。传统 RAG 的终点是让大模型基于检索到的片段回答问题而 WeKnora 在检索之后接入了 Agent 和沙箱让模型不仅能回答还能执行代码、调用工具、完成多步任务。这个差异决定了它适合的场景和传统 RAG 完全不同。2. WeKnora 的整体架构与设计思路拆解2.1 它到底解决了传统 RAG 的哪些痛点传统 RAG 的流程大家都很熟文档切块、向量化、存向量库、检索 Top-K、拼 Prompt、生成回答。这套流程在“问答”场景下够用但一旦遇到下面几种情况就露怯了。第一种是多跳推理。用户问“我们公司去年 Q3 的差旅报销标准相比 Q2 有哪些调整”答案分散在制度文档、通知邮件、财务表格三个地方单次检索很难把关联片段都捞出来。第二种是需要计算或执行。用户问“把这份销售数据里环比下降超过 10% 的产品列出来并算一下影响金额”这需要写代码跑数据纯文本生成做不到。第三种是文档解析质量差。扫描件、复杂表格、多栏 PDF很多 RAG 项目解析出来就是一堆乱码检索命中率自然上不去。WeKnora 的设计思路是针对性地补这三块短板。它在检索层做了多路召回和重排在生成层接入了 Agent 做任务规划在执行层提供了代码沙箱。这个“检索-规划-执行”的闭环就是 Agentic RAG 的典型形态。2.2 核心模块拆解从文档到答案的完整链路我把 WeKnora 的链路拆成五层来看这样理解起来更清晰。第一层是文档接入层。支持 PDF、Word、Markdown、HTML、Excel 等格式重点是它的解析器对复杂版式做了优化。我实测下来双栏 PDF 和带合并单元格的表格解析准确率比直接用 PyPDF2 高出一大截。它内部应该是用了版面分析模型先识别区域再按区域类型分别处理。第二层是切块与向量化层。切块策略支持按固定长度、按语义、按标题层级三种模式。这里有个细节值得说WeKnora 默认的切块不是简单按 token 数切而是会保留标题和上下文的关联。比如一个三级标题下的内容被切开后每个块都会带上父级标题作为元数据检索时这个元数据能参与过滤和重排。第三层是检索层。支持向量检索、关键词检索、混合检索三种模式。混合检索是默认推荐的它把 BM25 和向量相似度做加权融合。我调参时发现对于技术文档这类术语密集的语料关键词检索的权重调高到 0.4 左右效果最好对于口语化的客服问答向量权重占 0.7 更合适。第四层是 Agent 编排层。这是 WeKnora 区别于普通 RAG 的关键。它内置了一个任务规划器能根据用户问题判断是否需要多步操作。比如“帮我对比这两份合同的违约责任条款”规划器会拆成“检索合同 A 违约责任”“检索合同 B 违约责任”“对比生成”三步。这个规划过程是基于 LLM 的 Function Calling 能力实现的。第五层是沙箱执行层。当任务需要计算、数据处理、图表生成时Agent 会生成代码并在沙箱里执行。沙箱是隔离的有资源限制和超时控制。我试过让它处理一个 10 万行的 CSV做分组聚合和异常检测整个流程跑下来大概 8 秒沙箱没有出现内存溢出。2.3 和 Dify、RAGFlow 的选型对比选型时我把 WeKnora、Dify、RAGFlow 放在一起做了张对比表维度是我实际关心的几个点。对比维度WeKnoraDifyRAGFlow文档解析能力强复杂版式优化好中等依赖第三方强深度文档理解Agent 编排内置与检索深度耦合有但偏工作流较弱偏检索代码沙箱内置开箱即用需自行接入无内置部署复杂度中等依赖较多低Docker 一键中等适合场景Agentic RAG、多步任务对话应用、工作流纯知识库问答二次开发友好度高模块清晰高插件丰富中等这张表不是要分个高下而是说清楚各自的位置。Dify 强在应用编排和生态RAGFlow 强在文档解析深度WeKnora 的差异化在于把 Agent 和沙箱做进了 RAG 主流程。如果你的场景只是“文档问答”RAGFlow 可能更省事如果你要做“能干活的知识库”WeKnora 的架构更对路。3. 部署实操Windows 11 和 Linux 下的完整流程3.1 环境准备与依赖清单WeKnora 的部署依赖不算少我先把清单列出来避免你装到一半发现缺东西。Python 3.10 或 3.11官方推荐 3.10我用 3.11 也跑通了但 3.12 有几个依赖包编译会报错建议避开。Node.js 18前端构建需要如果只用后端 API 可以不装。Docker 与 Docker Compose沙箱执行和部分服务依赖容器化运行。PostgreSQL 14 与 pgvector向量存储默认用 pgvector也可以用 Milvus但配置更复杂。Redis 7任务队列和缓存。至少 16GB 内存解析大文档和跑 Agent 时内存占用会上去8GB 会频繁触发 OOM。Windows 11 下我建议用 WSL2 来跑原生 Windows 下有些依赖包的编译工具链配置很折腾。WSL2 里装 Ubuntu 22.04然后按 Linux 流程走省心很多。3.2 一步步部署从拉代码到跑通第一个知识库先拉代码这里注意要拉主分支的最新版本WeKnora 迭代比较快老版本可能有已知的解析 bug。git clone https://github.com/Tencent/WeKnora.git cd WeKnora然后配置环境变量。项目根目录有个.env.example复制成.env后重点改这几个# 数据库配置 POSTGRES_HOSTlocalhost POSTGRES_PORT5432 POSTGRES_DBweknora POSTGRES_USERweknora POSTGRES_PASSWORD你的密码 # Redis 配置 REDIS_HOSTlocalhost REDIS_PORT6379 # 模型配置这里以本地 Ollama 为例 LLM_PROVIDERollama LLM_BASE_URLhttp://localhost:11434 LLM_MODELqwen2.5:14b # Embedding 模型 EMBEDDING_PROVIDERollama EMBEDDING_MODELbge-m3提示Embedding 模型的选择对检索命中率影响极大。我实测 bge-m3 在中英文混合语料上表现明显优于默认的 all-MiniLM虽然向量维度高一些存储成本增加但检索质量提升值得。数据库初始化用项目自带的脚本docker compose up -d postgres redis python scripts/init_db.py前端和后端分别启动# 后端 python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload # 前端 cd web npm install npm run dev跑起来后访问http://localhost:3000用默认账号登录就能看到知识库管理界面了。3.3 第一个知识库上传、解析、检索全流程验证我拿了一份 80 页的技术白皮书做测试。上传后解析大概花了 40 秒解析结果可以在“文档详情”里看到分块情况。这里有个检查技巧重点看表格和代码块有没有被切碎。如果发现一个完整表格被切成七八块说明切块策略需要调整。在知识库设置里把切块模式改成“按标题层级”最大块长度设成 800 token重叠 100 token。重新解析后表格完整性明显改善。然后建一个问答测试问这份白皮书里提到的系统架构分为哪几层WeKnora 返回的答案会附带引用来源点开能看到具体命中了哪些块。如果命中块不相关就去检索设置里调权重。我一般先把混合检索的关键词权重从默认 0.3 调到 0.5看命中率变化再微调。4. 核心功能深度解析与调优经验4.1 文档解析为什么你的 PDF 总是解析失败“WeKnora 解析失败的原因是什么”这个问题我在社区里看到太多次了。归纳下来主要是三类。第一类是扫描件没有 OCR 层。纯图片 PDF 直接上传解析器拿不到文字。解决办法是先过一遍 OCR或者用带 OCR 的解析模式。WeKnora 支持接入 PaddleOCR配置在.env里打开ENABLE_OCRtrue即可。第二类是字体编码问题。有些 PDF 用了非标准字体文字提取出来是乱码。这种情况我一般先用pdf2htmlEX转一遍再上传 HTML 版本。第三类是文件过大触发超时。默认解析超时是 300 秒超过 200 页的文档建议拆成多个文件上传或者调大PARSE_TIMEOUT参数。注意解析失败时不要反复重试同一个文件先看日志里的具体报错。日志在logs/parser.log大部分失败原因那里写得比界面提示清楚。4.2 检索调优把命中率从 60% 拉到 90% 的实操记录检索命中率RAG hit rate是 RAG 项目的生命线。我拿 50 个测试问题做了一轮调优记录如下。初始配置纯向量检索Top-K5命中率 62%。问题主要是两类术语缩写检索不到以及跨段落的问题召回不全。第一步切换到混合检索关键词权重 0.3。命中率升到 71%。术语缩写问题改善了因为 BM25 对精确匹配更敏感。第二步开启重排Rerank。WeKnora 支持接入 bge-reranker我把 Top-K 先放大到 20重排后取前 5。命中率跳到 84%。这一步的代价是延迟增加从 1.2 秒涨到 2.8 秒但准确率提升明显。第三步调整切块策略。把最大块从 500 token 调到 800重叠从 50 调到 120。命中率到 89%。原因是跨段落的语义单元更完整了。第四步给文档加了元数据标签。比如给制度类文档打上“制度”“财务”“人事”标签检索时按标签过滤。命中率最终到 92%。这套调优逻辑不是 WeKnora 独有的但它的配置项暴露得比较全调起来顺手。4.3 Agent 与沙箱让知识库真正“能干活”Agent 和沙箱是 WeKnora 最有意思的部分。我设计了一个测试任务上传一份销售数据 CSV 和一份产品手册然后问“哪些产品的销售额环比下降超过 15%请列出产品名称和下降原因参考手册中的产品说明”。这个任务需要三步读 CSV 算环比、筛选下降超 15% 的产品、去手册里找这些产品的说明。WeKnora 的 Agent 规划器把它拆成了对应的子任务中间生成了一段 Python 代码在沙箱里跑。沙箱的执行日志可以在界面上看到代码、输出、耗时都有记录。我注意到沙箱默认限制了网络访问和文件系统写入只能读上传的文件这个安全设计是合理的。实操心得沙箱执行超时默认 30 秒处理大文件时容易超时。可以在知识库设置里调到 120 秒但要注意别设太大避免失控任务占用资源。4.4 和 Obsidian 的联动个人知识管理的玩法“weknora 和 obsidian”这个组合我试了一种用法把 Obsidian 的 vault 目录作为文档源定期同步到 WeKnora。这样我在 Obsidian 里写的笔记可以直接通过 WeKnora 做语义检索和问答。具体做法是用 Obsidian 的 Local REST API 插件暴露 vault然后写个定时脚本把新增或修改的 Markdown 推到 WeKnora 的 API。WeKnora 的文档上传接口支持增量更新传的时候带上doc_id就会覆盖旧版本。这个玩法适合笔记量大、又想要语义检索的人。缺点是 Obsidian 的双链语法 WeKnora 不解析检索时链接会变成纯文本但不影响内容召回。5. 常见问题排查与避坑指南5.1 部署阶段的典型报错与解决报错信息原因解决方法pgvector extension not foundPostgreSQL 没装 pgvector执行CREATE EXTENSION vector;CUDA out of memoryEmbedding 模型显存不足换小模型或改用 CPU 推理Connection refused: redisRedis 没启动或端口不对检查docker ps和.env配置ModuleNotFoundError: No module named xxx依赖没装全pip install -r requirements.txt前端白屏Node 版本不对切到 Node 18 LTS5.2 运行阶段的性能问题排查跑了一段时间后最容易遇到的是检索变慢。我遇到过一次检索延迟从 1 秒涨到 8 秒。排查下来是向量表没有建索引。pgvector 默认是精确检索数据量上到十万级就必须建 IVFFlat 或 HNSW 索引。CREATE INDEX ON embeddings USING hnsw (vector vector_cosine_ops);建完索引后延迟回到 1.5 秒左右。这个坑很典型数据量小的时候感觉不到一上量就暴露。另一个常见问题是内存泄漏。长时间运行后进程内存持续上涨重启就好。我看了下是文档解析的缓存没释放在配置里把PARSE_CACHE_SIZE调小可以缓解。5.3 检索质量问题的排查思路检索不准时按这个顺序排查先看解析结果对不对再看切块合不合理然后看检索模式选得对不对最后看重排有没有开。大部分“检索不准”的问题根子在解析和切块而不是检索算法本身。我整理了一个速查流程解析结果里搜关键词能搜到说明解析没问题搜不到就回去修解析。解析没问题但检索不到就去调切块和检索权重。这两步都做了还不行再考虑换 Embedding 模型。6. 我对 WeKnora 的一些个人判断用下来这段时间我觉得 WeKnora 最值得肯定的地方是它把 Agentic RAG 这条路走通了而且开源得比较彻底。代码结构清晰模块边界明确二次开发的成本不高。沙箱的设计也考虑到了安全不是那种随便跑代码的玩具。但它也不是没有短板。文档解析虽然比一般项目强但和专门的文档理解方案比还有差距复杂表格的还原度大概在 80% 左右。Agent 的规划能力依赖底层 LLM用小模型时规划经常出错建议至少用 14B 以上的模型。另外社区生态还在建设期插件和模板不多很多事得自己动手。如果你问我值不值得投入我的答案是如果你的场景需要“知识库 执行能力”WeKnora 目前是开源里比较完整的选择。如果只是纯问答有更轻量的方案。选型这事没有绝对好坏关键看你的任务形态和团队的技术储备。最后分享一个我调参时的小技巧改任何检索参数后别只看一两个问题的效果拿一组固定测试集跑一遍记录命中率变化。我一开始就是改一个参数试一个问题来回折腾了好几天后来建了 50 题的测试集调参效率高了很多。这个习惯做 RAG 的人都值得养成。
阅读完成 · 觉得有帮助？
