1. 从一条更新日志说起：WeKnora 到底是个什么东西

微信团队在开源社区扔出了一个叫 WeKnora 的项目，圈子里讨论度不低。我第一时间把代码拉下来跑了一遍，又翻了翻 issue 区和几个技术群的讨论，发现很多人对它的定位其实有偏差——有人把它当成“微信版 Obsidian”，有人以为是个通用 RAG 框架，还有人装完之后卡在解析失败上不知道怎么办。这篇就把我这几天的实操记录整理出来，从它解决什么问题、核心链路怎么走、到 Windows 11 下的完整部署和踩坑，一次讲清楚。

WeKnora 是微信开源的一套知识库构建与检索系统，核心能力是把非结构化文档（PDF、Word、Markdown、网页等）解析、切分、向量化，再通过 RAG（Retrieval-Augmented Generation，检索增强生成）的方式对外提供问答和检索接口。它同时带了一个 Agent 编排层，可以让模型在检索到知识之后自主决定下一步动作，也就是现在常说的 Agentic RAG 思路。适合谁看？如果你正在做企业内部知识库、文档问答、客服辅助，或者单纯想搞明白一个生产级 RAG 项目该怎么搭，这个项目值得花时间。它不是一个开箱即用的 SaaS 产品，而是一套需要你自己部署、自己接模型、自己调参数的工程骨架，这一点必须先说清楚，否则装完发现“怎么没有界面”会很懵。

我把它和市面上几个常见的 RAG 项目做了对比，WeKnora 的差异化在于两点：一是解析层做得比较扎实，对中文文档、复杂排版的兼容性明显好于很多英文优先的框架；二是它把 Agent 执行链路和检索链路做了耦合设计，不是简单地把检索结果塞进 prompt 就完事。这两点后面会展开讲。

2. 核心架构拆解：一条文档从上传到被问答的完整链路

2.1 解析层：为什么中文文档解析是第一个坎

RAG 项目翻车，十有八九翻在解析上。WeKnora 的解析层负责把各种格式的原始文档转成纯文本加结构化元数据，这一步的质量直接决定后面检索的命中率。我实测下来，它对 PDF 的处理用的是组合策略：先尝试提取文本层，如果文本层缺失或质量差（比如扫描件），再走 OCR 兜底。这个判断逻辑很关键，因为很多项目无脑走 OCR，结果对原生电子版 PDF 反而识别出一堆错字。

Word 文档走的是结构化解析，会保留标题层级、列表、表格这些信息。这一点比纯文本提取强太多——标题层级在后续切分时能作为天然的语义边界，表格则会被单独处理成结构化数据，避免被切碎后语义丢失。Markdown 和网页相对简单，但网页解析要注意正文提取，WeKnora 用的是基于密度的正文识别算法，能过滤掉导航栏、广告、页脚这些噪声。

注意：解析失败最常见的原因是文档本身加密、字体嵌入异常，或者 PDF 是纯图片扫描件但 OCR 模块没装好。遇到“weknora 解析失败”先别急着改代码，按后面第 5 节的排查表走一遍。

2.2 切分与向量化：chunk 大小不是拍脑袋定的

解析出来的长文本要切成 chunk（文本块）才能做向量化。WeKnora 默认的切分策略是递归字符切分，带重叠窗口。我一开始用的是默认参数，检索效果一般，后来调了几轮才找到比较合适的配置。这里给一个我实测的参数参考：

为什么 chunk_size 要调小？因为中文一个字符承载的信息量比英文单词大，500 个中文字符已经是一大段话了，向量化之后语义会被平均掉，检索时反而不精准。我试过 800 的块，问具体细节时经常召回一堆泛泛而谈的段落；降到 350 左右，命中率明显提升。重叠窗口的作用是防止一个完整语义被硬切断，比如一个定义跨了两个块，有重叠就能保证至少有一个块包含完整定义。

向量化模型的选择上，WeKnora 支持接多种 embedding 模型。中文场景我建议用专门针对中文优化的模型，不要直接用英文为主的通用模型，否则语义空间对不齐，检索命中率会打折扣。这块具体选哪个模型，取决于你的部署环境和算力预算，本地跑和调 API 各有取舍。

2.3 检索与 Agent 编排：Agentic RAG 到底 Agent 在哪

传统 RAG 的流程是线性的：用户提问 → 向量检索 → 拼 prompt → 模型生成。WeKnora 在检索之后加了一层 Agent 决策，模型可以判断“检索到的内容够不够回答”，不够的话可以改写查询再检索一轮，或者调用其他工具。这就是 Agentic RAG 的核心——把一次性检索变成可迭代的推理过程。

