1. 从“知识割裂”说起WeKnora 到底想解决什么问题如果你最近在折腾 RAG检索增强生成大概率会有一种很拧巴的感觉文档丢进去了向量库也建了问一个简单问题它答得还行但一旦问题稍微复杂一点——比如“我们去年Q3那次架构调整之后订单模块的负责人是谁他当时定的那个方案后来改过几版”——模型就开始胡言乱语要么答非所问要么把几个不相干的片段硬拼在一起。这不是你的提示词写得不好而是传统 RAG 的底层逻辑有硬伤。它把文档切成一块块互不相干的碎片检索的时候只看“哪块碎片和问题最像”完全不管碎片之间的逻辑关系。结果就是知识割裂答案明明散落在三四个文档里但系统只捞回来一两个剩下的全靠模型脑补。WeKnora 是腾讯微信团队开源的一个知识库项目它想干的事情就是把这堆碎片重新“缝”起来。它不是一个单纯的向量检索工具而是一套带Agent 编排能力的 RAG 框架——你可以把它理解成一个“会自己规划检索路径”的知识库。普通 RAG 是“你问一句它查一次”WeKnora 是“你问一句它先想想要查哪几个地方、按什么顺序查、查完怎么拼”这个“想”的过程就是 Agent 在起作用。这篇文章适合三类人看一是正在做企业知识库、被 RAG 召回率折磨的开发者二是想搞清楚 Agentic RAG 和普通 RAG 到底差在哪的技术负责人三是想在本机把 WeKnora 跑起来、但被部署文档绕晕的实操派。我会把原理、部署、踩坑、调优这几件事拆开讲尽量让你看完就能动手。2. WeKnora 的架构骨架Agent 编排 沙箱执行 多路检索2.1 为什么普通 RAG 会“卡在瓶颈上”先说清楚 RAG 的瓶颈到底在哪。传统 RAG 的流程是固定的用户提问 → 向量化 → 向量库相似度检索 → Top-K 片段塞进上下文 → LLM 生成。这条链路的问题在于检索是一次性的、无反馈的。如果第一次检索没捞到关键信息后面就没有补救机会了。我实测过一个场景问“某项目的验收标准里关于并发压测的那条是怎么写的”。文档里其实有两处提到一处是验收章节一处是测试方案附录。普通 RAG 只召回了验收章节那段但那段写的是“参照测试方案执行”真正的数值在附录里。模型拿到一个“参照执行”的片段只能编一个数值出来。WeKnora 的思路是引入Agent 循环检索完之后Agent 会判断“这些信息够不够回答问题”不够就换个查询词再检一次或者去查别的数据源。这个“判断—再检索”的过程可以迭代多轮直到信息足够或者达到轮次上限。这就是热词里说的agentic rag——RAG 不再是单次管道而是一个有决策能力的智能体。2.2 沙箱在 WeKnora 里扮演什么角色热词里“沙箱”出现频率很高很多人第一反应是支付宝沙箱支付但在 WeKnora 语境下沙箱指的是Agent 执行代码或工具调用的隔离环境。为什么需要沙箱因为 Agent 在编排过程中可能需要动态执行一些操作比如解析一个表格文件、调用一个计算函数、跑一段数据清洗脚本。这些操作如果直接在宿主机上跑风险很大——万一模型生成的代码有问题可能把系统文件删了。沙箱就是给这些操作划一块“安全操场”跑挂了也只影响沙箱内部。WeKnora 的沙箱机制我理解下来核心是两点一是资源隔离限制 CPU、内存、执行时间二是权限隔离沙箱内的代码只能访问被授权的数据碰不到宿主机的敏感目录。这个设计在企业场景里很关键因为企业知识库往往连着内部系统不能让 Agent 随便乱来。2.3 多路检索向量、关键词、图谱怎么配合WeKnora 不是只靠向量检索。它支持多路召回包括检索方式擅长场景短板向量检索语义相似、口语化提问对精确术语、编号不敏感关键词检索精确匹配、代码、编号无法理解同义表达图谱/本体检索实体关系、多跳推理构建成本高热词里提到的ontology rag和graphrag说的就是图谱这条路。比如你问“A 项目的负责人同时负责哪几个其他项目”向量检索很难直接答因为它需要“A 项目 → 负责人 → 该负责人的其他项目”这样两跳关系。图谱检索就是干这个的。WeKnora 的做法是把这几路结果做融合排序再交给 Agent 判断。这个融合不是简单加权而是根据问题类型动态调整权重——事实型问题偏关键词推理型问题偏图谱开放型问题偏向量的语义匹配。3. 本机部署 WeKnora从零到能问出第一句话3.1 部署前的环境盘点别急着敲命令很多人一上来就 clone 仓库、跑 docker compose结果卡在依赖上。我建议先花十分钟把环境盘清楚。WeKnora 的部署方式主要有两种Docker Compose 一键起或者手动分组件部署。对绝大多数人来说Docker Compose 是首选因为它把向量库、后端服务、前端、模型接入这些组件的依赖关系都处理好了。你需要准备的东西Docker 和 Docker Compose版本别太老Compose 建议 v2 以上v1 的语法在新版镜像里可能报错。至少 16GB 内存如果本地还要跑 embedding 模型32GB 更稳。我试过 8GB 的机器光向量库和 backend 就把内存吃满了模型加载直接 OOM。磁盘空间镜像加上模型文件预留 50GB 比较保险。embedding 模型和 rerank 模型加起来可能就十几个 G。模型接入方式你可以用在线 API也可以本地跑 Ollama。热词里“ollama 简易本地 rag 知识库”说的就是这个路子。本地跑的好处是数据不出内网坏处是慢而且吃显存。提示如果你只是想把流程跑通、看看效果先用在线 API 接入别一上来就折腾本地模型。等流程通了再换本地模型做数据隔离。3.2 Docker Compose 起服务的完整步骤假设你已经装好了 Docker下面是实操流程。第一步拿到项目代码。从官方仓库 clone 下来进入目录。目录结构里一般会有docker-compose.yml或者deploy文件夹先看一眼 README 里有没有额外的环境变量说明。第二步配置环境变量。这是最容易出问题的地方。通常需要配这几类# 模型相关 LLM_API_KEY你的key LLM_BASE_URL模型服务地址 EMBEDDING_MODEL嵌入模型名称 # 数据库相关 POSTGRES_PASSWORD自定义密码 VECTOR_DB_TYPE向量库类型 # 服务端口 BACKEND_PORT8080 FRONTEND_PORT3000这里有个坑环境变量的命名在不同版本里可能不一样。我遇到过.env.example里写的是OPENAI_API_KEY但代码里读的是LLM_API_KEY结果服务起来了但模型调不通。解决办法是去代码里搜一下os.getenv或者process.env确认实际读取的变量名。第三步起服务。docker compose up -d加-d是后台运行。起来之后用docker compose ps看各容器状态重点看 backend 和向量库是不是 healthy。如果某个容器一直 restart用docker compose logs 容器名看日志。第四步初始化。首次启动通常需要建库、建表、初始化管理员账号。有些版本会自动跑 migration有些需要手动执行初始化脚本。看日志里有没有 “migration completed” 之类的提示。第五步访问前端。默认一般是http://localhost:3000用初始化时设的账号登录然后创建一个知识库上传一个测试文档问一句话试试。3.3 部署阶段最容易踩的五个坑我把部署时踩过的坑列一下你对照着排查能省不少时间。坑一端口冲突。3000 和 8080 是最容易被占用的端口起服务前先lsof -i:3000看一眼。如果被占改 compose 文件里的端口映射。坑二向量库连不上。向量库容器起来了但 backend 报连接超时。多半是网络配置问题——compose 里各服务要在同一个 network 下且 backend 连向量库要用服务名而不是 localhost。坑三模型调用 401。环境变量配了但没生效或者 key 有空格。检查.env文件里有没有多余的空格和引号Docker 读环境变量对格式很敏感。坑四embedding 维度不匹配。你换了一个 embedding 模型但向量库里的 collection 是按旧模型维度建的插入数据时报维度错误。解决办法是重建 collection或者换回原维度模型。坑五内存不足导致容器被杀。日志里出现Killed或者 exit code 137基本就是 OOM。减少并发、换小模型或者加内存。4. 把文档喂进去解析、切分与知识图谱构建4.1 文档解析PDF、Word、图片各有什么坑WeKnora 支持多种文档格式但不同格式的解析质量差别很大。PDF 是最麻烦的。扫描版 PDF 需要 OCR文字版 PDF 如果排版复杂多栏、表格、公式解析出来经常是乱的。我实测下来带表格的 PDF 解析后表格结构基本丢失变成一堆错位的文字。如果你的知识库里有大量表格类文档建议先转成 Markdown 或者结构化格式再喂进去。Word 文档相对好一些但要注意样式。如果文档里用了大量文本框、艺术字解析也可能出问题。图片这块热词里有人问“rag 知识库能存储图片嘛”。答案是能存但检索逻辑不一样。图片通常需要先做多模态 embedding或者用 OCR 提取文字后再走文本检索。WeKnora 对图片的支持程度取决于你接入的模型能力——如果 embedding 模型支持多模态图片可以直接向量化如果不支持就得先 OCR。提示文档解析质量直接决定 RAG 的上限。与其在检索阶段调参不如在入库前把文档洗干净。这一步偷懒后面全是坑。4.2 切分策略为什么固定长度切分是灾难文档切分是 RAG 里最被低估的环节。很多人直接用默认的“按 512 token 切”结果切出来的片段要么语义不完整要么把关键信息切断了。WeKnora 支持更细的切分策略我建议按文档结构来切按标题层级切一级标题下的内容作为一个大块二级标题下作为子块。这样每个块都有明确的主题。按语义切用模型判断句子之间的语义连贯性在语义转折处切分。重叠切分相邻块之间保留一定重叠比如 10%避免关键信息正好落在切分点上被切断。我踩过一个坑一份技术方案文档关键结论写在章节末尾结果固定长度切分正好把结论和它前面的论据切开了。检索时只召回论据模型不知道结论是什么答出来的东西完全跑偏。后来改成按标题切分问题就解决了。4.3 知识图谱构建让实体关系不再割裂这是 WeKnora 区别于普通 RAG 的核心能力之一。它在文档入库时会尝试抽取实体和关系构建一个轻量级的知识图谱。比如文档里写“张三负责订单模块李四负责支付模块订单模块依赖支付模块”图谱会抽出三个实体张三、订单模块、支付模块和两条关系负责、依赖。当你问“订单模块出问题会影响谁”时图谱可以沿着“依赖”关系找到支付模块再找到李四。构建图谱的代价是入库变慢而且抽取质量依赖模型能力。我的经验是实体密集、关系复杂的文档值得建图谱纯叙述性、关系松散的文档建了也没多大用。你可以按知识库类型决定是否开启。5. 检索调优命中率上不去的排查链路5.1 先定位是召回问题还是生成问题RAG 答不好先别急着调模型。第一步是判断问题出在“没召回”还是“召回了但没答对”。方法很简单把检索到的片段打印出来看。如果片段里根本没有答案那是召回问题如果片段里有答案但模型没答对那是生成问题。WeKnora 的调试面板里一般能看到每次查询的检索结果和 Agent 的决策过程。如果没有面板就在日志里加打印。这一步不做后面所有调优都是瞎猜。5.2 召回率低的四种典型原因原因一查询词和文档用词不一致。用户问“怎么配置”文档里写的是“设置方法”。向量检索能缓解这个问题但如果 embedding 模型对领域术语不敏感还是会漏。解决办法是加同义词表或者用查询改写——让模型先把用户问题改写成几个不同表述分别检索。原因二Top-K 太小。默认 Top-K 可能是 3 或 5对于复杂问题不够。可以调到 10 甚至 20然后用 rerank 模型精排。热词里的rag hit rate说的就是这个指标。原因三切分粒度不对。块太大噪声多块太小信息不全。这个只能靠试没有万能参数。原因四多路检索权重失衡。如果关键词检索权重太低精确术语就召不回来如果图谱权重太高开放问题又会被过度结构化。WeKnora 允许调这些权重建议按知识库内容特点来配。5.3 Rerank 模型召回之后的第二道筛子召回阶段追求“不漏”rerank 阶段追求“精准”。WeKnora 支持接入 rerank 模型对召回的片段做二次排序。rerank 的原理是 cross-encoder把问题和每个片段拼在一起送进模型直接输出相关性分数。它比向量相似度准得多但慢得多。所以典型流程是向量检索召回 50 条 → rerank 精排出前 5 条 → 送给 LLM。我实测下来加了 rerank 之后命中率能提升 20% 到 30%尤其是那种“答案藏在长文档中间”的场景。代价是每次查询多几百毫秒延迟。如果你的场景对延迟不敏感强烈建议开。6. Agent 编排与并发从能用走向好用6.1 Agent 循环的轮次控制与死循环防范Agent 会自己决定“再检一次”但如果不加限制它可能陷入死循环——检了没找到换个词再检还没找到再换……最后把 token 烧光了也没答出来。WeKnora 里一般有最大轮次配置。我的建议是设 3 到 5 轮。超过 5 轮还没找到基本说明知识库里确实没有再检也是浪费。同时要设一个“无进展检测”如果连续两轮召回结果高度重合就强制停止。6.2 并发场景下 Agent 扛不扛得住热词里有人问“ai agent 怎么扛并发”。这是个真问题。Agent 编排比普通 RAG 重得多——一次查询可能触发多轮检索、多次模型调用资源消耗是普通 RAG 的好几倍。WeKnora 的并发能力取决于几个瓶颈模型服务的并发上限在线 API 一般有 QPS 限制本地模型看显存。向量库的查询并发Milvus、Qdrant 这类向量库并发能力不错但配置不当也会成瓶颈。沙箱的资源池如果 Agent 频繁执行代码沙箱的创建和销毁开销不小需要做池化。实操建议先压测单次查询的耗时和资源占用再算单机能扛多少并发。别一上来就追求高并发先把单次查询的质量做稳。6.3 和 Dify、RAGFlow 的定位差异热词里“dify ragflow weknora 开源版 企业功能比较”是个高频问题。我简单说下我的理解Dify更偏应用编排平台RAG 只是它的一块能力强项是可视化工作流。RAGFlow强在文档解析尤其是复杂 PDF 的深度解析切分质量高。WeKnora的差异点在 Agent 编排和沙箱执行更适合需要多步推理、动态工具调用的场景。选哪个不是非此即彼很多团队是组合用的——用 RAGFlow 做文档预处理用 WeKnora 做检索和 Agent 编排。7. 一些实操心得和后续可扩展的方向部署和调优过程中我最大的体会是RAG 的效果上限在数据准备阶段就决定了。文档解析、切分、图谱构建这三步做扎实后面检索调优是锦上添花这三步偷懒后面怎么调都是事倍功半。另外Agent 编排虽然强大但别滥用。简单的事实型问答普通 RAG 就够了上 Agent 反而增加延迟和不确定性。只有当问题需要多跳推理、多数据源融合、动态工具调用时Agent 的价值才体现出来。后续可以扩展的方向我个人比较关注两个一是OIDC 接入把知识库权限和企业统一身份认证打通这样不同部门的人只能看到自己有权限的文档二是和 Obsidian 这类本地笔记工具的联动热词里“weknora 和 obsidian”有人问思路是把 Obsidian 的 Markdown 库直接作为知识源同步进去这样个人笔记也能被 RAG 检索到。最后分享一个小技巧调检索参数时固定一组测试问题每次改完参数都跑一遍记录命中率。别凭感觉调感觉最不靠谱。我一开始就是凭感觉调 Top-K调了半天发现还不如默认值。后来建了个 20 条问题的测试集每次改动都有数据支撑效率高多了。