企业官网建设流程全解析

微信团队这次开源的知识库项目 WeKnora，在 RAG 和 Agent 圈子里讨论度不低。我第一时间在本地拉下来跑了一遍，从环境准备到模型接入、从文档解析到检索问答，整个链路走通之后，有几个感受特别明显：一是它对中文文档的处理比很多同类项目细致，二是它把 RAG 和 Agent 的边界处理得比较清楚，三是本地部署的门槛比想象中低。这篇文章就把我从零部署到实际使用的完整过程拆开讲，包括踩过的坑、参数怎么调、和 Dify、RAGFlow 这类项目的差异在哪，以及什么场景下值得用它、什么场景下别硬上。

1. 先搞清楚 WeKnora 到底解决什么问题

1.1 它不是又一个"上传文档就能问答"的玩具

市面上打着 RAG 旗号的项目很多，但大部分停留在"把文档切块、向量化、检索、拼 prompt"这个层面。真正用起来会发现，中文 PDF 里的表格、扫描件里的文字、跨页的段落，这些才是实际知识库的常态，而很多项目在这些环节直接摆烂。WeKnora 给我的第一印象是，它在文档解析这一层下了功夫，支持多种格式的解析，对中文排版的处理明显更认真。

从定位上看，WeKnora 是一个面向知识库场景的 RAG 加 Agent 框架。RAG 负责"从知识库里找到相关内容"，Agent 负责"根据找到的内容做多步推理和工具调用"。这两件事分开看都不新鲜，但把它们整合到一个项目里，并且把配置和扩展点暴露得比较清楚，这是它的价值所在。

1.2 谁适合用，谁可以先观望

如果你手头有一批内部文档、产品手册、技术资料，想让它们变成可问答的知识库，并且对数据隐私有要求、希望本地部署，那 WeKnora 值得认真试。如果你只是想快速搭一个 demo 给老板看，那用现成的云端服务可能更快。

另外要明确一点：WeKnora 不是开箱即用的 SaaS 产品，它更像一个需要你动手配置的框架。你得准备模型服务、得理解检索参数、得会看日志排查问题。如果你期待的是"下载完双击就能用"，那可能会失望。

提示：本地部署意味着你需要自己准备算力。如果只是测试，用 CPU 跑小模型也能出效果，但速度会慢；正式使用建议至少有一张消费级显卡。

1.3 和 Dify、RAGFlow 的差异在哪

这三个项目经常被放在一起比较。我的实际感受是：Dify 更偏向应用编排和工作流，RAG 只是它的一部分能力；RAGFlow 在文档解析和检索上做得很深，但 Agent 能力相对弱一些；WeKnora 则是在 RAG 和 Agent 之间找了一个平衡点，两边都覆盖，且对中文场景的适配更主动。

这个表不是要分高下，而是帮你判断：如果你主要痛点是中文文档解析，RAGFlow 可能更合适；如果你要的是多应用、多工作流编排，Dify 更顺手；如果你想要一个 RAG 和 Agent 都覆盖、中文友好的方案，WeKnora 是个不错的选择。

2. 本地部署 WeKnora 的完整链路

2.1 环境准备：别急着 clone，先把依赖理清楚

我踩的第一个坑就是环境。WeKnora 依赖 Python 环境、向量数据库、以及模型服务。如果你用 Docker 部署，会省很多事，但前提是 Docker 和 Docker Compose 版本要够新。我建议先把这几样确认好：

• Python 3.10 或以上，低于这个版本有些依赖装不上
• Docker 24 以上，Compose v2
• 至少 16GB 内存，如果本地跑模型建议 32GB
• 磁盘预留 50GB 以上，向量库和模型缓存很占空间

模型服务这块，你可以用本地部署的推理服务，也可以接兼容 OpenAI 接口的任意服务。WeKnora 的设计是模型可替换的，这点很关键，意味着你不必绑定某一家。

2.2 拉取代码与配置：配置文件里藏着关键开关

代码拉下来之后，先别急着启动。配置文件里有几个地方必须改，否则启动会报错或者效果很差。我整理了一下我改过的关键项：

# 克隆项目 git clone <项目地址> cd weknora # 复制配置模板 cp .env.example .env

然后编辑.env，重点看这几项：

# 模型服务地址，指向你的推理服务 LLM_BASE_URL=http://localhost:8000/v1 LLM_API_KEY=your_key_here LLM_MODEL_NAME=your_model # 向量模型，检索质量的关键 EMBEDDING_MODEL=your_embedding_model EMBEDDING_DIM=1024 # 向量数据库 VECTOR_DB_TYPE=your_db_type

这里有个经验：向量模型的维度必须和向量库配置一致，否则写入会失败。我第一次就是维度对不上，报了一堆看不懂的错，排查了半天才发现是这里。

2.3 启动与验证：看到日志里这行才算成功

配置改完，用 Docker Compose 启动：

docker compose up -d

启动之后别急着访问界面，先看日志：

docker compose logs -f

当你看到类似"服务已就绪""向量库连接成功"这样的日志，才说明后端起来了。如果卡在某个依赖上，多半是模型服务地址不通或者向量库没起来。

注意：首次启动会下载模型和初始化向量库，可能要几分钟到十几分钟，取决于网络和磁盘速度。别以为卡死了就反复重启。

2.4 接入模型：本地和远程怎么选

模型接入是决定效果的核心。我的建议是：

• 测试阶段：用远程兼容接口，省去本地部署模型的麻烦，快速验证链路
• 正式使用：本地部署推理服务，数据不出内网，隐私有保障
• 嵌入模型：这个建议本地部署，因为文档量大时调用频繁，远程会有延迟和成本

