UltraRAG

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/ultrarag_dark.svg"> <source media="(prefers-color-scheme: light)" srcset="./docs/ultrarag.svg"> <img alt="UltraRAG" src="./docs/ultrarag.svg" width="55%"> </picture> </p> <h3 align="center"> 更少代码，更低门槛，更快实现 </h3> <p align="center"> | <a href="https://ultrarag.openbmb.cn"><b>教程文档</b></a> | <a href="https://github.com/OpenBMB/UltraRAG/tree/rag-paper-daily/rag-paper-daily"><b>每日论文</b></a> | <b>简体中文</b> | <a href="./docs/README-English.md"><b>English</b></a> | </p> --- *更新日志* 🔥 - [2025.11.11] 🎉 UltraRAG 2.1 更新：强化知识接入与多模态支持，完善统一评估体系！ <details> <summary>历史更新</summary> - [2025.09.23] 新增每日 RAG 论文分享，每日更新最新前沿 RAG 工作 👉 |[📖 论文](https://github.com/OpenBMB/UltraRAG/tree/rag-paper-daily/rag-paper-daily)| - [2025.09.09] 发布轻量级 DeepResearch Pipeline 本地搭建教程 👉 |[📺 bilibili](https://www.bilibili.com/video/BV1p8JfziEwM/?spm_id_from=333.337.search-card.all.click)|[📖 博客](https://github.com/OpenBMB/UltraRAG/blob/page/project/blog/cn/01_build_light_deepresearch.md)| - [2025.09.01] 发布 UltraRAG 安装与完整 RAG 跑通视频 👉 |[📺 bilibili](https://www.bilibili.com/video/BV1B9apz4E7K/?share_source=copy_web&vd_source=7035ae721e76c8149fb74ea7a2432710)|[📖 博客](https://github.com/OpenBMB/UltraRAG/blob/page/project/blog/cn/00_Installing_and_Running_RAG.md)| - [2025.08.28] 🎉 发布 UltraRAG 2.0！UltraRAG 2.0 全新升级：几十行代码实现高性能 RAG，让科研专注思想创新！ - [2025.01.23] 发布 UltraRAG！让大模型读懂善用知识库！我们保留了UltraRAG 1.0的代码，可以点击 [v1](https://github.com/OpenBMB/UltraRAG/tree/v1) 查看。 </details> --- ## UltraRAG v2：面向科研的“RAG实验”加速器 检索增强生成系统（RAG）正从早期“检索+生成”的简单拼接，走向融合 **自适应知识组织**、**多轮推理**、**动态检索** 的复杂知识系统。但这种复杂度的提升，使科研人员在 **方法复现**、**快速迭代新想法** 时，面临着高昂的工程实现成本。 为了解决这一痛点，清华大学 [THUNLP](https://nlp.csai.tsinghua.edu.cn/) 实验室、东北大学 [NEUIR](https://neuir.github.io) 实验室、[OpenBMB](https://www.openbmb.cn/home) 与 [AI9stars](https://github.com/AI9Stars) 联合推出 UltraRAG v2 —— 首个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) 架构设计的 RAG 框架。这一设计让科研人员只需编写 YAML 文件，就可以直接声明串行、循环、条件分支等复杂逻辑，从而以极低的代码量快速实现多阶段推理系统。 其核心思路是： - 组件化封装：将RAG 的核心组件封装为**标准化的独立 MCP Server**； - 灵活调用与扩展：提供 **函数级 Tool** 接口，支持功能的灵活调用与扩展； - 轻量流程编排：借助 **MCP Client**，建立自上而下的简洁化链路搭建； 与传统框架相比，UltraRAG v2 显著降低了复杂 RAG 系统的 **技术门槛与学习成本**，让研究者能够将更多精力投入到 **实验设计与算法创新** 上，而不是陷入冗长的工程实现。 ## 🌟 核心亮点 - 🚀 **低代码构建复杂 Pipeline** - 原生支持 **串行、循环、条件分支** 等推理控制结构。开发者只需编写 YAML 文件，即可实现几十行代码构建的 **迭代式 RAG 流程**。 - 🖼️ **原生多模态支持：检索、生成、评估一体化** - 统一检索、生成与评估，构建真正意义上的 多模态 RAG 全链路； - 实现从 本地 PDF 建库 → 多模态检索 → 多模态生成 的闭环流程，显著提升复杂文档场景下的理解与问答能力。 - ⚡ **快速复现与功能扩展** 基于 **MCP 架构**，所有模块均封装为独立、可复用的 **Server**。 - 用户可按需自定义 Server 或直接复用现有模块； - 每个 Server 的功能以函数级 **Tool** 注册，新增功能仅需添加一个函数即可接入完整流程； - 同时支持调用 **外部 MCP Server**，轻松扩展 Pipeline 能力与应用场景。 - 📚 **知识接入与语料构建自动化** - 支持 PDF、Markdown、HTML、TXT 等多格式文档解析与分块建库； - 与 MinerU 无缝集成，自动完成结构化抽取、多模态切块（文本/表格/图片）； - 一键构建个人化与企业级知识库，适用于科研、企业文档、私有知识管理等场景。 - 🔗 统一构建与评估的 RAG 工作流 - 同时适配多种检索引擎与多种生成推理后端； - 内置标准化评估体系，支持全链路可视化调试与结果分析； - 📊 **统一评测与对比** 内置 **标准化评测流程与指标管理**，开箱即用支持多个主流科研 Benchmark。 - 持续集成最新基线； - 方便科研人员进行系统性对比与优化实验。 ## 秘诀：MCP 架构与原生流程控制 在不同的 RAG 系统中，检索、生成等核心能力在功能上具有高度相似性，但由于开发者实现策略各异，模块之间往往缺乏统一接口，难以跨项目复用。[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) 作为一种开放协议，规范了为大型语言模型（LLMs）提供上下文的标准方式，并采用 **Client–Server** 架构，使得遵循该协议开发的 Server 组件可以在不同系统间无缝复用。 受此启发，UltraRAG v2 基于 **MCP 架构**，将 RAG 系统中的检索、生成、评测等核心功能抽象并封装为相互独立的 **MCP Server**，并通过标准化的函数级 **Tool 接口**实现调用。这一设计既保证了模块功能扩展的灵活性，又允许新模块以“热插拔”的方式接入，无需对全局代码进行侵入式修改。在科研场景中，这种架构让研究者能够以极低的代码量快速适配新的模型或算法，同时保持整体系统的稳定性与一致性。 <p align="center"> <picture> <img alt="UltraRAG" src="./docs/architecture.png" width=90%> </picture> </p> 复杂 RAG 推理框架的开发具有显著挑战，而 UltraRAG v2 之所以能够在**低代码**条件下支持复杂系统的构建，核心在于其底层对多结构 **Pipeline 流程控制**的原生支持。无论是串行、循环还是条件分支，所有控制逻辑均可在 YAML 层完成定义与调度，覆盖复杂推理任务所需的多种流程表达方式。在实际运行中，推理流程的调度由内置 **Client** 执行，其逻辑完全由用户编写的外部 **Pipeline YAML 脚本** 脚本描述，从而实现与底层实现的解耦。开发者可以像使用编程语言关键字一样调用 loop、step 等指令，以声明的方式快速构建多阶段推理流程。 通过将 **MCP 架构** 与 **原生流程控制**深度融合，UltraRAG v2 让复杂 RAG 系统的搭建像“编排流程”一样自然高效。此外，框架内置多个主流 benchmark 任务与多种高质量 baseline，配合统一的评测体系与知识库支持，进一步提升了系统开发的效率与实验的可复现性。 ## 安装 ### 使用 Conda 创建虚拟环境： ```shell conda create -n ultrarag python=3.11 conda activate ultrarag ``` 通过 git 克隆项目到本地或服务器： ```shell git clone https://github.com/OpenBMB/UltraRAG.git --depth 1 cd UltraRAG ``` 我们推荐使用 uv 来进行包管理，提供更快、更可靠的 Python 依赖管理体验： ```shell pip install uv uv pip install -e . ``` 如果您更习惯 pip，也可以直接运行： ```shell pip install -e . ``` 运行以下命令验证安装是否成功： ```shell # 成功运行显示'Hello, UltraRAG 2.0!' 欢迎语 ultrarag run examples/sayhello.yaml ``` 【可选】UltraRAG v2 支持丰富的Server组件，开发者可根据实际任务灵活安装所需依赖： ```shell # Retriever/Reranker Server依赖： # infinity uv pip install infinity_emb # sentence_transformers uv pip install sentence_transformers # openai uv pip install openai # bm25 uv pip install bm25s # faiss（需要根据自己的硬件环境，手动编译安装 CPU 或 GPU 版本的 FAISS） # CPU版本： uv pip install faiss-cpu # GPU 版本（示例：CUDA