1. 为什么我盯上了 WeKnora 这个项目第一次看到 WeKnora 这个名字是在一个做企业知识管理的群里。有人甩了张截图说腾讯微信团队开源了一个 RAG 知识库项目支持 Agent 和代码沙箱部署完能直接对接自己的文档做问答。我当时的第一反应是又一个套壳 RAG毕竟这两年 RAG 项目满天飞从 LangChain 到 RAGFlow 再到 Dify能打的没几个能落地的更少。但仔细扒了一圈之后我发现 WeKnora 的定位跟市面上大多数 RAG 项目不太一样。它不是那种给你一堆组件自己拼的框架也不是开箱即用但改不动的 SaaS 产品。它更像是一个面向企业级场景的完整知识库解决方案把文档解析、向量检索、Agent 编排、代码沙箱执行这几块都做进去了而且代码是开源的可以自己部署、自己改。这就很有意思了。因为做过 RAG 落地的人都知道真正难的不是把向量库跑起来而是文档解析的准确率、检索的命中率、以及多轮对话中 Agent 的稳定性。WeKnora 在这几个点上都有针对性的设计尤其是它内置的 Agent 沙箱机制解决了很多 RAG 项目只能问答、不能执行的痛点。这篇文章我会从实际部署和使用的角度把 WeKnora 的核心架构、部署流程、检索优化、Agent 编排、沙箱机制、常见坑点全部拆一遍。不管你是刚接触 RAG 的新手还是已经在做企业知识库的老手应该都能从里面找到能直接抄作业的东西。2. WeKnora 到底解决了什么问题2.1 传统 RAG 的三个死穴在聊 WeKnora 之前得先说清楚传统 RAG 到底卡在哪。我做过好几个企业知识库项目踩过的坑基本集中在三个地方。第一个是文档解析。企业里的文档格式五花八门PDF、Word、Excel、PPT、扫描件、甚至图片里的文字。很多 RAG 项目用个 PyPDF2 就完事了结果表格解析出来全是乱的扫描件直接读不出内容。检索的时候命中率低得可怜用户问一个问题召回的片段驴唇不对马嘴。第二个是检索策略。纯向量检索有个天然缺陷它对关键词的精确匹配能力很弱。比如用户问XX 系统的登录接口超时时间是多少向量检索可能召回一堆讲系统登录的文档但就是找不到那个具体的超时时间参数。这时候就需要混合检索——向量加关键词再配合重排序。第三个是Agent 能力。传统 RAG 只能检索生成用户问什么它答什么。但实际业务场景里用户往往需要的是帮我查一下上个月的销售数据然后算个同比增长率。这就需要 Agent 能调用工具、能执行代码、能多步推理。而大多数 RAG 项目在这一块是缺失的或者只是简单接了个 Function Calling 就完事了。2.2 WeKnora 的差异化设计WeKnora 在这三个点上都有对应的解法。文档解析这块它内置了多种解析器支持 PDF、Word、Markdown、HTML 等格式对表格和结构化内容有专门的处理。检索这块它用的是混合检索加重排序的方案向量检索和关键词检索并行然后用一个重排序模型做精排。Agent 这块是 WeKnora 最有意思的地方。它内置了一个代码沙箱Agent 可以在沙箱里执行 Python 代码、调用外部 API、处理数据。这意味着它不只能回答问题还能真正做事。比如你问它帮我分析一下这份 CSV 里的销售趋势它可以自己写代码读取文件、做统计分析、生成图表描述。还有一个容易被忽略的点WeKnora 是腾讯微信团队出品的。这个背景意味着它在工程化程度上是有保障的不是那种个人开发者随手写的玩具项目。代码结构、文档质量、更新频率都相对靠谱。2.3 适合谁用WeKnora 不是那种五分钟跑起来的玩具。它更适合以下几类人企业知识库开发者需要给内部员工做一个能查文档、能问答、能执行简单任务的系统。RAG 进阶学习者已经玩过 LangChain 的基础 RAG想看看工业级项目是怎么做的。Agent 应用开发者对 Agent 编排和沙箱执行感兴趣想找一个可参考的开源实现。技术选型负责人在 Dify、RAGFlow、WeKnora 之间做比较需要了解各自的优劣。如果你只是想快速搭一个个人用的问答机器人WeKnora 可能有点重。但如果你要做的是企业级、需要长期维护、需要 Agent 能力的知识库那它值得认真研究。3. 核心架构拆解从文档到答案的完整链路3.1 整体架构分层WeKnora 的架构可以分成四层来看从下往上依次是存储层负责文档存储和向量存储。文档原文存在对象存储或本地文件系统向量存在向量数据库里。WeKnora 支持多种向量库后端包括 Milvus、Qdrant 等可以根据数据量级选择。检索层这是 RAG 的核心。WeKnora 在这一层做了混合检索向量检索负责语义匹配关键词检索负责精确匹配两路结果合并后用重排序模型精排。重排序模型的选择很关键它直接决定了最终召回片段的质量。编排层负责把检索结果和用户问题组装成 Prompt调用 LLM 生成答案。如果是 Agent 模式这一层还要负责工具调用、多步推理、沙箱执行。应用层对外提供 API 和 Web 界面支持多租户、权限管理、对话历史等。这个分层设计的好处是每一层都可以独立替换。比如你觉得默认的向量库不够快可以换成自己熟悉的觉得重排序模型效果不好可以换一个更强的。这种灵活性在企业场景里很重要因为不同公司的技术栈和需求差异很大。3.2 文档解析的关键细节文档解析是 RAG 的第一道关卡也是最容易被低估的环节。我见过太多项目向量库选得挺好LLM 也用得挺强但就是因为文档解析没做好整个系统效果拉胯。WeKnora 在文档解析上做了几件事值得说。首先是分块策略。它不是简单地按固定字数切分而是根据文档结构来切。比如 Markdown 按标题层级切PDF 按段落和表格切。这样切出来的块语义更完整检索时召回的内容更精准。其次是表格处理。企业文档里表格特别多财务数据、产品参数、人员名单都是表格。普通解析器把表格读成一堆乱码WeKnora 会把表格转成结构化的文本描述比如表格包含三列产品名称、价格、库存数量第一行数据是...。这样 LLM 能理解表格内容回答相关问题时不会瞎编。还有一个细节是元数据保留。每个文档块都会带上来源文件、页码、章节标题等元数据。检索的时候可以根据元数据做过滤比如只搜某个部门的文档或者只搜最近半年的文档。这个功能在实际使用中非常实用但很多 RAG 项目都忽略了。3.3 混合检索与重排序检索这块我想多聊几句因为这是 RAG 效果的分水岭。纯向量检索的问题在于它把文本映射到一个高维空间语义相近的文本距离近。但语义相近和能回答问题是两回事。用户问报销流程是什么向量检索可能召回一堆讲报销制度报销标准的文档但真正讲流程步骤的那段可能排在后面。WeKnora 的混合检索把向量检索和关键词检索的结果合并。关键词检索用的是 BM25 或类似的算法对精确匹配很敏感。两路结果合并后再用一个重排序模型通常是 Cross-Encoder 架构对每个候选片段和问题的相关性打分按分数排序。这个流程听起来简单但实际调优有很多讲究。比如两路检索的权重怎么分配召回多少条候选重排序模型选哪个都会影响最终效果。我的经验是召回阶段宁多勿少先召回 50 到 100 条候选再让重排序模型精排到 5 到 10 条。这样既保证了召回率又不会让 LLM 处理太多无关内容。3.4 Agent 编排与沙箱机制Agent 是 WeKnora 区别于普通 RAG 的核心能力。它的 Agent 编排支持多步推理可以调用工具、执行代码、访问外部 API。沙箱机制是这里的关键。Agent 生成的代码不会直接在服务器上执行而是在一个隔离的沙箱环境里跑。这个沙箱限制了代码能访问的资源比如不能读敏感文件、不能发起网络请求除非白名单、有执行时间限制。这样即使 Agent 生成了恶意代码也不会对系统造成危害。沙箱的实现方式通常有两种一种是基于容器比如 Docker的隔离每个执行任务起一个容器跑完就销毁另一种是基于进程的隔离用 seccomp 或类似机制限制系统调用。WeKnora 具体用哪种可以看它的源码实现。但不管哪种核心思路都是最小权限原则——只给代码必要的权限多一点都不给。这个设计在企业场景里特别重要。因为企业知识库往往连接着内部系统如果 Agent 能随意执行代码、访问内部 API安全风险很大。有了沙箱至少能把风险控制在一个可接受的范围内。4. 部署实操从零到跑通的完整流程4.1 环境准备与依赖检查WeKnora 的部署方式有几种Docker Compose 一键部署、源码部署、Kubernetes 部署。对于大多数场景Docker Compose 是最省事的。我下面以 Docker Compose 为例把整个流程走一遍。先说环境要求。WeKnora 对硬件的要求取决于你的数据量级和模型选择。如果只是测试8 核 16G 的机器够了。如果要上生产建议 16 核 32G 起步向量库和 LLM 分开部署。软件依赖主要是 Docker 和 Docker Compose。版本上Docker 建议 20.10 以上Compose 建议 v2 以上。另外需要确认服务器的网络能拉取镜像如果在内网环境需要提前把镜像拉下来传到内网仓库。# 检查 Docker 版本 docker --version docker compose version # 检查系统资源 free -h df -h nproc这几条命令跑一下确认环境没问题再往下走。我踩过的坑是磁盘空间不足向量库写数据写到一半报错排查了半天才发现是磁盘满了。所以部署前一定先看df -h。4.2 Docker Compose 部署步骤WeKnora 的仓库里通常会有docker-compose.yml文件。拉下来之后先看一下里面的服务定义了解它启动了哪些组件。git clone weknora-repo-url cd weknora cat docker-compose.yml典型的 Compose 文件会包含这几个服务WeKnora 主服务、向量数据库、关系型数据库存元数据和对话历史、Redis缓存、以及可选的 LLM 服务。启动之前需要配置环境变量。通常会有一个.env.example文件复制成.env然后改里面的配置。cp .env.example .env vim .env需要重点关注的配置项LLM 配置API Key、模型名称、Base URL。如果用的是本地模型比如 OllamaBase URL 指向本地地址。向量库配置连接地址、端口、集合名称。数据库配置连接字符串、用户名密码。沙箱配置是否启用、资源限制、超时时间。配置改好之后直接启动docker compose up -d然后看日志确认服务是否正常docker compose logs -f weknora如果看到服务启动成功的日志就可以访问 Web 界面了。默认端口通常是 8080 或 3000具体看配置。4.3 模型接入本地模型 vs 云端 APIWeKnora 支持多种 LLM 接入方式这是它比较灵活的地方。云端 API 方式配置最简单填个 API Key 就能用。适合快速验证和中小规模场景。缺点是数据要传到云端如果文档涉及敏感信息需要评估合规风险。另外就是成本大规模使用的话 API 费用不低。本地模型方式用 Ollama 或 vLLM 在本地跑模型。数据不出内网安全性高长期成本低。缺点是需要 GPU 资源部署和维护复杂度高。7B 到 14B 的模型在消费级显卡上能跑但效果和 GPT-4 级别的模型有差距。我的建议是混合使用检索和重排序用本地小模型这些任务对模型能力要求不高生成答案用云端大模型这个对效果影响最大。这样既控制了成本又保证了效果。配置本地模型的时候注意 Ollama 的默认端口是 11434vLLM 通常是 8000。在 WeKnora 的配置里填对地址就行。# Ollama 拉取模型示例 ollama pull qwen2.5:7b ollama pull bge-m3 # 测试模型是否可用 curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: 你好 }4.4 知识库初始化与文档导入服务跑起来之后第一件事是创建知识库。在 Web 界面里点新建知识库填名称和描述。然后就是导入文档。WeKnora 支持多种导入方式本地上传、URL 导入、API 批量导入。对于企业场景API 批量导入最实用可以写个脚本把内部文档系统的内容同步过来。导入文档的时候有几个参数需要注意分块大小默认可能是 512 或 1024 个 token。文档结构复杂的话建议调小一点比如 256这样每个块语义更聚焦。分块重叠相邻块之间的重叠 token 数通常设成分块大小的 10% 到 20%。这个参数是为了避免关键信息被切在块边界上。解析器选择根据文档类型选对应的解析器。PDF 选 PDF 解析器Markdown 选 Markdown 解析器。导入完成后系统会自动做向量化。这个过程的时间取决于文档数量和模型速度。几千页文档的话用本地模型可能要跑几个小时。提示导入大量文档时建议分批导入每批几百个文件。一次性导入太多容易导致内存溢出或向量库写入超时。4.5 验证部署是否成功部署完成后怎么确认系统真的能用了我一般会做几个测试。第一个是基础问答测试。问一个文档里明确写了答案的问题看能不能正确回答并且引用来源正确。第二个是边界测试。问一个文档里没有的问题看它是老实说不知道还是瞎编。RAG 系统最怕的就是幻觉如果它开始编答案说明检索或 Prompt 有问题。第三个是多轮对话测试。连续问几个相关的问题看它能不能记住上下文。比如先问XX 产品的价格是多少再问那它的保修期呢看它能不能理解它指的是什么。第四个是Agent 能力测试。如果启用了 Agent问一个需要计算或多步推理的问题比如帮我算一下文档里提到的三个项目的总预算看它能不能正确调用工具完成任务。这几个测试都过了基本可以确认部署成功。5. 检索效果调优让命中率从 60% 提到 90%5.1 影响检索命中率的关键因素检索命中率是 RAG 系统的生命线。命中率低后面 LLM 再强也白搭。我总结了一下影响命中率的因素主要有这么几个分块质量块切得不好关键信息被切碎或者混在一起检索自然不准。这是最基础也最重要的一环。向量模型选择不同的 Embedding 模型在不同语言和领域上的表现差异很大。中文场景下BGE 系列、M3E 系列表现不错。英文场景下OpenAI 的 text-embedding-3 系列很强。选模型的时候要看你的文档语言和领域。检索策略纯向量、纯关键词、还是混合检索效果差别很大。大多数场景下混合检索最优。重排序模型重排序是提升命中率的利器。一个好的重排序模型能把正确片段从第 20 名提到第 1 名。查询改写用户的问题往往很口语化跟文档的表述方式不一样。查询改写能把用户问题转成更适合检索的形式。5.2 分块策略的实战调整分块这件事没有万能参数得根据文档特点来调。我一般会按这个流程走先看文档的平均段落长度。如果段落普遍很短比如 FAQ 文档分块可以小一点256 token 左右。如果段落很长比如技术文档分块可以大一点512 到 1024 token。然后看文档的结构化程度。如果文档有清晰的标题层级按标题切分效果最好。WeKnora 支持按 Markdown 标题切分这个功能要用起来。最后做 A/B 测试。用同一批问题分别用不同的分块参数跑一遍看哪个命中率高。这个测试不用太复杂准备 20 到 30 个典型问题就够了。我实测下来对于大多数企业文档分块大小 512 token、重叠 64 token是一个比较稳的起点。然后根据测试结果微调。5.3 混合检索的权重调优WeKnora 的混合检索允许调整向量检索和关键词检索的权重。这个权重怎么设取决于你的查询特点。如果用户查询偏口语化、语义化比如怎么报销向量检索权重要高一些。如果用户查询偏精确比如XX-2024-001 号文件的第三条关键词检索权重要高一些。我的经验是默认 7:3 或 6:4向量:关键词比较平衡。然后根据实际查询日志调整。如果发现很多查询是精确匹配类的就把关键词权重提上去。还有一个技巧是动态权重。根据查询的长度和特征自动调整权重。短查询、包含数字或专有名词的查询提高关键词权重长查询、自然语言问句提高向量权重。WeKnora 是否支持动态权重可以看它的配置项。5.4 重排序模型的选型与部署重排序模型是提升命中率的最后一道关卡。常用的重排序模型有 BGE-Reranker、Cohere Rerank、以及一些基于 Cross-Encoder 的开源模型。选型的时候考虑几个因素效果、速度、资源占用。BGE-Reranker 系列在中文场景下效果不错而且有不同大小的版本可以根据资源情况选。Cohere Rerank 效果很好但是要调 API有成本。部署重排序模型的时候注意它和 Embedding 模型是分开的。Embedding 模型负责把文本转成向量重排序模型负责给问题-片段对打分。两个模型的输入输出格式不一样配置的时候别搞混。# 重排序调用示例伪代码 from reranker import Reranker reranker Reranker(model_namebge-reranker-large) query 报销流程是什么 candidates [片段1内容, 片段2内容, 片段3内容] scores reranker.compute_scores(query, candidates) ranked sorted(zip(candidates, scores), keylambda x: x[1], reverseTrue) top_k ranked[:5]重排序的计算量比向量检索大因为它要对每个候选片段做一次完整的模型推理。所以召回阶段不要召回太多50 到 100 条就够了。召回太多会导致重排序成为瓶颈。5.5 查询改写的实用技巧查询改写是我觉得最被低估的优化手段。用户问这个怎么弄直接拿去检索效果肯定差。但如果改写成XX 功能的操作步骤命中率会高很多。WeKnora 是否内置查询改写可以看它的功能列表。如果没有可以自己加一个预处理步骤用 LLM 把用户问题改写成更适合检索的形式。改写的策略有几种扩展把简短的问题扩展成完整的问句。比如报销改成公司的报销流程和所需材料是什么。分解把复杂问题拆成多个子问题。比如XX 和 YY 的区别以及各自的价格拆成XX 的特点、YY 的特点、XX 的价格、YY 的价格。同义替换把口语化表达替换成文档里的正式表达。比如咋弄改成如何操作。改写会增加一次 LLM 调用有延迟和成本。所以不是所有查询都需要改写。可以设置一个规则比如查询长度小于 10 个字才触发改写。6. Agent 与沙箱让知识库从能答到能做6.1 Agent 编排的核心逻辑WeKnora 的 Agent 能力是它区别于普通 RAG 的关键。普通 RAG 的流程是检索→生成Agent 的流程是理解意图→规划步骤→调用工具→执行→生成答案。这个流程的核心是工具调用。Agent 需要知道有哪些工具可用每个工具是干什么的什么时候该调用哪个。WeKnora 的工具注册机制通常是这样的定义一个工具的描述名称、功能、参数Agent 根据用户问题决定是否调用。举个例子用户问帮我查一下上个月的销售数据并算个同比增长。Agent 的推理过程是识别意图需要查询数据 计算调用数据查询工具获取上个月和去年同期的销售数据调用代码执行工具计算同比增长率整合结果生成自然语言回答这个过程涉及多步推理和工具编排。WeKnora 的 Agent 编排引擎负责管理这个流程包括工具选择、参数填充、结果传递、错误处理。6.2 代码沙箱的实现原理沙箱是 Agent 执行代码的安全保障。没有沙箱Agent 生成的代码直接在服务器上跑风险极大。有了沙箱代码被限制在一个隔离环境里即使有问题也不会影响主系统。沙箱的实现通常涉及几个层面的隔离文件系统隔离沙箱里的代码只能访问特定的目录不能读系统文件或其他用户的数据。网络隔离默认禁止网络访问或者只允许访问白名单里的地址。这是为了防止 Agent 把数据外传。资源限制限制 CPU 时间、内存使用、磁盘空间。防止代码跑飞了把服务器拖垮。系统调用限制用 seccomp 或类似机制限制代码能调用的系统调用。比如禁止 fork、exec 等危险操作。WeKnora 的沙箱具体怎么实现的可以看它的源码。但不管实现细节如何使用的时候要注意配置好资源限制。我见过有人没设超时Agent 写了个死循环把服务器 CPU 跑满了。6.3 工具注册与调用实战给 WeKnora 的 Agent 添加自定义工具通常需要写一个工具定义文件。工具定义包括名称、描述、参数 schema、以及执行函数。# 工具定义示例 tool_definition { name: query_sales_data, description: 查询指定时间范围的销售数据, parameters: { type: object, properties: { start_date: { type: string, description: 开始日期格式 YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式 YYYY-MM-DD } }, required: [start_date, end_date] } } def query_sales_data(start_date, end_date): # 实际查询逻辑 return results工具描述写得好不好直接影响 Agent 的调用准确率。描述要清晰说明工具的功能、适用场景、参数含义。参数描述要具体比如日期格式要写清楚。还有一个技巧是给工具起个好名字。名字要能反映功能让 Agent 一看就知道什么时候该用。比如calculate_growth_rate比calc好search_customer_info比query好。6.4 沙箱安全配置要点沙箱配置的核心是最小权限。只给代码必要的权限多一点都不给。具体配置项包括超时时间单次执行最长多久。建议 30 秒到 2 分钟看任务复杂度。内存限制最多用多少内存。建议 256MB 到 1GB。CPU 限制最多用几个核。建议 1 到 2 个。网络访问默认关闭需要时开白名单。文件访问只允许访问指定的临时目录。这些配置在 WeKnora 的配置文件里应该都有对应的项。部署的时候一定要检查一遍别用默认值上生产。注意沙箱不是万能的。它主要防的是意外和低级攻击对于高级的逃逸攻击防护能力有限。所以沙箱里不要放敏感数据也不要给太高的权限。7. 常见问题与排查实录7.1 部署阶段的高频问题问题一Docker Compose 启动后服务不断重启这个通常是因为配置错误或依赖服务没起来。排查步骤先看日志docker compose logs service找到报错信息。常见原因包括数据库连接失败、端口被占用、环境变量缺失。问题二向量库连接超时向量库启动比较慢主服务可能在向量库还没就绪的时候就尝试连接。解决办法是配置健康检查或者调整启动顺序。Compose 文件里可以用depends_on加healthcheck来控制。问题三模型调用返回 401 或 403API Key 配置错误或者 Base URL 不对。检查.env文件里的配置确认 Key 没有多余空格URL 没有拼写错误。问题四文档导入卡住不动大文件解析可能很慢尤其是 PDF 里的图片和表格。可以先导入小文件测试确认流程通了再导大文件。另外检查磁盘空间和内存是否充足。7.2 检索效果差的排查思路检索效果差是最常见的问题排查起来要有条理。第一步确认文档解析是否正确。在系统里查看解析后的文档块看内容是否完整、格式是否正常。如果解析出来是乱码那检索肯定不准。第二步测试向量检索是否正常。用一个文档里明确有的句子去搜看能不能搜到对应的块。如果搜不到说明向量化或索引有问题。第三步检查重排序是否生效。对比重排序前后的排序结果看正确片段的位置有没有提升。如果重排序没效果可能是模型配置有问题。第四步分析查询和文档的表述差异。用户查询和文档表述差异太大检索效果会差。这时候需要查询改写或者扩充同义词。7.3 Agent 执行失败的典型原因Agent 执行失败通常有几个原因工具调用参数错误Agent 填的参数格式不对导致工具执行失败。解决办法是优化工具的参数描述或者在工具执行函数里加参数校验和容错。沙箱超时代码执行时间超过限制。可以调大超时时间或者优化代码逻辑。依赖缺失沙箱环境里没有代码需要的库。需要在沙箱镜像里预装常用库或者允许动态安装。权限不足代码尝试访问没有权限的资源。检查沙箱配置确认权限设置是否合理。7.4 性能瓶颈的定位与优化WeKnora 的性能瓶颈通常出现在几个地方瓶颈位置表现优化方向文档解析导入慢CPU 高增加解析并发用更快的解析器向量化导入慢GPU 高用更小的模型或增加 GPU向量检索查询慢优化索引参数增加副本重排序查询慢用更小的重排序模型减少召回数量LLM 生成响应慢用更快的模型或流式输出沙箱执行Agent 响应慢优化代码增加资源限制定位瓶颈的方法是看监控指标。WeKnora 应该会暴露一些 Prometheus 指标或者至少能在日志里看到各阶段的耗时。找到最耗时的环节针对性优化。7.5 常见问题速查表问题现象可能原因排查方法解决方案服务启动失败配置错误/端口占用看日志修正配置/换端口文档导入失败格式不支持/文件损坏看导入日志转换格式/修复文件检索结果不相关分块差/模型不匹配查看解析结果调整分块/换模型回答有幻觉检索没召回/提示词差看召回片段优化检索/改提示词Agent 不调用工具工具描述不清看 Agent 日志优化工具描述沙箱执行超时代码效率低/限制太严看执行日志优化代码/调限制响应速度慢模型慢/资源不足看监控指标换模型/加资源8. 我踩过的坑和几条实在建议部署和使用 WeKnora 的过程中我踩了不少坑这里挑几个有代表性的说说。第一个坑是低估了文档解析的复杂度。一开始我觉得解析嘛不就是读文件提取文本。结果实际跑起来PDF 里的表格全乱了扫描件直接读不出。后来才发现文档解析是个专门的领域需要针对不同格式做不同处理。WeKnora 内置的解析器已经覆盖了大部分场景但特殊格式还是需要自己写解析器。第二个坑是向量模型选错了。一开始图省事用了个英文为主的 Embedding 模型结果中文检索效果很差。换成 BGE 的中文模型之后命中率明显提升。这个教训是模型选择要匹配数据语言和领域不能随便用一个就完事。第三个坑是沙箱配置太宽松。测试的时候为了方便把沙箱的超时和内存限制都设得很大。结果有一次 Agent 写了个死循环把服务器 CPU 跑满了影响了其他服务。后来把限制调严了虽然偶尔会有任务超时但至少不会影响主系统。几条实在建议从小规模开始。别一上来就导入几万篇文档先用几百篇跑通流程确认效果没问题再扩大规模。建立评估集。准备一批典型问题和标准答案每次调整参数后跑一遍评估看效果是提升还是下降。没有评估集调优就是盲人摸象。监控要跟上。部署完不是结束要监控服务的各项指标。响应时间、错误率、资源使用率这些都要盯着。出了问题能第一时间发现。日志要详细。排查问题全靠日志。确保关键环节都有日志输出包括检索召回了哪些片段、重排序的分数、Agent 调用了哪些工具。日志越详细排查越快。版本要锁定。WeKnora 还在快速迭代不同版本之间可能有 breaking change。生产环境要锁定版本升级前先在测试环境验证。备份要定期。向量库和数据库的数据要定期备份。万一出问题能快速恢复。最后说一个我觉得很重要的点RAG 系统的效果是系统工程不是单点优化。文档解析、分块、向量化、检索、重排序、Prompt、LLM每个环节都影响最终效果。不要指望换个模型就能解决所有问题要系统性地看整个链路找到真正的瓶颈在哪里。我在实际项目中的体会是把 80% 的精力花在文档解析和检索优化上比花在换 LLM 上收益大得多。因为 LLM 再强如果检索召回的内容不对它也答不对。反过来如果检索召回的内容精准即使 LLM 弱一点答案质量也不会太差。这个内容后续还可以这样扩展一是接入更多数据源比如 Confluence、Notion、企业微信文档二是做多模态检索支持图片和表格的语义搜索三是优化 Agent 的工具生态接入更多内部系统。这些方向都有实际需求值得深入做。