开源一个工程化 RAG 工作台：把文档加载、分块、向量化、检索、生成串成完整闭环开源一个工程化 RAG 工作台，打通文档

支持 20+ 文档格式、智能分块推荐、Embedding 模型推荐、Hybrid Retrieval、流式生成与来源引用。我想做的不是“跑通一条链”，而是一套能持续迭代的 RAG 工作台。

这几年看下来，RAG 项目很多，但真正让我觉得“能继续做下去”的并不多。大部分项目的问题并不是不能跑，而是只能跑一次: 传个文件、切个块、调个 Embedding、做个向量检索、拼个 Prompt，然后就结束了。

一旦你真的想把它拿去做内部知识库、业务验证、产品原型，问题就会立刻冒出来：文档怎么标准化解析，分块怎么按文档特征调优，Embedding 模型怎么选，索引怎么管理，检索怎么做质量治理，生成结果怎么做引用和历史管理。

所以我最近把自己做的一套端到端 RAG 项目整理成了一个开源仓库 RAG Pipeline Hub。它不是为了证明“RAG 可以跑通”，而是想回答另一个更现实的问题：能不能把 RAG 的每个环节都做成可配置、可调试、可复用、可查看结果的工程模块。

项目地址：

GitHub: https://github.com/qingni/rag-pipeline-hub

这是这个系列的第一篇。我先不展开某一个模块的实现细节，而是先把这个项目为什么做、解决什么问题、整体架构长什么样、每个模块分别负责什么讲清楚。

如果你也在做 RAG、知识库问答、企业内部检索增强系统，或者正在把一个 AI Demo 往工程化方向推进，这篇文章应该会比较对味。

为什么我想做这个项目

过去一段时间，我看过不少 RAG 项目，也自己做过不少链路验证。一个很明显的感受是：

很多项目能跑通，但很难真正拿来持续迭代。

常见的问题大概有这些：

文档加载只是“能传文件”，但没有统一的标准化结果
分块策略写死成一个 chunk_size，很难对不同文档做针对性处理
Embedding 只是调一次模型，没有模型选型、批处理、缓存、异常处理
向量索引只是“写进库里”，没有 Collection 管理、统计、恢复、推荐能力
检索停留在简单的向量 topK，缺少混合检索、融合、精排和查询增强
生成阶段只返回一段文本，没有流式输出、来源引用和历史管理

这些问题的本质不是“功能没做完”，而是很多项目一开始就瞄准了“打通最短路径”，而不是“搭建一个可持续演进的工程系统”。

所以我想做的不是另一个 RAG Demo，而是一个更接近真实业务工作流的 RAG 平台。

这个项目想解决什么问题

RAG Pipeline Hub 的目标很明确：

把 RAG 从一条黑盒链路，拆成一套清晰、可观察、可调参、可扩展的工程化工作台。

整个项目覆盖了 6 个核心阶段：

文档加载
文档分块
文档向量化
向量索引
搜索查询
文本生成

每个阶段都不是“做完就算”，而是尽量做到下面这几件事：

能独立配置
能单独调试
能查看中间结果
能记录历史
能和上下游模块清晰衔接

这也是我理解的工程化 RAG 和普通 Demo 的一个重要区别。

项目整体定位

简单来说，RAG Pipeline Hub 是一套面向真实业务流程的端到端 RAG Framework，适合以下几类场景：

AI 应用原型开发
内部知识库问答
RAG 技术验证与方案比较
多模块拆分式研发
后续二次开发与功能扩展

技术栈上，项目采用的是比较常见但实用的一套组合：

后端：Python 3.11 + FastAPI + SQLAlchemy + LangChain
前端：Vue 3 + Vite + Pinia + Vue Router + TDesign
向量库：Milvus
模型接口：兼容 OpenAI-compatible 的 Embedding 和 LLM 服务

也就是说，这个项目不是只为“展示一个效果”而存在，而是希望成为一个比较稳定的 RAG 工程基础盘。

整体架构怎么理解

从主处理链上看，这个项目的核心流程非常清晰：

上传文档
  -> 文档解析
  -> 文档分块
  -> 文档向量化
  -> 向量索引 / Collection 管理
  -> 搜索检索
  -> 文本生成

如果再往工程视角多看一层，它并不是一条简单的串行链，而是由三层组成：

1. 主处理链

