最近想找一个工程完成度足够高、又能拿来学 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 用一套分层抽象，把这件事变成了「加一个后端实现 + 改一个环境变量」。
上篇写了 MarkItDown，微软出的通用文件转Markdown 工具。今天这篇聊 MinerU——一个更专注、更狠的文档解析引擎。
如果说 MarkItDown 是"瑞士军刀"，什么格式都能转；那 MinerU 就是"手术刀"，专门对付最难啃的 PDF——扫描件、多栏排版、跨页表格、数学公式、手写体，这些让普通解析器哭出来的场景。
很多被高估的 AI 话题之所以显得迷人，是因为大家只看到了 demo 的上限，没有认真算集成成本、维护成本和失败代价。
补档说明：本文属于「AI 工程落地周记」系列，计划发布时间为 2025-10-22 09:10。当前先保留为草稿，后续补充真实案例、代码片段和复盘细节后再发布。
有一次我们为了把检索时延压下来，动了向量库的一组参数。改动本身不大，甚至可以说很“合理”：
结果上线后最先变化的不是延迟，而是答案味道。
用户不会告诉你“召回率下降了”，他们只会说：
后来追回去才发现，这次参数调整表面上节省了一点查询成本，实际上悄悄改掉了检索质量的下限。
这次排查很典型：业务方反馈“最近知识库回答突然变差”，但表面上看系统并没有报错，模型也没换，接口响应时间甚至还是正常的。真正的问题出在一个很容易被忽略的指标上，检索命中率突然掉了一截。
一开始大家本能地怀疑 Prompt、怀疑模型、怀疑重排，但继续查下去才发现，问题不是最后生成阶段，而是索引更新后，一部分文档的元数据缺失，导致相关片段虽然被召回了，却没有排进最终候选。
补档说明：本文属于「AI 工程落地周记」系列，计划发布时间为 2025-02-07 10:20。当前先保留为草稿，后续补充真实案例、代码片段和复盘细节后再发布。
很多团队在做 RAG 优化时，容易把问题切成几个独立模块来看：Chunk 怎么切、检索怎么召回、重排怎么加、最后模型怎么答。表面上看这很合理，因为技术栈确实也是这么拆开的。但真正调过一轮系统之后就会发现，这几个环节并不是并列关系，它们是串联关系，而且前一个环节的决策会强烈限制后一个环节的上限。
也就是说，很多 RAG 项目效果不好，不是某一个组件单独弱，而是顺序没想清楚：一开始切分就把信息结构破坏了，后面再怎么改召回和重排，都只能在一堆不完整片段里做“最优选择”。
所以我现在更在意的是这条链路的顺序：先怎么切，再怎么召，再怎么排，最后才轮到模型组织答案。