拆解六款开源RAG：自研知识库的架构蓝图与避坑指南

我花了大概两周时间把市面上六款主流开源RAG项目——RAGFlow、QAnything、Dify、FastGPT、LlamaIndex、Haystack——的源码和架构图翻了一遍。这么做的目的不是要直接抄代码而是想回答一个被问了很多次的问题如果我自己从头搭一套RAG到底需要哪些组件、哪些坑可以绕开、哪些设计从第一天就要定下来。这篇文章就是这份“逆向工程”的记录最终会落到一张可以直接开工的自研RAG蓝图上包括模块划分、技术选型、核心代码链路和分阶段落地路线。适合正在评估自研知识库方案的后端工程师和AI应用开发者也适合单纯想搞懂RAG在工程上到底难在哪的人。在往下拆之前先把结论放出来开源项目最大的价值不是开箱即用而是它们已经把“文档接入、切分、索引、检索、生成”这条链路踩过无数遍把共性抽出来自研就变成了一道填空题。1. 为什么要把开源RAG项目翻个底朝天1.1 闭门造车的三个代价很多人对RAG的第一印象是“向量库大模型”好像把文档塞进向量库再让大模型照着检索结果回答就行。这个理解不能说错但它只看到了两个点忽略了中间那条决定成败的管道。实际生产中的RAG要处理的是各类文件格式的解析、版面和表格、切分粒度、元数据、检索召回与融合、重排、上下文组装、引用溯源、知识更新。这些环节任何一个掉链子最终答案的质量都会明显下滑。开源项目恰恰每个环节都已经迭代过多个版本绕开了我已经预想到或根本没想到的坑。第二个代价是框架依赖。很多团队一开始用LangChain或LlamaIndex跑通了demo就觉得生产可以直接上。结果做到生产时发现框架的默认行为不透明、排错困难、升级有兼容性问题等到想把一个环节替换成自己的实现时API的封装反而拖后腿。反观那些开源RAG产品它们的架构相对完整、职责清晰哪怕只借鉴模块划分方式也足够让自研系统省掉大量架构试错。第三个代价是忽视成熟设计、闭门造车。比如切分策略很多自研项目上来就用“按字符数固定长度切”遇到PDF表格、双栏排版就一塌糊涂。而RAGFlow已经用版面分析解决了这个问题QAnything也验证了多路召回加重排的工程架构。不把这些经验吸收进来自研就变成了把业界踩过的坑重新踩一遍。1.2 哪六款产品值得逆向、各掏出什么我特意选了覆盖两类形态的项目而不是只看热度。RAGFlow、QAnything、Dify、FastGPT属于“应用级”拿起来就能部署出成品它们教会我RAG产品在运营层面必须具备哪些能力LlamaIndex和Haystack属于“框架级”拿来做二次开发它们教会我如何把链路抽象成可替换的组件。两组交叉看既能回答“产品应该有哪些模块”也能回答“代码应该怎么组织”。项目定位核心特色主要逆向点RAGFlow可部署知识库平台DeepDoc版面解析、深度文档理解文档解析管线、切分策略、chunk元数据模型QAnything企业问答平台多路召回 BCE重排两阶段检索结构、重排模型接入方式DifyLLM应用开发平台可视化工作流、知识库管理dataset/document/segment状态模型、检索节点设计FastGPT知识库问答服务平台知识库 工作流、多租户/分享知识库配置维度、检索逻辑的开关复用LlamaIndex开发框架索引/存储抽象、连接器生态可组合组件接口、Node与文档模型Haystack开发框架Pipeline管道、协议化组件组件协议、管道DAG设计这里说的“逆向工程”不是破解也不是反编译而是对开源项目做架构级阅读和推导看目录结构、看数据流、看核心类的依赖关系、看它暴露的配置项。这样得到的经验比读官方文档要扎实得多因为文档写的是“应该怎么用”源码告诉你“实际是怎么做的”。2. 拆完六款之后它们共享的“五层骨架”把六款产品放在一起对照后发现不管界面、定位、技术栈差多远背后都长着同一副骨架数据接入层、解析与切分层、索引存储层、检索编排层、生成与反馈层。这个骨架就是自研蓝图的地基后面所有设计都可以围绕它展开。2.1 数据接入层连接器和任务队列是标配六款中每一款都有“连接器”的概念。RAGFlow支持从S3、HTTP、本地路径拉取文件QAnything支持批量导入Dify和FastGPT支持从URL、Notion、Confluence等来源同步LlamaIndex有海量Data ConnectorHaystack也把文档转成统一格式再进管道。共同点是接入层不关心文件后续怎么处理只负责“把文件变成统一文档对象”并写入待处理队列。另一个共同点是异步化。文件解析和向量化是重活几十页PDF可能要几秒到几十秒如果同步处理上传接口就会长时间阻塞。六款产品无一例外地把摄取过程拆成异步任务。自研时至少要做到上传接口只存文件、提交任务并立即返回worker消费任务step包括解析、切分、embedding、入库每个步骤要有状态和重试。这个设计不是锦上添花它是知识库能否支撑真实使用节奏的前提。2.2 解析与切分最脏的活决定检索上限解析层的差异在这六款里体现得最明显。RAGFlow把版面分析当成核心能力专门用OCR和布局检测还原文档结构QAnything提供了基于文本的PDF解析加OCR兜底Dify和FastGPT默认用PyPDF等文本抽取但给了可配置的分段策略框架级产品则把解析器留给用户替换。这提示我们解析不是“把文本抽出来”这么简单而是要保留下结构语义——标题和正文的关系、表格的行列、图片的位置说明这些信息在后面切分和溯源时非常有用。切分策略方面六款产品基本都能归成三种。递归字符切分按分隔符和固定长度递归切速度快、实现简单适合通用纯文本语义切分用embedding相似度找自然段落边界块内语义更连贯但耗时且依赖模型质量结构切分按标题、章节、版面区域切分适合PDF、PPT、表格密集型文档质量最好但实现成本最高。自研第一版通常从第一种起步但必须预留后两种的接口。实践经验上对中文文档chunk_size通常设256到512 tokenoverlap设10%到20%。太大检索粒度过粗上下文浪费且相关性稀释太小信息被切碎召回的回答缺少完整背景。切分后给每个chunk打上元数据来源文件、页码、段落序号、标题路径。这条经验写在所有产品的检索实现里——没有元数据后面做过滤和引用溯源几乎无从下手。2.3 索引与检索向量之外永远要有关键词六款里但凡是面向生产的都不会只依赖向量检索。QAnything做了多路召回一路用向量表示语义一路用稀疏表示和关键词倒排再统一重排RAGFlow同样内置了混合检索选项Dify和FastGPT在知识库设置里也提供了检索模式开关。原因很简单向量检索擅长语义相似但遇到型号、编号、人名、报错信息这类精确匹配需求时它的排序常常不稳定BM25或者全文索引对精确词命中更可靠。混合检索的工程做法也很接近先用向量和关键词各自取topK比如各取50条合并去重后交给重排器。重排是这层的关键动作它把前面粗召回的结果重新打分排序让真正和用户问题相关的片段排在前面。自研最容易被省掉的就是重排省掉后就会看到“相关内容被召回但没有排进前几名”的尴尬。另外元数据过滤也常被忽略比如按部门、时间、文档类型、租户过滤能大幅减少无关召回。这层设计直接决定用户体感值得多花时间。2.4 生成与编排Prompt之外是流程状态Dify和FastGPT把生成环节做成了可视化工作流里面有检索节点、重排节点、LLM节点、回答节点。表面看只是拼接Prompt但真正值钱的是它背后的状态流用户问题进来先判断是否需要改写再检索、重排、组装上下文最后才是生成。QAnything和RAGFlow同样有类似链路只是封装在代码里。把它抽象出来RAG工程里的“生成”不再是“把Prompt拼起来调LLM”而是“一条有明确环节的流水线”。流水线里有两个容易被忽略的组成部分。第一是Query改写对话场景里用户常问“那下一步呢”“它和上一个有什么区别”你不改写就直接检索召回率会明显下降。第二是引用溯源好的RAG产品都会给出答案对应的出处。这两个能力应该从第一版就开始做而不是等到上线后补因为后续所有效果分析都依赖它们。我之前见过很多项目上线后才补引用结果不得不重构上下文组装逻辑。3. 反向图纸从源码里挖出的可复用配方这一节是干货浓度最高的部分。每款产品我只挑一个最能打的“配方”讲清它解决什么问题、自研如何低成本复刻不会罗列一堆用不上的功能。3.1 RAGFlow教会我做文档解析要先做版面检测RAGFlow与其说是RAG系统不如说是“文档理解系统”。它内置的DeepDoc管线会把PDF或扫描件先做版面检测把页面划分成标题、正文、表格、图片、页眉页脚等区域再做OCR和表格还原最后按结构切分。这个设计让它在复杂文档上的检索质量明显优于“纯文本抽取”也是很多团队选用它的核心理由。自研要复刻这个能力不需要一步到位。先把流程搭起来PDF转图像用pdftoppm按300dpi渲染页面再做版面区域检测可以通过开源版面模型如PP-Structure这类或轻量方案先按页分割再用标题字体或大纲粗定位对表格区域做结构识别转成Markdown对图片区域做OCR或视觉模型描述最后把版面信息写进chunk元数据检索时按页或表格过滤。如果你的第一版不想上模型我建议至少做“标题感知切分”解析PDF大纲按章节切大块再按块内长度切小块。实测下来这个方案比纯递归字符切分对长文档的问答质量提升非常明显而实现成本低得多。3.2 QAnything教会我召回不能只靠一路向量QAnything把检索拆成两个阶段召回阶段并行执行Dense向量检索和Sparse关键词检索各取一批候选排序阶段统一交给专用的BCE重排模型输出最终topK。这样既覆盖语义相近但用词不同的问题也覆盖用词精确但对语义向量不友好、索引不稳定的问题。它的核心思想是“别把所有鸡蛋放在一个篮子里”。自研版本可以直接照搬这个结构第一版不需要上很重的基础设施。关键词检索可以用SQLite FTS5或者Elasticsearch如果没有专用的重排模型可以先做分数融合比如score alpha * dense_score (1 - alpha) * sparse_scorealpha从0.5起步用评测集微调。一旦需要提升效果再把重排模型插进来接口不变。下面是这个结构最简化的实现骨架dense_hits vector_store.search(query, top_k50) sparse_hits bm25_store.search(query, top_k50) candidate merge_and_dedup(dense_hits, sparse_hits) reranked reranker.rerank(query, candidate, top_k5)3.3 Dify和FastGPT教会我知识库运营需要状态机用过Dify的人都会注意到知识库里有“数据集→文档→分段”三层结构文件上传后还有一个处理状态等待、处理中、已完成、失败。FastGPT类似知识库文件同样带着索引状态和刷新动作。这种设计背后是一个朴素的认知知识库不是一次性把文件塞进去就完事它会增删改、会解析失败、会被重新切分因此必须被当成有生命周期的实体管理。落到自研的数据模型上至少需要两张表。document表记录文件本身的状态和版本chunk表记录切分后的片段和元数据-- document表 document(id, source_uri, file_name, file_type, status, error_msg, chunk_count, doc_version, created_at, updated_at) -- chunk表 chunk(id, document_id, seq_no, content, page_no, title_path, meta_json, embedding_id, is_deleted, created_at)状态机配合任务队列能让你拥有重试、断点续跑、增量更新的能力。我在自研项目里吃过亏一开始没有状态字段解析失败只能人工排查加了一个status和error_msg之后问题定位从小时级降到分钟级。这算是我觉得从Dify身上学到最实用的一个点。3.4 LlamaIndex和Haystack教会我把每个环节变成独立组件框架级产品和应用级产品最大的不同是它们把RAG的每个环节定义成接口清晰的组件。LlamaIndex里有Document、Node、Index、Retriever、QueryEngine这些抽象Haystack要求每个组件声明输入输出通过Pipeline把它们连接成DAG。这样做最大的好处是每一环可以独立测试、独立替换整个流程可以用配置文件描述而不需要修改业务代码。自研时照着这两套框架把接口定清楚后面好处非常大。比如你第一天用OpenAI embedding第二天想换成本地bge模型只要实现同一个Embedder接口又比如调检索参数、换Prompt模板都不用动其他部分。很多自研项目到最后改不动就是因为每个环节都耦合在一起。先定义协议再写实现这个顺序不能反from dataclasses import dataclass from typing import Protocol dataclass class Chunk: text: str meta: dict class Splitter(Protocol): def split(self, doc: Document) - list[Chunk]: ... class Retriever(Protocol): def retrieve(self, query: str, top_k: int) - list[Chunk]: ... class Reranker(Protocol): def rerank(self, query: str, chunks: list[Chunk]) - list[Chunk]: ...3.5 六款产品共同认可的10条设计原则把六款产品的实现细节全部放下后我提炼出10条它们共同认可的设计原则。每条单独看不稀奇难的是同时做到。开源产品之所以效果稳定不是模型比自研强而是这些细节被反复打磨过。文档入库走异步任务解析失败可重试。chunk必须携带来源、页码、标题路径等元数据。生产检索至少一路向量加一路关键词。生成前必须有重排环节不能直接拿召回结果拼Prompt。Prompt模板版本化至少带上文档和chunk级引用。对话场景要做Query改写而不是拿原问题直接查。知识库按数据集或目录隔离检索层加过滤。所有外部调用模型、存储需要超时、重试和日志追踪。从第一天就建评测集用召回率和答案质量打分而不是靠肉眼。把链路写成Pipeline或状态机别在一个Controller里堆逻辑。4. 自研蓝图实操从零搭一套可维护的RAG讲完逆向拆解接下来是真正可以抄作业的部分。我会给出一套从零搭建的RAG架构不依赖任何重量级框架普通后端团队能维护且每一层都留了替换空间。4.1 整体架构与工程目录模块先分干净如果你打算用Python起项目我建议按下面的目录结构组织。api和worker分离保证上传不阻塞core模块之间互不依赖每个模块只有一到两个对外接口配置集中管理chunk_size、top_k、模型名这些参数都放进config.yaml而不是散落在代码里rag-app/ ├─ api/ # FastAPI路由 │ ├─ upload.py # 文件上传、任务提交 │ ├─ query.py # 问答接口 │ └─ admin.py # 知识库管理 ├─ worker/ # 后台任务 │ └─ ingest_tasks.py ├─ core/ │ ├─ ingest/parser.py # 文档解析 │ ├─ split/splitter.py # 切分策略 │ ├─ embed/embedder.py # embedding封装 │ ├─ retrieve/ # 向量关键词检索 │ ├─ rerank/reranker.py # 重排 │ ├─ generate/ # Prompt与生成 │ └─ pipeline.py # Pipeline编排 ├─ storage/ # pgvector/fts/对象存储抽象 ├─ models/ # document/chunk数据模型 ├─ eval/ # 评测脚本 └─ config.yaml # 参数集中配置这个结构是从六款产品和两个框架里抽出来的最小公约数。它足够简单第一周就能跑通也足够规整后面加增量更新、权限、多知识库时不会推倒重来。4.2 技术选型表向量库、切分器、重排器怎么选选型是自研里最纠结的部分我给一张根据实际经验整理的对照表。核心思路是MVP阶段尽量省力生产阶段再按需升级组件MVP阶段建议生产阶段建议说明向量库pgvector已有PostgreSQL或Qdrant单机Qdrant/Milvus集群faiss只适合离线验证不适合在线并发Embeddingbge-m3 / text-embedding-3-small同左或按领域微调中文检索优先考虑bge系列切分器递归字符切分 标题感知版面分析 结构切分先跑通再提升复杂文档效果关键词检索SQLite FTS5 / PostgreSQL全文Elasticsearch / ManticoreMVP不用上ES重排器分数融合alpha加权bge-reranker-v2-m3等cross-encoder重排对准确率提升最直接大模型OpenAI兼容接口 / 本地qwen系列同左按成本选择输出格式用JSON约束任务队列RQ/arqCelery或云托管队列保证任务状态可查这里的MVP建议偏省力。如果你已经在用PostgreSQLpgvector是最低成本的起点一个数据库同时管业务数据和向量等到向量量和并发上来了再迁到Qdrant或Milvus。前期的代码都围绕同一个检索和写入接口迁移并不伤筋动骨。4.3 核心代码链路摄取、检索、生成三段式核心链路可以用三段式概括摄取、检索、生成。下面是经过简化的可运行骨架每一步都对应前面规划的core模块。先看摄取。解析、切分、向量化、入库四步顺序执行其中前两步走worker后两步可以复用同一套存储接口def ingest_document(file_path: str, doc_id: str): docs parser.parse(file_path) # 返回一个或多个Document chunks splitter.split(docs) # 根据策略切分保留meta vectors embedder.embed([c.text for c in chunks]) store.upsert(doc_iddoc_id, chunkschunks, vectorsvectors) # 写入pgvector fts再看问答链路。这个链路里我特意保留了history、filters和with_citations三个细节。history交给rewrite而不是直接拼进Prompt是因为改写后检索结果能更好filters让不同知识库和权限隔离在检索阶段完成citations则在生成阶段回传来源为的是能追溯答案依据def answer(question: str, history: list[str]) - str: q query_rewriter.rewrite(question, history) dense_hits store.search_dense(q, top_k50, filterscurrent_filters) sparse_hits store.search_sparse(q, top_k50, filterscurrent_filters) candidates merge_and_dedup(dense_hits, sparse_hits) top reranker.rerank(q, candidates, top_k5) context format_context(top, with_citationsTrue) return generator.generate(q, context, citations[c.doc_id for c in top])4.4 分阶段落地路线MVP到生产环境的四次迭代蓝图归蓝图落地要分阶段。我建议把路线切成四个里程碑每个里程碑有明确验收标准避免一上来就追求大而全M1跑通闭环支持txt、md、pdf上传使用递归切分向量检索加关键词检索直接融合能输出带引用的回答。验收标准是20份测试文档中10个问题能答对。M2质量优化加入Query改写、重排模型、评测集。验收标准是同一测试集准确率提升可量化肉眼可见“相关片段排序变好”。M3运营能力知识库状态机、增量更新、多知识库隔离、权限过滤。验收标准是更新文档后问题答案能反映最新内容失败任务可查看和重试。M4性能与扩展按需把向量库迁移到分布式、加缓存、监控链路耗时、支持多模态解析。验收标准是并发提升、P95延迟达标。这四个里程碑不是功能清单而是“验证、优化、运营、规模化”的自然顺序。很多团队一上来就想做M4忽视M1和M2最后连基本效果都没保障架构却已经复杂得难以排查。5. 自研路上反复踩过的坑实录与排查这一节全部来自实际操作中的教训不是泛泛而谈的“最佳实践”。我把最常见的五类问题按排查方向和解决办法展开每一条都对应一个真实场景。5.1 检索效果差先检查切分而不是换模型最常见的排查场景用户问“2024年Q3毛利率是多少”系统答非所问。第一反应不要是换embedding模型或换大模型按下面顺序查一遍把实际召回的chunk打出来看是否包含正确页面。如果没有查切分是否把段落切碎、是否把页码标题去掉。如果有正确片段但排名靠后查融合权重和重排逻辑。如果连关键词都精确匹配了但还没召回再怀疑embedding和query改写。一个非常典型的例子是PDF双栏排版。按文本流切分时左栏一行和右栏一行经常被拼接在一起产生完全无意义的chunk而这类文件在技术文档、产品手册里占比极高。解决方案是页面内先按坐标分栏再按栏内段落切或者用版面模型标出栏边界。很多团队在这个问题上折腾一星期最后发现不是模型的问题是上游文本流本身就是乱的。5.2 重复文本和脏数据索引前的最后一道闸门真实的知识库大多不干净同一份规范被多次上传、模板文档里大量页眉页脚、目录页和封面页混进来。这些脏chunk会持续污染召回结果导致检索出的片段看似相关实则全是重复的模板信息。自研时必须把清洁步骤纳入管线去页眉页脚、去掉纯数字页码、过滤字数过短的chunk、做哈希去重更进一步的用simhash或embedding余弦相似度做近似去重。一个很实际的坑把公司规章文档全量导入后检索结果几乎全被“修订记录”页的相似文本占满因为它在每份文档里都重复出现向量召回里权重极高。后来加了“按文档结构排除页眉页脚和修订记录”的规则才改善。开源产品大多把这类规则藏在内部自研时别省这一步。下面是一个轻量去重的参考实现def is_dup(text, existing_hashes, min_sim0.95): h make_simhash(text) if h in existing_hashes: return True return vector_cos(text_vec, recent_vecs) min_sim5.3 增量更新知识库不是一次写完就结束文档一定会更新。如果没有增量更新机制旧embedding残留在库里同一个问题可能命中旧版内容答案随之过时。我在自研时采用的方案是给document维护doc_version字段替换文档时先解析新版本生成chunk再在事务里将旧chunk标记deleted并写入新chunk只有差异大的文件才重算embedding通过hash对比跳过未变化部分。还有另一个容易忽略的问题向量化的波动。同一条文本在不同时间被embedding模型生成的向量可能略有差别如果直接删旧写新索引会不一致。稳妥做法是“软切换”把新版本索引构建完成后再把查询流量切到新版本旧版本保留一段时间用于回滚。这个方法是从QAnything的版本管理思路里借鉴过来的虽然增加了一点存储成本但换来的是更新过程的可控性。5.4 图片和表格多模态RAG的现实路径回到很多人问的问题“RAG知识库能存储图片吗”技术上向量库当然能存图片的向量但如果你只把图片原始文件塞进去检索时无法通过自然语言语义找到它就算找到了大模型也看不到图里的信息。现实的做法是把图片“文本化”后再走常规RAG链路。具体分三类纯图片调用OCR提取文字或用视觉语言模型生成图片描述表格图片用表格结构识别工具还原成Markdown再作为文本chunkPDF图文混排则在版面解析时把“图标题、图内文字OCR、上下文文字”合成一个chunk这样检索到图片时大模型能够理解它的语境。不要直接把图片二进制丢给向量化接口就算完事那等于在知识库里放了无数个“看不见的盲区”。我的建议是MVP阶段只做文本和表格等OCR和视觉模型稳定后再扩展图片描述避免第一版就背上多模态的成本。如果业务确实需要看图优先选支持视觉输入的模型把图片转成文本描述比强行训练多模态检索链路更划算。5.5 别硬自研什么时候该用开源产品不是所有场景都值得自研。如果你的需求是“内部快速搭一个知识库问答工具”直接部署RAGFlow或QAnything配好分块和检索参数就能用如果需求是“做成面向用户的商业产品”需要深度定制权限、数据格式、检索策略、多租户隔离、可视化配置这时自研才有明确的增量价值。自研的本质不是为了技术自主而是为了获得不可替代的控制力。更务实的折中路线是fork开源项目后裁剪。你可以基于RAGFlow或Dify二次开发保留它们成熟的文档解析和知识库管理能力只替换自动化和业务相关的部分同时仍然按照前面说的接口化思想维护自己的层。我见过不少团队把“自研”等同于“从零写”结果维护成本远超预期真正合理的自研应该是在吸收开源精髓基础上的改造而不是把所有轮子都重新造一遍。6. 从图纸到代码给你的启动清单6.1 先做这四件事再决定要不要深挖如果你看完文章准备动手我建议从这四件事开始。第一花三天时间跑通最小闭环读取一份PDF、切分、写入pgvector和全文索引、检索、生成。第二建一个20到50条问题的评测集问题和标准答案都从真实业务文档里抽。第三在同一个评测集上对比单路向量、向量加BM25、加入重排三种方案的召回效果。第四把版本和状态记录到知识库模型里哪怕第一版只是加一个status字段。这几件事看起来基础但它们决定了后续所有优化是否有据可依。没有评测集你换任何模型都无法判断是变好还是变坏没有多路检索对比你永远不知道瓶颈在哪里。我自己在早期就是吃了“凭感觉调参”的亏后来把所有改动都挂到评测集上效率翻了几倍。6.2 我反复验证过的一个判断标准最后分享一个我自己的判断标准如果引入一个新技术或组件不能在三句话内说清它替换了哪个环节、带来什么收益、失败时如何回滚那就先别引入。RAG自研的复杂度不是来自某个模型而是来自链路里十几个环节的耦合。开源产品给了我们完整的参照系真正重要的是把这些环节拆开、理解、再按自己的场景组合起来。能把这套链路控制住自研RAG就变成一道填空题解析器是什么、切分策略是什么、索引用什么、重排用什么、生成用什么其余全是工程细节。把这些空格填好你的第一版自研RAG就可以安全起飞了。