很多人做 RAG（检索增强生成）项目时，最容易踩的坑不是模型选错，而是整条链路堆在一起。文档加载、文本解析、切片、嵌入、检索、重排、生成、评测，每一段都改起来费劲，随便动一个参数都可能影响最终答案，却说不清问题出在哪。
“模块化RAG项目”这个方向，就是为了解决这个问题。它不是指某一个固定开源仓库，而是一种把 RAG 按职责拆成独立模块的工程思路：每一层都有清晰边界，每一层都能单独替换、单独测试、单独评估。如果你已经在本地跑通过一个 RAG Demo，但到了做知识库问答落地时，发现结果质量不稳定、参数调不动、报错定位不到，那这套思路会很有参考价值。
下面我按实际落地顺序，把模块化 RAG 的拆分方式、技术选型、参数设置、指标评测和排查方法完整拆一遍。
1. 模块化RAG要解决的问题，不只是“能跑通”
1.1 从“跑通RAG”到“模块化RAG”，差的是可维护性
RAG 的核心链路是固定的：知识文档进来，先经过加载、解析、切分、嵌入，再写入向量库；用户问题进来，先做检索召回，再经过排序、提示词组装，最后交给大模型生成。
很多演示项目把它们写在一个脚本或一个大 Service 里，文件倒是分开了，但模块之间依然强耦合。比如切分逻辑直接操作 PDF 解析结果，检索函数直接依赖某个向量库的客户端，提示词模板和模型调用写在一起。看起来“能跑”，实际上改一处就要全链路回归。
真正模块化的 RAG 要做到两件事：每一层都有稳定的输入输出接口；每一层都能替换内部实现，而不影响其他层。
举个例子。切分这一层可以定义统一的输出结构：切片 ID、原文内容、元数据、字符偏移。后续嵌入层和检索层只认这个结构。这样你从固定大小切分换成语义切分，或者从通用文本切分换成 Markdown 结构切分，下游代码完全不用动。
1.2 模块化需要满足的三个判断标准
我判断一个 RAG 项目是不是真的做到模块化，一般看三点：
第一，接口是否稳定。内部实现怎么改，外部调用方式保持不变。比如检索层内部从 ES 换成 Milvus，调用方拿到的还是“候选列表”这一种结构。
第二，依赖是否单向。数据接入层不能反向依赖生成层，各模块只能依赖公共接口，不能互相调用对方的私有实现。
第三，评测是否能按模块拆开。可以单独评估检索效果，再单独评估生成效果，而不是只能端到端看“整个系统行不行”。
如果这三点都满足，基本就是模块化架构。如果只是把代码拆成多个文件，但数据格式各写各的、接口互相渗，那只是“文件拆得好”，不是模块化。
1.3 什么时候不需要模块化，什么时候必须模块化
我不建议任何场景都强行上模块化。
如果只是个人学习、跑一个最小 Demo、验证某个模型的问答能力，直接写一个 Python 脚本或 Notebook 就好。这时候引入复杂的模块设计，只会增加学习成本。
但如果是这些场景，模块化就很有必要：
- 知识库文档类型很多，PDF、Word、Markdown、扫描件、表格、代码仓库都要接入；
- 需要对比不同切分策略和不同 Embedding 模型对效果的影响；
- 需要把底层向量库或大模型替换成其他厂商的方案；
- 要在系统里接入权限、任务调度、失败重试、日志监控；
- 生成答案时必须要能追溯到引用的文档和切片。
只要有其中一个需求，模块化的收益就大于成本。它的核心价值不是让代码更“高级”，而是让后续每一次优化都可控、可回退、可验证。
2. 模块化RAG项目的顶层架构：模块划分、数据模型、技术栈选型
2.1 按职责拆开RAG全链路：分几层、每层做什么
一个模块化的 RAG 项目，通常可以拆成下面这些层：
- 数据接入层：负责文件上传、数据库流式读取、定时任务抓取、消息队列消费。统一输出“原始文档”对象。
- 格式解析层：负责 PDF、Word、Markdown、PPT、图片 OCR、表格解析。统一输出标准化文本或结构化文本。
- 文本切分层：负责块大小控制、重叠区间、按标题切分、按语义切分、按代码结构切分。统一输出“切片”对象。
- 向量化层：把切好的文本转成向量。要封装 Embedding 模型的调用，统一输出向量和原文。
- 向量存储与检索层：负责向量写入、相似度检索、元数据过滤。输出 TopK 候选。
- 重排层：对候选做二次排序，可以接 Rerank 模型，也可以加业务排序规则。输出最终 TopK。
- 提示词组装层：把检索结果、用户问题、历史记录、系统指令拼成完整 Prompt。
- 生成层：调用大模型，返回答案和引用来源。
- 评测层：离线指标计算、在线质量监控、Bad Case 收集。
每一层只依赖上一层的结果，不跨层。比如格式解析层不关心切片怎么切，重排层不关心向量库是哪个，生成层不关心检索用了什么算法。
2.2 用统一数据模型连接各模块
模块之间通信最怕的是各层自定义一套数据格式。联调时大量类型转换代码，边界越调越模糊。
建议为整个项目定义一套统一的跨模块传输模型：
{ "Document": { "docId": "doc_001", "sourceType": "pdf", "content": "原始文本或结构化文本", "metadata": { "title": "文档标题", "author": "作者", "category": "分类" } }, "Chunk": { "chunkId": "chunk_001", "docId": "doc_001", "content": "切片内容", "metadata": {}, "vector": [0.1, 0.2, 0.3] }, "RetrievalHit": { "chunkId": "chunk_001", "score": 0.85, "content": "命中内容", "metadata": {} }, "GenerationResult": { "answer": "最终答案", "citations": ["doc_001/chunk_001"], "tokens": 128 } }只要这套模型稳定，每个模块都可以独立演进。否则你会花大量时间在“A 模块的数据怎么转成 B 模块的格式”上。
2.3 Maven + SpringMVC + Tomcat下，Java工程怎么和RAG核心协作
很多团队的内网项目是 Java 体系，常见的是 Maven 构建的 SpringMVC 模块化项目，通过 IDEA 配置 Tomcat 容器启动。而 RAG 生态最丰富的又是 Python 侧。
这里我的建议是：不要让语言选择影响架构，要让架构兼容语言。
最常见也最稳的做法是双服务模式。Java 工程负责工程面：Web API、文件上传、任务调度、权限管理、前后端接口、数据库记录。独立的 RAG 核心服务负责算法面：文档解析、切分、Embedding、检索、重排、生成。两边通过 HTTP 接口或消息队列通信。
请求链路： 浏览器 -> Nginx -> Java SpringMVC服务 -> RAG核心服务 -> 大模型 | | |--- 任务状态存储 ---> 向量数据库这种结构里，Java 工程不需要关心 RAG 核心是不是 Python 写的。只要 RAG 核心服务提供稳定的 HTTP 接口，Java 侧只管调用。核心服务内部再按模块拆分，两边互不影响。
如果你的团队强约束必须纯 Java 实现，我建议先评估工作量。Embedding 模型和重排模型在 Java 生态里的现成实现远没有 Python 多，强行 Java 化会把大量时间花在造轮子上。我更推荐 Java 负责 Web 和任务编排，Python 负责算法模块，用进程隔离来保证模块边界。
3. 最小可运行的模块化RAG：从离线索引到在线问答
3.1 先跑通两条最小链路
我建议不要一开始就把所有模块都串起来。先跑通两条最小链路。
第一条，离线索引链路：
读取一个文件 -> 解析文本 -> 切分 -> 生成向量 -> 写入向量库第二条，在线问答链路：
接收用户问题 -> 向量检索 -> 取TopK -> 组装Prompt -> 调用大模型 -> 返回答案和引用先只用一个小样例文件，比如一份几千字的 Markdown 文档或一份 10 页的 PDF，验证整条链路有没有断点。这时候不建议直接上批量文档、多格式、多用户。
我见过很多项目上来就导入上万份文档，结果切分、Embedding 跑了一晚上，第二天一看，中途因为某个文件格式不对直接挂掉。模块化架构可以避免这个问题，但前提是第一个小样例就必须把日志链路建好。
3.2 SpringMVC侧的上传和异步任务设计
如果你的外层工程是 Maven 构建的 SpringMVC 项目，并通过 IDEA 配置 Tomcat 容器启动，那它的职责很清晰：上传文件、记录任务状态、提供查询接口。把上传的文档发送给 RAG 核心服务处理，把用户问题转发给 RAG 核心服务，再把答案返回前端。
这里有两个非常容易踩的坑。
第一个是 Tomcat 默认上传大小限制。Spring Boot 内嵌 Tomcat 默认单文件上传大小是 1MB，SpringMVC 传统部署也有类似限制。传大文档时，要提前把上传限制调大，否则文档还没进入 RAG 流程就被拦截了。
spring.servlet.multipart.max-file-size=50MB spring.servlet.multipart.max-request-size=100MB第二个是异步处理。不要把离线索引放在 HTTP 请求线程里同步执行。文档一多就会超时，前端一直转圈。更稳的做法是：上传后先返回一个任务 ID，后端通过线程池或消息队列异步处理，处理完再更新任务状态。
上传文档 -> 返回 taskId -> 异步解析/切分/Embedding -> 更新任务状态 -> 前端轮询状态3.3 切分参数、检索参数和重排参数怎么给
切分参数没有万能值。我的习惯是针对场景给一组起步值，再通过评测集调整。
| 场景 | chunk_size | overlap | 说明 |
|---|---|---|---|
| 通用文本 | 500-800 字 | 50-100 字 | 适合新闻、文章、产品文档 |
| 代码文档 | 300-500 字 | 30-50 字 | 代码结构尽量按函数或类边界切 |
| 合同、协议 | 按条款切 | 0-50 字 | 不要破坏条款完整性 |
| 表格文档 | 按行或按表头块切 | 0 | 尽量不要硬切表格行 |
| 长文档 | 先按标题切，再固定大小兜底 | 50 字 | 保留章节结构很重要 |
切得太大，一个 Chunk 里信息太杂，检索噪音高；切得太小，语义上下文不完整，召回容易漏。overlap 的作用是保留相邻切片的上下文衔接，但也不是越大越好，过大的 overlap 会让向量库里有大量重复内容。
检索阶段，先看 TopK 和 Score 阈值。
我的习惯是先以 TopK=20 做召回，再通过重排取 TopK=5。如果暂时没有重排模块，就先把 TopK 设小一点，比如 3-5，根据用户反馈调整。不要一味追求 TopK 数量，TopK 太大时，弱相关的内容会稀释 Prompt 中的有效信息，生成质量反而下降。
还有一个容易被忽略的点：元数据过滤。如果知识库有明确结构，比如分类、部门、协议版本、发布年份，要在检索时把过滤条件加进去。不要只依赖向量相似度。结构化过滤在很多时候比向量检索更稳定。
3.4 单条任务验证判断标准
一条任务跑完后，不要只看“模型返回了一段文字”就认为成功了。我一般检查四件事：
第一，是否正常命中。召回内容里有没有和问题真正相关的片段。如果召回的都是无关内容，再往下调 Prompt 也没有意义。
第二，引用是否可对齐。答案里的引用能否映射到具体的 Doc ID 和 Chunk ID。模块化架构里，这一步要能在日志里看到。
第三，耗时是否可接受。一次问答的检索耗时、生成耗时分别多少。如果检索耗时超过 1 秒，要看向量库量和索引情况；如果生成耗时过长，考虑降低 max_tokens 或换更快的模型。
第四，日志是否完整。能否在日志链路里看到“文档 ID、切片 ID、召回分数、Prompt 大小、生成 Token 数”。有了这些，才能做后续的指标评测。
4. RAG知识库指标：怎么理解指标，怎么用指标定位模块问题
4.1 三类指标：检索指标、生成指标、系统指标
搜索“RAG知识库指标有哪些”，会看到很多答案。按模块化思路拆开看，其实就三类：检索层、生成层、系统层。
检索层指标，看召回质量。
| 指标 | 含义 | 怎么理解 |
|---|---|---|
| Recall | 召回率 | 真实相关的切片有多少被召回了 |
| Precision | 精确率 | 召回来的结果里有多少是真的相关 |
| Hit Rate | 命中率 | TopK 里是否包含正确答案 |
| MRR | 平均倒数排名 | 第一个正确答案排在第几位 |
生成层指标，看生成质量。
| 指标 | 含义 | 怎么理解 |
|---|---|---|
| Faithfulness | 忠实度 | 答案是否忠实于检索到的资料，有没有编造 |
| Answer Relevance | 答案相关性 | 答案是否对上了用户问题 |
| Correctness | 正确性 | 答案与标准答案的语义一致性 |
系统层指标，看可用性。
- 端到端时延：每个环节分别耗时多少。
- 首 Token 时间：对交互系统很重要。
- 引用准确率：答案中的引用文档是否真实支撑了那句话。
这三类指标分别对应不同模块。检索指标差，问题大概率出在切分、Embedding 或检索策略上；生成指标差，问题可能在 Prompt 或模型选型上；系统指标差，要看服务和基础设施配置。
4.2 构建一个可用的评测集
评测集不需要一开始就很大。先收集 50-100 条有代表性的问答，每一条标注：
- 用户问题；
- 标准回答或关键要点；
- 对应的支持文档 ID 或切片 ID；
- 判断答案是否“可直接接受”。
这里最费时间的其实是标注，而不是跑评测。建议让业务方或领域专家一起参与，因为“这个答案是否准确”只有懂业务的人才能判断。
有了评测集，就可以做模块级对比。比如切分从 500 字改成 800 字，跑一遍检索指标，看看 Recall 是升是降。换一个 Embedding 模型，跑一遍同一批评测集，对比 Hit Rate。模块独立后，这类对比非常轻松。
4.3 从指标反推薄弱模块
指标异常时，先定位层级，再改模块。
- 召回率低：优先查切分参数、Embedding 模型、是否缺少元数据过滤。
- 精确率低：召回的东西不对，查检索排序，或者加过滤条件。
- 忠实度低：答案在编造，查 Prompt 里有没有“严格依据资料回答”，查检索内容是否足够覆盖问题。
- 答案相关性低：答案离题，查 Prompt 指令和模型选型。
- 端到端时延高：先分开看检索耗时和生成耗时。生成耗时高，降低 max_tokens；检索耗时高，查向量库压力和索引情况。
这种分层定位能力，正是模块化架构带来的最大价值。没有模块边界，你只能“试试这个、试试那个”，很难判断改动到底影响了哪一层。
5. 模块化RAG如何支撑重排、Agentic RAG、多模态和领域定制
5.1 重排模块为什么值得单独拆
向量召回阶段追求的是“让相关内容尽量进 TopK”，排序不一定精准。重排模型的作用是对召回的候选重新打分排序。
重排模块要单独拆出来，原因有三个：
- 可以单独替换 Rerank 模型，不用动检索代码；
- 可以单独评测“不重排”和“重排后”的指标差异；
- 可以根据业务定制重排规则，比如业务关键词加权、权限过滤、时效性加分。
实现上，重排模块接收“检索层输出的候选列表”，返回重新排序后的列表。它不关心向量库怎么存，也不关心 Prompt 怎么组。这样，检索层和生成层之间的这个“二次排序层”就可以独立演进。
5.2 Agentic RAG：把模块变成可编排工具
Agentic RAG 不是另一个完全不同的系统，它更像是把一个模块化 RAG 改造成“可被 Agent 编排的工具集”。
普通的模块化 RAG 流程是线性：问题进来，固定走一遍检索和生成。Agentic 方式下，Agent 可以根据问题动态决定：
- 使用哪种检索方式；
- 是否需要多轮检索、多次改写查询；
- 是否先查文档 A 再查关联文档 B；
- 是否需要调用外部工具或 API。
如果模块边界清晰，每个模块都可以暴露成“工具”，Agent 编排起来就很容易。比如“文档检索工具”“表格查询工具”“协议条款检索工具”各自是一个模块。如果核心流程写在同一个大函数里，Agent 就没有办法编排。
这其实就是 LangChain、MCP 等生态里常说的工具化思路。模块化 RAG 项目天然适合做这件事，因为你已经为每个模块定义了稳定接口，Agent 只需要按接口调用即可。
5.3 多模态RAG和领域RAG怎么扩模块
多模态 RAG 不是简单把图片也传进 Prompt，而是要把图片中的信息先提取成文本或向量，再进入检索链路。常见做法是 OCR 模块、图像描述模块、表格识别模块。这些在模块化架构里其实就是“格式解析层”的扩展。
领域 RAG 需要在三处做定制。
第一，数据接入和解析。比如银行合同 PDF 格式复杂，表格和签字栏混杂；3GPP 协议文档结构性强，通用解析器会丢层级关系。这时要针对文档格式写专用解析器。
第二，切分策略。用协议章节、合同条款、产品分类作为切片边界，而不是按固定字数硬切。
第三，检索条件。增加领域元数据，比如协议版本、协议编号、银行产品类型、风险分类、生效日期。
这些定制以“新增模块实现”的方式完成，不需要改全链路。模块化架构的优势就在这里：领域差异被隔离在少数几个模块里，其他部分保持通用。
6. 模块化RAG落地最容易踩的坑：排查顺序和分阶段建议
6.1 先看输入和环境，不要一上来改模型
文档加载解析环节是翻车重灾区。最常见的现象是：文档处理到中途报错，任务中止，业务方第一反应是“Embedding 模型有问题”。但大多数时候问题出在输入和环境：
- 文件其实是扫描件 PDF，但没配 OCR 组件；
- Word 或 PDF 缺少对应的读取依赖；
- 文件编码不是 UTF-8；
- 路径包含中文或空格；
- 上传大小被 Tomcat 拦截；
- 依赖版本冲突，比如某个库要求特定 Python 或 Java 版本。
排查顺序应该是：先看输入文件是否真的被读取并解析出了文本，再看切分数量，再看向量写入是否成功。如果解析层都没有输出有效文本，后面的模块再怎么调都没有意义。
6.2 检索不准的排查链路
出现“相关的问题都召不回”时，不要急着换向量库。先做一个小实验：手动从知识库里找到正确答案对应的文档片段，用当前 Embedding 计算它和问题的相似度。
如果相似度本身就不高，说明 Embedding 模型选型或切分方式有问题。这时候换一个 Embedding 模型，或者调整切分策略，比检查向量库配置更有用。
如果相似度很高但仍然排不在前面，说明候选过多或排序策略有问题。这时候需要加元数据过滤、调整 TopK，或者接入重排模型。
6.3 答案幻觉严重的排查链路
生成结果幻觉严重的根源，通常是生成阶段没有拿到足够支持“回答该问题”的内容。排查顺序：
- 先看检索召回的内容是否覆盖问题的关键信息；
- 再看 Prompt 里是否明确“只能根据给定资料回答，资料不足时直接说不知道”；
- 再看是否把所有召回结果无差别塞进 Prompt，如果质量差的内容太多，生成模型容易被带偏；
- 最后看是否需要做召回内容与问题的相关性检验，不相关的召回直接拦截。
这些步骤都有一个前提：召回结果和生成结果之间可以单独观察和调试。这又回到了模块化架构的价值。
6.4 分阶段落地的建议顺序
我建议按下面这个顺序推进：
第一阶段，打通单条链路。只跑通一个文件、一次问答的最小闭环，不追求全格式支持。
第二阶段，建立评测集。把检索指标和生成指标跑出来，形成基线。这一步越早做越好，否则后面所有优化都没有参照。
第三阶段，逐模块优化。每次只改一个模块，用评测集验证效果变化。替换切分策略、换 Embedding 模型、接入重排模型、调整 Prompt，逐个做 A/B 对比。
第四阶段，产品化。处理并发、权限、任务状态、日志、监控、失败重试。这时候模块化的收益最明显，因为每个模块都可以独立监控和扩容。
不要第一个版本就做“全都要”。模块化是给后续优化留空间，不是让第一版变复杂。
最后留一个经验
个人更建议把注意力放在“模块边界”和“评测链路”上，而不是纠结哪个框架更热门。RAG 技术更新很快，今天用向量库，明天可能换图数据库；今天用这个模型，明天可能换另一个。真正让一个 RAG 项目长期可维护的，不是某一个模型或框架，而是清晰的模块边界、稳定的接口、可复现的评测方法和一套能在设备资源有限的环境里跑通的降级路径。
很多问题看起来像“模型能力不够”，实际是切分粒度不对、检索条件缺失、Prompt 指令模糊、日志不完整。先把模块拆分做好，再去看每一项指标的波动，你会发现 RAG 系统的稳定性，远比想象中更容易控制。
