OpenBMB/UltraRAG — 面向复杂检索增强生成场景的 RAG 框架

更少代码，更低门槛，更快部署

简体中文  |  English

最新动态 🔥

• [2026.01.23] 🎉 UltraRAG 3.0 发布：告别"黑盒"开发——让每一行推理逻辑都清晰可见 👉 📖 博客
• [2026.01.20] 🎉 AgentCPM-Report 模型发布！DeepResearch 终于本地化了：8B 端侧写作智能体 AgentCPM-Report 开源 👉 🤗 模型

💡 关于 UltraRAG

UltraRAG 是首个基于 模型上下文协议 (MCP) 架构设计的轻量级 RAG 开发框架，由清华大学 THUNLP、东北大学 NEUIR、OpenBMB 和 AI9stars 联合推出。

专为研究探索和工业原型设计而打造，UltraRAG 将核心 RAG 组件（检索器、生成器等）标准化为独立的 MCP 服务器，并结合 MCP 客户端强大的工作流编排能力。开发者仅通过 YAML 配置文件，即可实现对条件分支、循环等复杂控制结构的精准编排。

🖥️ UltraRAG UI

UltraRAG UI 超越了传统聊天界面的界限，演变为一个集编排、调试与演示于一体的可视化 RAG 集成开发环境。

该系统内置强大的 Pipeline 构建器，支持"画布构建"与"代码编辑"的双向实时同步，允许对流水线参数和提示词进行精细的在线调整。此外，它引入了智能 AI 助手，赋能从流水线结构设计到参数调优和提示词生成的整个开发生命周期。构建完成的逻辑流可一键转换为交互式对话系统。系统无缝集成了知识库管理组件，使用户能够构建自定义知识库进行文档问答。这真正实现了从底层逻辑构建、数据治理到最终应用部署的一站式闭环。

https://github.com/user-attachments/assets/fcf437b7-8b79-42f2-bf4e-e3b7c2a896b9

✨ 核心亮点

📦 安装

我们提供两种安装方式：本地源码安装（推荐使用 uv 进行包管理）和 Docker 容器部署。

方式一：源码安装

我们强烈建议使用 uv 来管理 Python 环境和依赖，它可以极大地提升安装速度。

准备环境

如果你尚未安装 uv，请执行：

## 直接安装
pip install uv
## 下载
curl -LsSf https://astral.sh/uv/install.sh | sh

下载源码

git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG

安装依赖

根据你的使用场景，选择以下模式之一安装依赖：

A: 创建新环境 使用 uv sync 自动创建虚拟环境并同步依赖：

• 核心依赖：如果你只需要运行基础核心功能，例如仅使用 UltraRAG UI：
  shell uv sync

• 完整安装：如果你想完整体验 UltraRAG 的检索、生成、语料处理与评估功能，请运行：
  shell uv sync --all-extras

• 按需安装：如果你只需要运行特定模块，按需保留相应的 --extra，例如：

shell uv sync --extra retriever # 仅检索模块 uv sync --extra generation # 仅生成模块

安装完成后，激活虚拟环境：

# Windows CMD
.venv\Scripts\activate.bat

# Windows Powershell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

B: 安装到现有环境 要将 UltraRAG 安装到你当前活动的 Python 环境中，请使用 uv pip：

# 核心依赖
uv pip install -e .

# 完整安装
uv pip install -e ".[all]"

# 按需安装
uv pip install -e ".[retriever]"

方式二：Docker 容器部署

如果你不想配置本地 Python 环境，可以使用 Docker 进行部署。

获取代码和镜像

# 1. 克隆仓库
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG

# 2. 准备镜像（选择其一）
# 选项 A：从 Docker Hub 拉取
docker pull hdxin2002/ultrarag:v0.3.0-base-cpu # 基础版 (CPU)
docker pull hdxin2002/ultrarag:v0.3.0-base-gpu # 基础版 (GPU)
docker pull hdxin2002/ultrarag:v0.3.0          # 完整版 (GPU)

# 选项 B：本地构建
docker build -t ultrarag:v0.3.0 .

启动容器

# 启动容器（默认映射 5050 端口）
docker run -it --gpus all -p 5050:5050 <docker_image_name>

注意：容器启动后，UltraRAG UI 会自动运行。你可以直接在浏览器中访问 http://localhost:5050 使用。

验证安装

安装完成后，运行以下示例命令检查环境是否正常：

ultrarag run examples/experiments/sayhello.yaml

如果你看到以下输出，说明安装成功：

Hello, UltraRAG v3!

🚀 快速开始