也就是用户最容易理解的那条路径：

文档上传 -> 文档解析 -> 文档分块 -> 向量化 -> 索引入库 -> 搜索检索 -> 回答生成

2. 横向支撑层

为了让这条链能真正可用，项目里还做了很多横向支撑能力：

前端工作台
FastAPI API 编排层
Service 业务层
外部模型与解析服务适配
Milvus 向量库
结果存储与历史记录
异步任务与进度流
智能推荐与查询增强

3. 核心亮点层

这部分也是我觉得它和普通 RAG Demo 拉开差距的地方：

Docling Serve + fallback loaders
智能分块策略与参数推荐
Embedding 模型智能推荐
逻辑 Collection / 物理 Collection 分层
Dense + Sparse + RRF + Reranker 的混合检索链路
流式生成 + 来源引用 + 历史记录

如果用一句话概括它的整体设计思路，就是：

把 RAG 每个阶段都做成“可以单独拿出来观察和优化”的模块。

六大模块分别做什么

接下来按顺序快速过一遍每个模块的职责。

1. 文档加载

文档加载是整条内容链的入口。它负责把不同格式的原始文件转换成统一的标准化结果，供后续模块继续消费。

当前项目支持 PDF / DOCX / XLSX / PPTX / HTML / CSV / TXT / Markdown / JSON / XML 等 20+ 种文档格式，默认以 Docling Serve 作为高质量主解析器，同时保留 fallback loaders 作为降级方案，避免解析失败时整条链路中断。

换句话说，这一层不是简单的“上传文件”，而是一个完整的文档标准化入口。

2. 文档分块

分块模块是内容处理和语义表示之间的桥梁。

很多 RAG 项目在这一层只提供一个固定的 chunk_size，但在真实场景里，不同文档的结构差异很大，按统一策略切分往往效果很一般。

所以这个项目在分块层支持了多种方式，包括：

按字数
按段落
按标题
语义分块
父子分块
混合分块

更重要的是，这一层还做了智能推荐。系统会根据文档的标题结构、代码占比、格式特征、长度等信息，推荐更适合的分块策略和参数，并给出置信度和推荐理由。

这部分我后面会单独展开，因为它是整个项目里非常关键的一块。

3. 文档向量化

向量化模块负责把分块后的内容转换成可检索的向量表示。

但在工程项目里，向量化远远不只是“调用一下 Embedding API”。它还涉及：

模型选型
批量处理
缓存复用
重试机制
进度反馈
结果持久化

当前项目支持 bge-m3、qwen3-embedding-8b、qwen3-vl-embedding-8b 等模型，并且内置了模型推荐能力。系统会结合文档语言、领域特征和多模态特征，推荐更适合的 Embedding 模型。

这也是我想重点避免的一件事：让“向量化”变成一个只能盲选模型的黑盒步骤。

4. 向量索引

很多人做 RAG 时，会把“向量写进库里”当成索引层的全部工作。

但如果真的要把系统跑起来，索引层通常还得负责：

Index 管理
Collection 管理
向量写入与删除
统计信息
持久化与恢复
检索能力支撑

在这个项目里，向量索引模块基于 Milvus 构建，并且不仅仅把它当成一个存储容器，而是作为可管理、可恢复、可扩展的检索基础设施来设计。

项目里还考虑了逻辑 Collection 与物理 Collection 的分层，以及为混合检索预留 sparse 能力，这些都属于一开始看不到、但做大以后一定会遇到的问题。

5. 搜索查询

如果说分块和向量化决定了“能不能找到内容”，那搜索查询决定的就是“找出来的内容质量怎么样”。

这一层我没有停留在简单的向量 topK 检索，而是尽量把真实业务里常见的质量治理链路串了起来：

Dense Recall
Sparse Recall
RRF 融合
Reranker 精排
Query Enhancement

这意味着它不是“查一下库返回结果”那么简单，而是围绕“结果相关性”和“检索稳定性”做了一整套编排。

对我来说，RAG 项目真正拉开差距的地方，很多时候就在检索层。

6. 文本生成

文本生成模块是整套系统面向最终用户的交付层。

很多 Demo 到这一步就结束了：把检索结果拼进 Prompt，调用一下 LLM，返回一段文本。

但在产品化场景里，通常还需要更多能力：

