企业官网建设流程全解析

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。如果用的是本地模型（比如 Ollama），Base URL 指向本地地址。
• 向量库配置：连接地址、端口、集合名称。
• 数据库配置：连接字符串、用户名密码。
• 沙箱配置：是否启用、资源限制、超时时间。

配置改好之后，直接启动：

docker compose up -d

然后看日志确认服务是否正常：

docker compose logs -f weknora

如果看到服务启动成功的日志，就可以访问 Web 界面了。默认端口通常是 8080 或 3000，具体看配置。

4.3 模型接入：本地模型 vs 云端 API

WeKnora 支持多种 LLM 接入方式，这是它比较灵活的地方。

云端 API 方式：配置最简单，填个 API Key 就能用。适合快速验证和中小规模场景。缺点是数据要传到云端，如果文档涉及敏感信息，需要评估合规风险。另外就是成本，大规模使用的话 API 费用不低。

本地模型方式：用 Ollama 或 vLLM 在本地跑模型。数据不出内网，安全性高，长期成本低。缺点是需要 GPU 资源，部署和维护复杂度高。7B 到 14B 的模型在消费级显卡上能跑，但效果和 GPT-4 级别的模型有差距。

我的建议是混合使用：检索和重排序用本地小模型（这些任务对模型能力要求不高），生成答案用云端大模型（这个对效果影响最大）。这样既控制了成本，又保证了效果。

配置本地模型的时候，注意 Ollama 的默认端口是 11434，vLLM 通常是 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_name="bge-reranker-large") query = "报销流程是什么" candidates = ["片段1内容", "片段2内容", "片段3内容"] scores = reranker.compute_scores(query, candidates) ranked = sorted(zip(candidates, scores), key=lambda x: x[1], reverse=True) 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 的推理过程是：

1. 识别意图：需要查询数据 + 计算
2. 调用数据查询工具，获取上个月和去年同期的销售数据
3. 调用代码执行工具，计算同比增长率
4. 整合结果，生成自然语言回答

这个过程涉及多步推理和工具编排。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 或 403

API Key 配置错误，或者 Base URL 不对。检查.env文件里的配置，确认 Key 没有多余空格，URL 没有拼写错误。

问题四：文档导入卡住不动

大文件解析可能很慢，尤其是 PDF 里的图片和表格。可以先导入小文件测试，确认流程通了再导大文件。另外检查磁盘空间和内存是否充足。

7.2 检索效果差的排查思路

检索效果差是最常见的问题，排查起来要有条理。

第一步：确认文档解析是否正确。在系统里查看解析后的文档块，看内容是否完整、格式是否正常。如果解析出来是乱码，那检索肯定不准。

第二步：测试向量检索是否正常。用一个文档里明确有的句子去搜，看能不能搜到对应的块。如果搜不到，说明向量化或索引有问题。

第三步：检查重排序是否生效。对比重排序前后的排序结果，看正确片段的位置有没有提升。如果重排序没效果，可能是模型配置有问题。

第四步：分析查询和文档的表述差异。用户查询和文档表述差异太大，检索效果会差。这时候需要查询改写或者扩充同义词。

7.3 Agent 执行失败的典型原因

Agent 执行失败通常有几个原因：

工具调用参数错误：Agent 填的参数格式不对，导致工具执行失败。解决办法是优化工具的参数描述，或者在工具执行函数里加参数校验和容错。

沙箱超时：代码执行时间超过限制。可以调大超时时间，或者优化代码逻辑。

依赖缺失：沙箱环境里没有代码需要的库。需要在沙箱镜像里预装常用库，或者允许动态安装。

权限不足：代码尝试访问没有权限的资源。检查沙箱配置，确认权限设置是否合理。

7.4 性能瓶颈的定位与优化

WeKnora 的性能瓶颈通常出现在几个地方：

定位瓶颈的方法是看监控指标。WeKnora 应该会暴露一些 Prometheus 指标，或者至少能在日志里看到各阶段的耗时。找到最耗时的环节，针对性优化。

7.5 常见问题速查表

8. 我踩过的坑和几条实在建议

部署和使用 WeKnora 的过程中，我踩了不少坑，这里挑几个有代表性的说说。

第一个坑是低估了文档解析的复杂度。一开始我觉得解析嘛，不就是读文件提取文本。结果实际跑起来，PDF 里的表格全乱了，扫描件直接读不出。后来才发现，文档解析是个专门的领域，需要针对不同格式做不同处理。WeKnora 内置的解析器已经覆盖了大部分场景，但特殊格式还是需要自己写解析器。

第二个坑是向量模型选错了。一开始图省事用了个英文为主的 Embedding 模型，结果中文检索效果很差。换成 BGE 的中文模型之后，命中率明显提升。这个教训是：模型选择要匹配数据语言和领域，不能随便用一个就完事。

第三个坑是沙箱配置太宽松。测试的时候为了方便，把沙箱的超时和内存限制都设得很大。结果有一次 Agent 写了个死循环，把服务器 CPU 跑满了，影响了其他服务。后来把限制调严了，虽然偶尔会有任务超时，但至少不会影响主系统。

几条实在建议：

从小规模开始。别一上来就导入几万篇文档，先用几百篇跑通流程，确认效果没问题再扩大规模。

建立评估集。准备一批典型问题和标准答案，每次调整参数后跑一遍评估，看效果是提升还是下降。没有评估集，调优就是盲人摸象。

监控要跟上。部署完不是结束，要监控服务的各项指标。响应时间、错误率、资源使用率，这些都要盯着。出了问题能第一时间发现。

日志要详细。排查问题全靠日志。确保关键环节都有日志输出，包括检索召回了哪些片段、重排序的分数、Agent 调用了哪些工具。日志越详细，排查越快。

版本要锁定。WeKnora 还在快速迭代，不同版本之间可能有 breaking change。生产环境要锁定版本，升级前先在测试环境验证。

备份要定期。向量库和数据库的数据要定期备份。万一出问题，能快速恢复。

最后说一个我觉得很重要的点：RAG 系统的效果是系统工程，不是单点优化。文档解析、分块、向量化、检索、重排序、Prompt、LLM，每个环节都影响最终效果。不要指望换个模型就能解决所有问题，要系统性地看整个链路，找到真正的瓶颈在哪里。

我在实际项目中的体会是，把 80% 的精力花在文档解析和检索优化上，比花在换 LLM 上收益大得多。因为 LLM 再强，如果检索召回的内容不对，它也答不对。反过来，如果检索召回的内容精准，即使 LLM 弱一点，答案质量也不会太差。

这个内容后续还可以这样扩展：一是接入更多数据源，比如 Confluence、Notion、企业微信文档；二是做多模态检索，支持图片和表格的语义搜索；三是优化 Agent 的工具生态，接入更多内部系统。这些方向都有实际需求，值得深入做。