企业官网建设流程全解析

1. 这个项目到底解决了什么问题

微信把 WeKnora 开源出来的消息，我是在一个做企业知识管理的群里看到的。当时群里第一反应是“微信居然做开源知识库了”，第二反应是“RAG 这块又要卷起来了”。我花了两天时间把仓库拉下来、在本地跑通、又拿几份真实文档做了检索测试，下面把整个过程和踩到的坑完整记录一遍。

WeKnora 是一个基于 RAG 架构的知识库问答系统，核心能力是把非结构化的文档（PDF、Word、Markdown、网页等）解析、切分、向量化之后存进检索库，用户提问时先召回相关片段，再交给大模型生成带出处的回答。它同时提供了 Agent 模式的编排能力，可以调用外部工具完成多步任务。适合谁用？三类人：一是想给自己团队搭内部知识库的开发者，二是正在学 RAG 想找一个能跑通的完整项目练手的同学，三是需要评估“自建知识库 vs 直接用云服务”的决策者。

它解决的问题很具体：过去搭一套 RAG，你得自己拼文档解析、切分策略、embedding 模型、向量库、检索重排、prompt 编排、前端界面这一整条链路，每一环都有坑。WeKnora 把这些环节做成了一个开箱即用的整体，并且因为背靠微信生态，在文档格式兼容和中文语义处理上有一些针对性的优化。这一点对中文场景特别重要，很多开源 RAG 项目默认的切分和检索策略是按英文语料调的，直接拿来处理中文合同、技术文档，召回质量会明显掉一档。

2. 整体架构与设计思路拆解

2.1 为什么是 RAG 而不是纯微调

先讲清楚一个前提：知识库问答为什么普遍选 RAG 而不是把知识微调进模型。微调的成本在于，每次知识更新都要重新训练，而且模型对训练语料里的细节记忆并不可靠，容易一本正经地胡说。RAG 的思路是把“知识存储”和“语言生成”解耦——知识放在外部检索库里，随时可增删改，模型只负责根据召回的片段组织语言。代价是检索环节一旦召回不准，回答质量直接崩。

WeKnora 走的就是这条路线，而且它把检索质量当成核心指标来做。从热词里能看到 “rag hit rate” 这个词，说明大家最关心的就是召回命中率。这个指标决定了整个系统的上限：召回都错了，后面生成再强也没用。

2.2 分层结构

我把它的结构理解成四层，这样看代码和排查问题会清晰很多：

这么分层的好处是，任何一层出问题都能单独定位。比如“解析失败”就是处理层的问题，“召回不准”是检索层的问题，两者排查方向完全不同。我后面会专门讲这两类问题的排查方法。

2.3 选型背后的取舍

文档解析这块，它需要处理多种格式，PDF 是最麻烦的——扫描件要 OCR，带复杂表格的要保留结构，多栏排版要正确排序。切分策略上，固定长度切分会切断语义，按标题层级切分又依赖文档本身结构良好。WeKnora 在这块做了混合策略，具体参数后面实操部分讲。

向量化模型的选择直接决定检索效果。中文场景下，通用多语言模型和中文专优模型的表现差异很明显。我的建议是先用项目默认配置跑通，再根据自己语料的领域特点换模型做对比测试，不要一上来就纠结模型选型，先把链路跑通更重要。

Agent 能力是这两年 RAG 项目的标配了。纯 RAG 只能回答“文档里写了什么”，Agent 模式可以做到“根据文档内容去执行一个操作”，比如查到某个数据后调用接口、或者多轮检索后再汇总。WeKnora 的 Agent 编排让它在“问答”之外多了一层“办事”的能力。

3. 本地部署实操：从零到跑通

3.1 环境准备与依赖检查

我是在 Windows 11 上部署的，这是热词里问得最多的场景。先说结论：Windows 下能跑通，但有几个前置条件必须满足。

第一是 Docker。项目依赖容器化部署，Windows 下需要装 Docker Desktop 并开启 WSL2 后端。这一步如果没开 WSL2，容器启动会报各种奇怪的错。检查方法是在 PowerShell 里执行wsl --status，确认默认版本是 2。

第二是资源。向量化和 LLM 推理都吃内存，我建议至少给 Docker 分配 8GB 内存，16GB 更稳。低于 8GB 的话，embedding 阶段容易 OOM。

第三是端口占用。默认会用到几个端口，部署前先确认没被占用：

# Windows PowerShell 检查端口占用 netstat -ano | findstr :8000 netstat -ano | findstr :5432

如果端口被占，要么改配置，要么先停掉占用进程。我踩过一次坑，本地已经跑了一个 PostgreSQL，结果容器里的数据库起不来，排查了半小时才发现是端口冲突。

3.2 拉取代码与配置

git clone <项目仓库地址> cd weknora

配置环节是新手最容易卡住的地方。核心是几个环境变量：数据库连接、向量库地址、embedding 模型路径、LLM 的 API 配置。我的建议是先把配置文件里的默认值过一遍，把明显需要改的（比如模型路径、API key）改掉，其他保持默认先跑通。

注意：配置文件里的模型路径如果是相对路径，要确认相对于哪个目录。我遇到过路径写对了但工作目录不对导致加载失败的情况，改成绝对路径最省心。

3.3 启动与验证

启动命令按项目文档走，一般是 docker compose 一把起。启动后重点看日志里这几个信号：

• 数据库连接成功
• 向量库初始化完成
• embedding 模型加载完成
• API 服务监听在预期端口

如果卡在模型加载，多半是模型文件没下全或者路径不对。如果卡在向量库初始化，检查向量库容器的健康状态。

验证是否跑通，最直接的方法是上传一份小文档然后提问。我建议第一份测试文档用结构清晰的 Markdown，不要一上来就丢扫描版 PDF，那样出问题你分不清是部署问题还是解析问题。