我举个实际例子。问“WeKnora 支持哪些文档格式”，第一轮检索可能只召回了 PDF 相关的段落，Agent 判断信息不完整，会自动把查询改写成“WeKnora 文档格式支持列表”，再检索一轮，把 Word、Markdown 的结果补进来，最后综合生成答案。这个迭代过程对复杂问题特别有用，代价是响应时间变长，因为多了一轮模型调用。

Agent 的执行链路是可配置的，你可以设定最大迭代次数、是否允许改写查询、是否启用工具调用。我的建议是初期把迭代次数限制在 2 次以内，否则容易陷入反复检索的死循环，既慢又费 token。等检索质量调好了再逐步放开。

3. Windows 11 下的完整部署实操

3.1 环境准备：别跳过版本检查

我在 Windows 11 上部署时，第一步就卡了半小时，原因是 Python 版本不对。WeKnora 对 Python 版本有要求，太老的版本缺依赖，太新的版本某些库还没适配。我最后用的是 3.10，比较稳。以下是完整的环境清单：

• 操作系统：Windows 11（22H2 及以上）
• Python：3.10.x（3.11 也能跑，但个别依赖需要手动处理）
• 包管理：pip 升级到最新
• 向量数据库：项目默认集成的那个，不用单独装
• 模型服务：本地模型或 API 二选一

装依赖之前先建虚拟环境，这是铁律，别往全局环境里装，否则依赖冲突会让你怀疑人生。命令如下：

python -m venv weknora_env weknora_env\Scripts\activate pip install --upgrade pip

虚拟环境激活后，命令行前面会出现(weknora_env)标识，确认一下再继续。

3.2 拉取代码与安装依赖

从开源仓库拉代码，注意选稳定分支，别直接上 main，除非你想帮忙测 bug。拉下来之后先看 README 和 requirements 文件，确认依赖清单。

git clone <仓库地址> cd weknora pip install -r requirements.txt

安装过程中如果遇到某个包编译失败，大概率是缺 C++ 编译工具。Windows 上装一下 Visual Studio Build Tools，勾选 C++ 生成工具即可。这个坑我踩过，报错信息里会提到 “Microsoft Visual C++ 14.0 or greater is required”，看到这句就去装 Build Tools，别去网上找什么预编译 wheel，版本对不上更麻烦。

3.3 模型配置：本地还是 API

WeKnora 需要两类模型：embedding 模型（做向量化）和生成模型（做问答）。两种配置方式：

方式一：全部走本地。用 Ollama 之类的本地推理服务，好处是数据不出本地，适合对隐私敏感的场景。代价是需要一定的显存，embedding 模型还好，生成模型 7B 起步的话，显存至少 8G 才比较舒服。

方式二：embedding 本地 + 生成走 API。这是我比较推荐的折中方案。embedding 模型体积小，本地跑没压力；生成模型走 API，省显存，响应也快。配置的时候在项目的配置文件里分别指定两类的服务地址和模型名。

配置文件里几个关键项要改对：模型服务地址、模型名称、API 密钥（如果用 API 的话）、向量维度（必须和 embedding 模型输出维度一致，否则检索会报维度不匹配）。向量维度这个坑很隐蔽，配错了不会立刻报错，而是检索结果全是乱的，排查起来费劲。

3.4 启动与验证

配置改完，启动服务。启动脚本一般在项目根目录，Windows 下用对应的 bat 或直接 python 命令。启动后看日志，确认几件事：向量库连接成功、模型服务可达、解析模块加载正常。日志里如果有 warning 说某个可选依赖没装，不影响核心功能可以先忽略。

验证环节我建议分三步走：先传一个简单的 Markdown 文件，确认解析和向量化没问题；再传一个带表格的 Word，确认结构化解析正常；最后传一个扫描版 PDF，确认 OCR 兜底生效。三步都过了，说明基础链路是通的。然后问几个问题，看检索和生成的结果是否合理。

提示：第一次启动会比较慢，因为要加载模型和初始化向量库，别以为卡死了就强杀进程。等日志打出 “service ready” 之类的字样再操作。

4. 检索效果调优：从“能跑”到“好用”的关键几步

4.1 命中率上不去的三个常见原因

部署完能跑只是起点，检索命中率（hit rate）才是决定这套系统能不能用的核心指标。我调优过程中遇到命中率低，基本逃不出这三个原因：

第一，切分粒度不对。前面说过，块太大语义被稀释，块太小语义不完整。判断方法很简单：随便挑几个问题，看召回的 chunk 是不是“答非所问”或者“只答了一半”。如果是，调 chunk_size 和 overlap。

第二，embedding 模型和语料语言不匹配。中文语料用英文模型，语义空间对不齐，检索出来的东西看着相关其实不精准。换中文优化的模型，命中率往往能提升一大截。