嵌入模型的选择直接影响检索质量。中文场景下，选一个在中文语料上表现好的嵌入模型，比选一个参数大的通用模型更有效。我实测下来，专门针对中文优化的嵌入模型，在中文知识库上的召回率明显更高。

3. 文档解析与入库：决定知识库质量的关键一步

3.1 支持哪些格式，哪些格式要小心

WeKnora 支持常见的文档格式，包括 PDF、Word、Markdown、纯文本等。但我要提醒的是，格式支持不等于解析质量好。实际使用中：

• Markdown 和纯文本：解析最稳，几乎不会出问题
• Word 文档：一般没问题，但复杂表格可能错位
• PDF：分两种情况，文字型 PDF 解析不错，扫描型 PDF 需要 OCR，效果取决于 OCR 质量
• 图片：如果知识库需要存图片，得确认你的方案是否支持多模态

关于"RAG 知识库能不能存图片"这个问题，答案是能，但要看实现方式。纯文本 RAG 存的是图片的描述或 OCR 结果，多模态 RAG 才能直接存图片向量。WeKnora 在这块的支持程度，取决于你接入的模型是否多模态。

3.2 切块策略：切得好，检索才准

文档切块是 RAG 里最容易被忽视、但影响最大的环节。切得太大，检索出来的内容冗余，模型抓不住重点；切得太小，上下文丢失，答案不完整。

我的经验参数：

WeKnora 的切块策略可以配置，建议先用默认值跑一遍，看看检索效果，再针对性调整。别一上来就调参数，没有基准你根本不知道调好还是调坏了。

3.3 入库过程中的常见报错

入库阶段我遇到几个典型问题，列出来帮你省时间：

• 编码错误：文档里有特殊字符，导致解析失败。解决方法是先做文本清洗
• 超长文档：单个文档太大，处理超时。建议拆分后再入库
• 重复入库：同一文档多次入库，导致检索结果重复。入库前做去重
• 向量维度不匹配：前面提过，检查嵌入模型和向量库配置

提示：入库是个耗时操作，建议批量处理时加日志，记录每个文档的处理状态，出问题好定位。

4. 检索与问答：从"能用"到"好用"的调优

4.1 检索参数怎么调

检索环节的核心参数是召回数量（top_k）和相似度阈值。这两个参数直接决定喂给模型的内容质量。

• top_k 太小：可能漏掉关键信息，答案不完整
• top_k 太大：引入无关内容，干扰模型判断
• 阈值太高：召回内容太少
• 阈值太低：召回一堆不相关的

我的建议是 top_k 从 5 开始试，阈值从 0.5 开始，然后根据实际问答效果微调。如果发现答案经常缺信息，就加大 top_k；如果答案经常跑偏，就提高阈值。

4.2 重排序：提升精度的关键一招

如果 WeKnora 支持重排序（rerank），强烈建议开启。原理很简单：先用向量检索快速召回一批候选，再用重排序模型精排，把最相关的排前面。这一步对精度提升很明显，尤其是文档量大、内容相似度高的时候。

重排序模型也有中文优化的版本，选对了效果更好。代价是增加一点延迟，但换来的是答案质量提升，我觉得值。

4.3 Agent 模式：什么时候该用，什么时候别用

WeKnora 的 Agent 能力是它的亮点之一。Agent 模式适合需要多步推理、工具调用的场景，比如"先查文档，再根据结果计算，最后给出建议"这种。但如果你的需求只是简单的文档问答，用普通 RAG 模式就够了，上 Agent 反而增加复杂度和不确定性。

我的判断标准：

• 单轮问答、答案在文档里能找到：用 RAG
• 需要多步推理、需要调用外部工具：用 Agent
• 需要结合多个知识库：用 Agent 编排

Agent 的并发能力也是要考虑的。如果并发高，Agent 的多步调用会放大延迟，这时候要么加机器，要么限制并发。

5. 实际使用中的经验与坑

5.1 中文分词的坑

中文和英文不一样，英文按空格分词就行，中文需要专门的分词。如果分词没做好，检索效果会大打折扣。WeKnora 在中文处理上有考虑，但你接入的嵌入模型和检索策略也要配合。我建议在测试阶段，专门用中文长句、专业术语去测检索，看看召回是否准确。

5.2 知识库更新与增量入库

知识库不是一次性的，文档会更新。增量入库时要注意：旧文档要删除或标记失效，否则新旧内容混在一起，检索结果会矛盾。WeKnora 的文档管理功能要熟悉一下，知道怎么更新、怎么删除。

5.3 和 Obsidian 等笔记工具的配合

有人问 WeKnora 能不能和 Obsidian 配合。思路是：把 Obsidian 的 Markdown 笔记导出，入库到 WeKnora，就能对笔记做问答。这个场景挺实用，尤其是笔记量大的人。注意导出时保持 Markdown 格式，解析效果最好。

5.4 性能与并发

本地部署的性能瓶颈通常在模型推理。如果并发高，要么加显卡，要么用更小的模型，要么做请求队列。Agent 模式比 RAG 模式更吃资源，因为一次问答可能触发多次模型调用。规划容量时要把这个算进去。

6. 我的整体判断

WeKnora 是一个认真做的项目，它在中文文档处理和 RAG 加 Agent 整合上有自己的思考。它不是那种"下载即用"的产品，需要你动手配置、调优，但换来的是可控和可定制。如果你有中文知识库的需求，又希望本地部署、数据可控，它值得花时间研究。

我个人的使用体会是：先把 RAG 链路跑通、调好检索，再考虑上 Agent。很多人一上来就追求 Agent 的炫酷，结果基础检索都没做好，效果自然差。基础打牢了，Agent 才有意义。另外，嵌入模型和重排序模型的选择，对最终效果的影响比很多人想象的大，值得多花时间对比测试。