最近想找一个工程完成度足够高、又能拿来学 RAG 全链路的开源项目，翻了一圈最后停在腾讯开源的 WeKnora 上。它是 MIT 协议、当前版本 v0.8.2，把「文档理解 + 语义检索 + 自主推理」做成了一套可自托管的框架，代码结构比大多数 demo 级的 RAG 仓库认真得多。
我打算用一个系列把它拆开讲。这是第一篇，先建立整体认知：它分成哪几层、为什么主后端用 Go 而文档解析单独拎出一个 Python 服务、一条文档从上传到能被检索中间到底发生了什么。后面三篇分别深入分片机制、检索管线和 Agent 能力。
做 RAG 的人迟早会撞到一堵墙：检索命中率上不去，答案总是缺上下文，或者命中的块跟问题根本不相关。排查到最后，问题往往不在模型、不在向量库，而在最前面那一步——分片（chunking）。
大多数项目的分片逻辑简单粗暴：按固定字符数切，加个 overlap 完事。这在一篇结构规整的文章上凑合能用，但真实世界的文档千奇百怪——有带规范标题的技术手册，有 OCR 出来的、连标题都没有的扫描件，有 FAQ 那样的原子条目，也有长篇叙事报告。用同一把尺子去量所有文档，注定顾此失彼。
WeKnora 的分片器（Go 侧 internal/infrastructure/chunker 包）给出的答案是一套自适应架构。这是系列第二篇，我按源码把它逐层拆开。
分片切好了、向量也建好了，接下来的问题是：用户提一个问题，系统怎么从成千上万个块里捞出最相关的那几个，排好序，再拼成 prompt 喂给模型？
很多人以为这一步就是「算个 query 向量、查一次向量库、取 Top-K」。真做过就知道，这条链路里藏着一堆工程细节：多轮对话的历史怎么带、查询要不要改写、向量和关键词怎么融合、召回一堆重复的怎么办、怎么保证结果既有相关性又有多样性。WeKnora 把这些环节抽象成了一条事件驱动、按需装配的 Pipeline。这是系列第三篇。
前三篇我们一路沿着数据流走下来：架构分层、文档怎么被解析分片、检索管线怎么把内容捞出来排序。但这些都还停留在「RAG」的范畴——用户问一句，系统检索一次、答一句，是被动的。
WeKnora 真正想做的不止于此。它在检索之上搭了一个 ReAct Agent，让系统能自己规划多步任务、调用工具、写代码、开浏览器、还能把一堆原始文档蒸馏成一个自维护的 Wiki。这是系列收官篇，我们看看问答之上的这层「自主推理」是怎么组织的，也顺便给整个 RAG 全链路收个口。
第一篇讲架构全景时提到，WeKnora 横向用「接口 + 注册表」让向量库、模型、存储都可插拔；第三篇讲检索管线时又带过混合召回。这篇番外把镜头对准「可插拔」这三个字本身：它到底怎么做到换一个向量库像改一行配置一样简单。
先说清楚这件事的分量。一个生产级 RAG 系统，向量库选型经常会变：起步用 Postgres 加 pgvector 图省事，数据量上来了想换 Milvus 或 Qdrant，要做全文检索想上 Elasticsearch，部署在腾讯云又想用腾讯云向量库。如果每换一次都要把索引、检索、删除的代码重写一遍，迁移成本会高到没人敢动。WeKnora 用一套分层抽象，把这件事变成了「加一个后端实现 + 改一个环境变量」。