3.4 参数计算：切分长度怎么定

切分长度（chunk size）和重叠长度（overlap）是两个必须理解的参数。切分太短，一个完整语义被切碎，召回片段信息不全；切分太长，一个片段里混了多个主题，检索精度下降，而且塞进 LLM 上下文时浪费 token。

一个实用的估算方法：假设你的文档平均每段 200 到 400 字，chunk size 设在 500 到 800 字比较合适，overlap 设在 chunk size 的 10% 到 20%。overlap 的作用是防止关键信息正好落在切分边界上被割裂。

举个例子，如果 chunk size 是 600，overlap 是 100，那么相邻两个片段有 100 字的重叠区。这样即使一句话横跨边界，至少有一个片段能完整包含它。代价是存储和检索量增加，overlap 越大冗余越多，所以不要超过 20%。

4. 核心环节实现细节

4.1 文档解析：为什么你的文档解析失败

热词里 “weknora解析失败的原因是什么” 出现频率很高，我把常见原因整理成排查表：

我的经验是，解析失败八成出在 PDF 上。PDF 本质是“打印描述”而不是“结构化文档”，同样一段文字在不同 PDF 里的存储方式可能完全不同。带复杂表格和公式的 PDF 尤其难搞，这时候与其死磕解析器，不如先把 PDF 转成 Markdown 再上传，效果往往更好。

4.2 向量化与检索

向量化的本质是把文本映射到一个高维空间，语义相近的文本在空间里距离更近。检索时把问题也向量化，然后找距离最近的若干片段。这里有个关键点：embedding 模型必须和检索时用的是同一个，否则向量空间对不上，检索结果就是随机的。

检索策略上，纯向量检索有个弱点——对精确匹配不敏感。比如你问一个具体的编号、人名、型号，向量检索可能召回一堆语义相近但没这个编号的片段。所以成熟方案都会做混合检索：向量检索负责语义召回，关键词检索负责精确召回，两路结果合并后重排。WeKnora 在检索层做了这类优化，这也是它 hit rate 表现还不错的原因之一。

重排（rerank）是提升精度的关键一步。初筛召回比如 20 个片段，重排模型对这 20 个逐一打分，选出最相关的 3 到 5 个送给 LLM。多这一步的代价是延迟增加，但精度提升明显。如果你的场景对准确率要求高，重排不要省。

4.3 Agent 编排

Agent 模式和普通问答的区别在于“多步”和“工具”。普通问答是一问一答，Agent 可以拆解任务、调用工具、根据中间结果决定下一步。比如用户问“帮我对比 A 文档和 B 文档里的方案差异”，Agent 会先分别检索两份文档，再对比，最后汇总。

这里要注意 Agent 的失败模式。热词里有个 “agent execution terminated due to error”，这是 Agent 跑飞了的典型表现。常见原因是工具调用返回了预期外的格式，或者陷入了循环。排查时重点看 Agent 的执行日志，确认它在哪一步卡住、调用了什么工具、返回了什么。

提示：Agent 模式调试时，先把工具调用关掉，只跑纯检索问答，确认基础链路没问题再开工具。这样能把问题范围缩小。

5. 常见问题与排查技巧实录

5.1 部署类问题

容器起不来：先看日志，九成是端口冲突或资源不足。Windows 下还要确认 WSL2 正常。

模型加载失败：检查模型文件完整性，确认路径是绝对路径，确认磁盘空间够。

数据库连接失败：确认数据库容器健康，确认连接串里的主机名在容器网络里能解析。容器之间通信用服务名，不是 localhost。

5.2 检索类问题

召回不准：先确认 embedding 模型一致，再检查切分是否合理，最后考虑加混合检索和重排。

回答没有引用：检查生成阶段的 prompt 是否要求标注来源，以及检索结果是否带上了元数据。

回答答非所问：多半是召回片段和问题不相关，回到检索层排查，不要只盯着 LLM。

5.3 性能类问题

响应慢：拆解耗时分布，是检索慢还是生成慢。检索慢优化索引，生成慢考虑换更小的模型或减少上下文长度。

并发上不去：检查向量库和 LLM 的并发配置，很多默认配置是单请求优化的，并发场景要调。

5.4 我的避坑心得

第一条，永远先用小文档、简单格式跑通全链路，再上真实语料。我见过太多人一上来就丢几百页 PDF，然后卡在解析环节，根本分不清是部署问题还是数据问题。

第二条，把每次配置改动记下来。RAG 系统参数多，改着改着就忘了哪个参数是什么值，出问题回溯很痛苦。

第三条，评估检索质量要单独做。准备一批“问题-标准答案”对，只看检索环节召回了什么，不要被 LLM 的流畅回答迷惑。LLM 很擅长把不相关的片段编成通顺的话，看起来像对的，其实全是错的。

6. 这套东西适合怎么用

如果你只是想快速验证一个知识库问答的想法，WeKnora 能帮你省掉搭链路的时间，直接进入调优阶段。如果你是要给团队做内部知识库，建议先小范围试点，用真实语料测召回率，达标了再推广。如果你是在学 RAG，把它当成一个完整的参考实现来读，重点看它的切分策略、检索合并和 Agent 编排这三块，这三块是 RAG 项目里最能体现工程水平的地方。

我自己用下来最大的感受是，RAG 的难点从来不在“把模型接上”，而在“让检索准”。模型能力现在都很强，真正拉开差距的是文档处理质量和检索策略。WeKnora 把这两块做成了可配置的模块，你可以按自己的语料特点去调，这比从零手写要省太多事。后续我打算拿它接一批技术文档做长期测试，重点观察不同切分参数下的 hit rate 变化，有结果再单独写一篇。