同步生成
SSE 流式输出
来源引用
历史记录
取消生成
Markdown 安全渲染

所以这一层在本项目里的目标，不是“让模型回答出来”，而是让最终交互体验更接近一个真实可用的知识库产品。

这个项目有哪些我比较看重的亮点

如果只挑几个最能代表项目特点的点，我会选下面 6 个：

1. 20+ 文档格式支持

RAG 的第一步永远是内容接入。格式支持越丰富，项目能覆盖的场景就越多。

2. `Docling Serve + fallback loaders`

这解决的是“解析质量”和“系统稳定性”之间的平衡问题。高质量主解析器负责效果，fallback 负责兜底。

3. 智能分块推荐

分块不是只改 chunk_size 就能解决的。能针对文档特征做策略和参数推荐，才更接近真实项目需求。

4. Embedding 模型推荐

向量化模型不应该让用户盲选。不同语言、领域、内容形态下，模型适配度本来就不一样。

5. Hybrid Retrieval

Dense + Sparse + RRF + Reranker 这套链路，本质上是在做检索质量治理，而不是只做“检索功能”。

6. 流式生成与来源引用

真正可用的 RAG，不只是“答出来”，而是要让用户知道答案来自哪里，并且在交互体验上足够顺畅。

这个项目适合谁

如果你属于下面这些角色，我觉得这个项目会比较有参考价值：

正在做 RAG 或知识库问答的后端工程师
希望把 AI Demo 往工程化落地推进的全栈开发者
想研究完整 RAG 链路拆分方式的架构师
想快速搭一个可演示原型的产品团队
想对比不同链路设计方案的 AI 应用开发者

如果你只是想看一个最简的“几百行代码跑通 RAG”，那这个项目可能不是最轻量的选择。

但如果你更关注“模块边界、调试能力、工程扩展性、链路可观测性”，它会更适合你。

现在已经具备了哪些能力

目前这个项目已经包含：

FastAPI 后端
Vue 3 前端工作台
六大核心模块
模块化文档体系
快速启动脚本
基于 Milvus 的向量检索基础设施

前端目前也已经提供了对应页面入口：

/documents/load
/documents/chunk
/documents/embed
/index
/search
/generation

也就是说，它已经不是一个“停留在概念图”的项目，而是一套可以实际跑起来、可以继续演进的工作台雏形。

如何快速跑起来

如果你想本地体验，项目的基本启动条件并不复杂：

Python 3.11+
Node.js 18+
Docker 或 Colima
可用的 OpenAI-compatible Embedding / LLM 服务

核心启动步骤大致是：

git clone https://github.com/qingni/rag-pipeline-hub.git
cd rag-pipeline-hub

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

./scripts/start_milvus.sh
./scripts/start_backend.sh
./scripts/start_frontend.sh

如果你想启用更高质量的解析链路，也可以额外启动 Docling Serve。

后面如果大家感兴趣，我也可以单独写一篇“怎么把这个项目本地完整跑起来”的实战文章，把环境配置、模型服务接入和常见坑都整理出来。

为什么我要按模块写这个系列

这篇文章只是开个头。

对这个项目来说，真正值得展开讲的，不是“我做了一个 RAG 项目”，而是下面这些更具体的工程问题：

文档加载为什么不能只做上传
分块为什么不能只改 chunk_size
向量化为什么不只是调个 Embedding API
向量索引为什么不只是把向量塞进 Milvus
检索为什么不能只做向量 topK
生成层为什么必须考虑流式、引用和历史记录

所以接下来我会把这个系列继续写下去，按模块逐篇拆开。

目前已经规划好的主题包括：

文档加载模块设计
文档分块与智能推荐
向量化与模型推荐
向量索引与 Collection 管理
搜索查询与混合检索链路
文本生成与最终交互体验

下一篇我准备先写：

《RAG 的第一步不是 Embedding，而是高质量文档解析：文档加载模块设计实战》

最后

如果你看到这里，说明你大概率也已经不满足于“再看一个能跑通的 RAG Demo”了，而是更关心：

每个模块的边界怎么划分
检索质量怎么持续优化
中间结果怎么观察和调试
一套 RAG 系统怎么真正具备演进能力

这也是我把 RAG Pipeline Hub 开源出来的原因。希望它不只是一个仓库链接，而是能成为大家讨论工程化 RAG 设计、实现和取舍的一个起点。