我们提供从入门到进阶的完整教程示例。无论你是进行学术研究还是构建工业应用，都能在此找到指导。欢迎访问文档了解更多细节。

🔬 研究实验

为研究人员设计，提供数据、实验工作流和可视化分析工具。
- 入门指南：学习如何基于 UltraRAG 快速运行标准 RAG 实验工作流。
- 评估数据：下载 RAG 领域最常用的公开评估数据集和大规模检索语料，可直接用于研究基准测试。
- 案例分析：提供可视化的案例研究界面，深度追踪工作流的每个中间输出，辅助分析和错误归因。
- 结构化调试指南（中文）：当答案可疑、检索命中不稳、推理链漂移或部署后行为异常时，从输入与检索、推理与规划、状态与上下文、部署与运行时四个层面进行排查。
- 代码集成：学习如何在 Python 代码中直接调用 UltraRAG 组件，实现更灵活的定制化开发。

🛠️ Demo 系统

为开发者和最终用户设计，提供完整的 UI 交互和复杂应用案例。
- 快速上手：学习如何启动 UltraRAG UI 并在管理员模式下熟悉各种高级配置。
- 部署指南：详细的生产环境部署教程，涵盖检索器、生成模型和 Milvus 向量数据库的配置。
- 深度研究：旗舰案例，部署一个 Deep Research Pipeline。结合 AgentCPM-Report 模型，可自动进行多步检索与整合，生成数万字的调研报告。

🤝 贡献

感谢以下贡献者的代码提交和测试。我们也欢迎新成员加入，共同构建完整的 RAG 生态系统！

你可以通过标准流程贡献：Fork 此仓库 → 提交 Issues → 创建 Pull Requests (PRs)。

⭐ 支持我们

如果你觉得这个仓库对你的研究有帮助，请考虑给我们一个 ⭐ 以示支持。

💬 联系我们

• 对于技术问题和功能请求，请使用 GitHub Issues。
• 关于使用问题、反馈或任何与 RAG 技术相关的讨论，欢迎加入我们的 微信群、飞书群 和 Discord 与我们交流。
• 如果您有任何问题、反馈或希望与我们取得联系，请随时通过电子邮件 yanyk.thu@gmail.com 联系我们。

微信交流群

飞书交流群

Discord

📖 出版物

论文

1. Shi Yu, Chaoyue Tang, Bokai Xu, Junbo Cui, Junhao Ran, Yukun Yan, Zhenghao Liu, Shuo Wang, Xu Han, Zhiyuan Liu, Maosong Sun. (2025) VisRAG: 基于视觉的多模态文档检索增强生成. arXiv:2410.10594 并在 第十三届国际学习表征大会 (ICLR 2025) 论文集 中发表。

2. Xinze Li, Sen Mei, Zhenghao Liu, Yukun Yan, Shuo Wang, Shi Yu, Zheni Zeng, Hao Chen, Ge Yu, Zhiyuan Liu, Maosong Sun, Chenyan Xiong. (2025) RAG-DDR: 利用可微数据奖励优化检索增强生成. arXiv:2410.13509 并在 第十三届国际学习表征大会 (ICLR 2025) 论文集 中发表。

3. Kunlun Zhu, Yifan Luo, Dingling Xu, Yukun Yan, Zhenghao Liu, Shi Yu, Ruobing Wang, Shuo Wang, Yishan Li, Nan Zhang, Xu Han, Zhiyuan Liu, Maosong Sun. (2025) RAGEval: 场景特定的 RAG 评估数据集生成框架. arXiv:2408.01262 并在 第63届计算语言学会年会 (ACL 2025) 论文集 中发表。

4. Ruobing Wang, Qingfei Zhao, Yukun Yan, Daren Zha, Yuxuan Chen, Shi Yu, Zhenghao Liu, Yixuan Wang, Shuo Wang, Xu Han, Zhiyuan Liu, Maosong Sun. (2025) DeepNote: 以笔记为中心的深度检索增强生成. arXiv:2410.08821 并在 计算语言学协会发现：EMNLP 2025 中发表。

模型

1. Yishan Li, Wentong Chen, Yukun Yan, Mingwei Li, Sen Mei, Xiaorong Wang, Kunpeng Liu, Xin Cong, Shuo Wang, Zhong Zhang, Yaxi Lu, Zhenghao Liu, Yankai Lin, Zhiyuan Liu, Maosong Sun. (2026) AgentCPM-Report: 交织草稿与深化实现开放端深度研究. arXiv:2602.06540.

2. OpenBMB. MiniCPM-Embedding-Light. Hugging Face 模型卡.