第三，查询和文档的表达差异太大。用户问“怎么装”，文档里写的是“安装步骤”，字面不匹配但语义相同。这种情况靠纯向量检索可能不够，需要引入查询改写或者混合检索（向量+关键词）。WeKnora 的 Agent 层支持查询改写，把这个能力打开能缓解不少。

4.2 混合检索的取舍

纯向量检索擅长语义匹配，但对精确的关键词、专有名词、代码标识符不敏感。比如你问某个具体的配置项名称，向量检索可能召回一堆语义相近但名字不对的段落。混合检索把向量检索和关键词检索的结果做融合排序，能兼顾两者。

WeKnora 里配置混合检索需要调权重参数，向量和关键词各占多少。我的经验是中文技术文档场景下，向量权重 0.6、关键词权重 0.4 起步，然后根据实际效果微调。如果文档里专有名词特别多，关键词权重可以再高一点。这个没有标准答案，得拿你自己的语料测。

4.3 用真实问题集做回归测试

调参最忌讳凭感觉。我建议你准备一个 20 到 50 条的真实问题集，每条问题标注好期望召回的文档片段，每次调完参数跑一遍，看命中率的变化。这个工作前期花点时间，后面调参会轻松很多，而且能避免“改了一个参数，修好了 A 问题，弄坏了 B 问题”这种反复横跳。

问题集要覆盖不同类型：事实型（某个参数是多少）、列举型（支持哪些格式）、推理型（A 和 B 有什么区别）。不同类型对检索的要求不一样，分开看指标才能定位问题。

5. 常见问题与排查速查表

5.1 解析失败类问题

解析失败是问得最多的。我把遇到过的和群里看到的情况整理成表：

5.2 检索与生成类问题

检索结果不相关，先别怀疑模型，按顺序查：切分参数、embedding 模型、查询改写是否开启、混合检索权重。生成结果胡编乱造，检查 prompt 模板里有没有明确要求“基于检索内容回答，不知道就说不知道”，这个约束不加，模型很容易自由发挥。

Agent 执行报错 “execution terminated due to error”，通常是工具调用返回了异常或者迭代次数超限。看日志里具体是哪一步失败，如果是工具调用，检查工具的参数格式；如果是迭代超限，调大最大迭代次数或者优化查询改写策略。

5.3 部署环境类问题

Windows 下最常见的还是依赖和路径问题。路径里有中文或空格，某些库会出问题，项目目录尽量用纯英文路径。端口被占用也是高频问题，启动前用netstat查一下端口，冲突了就改配置。

注意：不要在生产环境直接用开发模式的启动命令，性能和安全都没保障。正式部署要配反向代理、开鉴权、限制上传文件大小和类型。

6. 和 Obsidian、其他 RAG 项目的定位差异

很多人问 WeKnora 和 Obsidian 能不能配合用。这俩定位完全不同：Obsidian 是个人笔记工具，强在编辑和双链；WeKnora 是知识库检索系统，强在解析、向量化和问答。真要配合，可以把 Obsidian 的 Markdown 库作为 WeKnora 的数据源导入，用 WeKnora 做检索问答，Obsidian 继续做日常编辑。但别指望 WeKnora 替代 Obsidian 的编辑体验，它不是干这个的。

和其他 RAG 框架比，WeKnora 的优势在中文解析和 Agent 编排的完整度，劣势在生态和文档还在完善中，遇到问题可能需要自己看源码。选它还是选别的，取决于你的语料是不是中文为主、你是不是需要 Agent 能力。如果只是英文文档问答，很多成熟框架也能满足；如果是中文复杂文档加多轮推理，WeKnora 值得一试。

7. 我在实际部署中总结的几条经验

第一，先把解析和切分调好，再动检索和生成。很多人一上来就折腾模型和 prompt，结果底层数据质量不行，怎么调都白搭。数据是地基，地基不稳上面盖什么都晃。

第二，参数不要一次改多个。每次只动一个变量，跑完回归测试看效果，否则你根本不知道是哪个改动起了作用。这个习惯能帮你省下大量返工时间。

第三，日志要开详细级别。排查问题时，详细日志能告诉你每一步的输入输出，比猜快得多。生产环境可以调低日志级别，但调试阶段别省这点磁盘。

第四，小步验证，别一次性导入全部文档。先拿几十个代表性文档跑通全流程，确认没问题再批量导入。批量导入出问题，定位起来非常痛苦。

最后分享一个我常用的小技巧：给每个 chunk 打上来源文档和章节的元数据标签，检索结果里带上这些标签，一方面方便溯源，另一方面在生成时可以按来源做去重和排序，答案质量会更好。这个改动不大，但效果立竿见影。