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 放在一起做了张对比表，维度是我实际关心的几个点。
| 对比维度 | WeKnora | Dify | RAGFlow |
|---|---|---|---|
| 文档解析能力 | 强，复杂版式优化好 | 中等，依赖第三方 | 强，深度文档理解 |
| 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_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=weknora POSTGRES_USER=weknora POSTGRES_PASSWORD=你的密码 # Redis 配置 REDIS_HOST=localhost REDIS_PORT=6379 # 模型配置，这里以本地 Ollama 为例 LLM_PROVIDER=ollama LLM_BASE_URL=http://localhost:11434 LLM_MODEL=qwen2.5:14b # Embedding 模型 EMBEDDING_PROVIDER=ollama EMBEDDING_MODEL=bge-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_OCR=true即可。
第二类是字体编码问题。有些 PDF 用了非标准字体，文字提取出来是乱码。这种情况我一般先用pdf2htmlEX转一遍，再上传 HTML 版本。
第三类是文件过大触发超时。默认解析超时是 300 秒，超过 200 页的文档建议拆成多个文件上传，或者调大PARSE_TIMEOUT参数。
注意：解析失败时不要反复重试同一个文件，先看日志里的具体报错。日志在
logs/parser.log，大部分失败原因那里写得比界面提示清楚。
4.2 检索调优：把命中率从 60% 拉到 90% 的实操记录
检索命中率（RAG hit rate）是 RAG 项目的生命线。我拿 50 个测试问题做了一轮调优，记录如下。
初始配置：纯向量检索，Top-K=5，命中率 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 found | PostgreSQL 没装 pgvector | 执行CREATE EXTENSION vector; |
CUDA out of memory | Embedding 模型显存不足 | 换小模型或改用 CPU 推理 |
Connection refused: redis | Redis 没启动或端口不对 | 检查docker ps和.env配置 |
ModuleNotFoundError: No module named 'xxx' | 依赖没装全 | pip install -r requirements.txt |
| 前端白屏 | Node 版本不对 | 切到 Node 18 LTS |
5.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 的人都值得养成。
