拓冰网站定制 
1. 为什么我盯上了 WeKnora 这个项目第一次看到 WeKnora 这个名字是在一个做企业知识管理的群里。有人甩了张截图说腾讯微信团队开源了一个 AI 知识库工具支持 RAG、Agent、沙箱还能本机部署。我当时第一反应是又一个套壳 RAG毕竟这两年“知识库”三个字已经被玩烂了从 LangChain 到 Dify 再到 RAGFlow几乎每个月都有新东西冒出来。但“微信团队出品”这几个字还是让我多看了两眼——这帮人做产品的功底是经过十亿级用户验证的他们出手做知识库大概率不是玩票。我花了大概两周时间把 WeKnora 从部署到实际跑通完整链路中间踩了不少坑也对比了 Dify、RAGFlow 这些同类方案。这篇文章不打算写成官方文档的中文翻译而是把我自己从零到一的过程、关键决策点、以及那些文档里不会写的坑原原本本记录下来。如果你正在选型企业知识库、想搞清楚 RAG 和 Agent 到底怎么结合、或者单纯想找个能本机跑的知识库方案这篇应该能帮你省下不少试错时间。WeKnora 本质上是一个面向企业场景的 AI 知识库框架核心能力包括文档解析、向量检索、RAG 问答、Agent 编排以及一个被很多人忽略但极其重要的沙箱执行环境。它解决的核心问题是企业内部的文档散落在各处格式五花八门传统搜索只能匹配关键词而大模型又容易胡说八道。WeKnora 想做的是把“文档进、答案出”这条链路标准化同时用 Agent 和沙箱把“答案”从纯文本扩展到可执行的操作。适合谁看如果你是技术选型负责人想评估 WeKnora 和 Dify、RAGFlow 的差异第二部分有详细对比如果你是开发者想本机部署一套跑通 RAG 全流程第三部分有完整步骤如果你关心 Agent 和沙箱的安全边界第四部分专门讲这个。我不假设你有很深的 AI 背景但基本的 Docker 和命令行操作经验是需要的。2. WeKnora 的整体设计与选型逻辑拆解2.1 它到底解决了知识库的哪个痛点大部分企业知识库的死穴不在“检索”而在“知识割裂”。我见过太多公司产品文档在 Confluence客服话术在飞书技术方案在 GitLab销售案例在某个离职员工的硬盘里。你问一个问题答案可能散落在三个系统里传统搜索根本串不起来。RAG 的思路是好的——把文档切片、向量化、检索、喂给大模型生成答案。但实际落地时问题一大堆PDF 里的表格解析出来全是乱码扫描件根本没法处理检索回来的片段驴唇不对马嘴大模型拿着错误的上下文一本正经地胡说。WeKnora 的设计思路我理解下来是把 RAG 当成一个系统工程来做而不是一个模型调用。它没有把宝全押在“换个更强的 Embedding 模型”上而是在文档解析、切片策略、检索召回、重排序、Agent 编排这几个环节都做了工程化处理。举个例子它的文档解析模块对 PDF 和 Word 的处理明显比 LangChain 默认的 loader 要细表格会尝试保留结构标题层级会被识别出来用于后续的切片边界判断。这个细节很关键——切片切得好检索命中率能差出百分之二三十。另一个核心设计是Agent 与 RAG 的耦合方式。很多方案里Agent 和 RAG 是两张皮Agent 调 RAG 就是一个工具调用检索回来的东西直接塞进 prompt。WeKnora 的做法更接近 Agentic RAG 的思路Agent 可以根据问题类型决定要不要检索、检索哪个知识库、检索几次、要不要对检索结果做二次加工。这听起来简单但实现上需要一套编排引擎来管理状态和工具调用这也是为什么它内置了沙箱——有些操作需要执行代码或调用外部 API不能直接在宿主环境跑。2.2 和 Dify、RAGFlow 的差异在哪这三个经常被放在一起比我实际用下来的感受是Dify 强在应用编排和生态RAGFlow 强在文档解析深度WeKnora 强在 Agent 与知识库的原生融合。Dify 的定位更偏向“AI 应用开发平台”知识库只是它的一个模块你可以用它搭聊天机器人、工作流、Agent但知识库本身的检索调优空间相对有限。RAGFlow 在文档解析上下了很大功夫尤其是复杂版式和扫描件它的 DeepDoc 模块确实比一般方案强但 Agent 能力相对薄弱更像一个“检索增强的问答系统”。WeKnora 的差异点在于它把 Agent 当成一等公民。你可以定义一个 Agent给它挂载多个知识库配置它的推理策略甚至让它调用沙箱里的工具。这种设计更适合“知识库不只是用来问答还要驱动操作”的场景。比如客服场景Agent 检索到退款政策后可以直接在沙箱里调用退款接口的模拟环境验证流程是否走得通而不是只给用户一段文字。当然这不是说 WeKnora 全面碾压。Dify 的插件生态和可视化编排更成熟RAGFlow 的解析能力在极端文档上更稳。选型时得看你的核心诉求如果只是做个问答机器人Dify 可能更快如果文档格式极其复杂RAGFlow 更省心如果要构建有执行能力的知识型 AgentWeKnora 的架构更顺。2.3 沙箱机制为什么值得单独说沙箱这个词在热搜里出现了好几次我一开始也没太在意觉得就是个安全隔离。但实际用下来沙箱是 WeKnora 区别于其他知识库框架的关键设计。它的沙箱不是简单的 Docker 容器而是一个受控的执行环境Agent 生成的代码或操作指令会在这里运行有资源限制、网络隔离、文件系统隔离。为什么需要这个因为当 Agent 从知识库里检索到一段“如何调用退款接口”的文档后它可能会生成一段调用代码。如果没有沙箱这段代码直接在服务器上跑风险极大。有了沙箱代码只能在隔离环境里执行即使出错也不会影响主系统。这个设计在企业场景里是刚需尤其是金融、医疗这类对安全敏感的行业。我实测下来沙箱的启动速度还可以冷启动大概两三秒热启动基本无感。资源限制可以配置默认是 1 核 512MB对于大多数工具调用够用了。但要注意沙箱里的网络访问默认是受限的如果需要调用外部 API得在配置里显式放行这个后面实操部分会细说。3. 本机部署与核心环节实操3.1 环境准备与依赖安装我用的是一台 Ubuntu 22.04 的机器16GB 内存带一张 RTX 3060 12GB。官方推荐至少 16GB 内存如果要用本地 Embedding 模型显存最好 8GB 以上。纯 CPU 也能跑但检索速度会慢不少尤其是文档量大的时候。依赖主要是 Docker 和 Docker Compose版本别太老Docker 20.10 以上、Compose v2 以上。Python 环境建议 3.10 或 3.113.12 有些依赖包还没跟上。Node.js 如果要用前端界面需要 18 以上但我主要用 API前端只做验证。# 检查 Docker 版本 docker --version docker compose version # 克隆仓库 git clone https://github.com/Tencent/WeKnora.git cd WeKnora # 复制环境变量模板 cp .env.example .env.env文件里需要改几个关键配置。LLM_API_KEY和LLM_BASE_URL如果你用 OpenAI 兼容的接口就填对应的我用的是本地 Ollama所以 base url 填http://host.docker.internal:11434/v1key 随便填一个非空值。Embedding 模型我一开始想用本地的 bge-large但发现显存吃紧后来换成了text-embedding-3-small的兼容接口速度快很多效果对于中文文档也够用。注意如果你用 Ollama记得在宿主机上先ollama pull好模型并且确认 Ollama 监听了0.0.0.0否则容器里访问不到。这个坑我踩过默认 Ollama 只监听 127.0.0.1容器里连不上改配置重启才行。3.2 启动服务与初始化配置配置改好后直接docker compose up -d。第一次启动会拉镜像大概需要几分钟。启动完成后用docker compose ps检查各个服务状态正常应该有weknora-api、weknora-worker、postgres、redis、minio这几个容器在跑。# 查看服务状态 docker compose ps # 查看 API 日志确认没有报错 docker compose logs -f weknora-apiAPI 默认跑在 8080 端口前端在 3000。浏览器打开http://localhost:3000应该能看到登录页。初始管理员账号在.env里配置默认是admin/admin123第一次登录后务必改掉。登录进去后第一件事是配置模型。在“系统设置”里填 LLM 和 Embedding 的连接信息。这里有个细节WeKnora 支持为不同用途配置不同模型比如问答用一个模型摘要用另一个Embedding 单独配。我建议问答用能力强的模型Embedding 用速度快的因为 Embedding 调用频率远高于问答。配置完模型后创建一个知识库。知识库的配置项不少我挑几个关键的讲切片策略默认是按固定长度切我建议改成按标题层级切尤其是技术文档这样每个切片语义更完整。切片长度默认 512 token我调到 800 左右因为中文文档信息密度高切太碎反而丢上下文。重叠长度设成切片长度的 10% 到 15%防止关键信息被切断。检索召回数默认 5我调到 10配合重排序用命中率明显提升。3.3 文档入库与检索调优文档上传支持拖拽也支持 API 批量导入。我测试了 PDF、Word、Markdown、Excel 几种格式PDF 里的表格确实能解析出来但复杂合并单元格还是会有错位这个目前没有完美方案RAGFlow 在这方面稍好一些。扫描件需要 OCRWeKnora 内置了 OCR 模块但中文识别率一般建议外接更好的 OCR 服务。文档入库后可以在“检索测试”里直接试。输入一个问题看返回的片段和相似度分数。这里有个调优技巧如果发现检索结果不相关先别急着换 Embedding 模型先检查切片。我遇到过一个问题问“退款流程是什么”检索回来的全是“退款政策”的片段但答案其实在“售后操作手册”里。原因是“售后操作手册”的切片被切得太碎关键段落被分到了两个切片里检索时都没排到前面。后来调整了切片策略把标题层级纳入切片边界判断问题就解决了。重排序模型也值得开。WeKnora 支持配置 rerank 模型我用的是 bge-reranker-base加上之后 Top3 命中率大概提升了 15% 左右。代价是每次检索多几百毫秒对于问答场景可以接受。3.4 Agent 配置与沙箱联动Agent 的配置是 WeKnora 最有意思的部分。在“Agent 管理”里新建一个 Agent可以给它挂载多个知识库配置系统提示词选择推理策略。推理策略有几种模式简单问答、多步推理、工具调用。我主要用多步推理加工具调用。工具调用的配置需要和沙箱配合。比如我配了一个“查询订单状态”的工具Agent 检索到相关文档后会生成一段调用代码这段代码在沙箱里执行。沙箱的配置在.env里可以设置超时时间、内存限制、网络白名单。# docker-compose.yml 里沙箱相关配置片段 sandbox: image: weknora/sandbox:latest environment: - SANDBOX_TIMEOUT30 - SANDBOX_MEMORY_LIMIT512m - SANDBOX_NETWORK_WHITELISTapi.example.com networks: - sandbox-net注意沙箱的网络白名单一定要配否则 Agent 生成的代码可能访问任意地址虽然沙箱有隔离但能限制还是限制。另外超时时间别设太长30 秒足够大多数操作设太长容易卡住。我实测了一个场景问“帮我查一下订单 12345 的退款进度”Agent 先检索知识库找到退款查询的 API 文档然后生成调用代码在沙箱里执行返回模拟结果。整个过程大概 5 到 8 秒其中沙箱执行占 2 秒左右。这个链路跑通后知识库就不只是“回答问题”而是“执行任务”了。4. 常见问题与排查技巧实录4.1 部署阶段的高频报错问题一容器启动后 API 一直重启。最常见的原因是数据库连不上。检查docker compose logs weknora-api如果看到connection refused大概率是 Postgres 还没初始化完。等一两分钟再试或者手动docker compose restart weknora-api。如果还不行检查.env里的数据库密码和docker-compose.yml里的是否一致。问题二上传文档后一直显示“处理中”。这是 worker 容器的问题。docker compose logs weknora-worker看日志如果是内存不足被 kill 了调大 worker 的内存限制。如果是模型调用超时检查 Embedding 服务的网络连通性。我遇到过因为 Embedding 接口响应太慢导致 worker 卡死的情况后来换了个更快的 Embedding 服务就好了。问题三检索结果为空。先确认文档是否真的入库成功在“文档管理”里看状态。如果状态是“已完成”但检索不到检查 Embedding 模型是否一致——入库时用的模型和检索时用的模型必须相同否则向量空间不对齐相似度计算全是乱的。这个坑很隐蔽因为系统不会报错只是默默返回空结果。4.2 检索效果差的排查思路检索效果差是问得最多的问题。我整理了一个排查顺序按这个顺序走基本能定位到原因排查项检查方法常见问题切片质量在文档详情里看切片内容切片太碎或太长语义不完整Embedding 一致性确认入库和检索用同一模型模型不一致导致向量空间错位召回数量调大召回数看是否改善召回太少正确答案没进候选重排序开启 rerank 对比效果未开启导致排序不准查询改写看 Agent 是否改写了查询原始查询太短或歧义知识库范围确认问题对应的知识库已挂载答案在另一个知识库里我踩过最坑的一个问题是知识库里有一份 PDF 是扫描件OCR 出来的文字错别字很多导致检索时关键词匹配不上。后来把这份文档重新用更好的 OCR 处理了一遍问题才解决。所以文档入库前的质量检查很重要别什么都往里塞。4.3 Agent 与沙箱的典型故障Agent 不调用工具只返回文本答案。这种情况通常是系统提示词没写清楚。Agent 需要明确的指令才会调用工具比如“你必须先检索知识库如果找到相关 API 文档则生成调用代码并在沙箱执行”。提示词里要明确工具的使用条件和步骤否则模型会偷懒。沙箱执行超时。先看沙箱日志如果是代码本身死循环那没辙只能优化代码。如果是网络请求慢检查白名单是否配了目标地址。我遇到过沙箱里 DNS 解析失败的情况原因是沙箱容器的 DNS 配置没继承宿主机的后来在docker-compose.yml里显式指定了 DNS 才解决。Agent 返回的结果和知识库内容不一致。这通常是 Agent 在生成答案时“自由发挥”了。解决办法是在提示词里强调“答案必须基于检索到的内容如果检索不到就明确说不知道”。另外可以调低模型的 temperature减少随机性。4.4 性能与并发方面的经验WeKnora 的并发能力取决于几个环节API 层、检索层、模型调用层。API 层是无状态的可以水平扩展。检索层依赖向量数据库Postgres 的 pgvector 在数据量大了之后性能会下降建议超过百万级向量就换 Milvus 或 Qdrant。模型调用层是最大的瓶颈尤其是用本地模型时并发一高就排队。我实测下来单张 3060 跑 7B 的模型并发 5 左右就比较吃力了。如果要做生产部署建议 LLM 和 Embedding 都用外部 API或者上多卡。沙箱的并发也要注意每个沙箱实例占资源默认配置下同时跑 10 个沙箱实例内存就吃紧了需要根据机器配置调整。提示如果并发要求高可以把沙箱改成按需创建、用完即毁的模式虽然冷启动有开销但资源利用率更高。WeKnora 支持配置沙箱池的大小这个参数在.env里叫SANDBOX_POOL_SIZE默认是 5可以按机器配置调。5. 一些个人体会和后续可折腾的方向用了这段时间我对 WeKnora 的整体感受是它不是一个开箱即用的产品而是一个需要调优的框架。官方给的默认配置能跑通但效果离“好用”还有距离。切片策略、检索参数、Agent 提示词这些都需要根据你的文档特点和业务场景去磨。磨好了效果确实比通用方案好一截不磨可能还不如直接用关键词搜索。另外WeKnora 和 Obsidian 的结合是个有意思的方向。有人把 Obsidian 的笔记库通过 API 同步到 WeKnora然后用 Agent 做笔记问答和关联推荐。我试了一下对于结构化的 Markdown 笔记效果不错因为 Markdown 的标题层级天然适合做切片边界。如果你有大量 Obsidian 笔记可以试试这个路子。后续我打算折腾两个方向一是把 GraphRAG 的思路接进来用知识图谱增强实体关系的检索二是把沙箱的能力扩展到更多工具比如数据库查询、文件操作让 Agent 真正能“动手做事”。这两个方向都有坑等踩完了再写。 腾讯WeKnora企业级AI知识库实战：RAG与Agent融合及沙箱部署指南
1. 为什么我盯上了 WeKnora 这个项目第一次看到 WeKnora 这个名字是在一个做企业知识管理的群里。有人甩了张截图说腾讯微信团队开源了一个 AI 知识库工具支持 RAG、Agent、沙箱还能本机部署。我当时第一反应是又一个套壳 RAG毕竟这两年“知识库”三个字已经被玩烂了从 LangChain 到 Dify 再到 RAGFlow几乎每个月都有新东西冒出来。但“微信团队出品”这几个字还是让我多看了两眼——这帮人做产品的功底是经过十亿级用户验证的他们出手做知识库大概率不是玩票。我花了大概两周时间把 WeKnora 从部署到实际跑通完整链路中间踩了不少坑也对比了 Dify、RAGFlow 这些同类方案。这篇文章不打算写成官方文档的中文翻译而是把我自己从零到一的过程、关键决策点、以及那些文档里不会写的坑原原本本记录下来。如果你正在选型企业知识库、想搞清楚 RAG 和 Agent 到底怎么结合、或者单纯想找个能本机跑的知识库方案这篇应该能帮你省下不少试错时间。WeKnora 本质上是一个面向企业场景的 AI 知识库框架核心能力包括文档解析、向量检索、RAG 问答、Agent 编排以及一个被很多人忽略但极其重要的沙箱执行环境。它解决的核心问题是企业内部的文档散落在各处格式五花八门传统搜索只能匹配关键词而大模型又容易胡说八道。WeKnora 想做的是把“文档进、答案出”这条链路标准化同时用 Agent 和沙箱把“答案”从纯文本扩展到可执行的操作。适合谁看如果你是技术选型负责人想评估 WeKnora 和 Dify、RAGFlow 的差异第二部分有详细对比如果你是开发者想本机部署一套跑通 RAG 全流程第三部分有完整步骤如果你关心 Agent 和沙箱的安全边界第四部分专门讲这个。我不假设你有很深的 AI 背景但基本的 Docker 和命令行操作经验是需要的。2. WeKnora 的整体设计与选型逻辑拆解2.1 它到底解决了知识库的哪个痛点大部分企业知识库的死穴不在“检索”而在“知识割裂”。我见过太多公司产品文档在 Confluence客服话术在飞书技术方案在 GitLab销售案例在某个离职员工的硬盘里。你问一个问题答案可能散落在三个系统里传统搜索根本串不起来。RAG 的思路是好的——把文档切片、向量化、检索、喂给大模型生成答案。但实际落地时问题一大堆PDF 里的表格解析出来全是乱码扫描件根本没法处理检索回来的片段驴唇不对马嘴大模型拿着错误的上下文一本正经地胡说。WeKnora 的设计思路我理解下来是把 RAG 当成一个系统工程来做而不是一个模型调用。它没有把宝全押在“换个更强的 Embedding 模型”上而是在文档解析、切片策略、检索召回、重排序、Agent 编排这几个环节都做了工程化处理。举个例子它的文档解析模块对 PDF 和 Word 的处理明显比 LangChain 默认的 loader 要细表格会尝试保留结构标题层级会被识别出来用于后续的切片边界判断。这个细节很关键——切片切得好检索命中率能差出百分之二三十。另一个核心设计是Agent 与 RAG 的耦合方式。很多方案里Agent 和 RAG 是两张皮Agent 调 RAG 就是一个工具调用检索回来的东西直接塞进 prompt。WeKnora 的做法更接近 Agentic RAG 的思路Agent 可以根据问题类型决定要不要检索、检索哪个知识库、检索几次、要不要对检索结果做二次加工。这听起来简单但实现上需要一套编排引擎来管理状态和工具调用这也是为什么它内置了沙箱——有些操作需要执行代码或调用外部 API不能直接在宿主环境跑。2.2 和 Dify、RAGFlow 的差异在哪这三个经常被放在一起比我实际用下来的感受是Dify 强在应用编排和生态RAGFlow 强在文档解析深度WeKnora 强在 Agent 与知识库的原生融合。Dify 的定位更偏向“AI 应用开发平台”知识库只是它的一个模块你可以用它搭聊天机器人、工作流、Agent但知识库本身的检索调优空间相对有限。RAGFlow 在文档解析上下了很大功夫尤其是复杂版式和扫描件它的 DeepDoc 模块确实比一般方案强但 Agent 能力相对薄弱更像一个“检索增强的问答系统”。WeKnora 的差异点在于它把 Agent 当成一等公民。你可以定义一个 Agent给它挂载多个知识库配置它的推理策略甚至让它调用沙箱里的工具。这种设计更适合“知识库不只是用来问答还要驱动操作”的场景。比如客服场景Agent 检索到退款政策后可以直接在沙箱里调用退款接口的模拟环境验证流程是否走得通而不是只给用户一段文字。当然这不是说 WeKnora 全面碾压。Dify 的插件生态和可视化编排更成熟RAGFlow 的解析能力在极端文档上更稳。选型时得看你的核心诉求如果只是做个问答机器人Dify 可能更快如果文档格式极其复杂RAGFlow 更省心如果要构建有执行能力的知识型 AgentWeKnora 的架构更顺。2.3 沙箱机制为什么值得单独说沙箱这个词在热搜里出现了好几次我一开始也没太在意觉得就是个安全隔离。但实际用下来沙箱是 WeKnora 区别于其他知识库框架的关键设计。它的沙箱不是简单的 Docker 容器而是一个受控的执行环境Agent 生成的代码或操作指令会在这里运行有资源限制、网络隔离、文件系统隔离。为什么需要这个因为当 Agent 从知识库里检索到一段“如何调用退款接口”的文档后它可能会生成一段调用代码。如果没有沙箱这段代码直接在服务器上跑风险极大。有了沙箱代码只能在隔离环境里执行即使出错也不会影响主系统。这个设计在企业场景里是刚需尤其是金融、医疗这类对安全敏感的行业。我实测下来沙箱的启动速度还可以冷启动大概两三秒热启动基本无感。资源限制可以配置默认是 1 核 512MB对于大多数工具调用够用了。但要注意沙箱里的网络访问默认是受限的如果需要调用外部 API得在配置里显式放行这个后面实操部分会细说。3. 本机部署与核心环节实操3.1 环境准备与依赖安装我用的是一台 Ubuntu 22.04 的机器16GB 内存带一张 RTX 3060 12GB。官方推荐至少 16GB 内存如果要用本地 Embedding 模型显存最好 8GB 以上。纯 CPU 也能跑但检索速度会慢不少尤其是文档量大的时候。依赖主要是 Docker 和 Docker Compose版本别太老Docker 20.10 以上、Compose v2 以上。Python 环境建议 3.10 或 3.113.12 有些依赖包还没跟上。Node.js 如果要用前端界面需要 18 以上但我主要用 API前端只做验证。# 检查 Docker 版本 docker --version docker compose version # 克隆仓库 git clone https://github.com/Tencent/WeKnora.git cd WeKnora # 复制环境变量模板 cp .env.example .env.env文件里需要改几个关键配置。LLM_API_KEY和LLM_BASE_URL如果你用 OpenAI 兼容的接口就填对应的我用的是本地 Ollama所以 base url 填http://host.docker.internal:11434/v1key 随便填一个非空值。Embedding 模型我一开始想用本地的 bge-large但发现显存吃紧后来换成了text-embedding-3-small的兼容接口速度快很多效果对于中文文档也够用。注意如果你用 Ollama记得在宿主机上先ollama pull好模型并且确认 Ollama 监听了0.0.0.0否则容器里访问不到。这个坑我踩过默认 Ollama 只监听 127.0.0.1容器里连不上改配置重启才行。3.2 启动服务与初始化配置配置改好后直接docker compose up -d。第一次启动会拉镜像大概需要几分钟。启动完成后用docker compose ps检查各个服务状态正常应该有weknora-api、weknora-worker、postgres、redis、minio这几个容器在跑。# 查看服务状态 docker compose ps # 查看 API 日志确认没有报错 docker compose logs -f weknora-apiAPI 默认跑在 8080 端口前端在 3000。浏览器打开http://localhost:3000应该能看到登录页。初始管理员账号在.env里配置默认是admin/admin123第一次登录后务必改掉。登录进去后第一件事是配置模型。在“系统设置”里填 LLM 和 Embedding 的连接信息。这里有个细节WeKnora 支持为不同用途配置不同模型比如问答用一个模型摘要用另一个Embedding 单独配。我建议问答用能力强的模型Embedding 用速度快的因为 Embedding 调用频率远高于问答。配置完模型后创建一个知识库。知识库的配置项不少我挑几个关键的讲切片策略默认是按固定长度切我建议改成按标题层级切尤其是技术文档这样每个切片语义更完整。切片长度默认 512 token我调到 800 左右因为中文文档信息密度高切太碎反而丢上下文。重叠长度设成切片长度的 10% 到 15%防止关键信息被切断。检索召回数默认 5我调到 10配合重排序用命中率明显提升。3.3 文档入库与检索调优文档上传支持拖拽也支持 API 批量导入。我测试了 PDF、Word、Markdown、Excel 几种格式PDF 里的表格确实能解析出来但复杂合并单元格还是会有错位这个目前没有完美方案RAGFlow 在这方面稍好一些。扫描件需要 OCRWeKnora 内置了 OCR 模块但中文识别率一般建议外接更好的 OCR 服务。文档入库后可以在“检索测试”里直接试。输入一个问题看返回的片段和相似度分数。这里有个调优技巧如果发现检索结果不相关先别急着换 Embedding 模型先检查切片。我遇到过一个问题问“退款流程是什么”检索回来的全是“退款政策”的片段但答案其实在“售后操作手册”里。原因是“售后操作手册”的切片被切得太碎关键段落被分到了两个切片里检索时都没排到前面。后来调整了切片策略把标题层级纳入切片边界判断问题就解决了。重排序模型也值得开。WeKnora 支持配置 rerank 模型我用的是 bge-reranker-base加上之后 Top3 命中率大概提升了 15% 左右。代价是每次检索多几百毫秒对于问答场景可以接受。3.4 Agent 配置与沙箱联动Agent 的配置是 WeKnora 最有意思的部分。在“Agent 管理”里新建一个 Agent可以给它挂载多个知识库配置系统提示词选择推理策略。推理策略有几种模式简单问答、多步推理、工具调用。我主要用多步推理加工具调用。工具调用的配置需要和沙箱配合。比如我配了一个“查询订单状态”的工具Agent 检索到相关文档后会生成一段调用代码这段代码在沙箱里执行。沙箱的配置在.env里可以设置超时时间、内存限制、网络白名单。# docker-compose.yml 里沙箱相关配置片段 sandbox: image: weknora/sandbox:latest environment: - SANDBOX_TIMEOUT30 - SANDBOX_MEMORY_LIMIT512m - SANDBOX_NETWORK_WHITELISTapi.example.com networks: - sandbox-net注意沙箱的网络白名单一定要配否则 Agent 生成的代码可能访问任意地址虽然沙箱有隔离但能限制还是限制。另外超时时间别设太长30 秒足够大多数操作设太长容易卡住。我实测了一个场景问“帮我查一下订单 12345 的退款进度”Agent 先检索知识库找到退款查询的 API 文档然后生成调用代码在沙箱里执行返回模拟结果。整个过程大概 5 到 8 秒其中沙箱执行占 2 秒左右。这个链路跑通后知识库就不只是“回答问题”而是“执行任务”了。4. 常见问题与排查技巧实录4.1 部署阶段的高频报错问题一容器启动后 API 一直重启。最常见的原因是数据库连不上。检查docker compose logs weknora-api如果看到connection refused大概率是 Postgres 还没初始化完。等一两分钟再试或者手动docker compose restart weknora-api。如果还不行检查.env里的数据库密码和docker-compose.yml里的是否一致。问题二上传文档后一直显示“处理中”。这是 worker 容器的问题。docker compose logs weknora-worker看日志如果是内存不足被 kill 了调大 worker 的内存限制。如果是模型调用超时检查 Embedding 服务的网络连通性。我遇到过因为 Embedding 接口响应太慢导致 worker 卡死的情况后来换了个更快的 Embedding 服务就好了。问题三检索结果为空。先确认文档是否真的入库成功在“文档管理”里看状态。如果状态是“已完成”但检索不到检查 Embedding 模型是否一致——入库时用的模型和检索时用的模型必须相同否则向量空间不对齐相似度计算全是乱的。这个坑很隐蔽因为系统不会报错只是默默返回空结果。4.2 检索效果差的排查思路检索效果差是问得最多的问题。我整理了一个排查顺序按这个顺序走基本能定位到原因排查项检查方法常见问题切片质量在文档详情里看切片内容切片太碎或太长语义不完整Embedding 一致性确认入库和检索用同一模型模型不一致导致向量空间错位召回数量调大召回数看是否改善召回太少正确答案没进候选重排序开启 rerank 对比效果未开启导致排序不准查询改写看 Agent 是否改写了查询原始查询太短或歧义知识库范围确认问题对应的知识库已挂载答案在另一个知识库里我踩过最坑的一个问题是知识库里有一份 PDF 是扫描件OCR 出来的文字错别字很多导致检索时关键词匹配不上。后来把这份文档重新用更好的 OCR 处理了一遍问题才解决。所以文档入库前的质量检查很重要别什么都往里塞。4.3 Agent 与沙箱的典型故障Agent 不调用工具只返回文本答案。这种情况通常是系统提示词没写清楚。Agent 需要明确的指令才会调用工具比如“你必须先检索知识库如果找到相关 API 文档则生成调用代码并在沙箱执行”。提示词里要明确工具的使用条件和步骤否则模型会偷懒。沙箱执行超时。先看沙箱日志如果是代码本身死循环那没辙只能优化代码。如果是网络请求慢检查白名单是否配了目标地址。我遇到过沙箱里 DNS 解析失败的情况原因是沙箱容器的 DNS 配置没继承宿主机的后来在docker-compose.yml里显式指定了 DNS 才解决。Agent 返回的结果和知识库内容不一致。这通常是 Agent 在生成答案时“自由发挥”了。解决办法是在提示词里强调“答案必须基于检索到的内容如果检索不到就明确说不知道”。另外可以调低模型的 temperature减少随机性。4.4 性能与并发方面的经验WeKnora 的并发能力取决于几个环节API 层、检索层、模型调用层。API 层是无状态的可以水平扩展。检索层依赖向量数据库Postgres 的 pgvector 在数据量大了之后性能会下降建议超过百万级向量就换 Milvus 或 Qdrant。模型调用层是最大的瓶颈尤其是用本地模型时并发一高就排队。我实测下来单张 3060 跑 7B 的模型并发 5 左右就比较吃力了。如果要做生产部署建议 LLM 和 Embedding 都用外部 API或者上多卡。沙箱的并发也要注意每个沙箱实例占资源默认配置下同时跑 10 个沙箱实例内存就吃紧了需要根据机器配置调整。提示如果并发要求高可以把沙箱改成按需创建、用完即毁的模式虽然冷启动有开销但资源利用率更高。WeKnora 支持配置沙箱池的大小这个参数在.env里叫SANDBOX_POOL_SIZE默认是 5可以按机器配置调。5. 一些个人体会和后续可折腾的方向用了这段时间我对 WeKnora 的整体感受是它不是一个开箱即用的产品而是一个需要调优的框架。官方给的默认配置能跑通但效果离“好用”还有距离。切片策略、检索参数、Agent 提示词这些都需要根据你的文档特点和业务场景去磨。磨好了效果确实比通用方案好一截不磨可能还不如直接用关键词搜索。另外WeKnora 和 Obsidian 的结合是个有意思的方向。有人把 Obsidian 的笔记库通过 API 同步到 WeKnora然后用 Agent 做笔记问答和关联推荐。我试了一下对于结构化的 Markdown 笔记效果不错因为 Markdown 的标题层级天然适合做切片边界。如果你有大量 Obsidian 笔记可以试试这个路子。后续我打算折腾两个方向一是把 GraphRAG 的思路接进来用知识图谱增强实体关系的检索二是把沙箱的能力扩展到更多工具比如数据库查询、文件操作让 Agent 真正能“动手做事”。这两个方向都有坑等踩完了再写。