1. 从“知识割裂”说起WeKnora 到底想解决什么问题如果你在企业里做过内部知识库大概率经历过这样的场景文档散落在 Confluence、飞书、Notion、本地 Word、PDF 里员工搜一个“报销标准”能搜出五个版本最后还得在群里问一句“以哪个为准”。这就是热词里提到的“知识割裂”——信息不是没有而是散、乱、版本不一致检索出来的东西没法直接用。WeKnora 是腾讯微信团队开源的一套 AI 知识库框架核心定位就是围绕RAG检索增强生成和Agent智能体两条主线把“文档入库—切分—向量化—检索—生成—执行”这条链路打通。它不是单纯的向量数据库也不是单纯的聊天前端而是一个把 RAG 检索、Agent 编排、沙箱执行、OIDC 鉴权这些能力整合在一起的工程化框架。我拿到这个项目后第一反应是市面上 RAG 框架已经很多了LangChain、LlamaIndex、Dify、RAGFlow 都能做WeKnora 的差异点在哪实测下来它比较突出的地方有三个一是微信团队出品工程完成度相对高不是那种跑个 Demo 就散架的玩具二是原生支持 Agent 沙箱这对需要执行代码、调用工具的场景很关键三是支持 OIDC 单点登录说明它是奔着企业内网部署去的不是个人玩具。这篇文章适合三类人看第一类是想自己搭一套本地 RAG 知识库的开发者第二类是在做 Agent 应用、关心并发和沙箱安全的工程师第三类是在 Dify、RAGFlow、WeKnora 之间做选型的技术负责人。我会从架构拆解、部署实操、RAG 检索调优、Agent 沙箱机制、选型对比几个角度把我在实际折腾过程中踩过的坑和总结的经验都摊开讲。提示本文所有操作均基于本地或企业内网自建环境不涉及任何外部网络访问工具请确保你的部署环境符合所在组织的安全规范。2. WeKnora 的架构骨架RAG 与 Agent 是怎么缝合的2.1 三层结构接入层、编排层、执行层把 WeKnora 拆开看它大致分三层。接入层负责文档导入、用户鉴权OIDC、API 网关编排层是核心负责 RAG 检索链路和 Agent 任务编排执行层是沙箱负责跑代码、调工具、执行 Agent 产生的动作。这个分层不是随便切的。我见过很多 RAG 项目把检索和生成揉在一个函数里结果想换个向量模型就得改一大片代码。WeKnora 把编排层独立出来好处是检索策略、重排模型、生成模型可以分别替换。比如你一开始用 Ollama 跑本地模型后面想换成企业内网的推理服务只需要改编排层的模型配置不用动文档处理逻辑。编排层里 RAG 和 Agent 是两条并行的链路但共享同一套知识底座。RAG 链路是“用户提问 → 向量检索 → 重排 → 拼上下文 → LLM 生成”Agent 链路是“任务解析 → 工具选择 → 沙箱执行 → 结果回填 → 再推理”。两条链路的交汇点在于Agent 在执行过程中可以调用 RAG 检索作为工具这就是热词里说的Agentic RAG——检索不再是固定的一步而是 Agent 按需触发的动作。2.2 为什么 RAG 和 Agent 要放在一个框架里单独做 RAG 的项目很多单独做 Agent 的框架也很多但把两者缝合好的不多。原因在于纯 RAG 的天花板很明显它只能回答“知识库里有什么”回答不了“根据知识库帮我做一件事”。比如你问“上季度销售数据里哪个区域增长最快”纯 RAG 只能把相关文档片段捞出来让 LLM 总结但如果数据在数据库里RAG 就无能为力了。Agent 的价值在于它能“动手”。它可以先调 RAG 检索出表结构说明再生成 SQL再在沙箱里执行 SQL最后把结果整理成回答。这条链路里RAG 负责“知道”Agent 负责“做到”。WeKnora 把两者放在一起本质上是想让知识库从“问答工具”升级成“执行工具”。我实测下来的感受是如果你的场景只是文档问答纯 RAG 就够了上 Agent 反而增加复杂度但如果你需要跨数据源、需要执行动作那 Agentic RAG 是绕不开的。WeKnora 在这块的设计思路是对的但配置复杂度也确实上来了后面会讲怎么简化。2.3 和 Dify、RAGFlow 的定位差异热词里有人问“dify ragflow weknora 开源版企业功能比较”我实际都部署过简单说下差异。Dify 强在工作流编排和可视化拖拽式搭 Agent 很顺手但它的 RAG 检索调优空间相对有限深度定制要改源码。RAGFlow 强在文档解析尤其是复杂 PDF、表格的切分做得细但 Agent 能力偏弱沙箱执行不是它的重点。WeKnora 的定位介于两者之间RAG 检索的工程化程度比 Dify 深Agent 沙箱比 RAGFlow 完整OIDC 鉴权是企业级特性。缺点是生态和文档还不如前两者成熟很多配置得看源码和 issue 才能搞明白。选型建议是要可视化工作流选 Dify要复杂文档解析选 RAGFlow要 Agent 沙箱加企业鉴权选 WeKnora。维度DifyRAGFlowWeKnoraRAG 检索调优中等强强Agent 沙箱弱弱强文档解析中等强中等OIDC 鉴权企业版有限原生支持可视化编排强中等中等上手难度低中中高3. 本机部署 WeKnora从零到跑通的完整路径3.1 环境准备里最容易翻车的三个点热词里“本机部署 weknora”“腾讯 weknora 部署”出现频率很高说明大家最关心的还是怎么跑起来。我按官方文档走了一遍踩了三个坑先提前说。第一个坑是Docker 资源限制。WeKnora 依赖向量数据库、关系数据库、后端服务、前端服务好几个容器如果你在 Windows 上用 Docker Desktop默认内存可能只有 2G跑起来会各种 OOM。建议至少给到 8G 内存、4 核 CPU。Mac 上如果是 M 系列芯片注意镜像的 arm64 支持情况部分依赖可能需要指定平台。第二个坑是端口冲突。WeKnora 默认会占用几个常见端口如果你本机已经跑了其他服务比如 5432 被 PostgreSQL 占了启动就会失败。建议部署前先netstat或lsof查一遍端口占用。第三个坑是模型配置。WeKnora 支持接 Ollama 本地模型也支持接内网推理服务。如果你用 Ollama注意模型要先ollama pull下来而且 embedding 模型和生成模型要分开配。很多人只配了生成模型忘了 embedding 模型结果文档入库时向量化失败。# 检查端口占用Linux/Mac lsof -i :5432 lsof -i :8000 # 检查 Docker 资源 docker info | grep -i memory3.2 部署步骤分阶段验证比一把梭靠谱我的建议是分阶段部署不要一上来就docker compose up全部拉起。先起数据库再起后端再起前端每步验证通过再往下走。第一步拉代码。从官方仓库 clone 下来进到部署目录。第二步改配置文件。重点改数据库密码、模型服务地址、OIDC 配置如果暂时不用可以先关掉。第三步起数据库容器确认能连上。第四步起后端服务看日志有没有报错。第五步起前端浏览器访问确认页面能打开。# 分阶段启动示例 docker compose up -d postgres docker compose logs -f postgres docker compose up -d backend docker compose logs -f backend docker compose up -d frontend注意后端启动时如果报“connection refused”九成是数据库还没 ready。加个健康检查或者等 30 秒再起后端别急着怀疑配置。3.3 首次入库文档切分参数怎么定部署跑通后第一件事是导入文档测试。WeKnora 的文档切分支持按固定长度、按段落、按标题层级几种策略。我实测下来中文文档建议按标题层级切分因为中文段落长固定长度切分容易把一句话切断检索时召回质量差。切分长度chunk size和重叠长度overlap是两个关键参数。chunk size 太小上下文不完整太大检索精度下降。我的经验值是中文技术文档 chunk size 设 500-800 字overlap 设 100-150 字。这个范围是试出来的太小比如 200 字一个完整概念被切碎太大比如 2000 字检索出来的片段里一半是无关内容。重叠的作用是防止关键信息正好落在切分边界上。比如一句话被切成两半前半段在 chunk A后半段在 chunk B如果没 overlap检索 chunk A 时拿不到完整语义。overlap 设 100-150 字基本能覆盖大部分边界情况。3.4 验证检索效果别只看“能不能答”要看“召回准不准”很多人部署完问一句“你好”能回就以为成功了这远远不够。真正要验证的是检索召回质量。我的做法是准备 20 个已知答案的问题跑一遍看命中率hit rate。热词里“rag hit rate”就是这个意思。具体操作把问题、标准答案、答案所在文档记下来然后逐个提问看检索出来的 top-3 片段里有没有包含标准答案。如果 20 个问题里命中少于 15 个说明切分或 embedding 有问题得调。常见原因是 embedding 模型对中文支持不好换成中文优化过的模型通常能提升明显。4. RAG 检索调优从“能搜到”到“搜得准”4.1 向量检索的瓶颈到底在哪热词里“rag 瓶颈”是个好问题。我踩下来的感受是RAG 的瓶颈通常不在向量数据库本身而在切分质量和embedding 质量。向量数据库再快切分切得稀碎检索出来的也是垃圾。举个例子一份产品手册里有“保修政策”章节如果切分时把“保修期 12 个月”和“保修范围”切到两个 chunk用户问“保修多久”检索可能只召回“保修范围”那个 chunk答非所问。解决办法是按语义切分让一个完整政策落在一个 chunk 里。另一个瓶颈是多义词。比如“苹果”既指水果也指公司纯向量检索可能把水果文档召回给问公司产品的用户。这时候需要混合检索——向量检索加关键词检索用关键词把范围收窄。WeKnora 支持配置混合检索权重我一般设向量 0.7、关键词 0.3实测比纯向量准。4.2 重排Rerank什么时候必须上向量检索召回 top-10但真正相关的可能只有 2-3 个。如果直接把这 10 个都塞给 LLM一是浪费上下文窗口二是无关内容会干扰生成。这时候就需要重排模型对召回的片段重新打分排序取 top-3 给 LLM。重排不是必须的但在文档量大、问题复杂时收益很明显。我实测过一个场景知识库有 5000 份文档不加重排时答案准确率大概 60%加了重排后提到 80% 左右。代价是每次查询多几百毫秒延迟。如果你的场景对延迟不敏感、对准确率敏感重排值得上。WeKnora 的重排配置在编排层可以接本地重排模型也可以接内网服务。注意重排模型和 embedding 模型是两回事别搞混。embedding 负责把文本转向量重排负责对候选片段精排。4.3 图片和表格RAG 知识库能存图片吗热词里“rag 知识库能存储图片嘛”问的人很多。答案是能存但检索逻辑不一样。纯文本 RAG 检索的是文本向量图片要先做 OCR 或多模态 embedding 才能被检索到。WeKnora 对图片的处理方式是如果文档里有图片可以配置 OCR 把图片里的文字提取出来作为文本入库。这样图片里的信息就能被文本检索命中。但如果图片是纯图形没有文字比如流程图、架构图OCR 就无能为力了需要多模态模型来理解。表格的处理更麻烦。表格如果直接按文本切分行列关系会丢失。我的做法是表格单独处理转成 Markdown 或 JSON 格式再入库保留行列结构。这样检索出来的表格片段 LLM 能看懂。WeKnora 对表格的支持还在完善中复杂表格建议预处理。4.4 GraphRAG 和本体 RAG 值不值得上热词里“rag graphrag llm wiki 本体 rag”“ontology rag”这些词说明大家在关注进阶方案。GraphRAG 的思路是把文档里的实体和关系抽出来构建知识图谱检索时走图查询而不是纯向量。好处是能回答“A 和 B 有什么关系”这类问题纯向量 RAG 很难答好。但 GraphRAG 的代价是构建成本高。抽取实体关系要跑一遍 LLM文档量大时时间和费用都不低。而且图谱质量依赖抽取质量抽错了反而误导。我的建议是文档量小于 1000 份、关系型问题不多时别上 GraphRAG纯向量加混合检索够用。等知识库大了、关系查询需求明确了再考虑。本体 RAGOntology RAG更重需要先定义本体 schema再按 schema 抽取。适合领域知识结构清晰的场景比如医疗、法律。通用场景上本体 RAG 是过度设计。5. Agent 沙箱安全边界与并发扛压5.1 沙箱到底在防什么热词里“agent 安全”“沙箱”“agent 沙盒”反复出现说明大家意识到 Agent 执行代码是有风险的。沙箱防的主要是三件事防越权访问Agent 生成的代码不能读宿主机敏感文件、防资源耗尽不能一个死循环把 CPU 跑满、防网络滥用不能随意对外发起请求。WeKnora 的沙箱机制是在容器里执行 Agent 生成的代码容器有独立的文件系统、网络命名空间和资源配额。我实测时故意让 Agent 生成一段while True的代码沙箱会在超时后强制终止不会拖垮宿主机。这一点比很多“裸跑”的 Agent 框架强。但沙箱不是万能的。如果沙箱配置不当比如挂载了宿主机目录、开放了全部网络那沙箱形同虚设。部署时一定要检查沙箱的挂载配置和网络策略默认拒绝、按需开放是原则。5.2 Agent 怎么扛并发热词里“ai agent 怎么扛并发”是个工程难题。Agent 执行比纯 RAG 重得多一次任务可能涉及多次 LLM 调用、多次沙箱执行耗时从几秒到几十秒不等。并发上来后瓶颈通常在沙箱资源和LLM 调用配额。我的做法是三层限流。第一层在接入层限制单用户的并发任务数防止一个用户刷爆。第二层在编排层用队列把任务排队控制同时执行的 Agent 数量。第三层在沙箱层限制每个沙箱的 CPU 和内存防止单个任务吃满资源。# 沙箱资源限制示例概念配置 sandbox: cpu_limit: 1.0 memory_limit: 512Mi timeout_seconds: 30 network: none实测下来单机 8 核 16G 的配置同时跑 5-8 个 Agent 任务比较稳再多延迟就明显上升。如果要扛更高并发得横向扩展沙箱节点把执行层独立部署。5.3 Agent 记忆短期和长期怎么分热词里“agent 记忆”也是高频词。Agent 记忆分短期和长期。短期记忆是当前任务的上下文比如用户前面说了什么、Agent 已经执行了哪些步骤。长期记忆是跨会话的知识比如用户的偏好、历史结论。WeKnora 里短期记忆靠对话上下文管理长期记忆可以落到 RAG 知识库里。我的做法是任务内的中间结果放短期记忆任务结束后的结论摘要写回知识库。这样下次遇到类似任务Agent 能检索到之前的结论不用从头再来。注意长期记忆要控制写入量不是什么都要记。我见过有人把每轮对话都写回知识库结果知识库被噪音污染检索质量下降。只写经过验证的、可复用的结论。5.4 Agent 执行报错怎么排查热词里“agent execution terminated due to error”是个典型报错。这个报错信息很泛得看日志定位。常见原因有四类一是沙箱超时任务跑太久被 kill二是代码语法错误Agent 生成的代码本身有问题三是依赖缺失沙箱里没装需要的库四是权限不足代码试图访问不允许的资源。排查顺序建议先看沙箱日志确认是超时还是报错再看 Agent 生成的代码有没有明显问题再检查沙箱镜像里依赖是否齐全最后看权限配置。我踩过最坑的一次是沙箱镜像里没装 pandasAgent 生成的代码一 import 就挂日志里只显示“execution terminated”查了半天才发现是依赖问题。6. 鉴权与集成OIDC 和 Obsidian 怎么接6.1 OIDC 接入的配置要点热词里“weknora oidc”说明企业用户关心单点登录。OIDC 接入的核心是配好四个东西issuer 地址、client id、client secret、回调地址。issuer 是身份提供方的地址client id 和 secret 是 WeKnora 在身份提供方注册后拿到的凭证回调地址是登录成功后跳回的地址。配置时最容易错的是回调地址。回调地址必须和身份提供方注册的完全一致多一个斜杠少一个斜杠都会失败。另外注意 issuer 地址的末尾斜杠有些身份提供方对末尾斜杠敏感配错了会报“issuer mismatch”。注意OIDC 配置涉及企业身份系统务必在测试环境验证通过后再上生产避免影响正常登录。6.2 和 Obsidian 的联动思路热词里“weknora 和 obsidian”问的是能不能把 Obsidian 笔记同步到 WeKnora。Obsidian 的笔记是本地 Markdown 文件WeKnora 支持 Markdown 导入所以理论上可以同步。我的做法是用脚本定期把 Obsidian vault 里的 Markdown 推到 WeKnora 的导入接口。但要注意两点一是 Obsidian 笔记里有很多[[双链]]语法直接导入会被当成普通文本检索时可能干扰。建议导入前做一次清洗把双链转成普通文本或去掉。二是 Obsidian 笔记更新频繁全量同步浪费资源建议做增量同步只推变化的文件。# 增量同步思路伪代码 import os, hashlib, json def sync_vault(vault_path, state_file): state json.load(open(state_file)) if os.path.exists(state_file) else {} for root, _, files in os.walk(vault_path): for f in files: if f.endswith(.md): path os.path.join(root, f) h hashlib.md5(open(path, rb).read()).hexdigest() if state.get(path) ! h: upload_to_weknora(path) state[path] h json.dump(state, open(state_file, w))6.3 和 Dify 的取舍热词里“weknora dify”也是常见对比。我的看法是Dify 适合快速搭原型可视化编排省事WeKnora 适合需要深度定制 RAG 和 Agent 沙箱的场景。如果你团队里没有能改源码的工程师Dify 更友好如果有WeKnora 的可定制空间更大。两者不是非此即彼也可以组合用用 Dify 做前端编排用 WeKnora 做后端 RAG 和沙箱执行。但组合会引入集成成本接口对齐、鉴权打通都要做小团队慎选。7. 我在实际折腾中总结的几条经验第一别一上来就追求大而全。我见过有人部署完 WeKnora 第一件事就是接 GraphRAG、接多模态、接一堆工具结果基础 RAG 还没调好问题一堆。正确顺序是先把纯文本 RAG 跑通、调准再加 Agent再加进阶能力。第二embedding 模型的选择比生成模型更影响检索质量。很多人花大力气调生成模型其实检索召回不准生成模型再好也白搭。中文场景建议选中文优化过的 embedding 模型实测比通用模型召回率高不少。第三沙箱一定要做资源限制。我踩过一次坑Agent 生成了一段内存泄漏的代码没设内存上限直接把容器跑挂了。后来加了 memory_limit 和 timeout再没出过事。第四日志要留全。Agent 执行链路长出问题时如果日志不全根本没法定位。建议把 LLM 调用、检索、沙箱执行都打上 trace id方便串联排查。第五知识库要定期清理。用久了会有过期文档、重复文档检索质量会下降。我一般每月做一次清理把过期内容归档重复内容去重。这个活儿不性感但对检索质量影响很大。最后分享一个小技巧调 RAG 参数时别凭感觉调建一个评测集。准备 50 个问题和标准答案每次调参跑一遍看命中率变化。这样调参有依据不会越调越乱。我一开始也是凭感觉后来建了评测集效率高多了。
腾讯WeKnora开源框架实战：RAG检索调优与Agent沙箱部署指南
1. 从“知识割裂”说起WeKnora 到底想解决什么问题如果你在企业里做过内部知识库大概率经历过这样的场景文档散落在 Confluence、飞书、Notion、本地 Word、PDF 里员工搜一个“报销标准”能搜出五个版本最后还得在群里问一句“以哪个为准”。这就是热词里提到的“知识割裂”——信息不是没有而是散、乱、版本不一致检索出来的东西没法直接用。WeKnora 是腾讯微信团队开源的一套 AI 知识库框架核心定位就是围绕RAG检索增强生成和Agent智能体两条主线把“文档入库—切分—向量化—检索—生成—执行”这条链路打通。它不是单纯的向量数据库也不是单纯的聊天前端而是一个把 RAG 检索、Agent 编排、沙箱执行、OIDC 鉴权这些能力整合在一起的工程化框架。我拿到这个项目后第一反应是市面上 RAG 框架已经很多了LangChain、LlamaIndex、Dify、RAGFlow 都能做WeKnora 的差异点在哪实测下来它比较突出的地方有三个一是微信团队出品工程完成度相对高不是那种跑个 Demo 就散架的玩具二是原生支持 Agent 沙箱这对需要执行代码、调用工具的场景很关键三是支持 OIDC 单点登录说明它是奔着企业内网部署去的不是个人玩具。这篇文章适合三类人看第一类是想自己搭一套本地 RAG 知识库的开发者第二类是在做 Agent 应用、关心并发和沙箱安全的工程师第三类是在 Dify、RAGFlow、WeKnora 之间做选型的技术负责人。我会从架构拆解、部署实操、RAG 检索调优、Agent 沙箱机制、选型对比几个角度把我在实际折腾过程中踩过的坑和总结的经验都摊开讲。提示本文所有操作均基于本地或企业内网自建环境不涉及任何外部网络访问工具请确保你的部署环境符合所在组织的安全规范。2. WeKnora 的架构骨架RAG 与 Agent 是怎么缝合的2.1 三层结构接入层、编排层、执行层把 WeKnora 拆开看它大致分三层。接入层负责文档导入、用户鉴权OIDC、API 网关编排层是核心负责 RAG 检索链路和 Agent 任务编排执行层是沙箱负责跑代码、调工具、执行 Agent 产生的动作。这个分层不是随便切的。我见过很多 RAG 项目把检索和生成揉在一个函数里结果想换个向量模型就得改一大片代码。WeKnora 把编排层独立出来好处是检索策略、重排模型、生成模型可以分别替换。比如你一开始用 Ollama 跑本地模型后面想换成企业内网的推理服务只需要改编排层的模型配置不用动文档处理逻辑。编排层里 RAG 和 Agent 是两条并行的链路但共享同一套知识底座。RAG 链路是“用户提问 → 向量检索 → 重排 → 拼上下文 → LLM 生成”Agent 链路是“任务解析 → 工具选择 → 沙箱执行 → 结果回填 → 再推理”。两条链路的交汇点在于Agent 在执行过程中可以调用 RAG 检索作为工具这就是热词里说的Agentic RAG——检索不再是固定的一步而是 Agent 按需触发的动作。2.2 为什么 RAG 和 Agent 要放在一个框架里单独做 RAG 的项目很多单独做 Agent 的框架也很多但把两者缝合好的不多。原因在于纯 RAG 的天花板很明显它只能回答“知识库里有什么”回答不了“根据知识库帮我做一件事”。比如你问“上季度销售数据里哪个区域增长最快”纯 RAG 只能把相关文档片段捞出来让 LLM 总结但如果数据在数据库里RAG 就无能为力了。Agent 的价值在于它能“动手”。它可以先调 RAG 检索出表结构说明再生成 SQL再在沙箱里执行 SQL最后把结果整理成回答。这条链路里RAG 负责“知道”Agent 负责“做到”。WeKnora 把两者放在一起本质上是想让知识库从“问答工具”升级成“执行工具”。我实测下来的感受是如果你的场景只是文档问答纯 RAG 就够了上 Agent 反而增加复杂度但如果你需要跨数据源、需要执行动作那 Agentic RAG 是绕不开的。WeKnora 在这块的设计思路是对的但配置复杂度也确实上来了后面会讲怎么简化。2.3 和 Dify、RAGFlow 的定位差异热词里有人问“dify ragflow weknora 开源版企业功能比较”我实际都部署过简单说下差异。Dify 强在工作流编排和可视化拖拽式搭 Agent 很顺手但它的 RAG 检索调优空间相对有限深度定制要改源码。RAGFlow 强在文档解析尤其是复杂 PDF、表格的切分做得细但 Agent 能力偏弱沙箱执行不是它的重点。WeKnora 的定位介于两者之间RAG 检索的工程化程度比 Dify 深Agent 沙箱比 RAGFlow 完整OIDC 鉴权是企业级特性。缺点是生态和文档还不如前两者成熟很多配置得看源码和 issue 才能搞明白。选型建议是要可视化工作流选 Dify要复杂文档解析选 RAGFlow要 Agent 沙箱加企业鉴权选 WeKnora。维度DifyRAGFlowWeKnoraRAG 检索调优中等强强Agent 沙箱弱弱强文档解析中等强中等OIDC 鉴权企业版有限原生支持可视化编排强中等中等上手难度低中中高3. 本机部署 WeKnora从零到跑通的完整路径3.1 环境准备里最容易翻车的三个点热词里“本机部署 weknora”“腾讯 weknora 部署”出现频率很高说明大家最关心的还是怎么跑起来。我按官方文档走了一遍踩了三个坑先提前说。第一个坑是Docker 资源限制。WeKnora 依赖向量数据库、关系数据库、后端服务、前端服务好几个容器如果你在 Windows 上用 Docker Desktop默认内存可能只有 2G跑起来会各种 OOM。建议至少给到 8G 内存、4 核 CPU。Mac 上如果是 M 系列芯片注意镜像的 arm64 支持情况部分依赖可能需要指定平台。第二个坑是端口冲突。WeKnora 默认会占用几个常见端口如果你本机已经跑了其他服务比如 5432 被 PostgreSQL 占了启动就会失败。建议部署前先netstat或lsof查一遍端口占用。第三个坑是模型配置。WeKnora 支持接 Ollama 本地模型也支持接内网推理服务。如果你用 Ollama注意模型要先ollama pull下来而且 embedding 模型和生成模型要分开配。很多人只配了生成模型忘了 embedding 模型结果文档入库时向量化失败。# 检查端口占用Linux/Mac lsof -i :5432 lsof -i :8000 # 检查 Docker 资源 docker info | grep -i memory3.2 部署步骤分阶段验证比一把梭靠谱我的建议是分阶段部署不要一上来就docker compose up全部拉起。先起数据库再起后端再起前端每步验证通过再往下走。第一步拉代码。从官方仓库 clone 下来进到部署目录。第二步改配置文件。重点改数据库密码、模型服务地址、OIDC 配置如果暂时不用可以先关掉。第三步起数据库容器确认能连上。第四步起后端服务看日志有没有报错。第五步起前端浏览器访问确认页面能打开。# 分阶段启动示例 docker compose up -d postgres docker compose logs -f postgres docker compose up -d backend docker compose logs -f backend docker compose up -d frontend注意后端启动时如果报“connection refused”九成是数据库还没 ready。加个健康检查或者等 30 秒再起后端别急着怀疑配置。3.3 首次入库文档切分参数怎么定部署跑通后第一件事是导入文档测试。WeKnora 的文档切分支持按固定长度、按段落、按标题层级几种策略。我实测下来中文文档建议按标题层级切分因为中文段落长固定长度切分容易把一句话切断检索时召回质量差。切分长度chunk size和重叠长度overlap是两个关键参数。chunk size 太小上下文不完整太大检索精度下降。我的经验值是中文技术文档 chunk size 设 500-800 字overlap 设 100-150 字。这个范围是试出来的太小比如 200 字一个完整概念被切碎太大比如 2000 字检索出来的片段里一半是无关内容。重叠的作用是防止关键信息正好落在切分边界上。比如一句话被切成两半前半段在 chunk A后半段在 chunk B如果没 overlap检索 chunk A 时拿不到完整语义。overlap 设 100-150 字基本能覆盖大部分边界情况。3.4 验证检索效果别只看“能不能答”要看“召回准不准”很多人部署完问一句“你好”能回就以为成功了这远远不够。真正要验证的是检索召回质量。我的做法是准备 20 个已知答案的问题跑一遍看命中率hit rate。热词里“rag hit rate”就是这个意思。具体操作把问题、标准答案、答案所在文档记下来然后逐个提问看检索出来的 top-3 片段里有没有包含标准答案。如果 20 个问题里命中少于 15 个说明切分或 embedding 有问题得调。常见原因是 embedding 模型对中文支持不好换成中文优化过的模型通常能提升明显。4. RAG 检索调优从“能搜到”到“搜得准”4.1 向量检索的瓶颈到底在哪热词里“rag 瓶颈”是个好问题。我踩下来的感受是RAG 的瓶颈通常不在向量数据库本身而在切分质量和embedding 质量。向量数据库再快切分切得稀碎检索出来的也是垃圾。举个例子一份产品手册里有“保修政策”章节如果切分时把“保修期 12 个月”和“保修范围”切到两个 chunk用户问“保修多久”检索可能只召回“保修范围”那个 chunk答非所问。解决办法是按语义切分让一个完整政策落在一个 chunk 里。另一个瓶颈是多义词。比如“苹果”既指水果也指公司纯向量检索可能把水果文档召回给问公司产品的用户。这时候需要混合检索——向量检索加关键词检索用关键词把范围收窄。WeKnora 支持配置混合检索权重我一般设向量 0.7、关键词 0.3实测比纯向量准。4.2 重排Rerank什么时候必须上向量检索召回 top-10但真正相关的可能只有 2-3 个。如果直接把这 10 个都塞给 LLM一是浪费上下文窗口二是无关内容会干扰生成。这时候就需要重排模型对召回的片段重新打分排序取 top-3 给 LLM。重排不是必须的但在文档量大、问题复杂时收益很明显。我实测过一个场景知识库有 5000 份文档不加重排时答案准确率大概 60%加了重排后提到 80% 左右。代价是每次查询多几百毫秒延迟。如果你的场景对延迟不敏感、对准确率敏感重排值得上。WeKnora 的重排配置在编排层可以接本地重排模型也可以接内网服务。注意重排模型和 embedding 模型是两回事别搞混。embedding 负责把文本转向量重排负责对候选片段精排。4.3 图片和表格RAG 知识库能存图片吗热词里“rag 知识库能存储图片嘛”问的人很多。答案是能存但检索逻辑不一样。纯文本 RAG 检索的是文本向量图片要先做 OCR 或多模态 embedding 才能被检索到。WeKnora 对图片的处理方式是如果文档里有图片可以配置 OCR 把图片里的文字提取出来作为文本入库。这样图片里的信息就能被文本检索命中。但如果图片是纯图形没有文字比如流程图、架构图OCR 就无能为力了需要多模态模型来理解。表格的处理更麻烦。表格如果直接按文本切分行列关系会丢失。我的做法是表格单独处理转成 Markdown 或 JSON 格式再入库保留行列结构。这样检索出来的表格片段 LLM 能看懂。WeKnora 对表格的支持还在完善中复杂表格建议预处理。4.4 GraphRAG 和本体 RAG 值不值得上热词里“rag graphrag llm wiki 本体 rag”“ontology rag”这些词说明大家在关注进阶方案。GraphRAG 的思路是把文档里的实体和关系抽出来构建知识图谱检索时走图查询而不是纯向量。好处是能回答“A 和 B 有什么关系”这类问题纯向量 RAG 很难答好。但 GraphRAG 的代价是构建成本高。抽取实体关系要跑一遍 LLM文档量大时时间和费用都不低。而且图谱质量依赖抽取质量抽错了反而误导。我的建议是文档量小于 1000 份、关系型问题不多时别上 GraphRAG纯向量加混合检索够用。等知识库大了、关系查询需求明确了再考虑。本体 RAGOntology RAG更重需要先定义本体 schema再按 schema 抽取。适合领域知识结构清晰的场景比如医疗、法律。通用场景上本体 RAG 是过度设计。5. Agent 沙箱安全边界与并发扛压5.1 沙箱到底在防什么热词里“agent 安全”“沙箱”“agent 沙盒”反复出现说明大家意识到 Agent 执行代码是有风险的。沙箱防的主要是三件事防越权访问Agent 生成的代码不能读宿主机敏感文件、防资源耗尽不能一个死循环把 CPU 跑满、防网络滥用不能随意对外发起请求。WeKnora 的沙箱机制是在容器里执行 Agent 生成的代码容器有独立的文件系统、网络命名空间和资源配额。我实测时故意让 Agent 生成一段while True的代码沙箱会在超时后强制终止不会拖垮宿主机。这一点比很多“裸跑”的 Agent 框架强。但沙箱不是万能的。如果沙箱配置不当比如挂载了宿主机目录、开放了全部网络那沙箱形同虚设。部署时一定要检查沙箱的挂载配置和网络策略默认拒绝、按需开放是原则。5.2 Agent 怎么扛并发热词里“ai agent 怎么扛并发”是个工程难题。Agent 执行比纯 RAG 重得多一次任务可能涉及多次 LLM 调用、多次沙箱执行耗时从几秒到几十秒不等。并发上来后瓶颈通常在沙箱资源和LLM 调用配额。我的做法是三层限流。第一层在接入层限制单用户的并发任务数防止一个用户刷爆。第二层在编排层用队列把任务排队控制同时执行的 Agent 数量。第三层在沙箱层限制每个沙箱的 CPU 和内存防止单个任务吃满资源。# 沙箱资源限制示例概念配置 sandbox: cpu_limit: 1.0 memory_limit: 512Mi timeout_seconds: 30 network: none实测下来单机 8 核 16G 的配置同时跑 5-8 个 Agent 任务比较稳再多延迟就明显上升。如果要扛更高并发得横向扩展沙箱节点把执行层独立部署。5.3 Agent 记忆短期和长期怎么分热词里“agent 记忆”也是高频词。Agent 记忆分短期和长期。短期记忆是当前任务的上下文比如用户前面说了什么、Agent 已经执行了哪些步骤。长期记忆是跨会话的知识比如用户的偏好、历史结论。WeKnora 里短期记忆靠对话上下文管理长期记忆可以落到 RAG 知识库里。我的做法是任务内的中间结果放短期记忆任务结束后的结论摘要写回知识库。这样下次遇到类似任务Agent 能检索到之前的结论不用从头再来。注意长期记忆要控制写入量不是什么都要记。我见过有人把每轮对话都写回知识库结果知识库被噪音污染检索质量下降。只写经过验证的、可复用的结论。5.4 Agent 执行报错怎么排查热词里“agent execution terminated due to error”是个典型报错。这个报错信息很泛得看日志定位。常见原因有四类一是沙箱超时任务跑太久被 kill二是代码语法错误Agent 生成的代码本身有问题三是依赖缺失沙箱里没装需要的库四是权限不足代码试图访问不允许的资源。排查顺序建议先看沙箱日志确认是超时还是报错再看 Agent 生成的代码有没有明显问题再检查沙箱镜像里依赖是否齐全最后看权限配置。我踩过最坑的一次是沙箱镜像里没装 pandasAgent 生成的代码一 import 就挂日志里只显示“execution terminated”查了半天才发现是依赖问题。6. 鉴权与集成OIDC 和 Obsidian 怎么接6.1 OIDC 接入的配置要点热词里“weknora oidc”说明企业用户关心单点登录。OIDC 接入的核心是配好四个东西issuer 地址、client id、client secret、回调地址。issuer 是身份提供方的地址client id 和 secret 是 WeKnora 在身份提供方注册后拿到的凭证回调地址是登录成功后跳回的地址。配置时最容易错的是回调地址。回调地址必须和身份提供方注册的完全一致多一个斜杠少一个斜杠都会失败。另外注意 issuer 地址的末尾斜杠有些身份提供方对末尾斜杠敏感配错了会报“issuer mismatch”。注意OIDC 配置涉及企业身份系统务必在测试环境验证通过后再上生产避免影响正常登录。6.2 和 Obsidian 的联动思路热词里“weknora 和 obsidian”问的是能不能把 Obsidian 笔记同步到 WeKnora。Obsidian 的笔记是本地 Markdown 文件WeKnora 支持 Markdown 导入所以理论上可以同步。我的做法是用脚本定期把 Obsidian vault 里的 Markdown 推到 WeKnora 的导入接口。但要注意两点一是 Obsidian 笔记里有很多[[双链]]语法直接导入会被当成普通文本检索时可能干扰。建议导入前做一次清洗把双链转成普通文本或去掉。二是 Obsidian 笔记更新频繁全量同步浪费资源建议做增量同步只推变化的文件。# 增量同步思路伪代码 import os, hashlib, json def sync_vault(vault_path, state_file): state json.load(open(state_file)) if os.path.exists(state_file) else {} for root, _, files in os.walk(vault_path): for f in files: if f.endswith(.md): path os.path.join(root, f) h hashlib.md5(open(path, rb).read()).hexdigest() if state.get(path) ! h: upload_to_weknora(path) state[path] h json.dump(state, open(state_file, w))6.3 和 Dify 的取舍热词里“weknora dify”也是常见对比。我的看法是Dify 适合快速搭原型可视化编排省事WeKnora 适合需要深度定制 RAG 和 Agent 沙箱的场景。如果你团队里没有能改源码的工程师Dify 更友好如果有WeKnora 的可定制空间更大。两者不是非此即彼也可以组合用用 Dify 做前端编排用 WeKnora 做后端 RAG 和沙箱执行。但组合会引入集成成本接口对齐、鉴权打通都要做小团队慎选。7. 我在实际折腾中总结的几条经验第一别一上来就追求大而全。我见过有人部署完 WeKnora 第一件事就是接 GraphRAG、接多模态、接一堆工具结果基础 RAG 还没调好问题一堆。正确顺序是先把纯文本 RAG 跑通、调准再加 Agent再加进阶能力。第二embedding 模型的选择比生成模型更影响检索质量。很多人花大力气调生成模型其实检索召回不准生成模型再好也白搭。中文场景建议选中文优化过的 embedding 模型实测比通用模型召回率高不少。第三沙箱一定要做资源限制。我踩过一次坑Agent 生成了一段内存泄漏的代码没设内存上限直接把容器跑挂了。后来加了 memory_limit 和 timeout再没出过事。第四日志要留全。Agent 执行链路长出问题时如果日志不全根本没法定位。建议把 LLM 调用、检索、沙箱执行都打上 trace id方便串联排查。第五知识库要定期清理。用久了会有过期文档、重复文档检索质量会下降。我一般每月做一次清理把过期内容归档重复内容去重。这个活儿不性感但对检索质量影响很大。最后分享一个小技巧调 RAG 参数时别凭感觉调建一个评测集。准备 50 个问题和标准答案每次调参跑一遍看命中率变化。这样调参有依据不会越调越乱。我一开始也是凭感觉后来建了评测集效率高多了。
