UltraRAG​翻译站点

UltraRAG 是 OpenBMB 团队联合清华大学 THUNLP、东北大学 NEUIR、AI9Stars 共同推出的基于 MCP 架构的轻量级 RAG 开发框架，Apache-2.0 许可。

它是首个基于 Model Context Protocol（MCP）架构设计的轻量级 RAG 开发框架​ ，将 Retriever、Generation 等核心 RAG 组件标准化封装为独立的 MCP Server，开发者通过 YAML 配置即可精确编排条件分支、循环等复杂控制结构 。

v3.0 进一步演化为可视化 RAG 集成开发环境（IDE）——画布构建与代码编辑双向实时同步、一键将 Pipeline 逻辑转化为交互式 Web UI、白盒推理链可视化（”Show Thinking”面板）、内置智能开发助手 。官方定位：”A Low-Code MCP Framework for Building Complex and Innovative RAG Pipelines” 。它是 RAG 分类中“低代码 RAG 流程编排与科研原型框架”的代表作，与 FastGPT（企业级 Agent 构建平台）、RAGFlow（深度文档解析引擎）、R2R（生产级 RAG API 引擎）、Onyx Cloud（企业搜索 AI 平台）、PrivateGPT（隐私离线文档 RAG）、PaperQA2（科研文献高精度 RAG 库）、Quivr（第二大脑式 RAG 平台）形成清晰的差异化。

 

产品概述

UltraRAG 于 2025 年 1 月 23 日首次发布 ，2026 年 1 月 23 日发布的 v3.0 标志着其从”轻量级 RAG 开发框架”演进为”可视化 RAG IDE” 。项目由清华大学 THUNLP 张正副教授团队、东北大学 NEUIR、面壁智能（ModelBest）、AI9Stars 联合推出 。

 

核心定位哲学：

官方 GitHub 描述开宗明义——”UltraRAG is the first lightweight RAG development framework based on the Model Context Protocol (MCP) architecture design… Designed for research exploration and industrial prototyping” 。三个不可妥协的设计原则：

• MCP 架构：将 RAG 核心组件（Retriever、Generation 等）标准化为独立的 MCP Server，实现函数级 Tool 接口的灵活扩展
• 低代码编排：开发者仅需编写 YAML 配置文件，即可在数十行代码内实现复杂的迭代式 RAG 逻辑（串行、循环、条件分支）
• 白盒透明：v3.0 引入”Show Thinking”面板，对复杂长链任务的每一次循环、分支、决策细节进行像素级实时可视化

 

它做什么 / 不做什么（关键归类）：

• ✅ 做：作为开发框架运行 → 接收 YAML Pipeline 定义 → MCP Client 调度各 MCP Server（Retriever/Generator/Embedder 等）→ 执行复杂控制结构（串行/循环/条件分支）→ 通过 UI 层一键生成交互式 Web UI → 在此之上提供可视化 IDE（画布+代码双向同步）、统一评测与基准对比、多模态 RAG（文本/图像/音频/视频）、Agentic 研究循环（state-machine 路由 gather/plan/write）
• ❌ 不做：不做企业级 SaaS 平台（这是 FastGPT/Onyx Cloud 的定位）、不做深度文档解析优化（这是 RAGFlow 的能力）、不做生产级 REST API 引擎（这是 R2R 的能力）、不面向业务用户提供可视化工作流编排器
• 本质是低代码 RAG 流程编排与科研原型框架：它是 RAG 分类中唯一的”基于 MCP 架构 + YAML 低代码 + 可视化 IDE + 白盒推理”的框架——LangChain/LlamaIndex 是通用框架（需自己拼装），FastGPT 是业务级 Agent 平台，UltraRAG 是科研与工业原型导向的 RAG 流程编排框架，核心价值在”流程可复现、推理可见、一键交付”。

 

技术架构​ ：

UltraRAG 采用四层核心抽象 ：

 

v3.0 关键升级​ ：

• 可视化 RAG IDE：画布模式（Canvas Mode）与代码模式（Code Mode）双向实时同步
• 白盒推理可视化：”Show Thinking”面板像素级展示循环/分支/工具调用的每一步
• 内置智能开发助手：AI 助手理解框架语义，通过自然语言交互生成 Pipeline 配置与优化 Prompt
• 一键逻辑到应用：YAML 定义即应用，静态代码瞬间变为交互式 Demo
• Agentic 研究循环：state-machine 在 gathering、planning、writing 间路由，产出长表单研究报告

 

多模态能力​ ：

UltraRAG 3.0 内置多模态嵌入（Sentence Transformers v5.4），支持文本、图像、音频、视频的同时编码 ；将向量检索与视觉记忆图（Multimodal Memory Graph）结合，参考 Alibaba VimRAG 的图结构记忆设计 。

 

部署形态​ ：

• 源码安装：推荐 uv 管理 Python 环境，uv pip install -e .
• Docker 部署：docker compose up --build -d 标准化环境
• 本地研究智能体：支持离线运行，保障数据隐私
• 环境要求：Python 3.10+，CUDA 12.2+（GPU 模式）
• Web UI 访问：http://localhost:8843

 

许可策略：Apache-2.0 许可证 ，允许商用、修改、分发，明确包含专利授权条款，与 PaperQA2/Quivr 同属最干净许可阵营。

 

社区与治理​ ：

• 主仓库：GitHub OpenBMB/UltraRAG
• 沟通渠道：GitHub Issues、微信群、飞书群、Discord
• 治理：OpenBMB 维护，遵循 Contributor Covenant 行为准则
• 配套资源：开源数据集 UltraRAG_Benchmark（ModelScope）

💡 与同层 RAG 项目的关键差异：

• vs FastGPT：FastGPT 是”企业级 Agent 构建平台”，可视化工作流编排+知识库 RAG，面向业务用户；UltraRAG 是”低代码 RAG 开发框架”，YAML 编排+可视化 IDE，面向科研与开发者
• vs RAGFlow：RAGFlow 是”深度文档理解引擎”，擅长复杂文档精准解析；UltraRAG 是”RAG 流程编排框架”，文档解析依赖集成
• vs R2R：R2R 是”生产级 RAG API 引擎”，RESTful API 优先；UltraRAG 是”开发框架”，不提供生产级 REST API 表面
• vs Onyx Cloud：Onyx Cloud 是”企业搜索 AI 平台”，40+ 连接器；UltraRAG 是科研原型框架，连接器需自行集成
• vs PrivateGPT：PrivateGPT 是”隐私优先离线文档 RAG”；UltraRAG 支持本地研究智能体离线运行，但默认依赖外部 LLM API
• vs PaperQA2：PaperQA2 是科研文献垂直高精度 RAG 库；UltraRAG 是通用 RAG 流程编排框架，可复现 PaperQA2 类科研 RAG 方法
• vs Quivr：Quivr 是”第二大脑式 RAG 平台”，Opinionated 默认配置；UltraRAG 是低代码框架，流程完全可定制可复现

 

 

核心能力

 

-MCP 架构与原子化 Server（核心差异化）

• MCP Server 标准化：Retriever、Generation、Embedder 等核心组件封装为独立 MCP Server
• 函数级 Tool 扩展：新功能仅需以函数级 Tool 形式注册，即可无缝接入流程
• 极高复用性：原子化 Server 实现模块级复用与组合
• Client 调度中枢：MCP Client 解析 YAML Pipeline，统一协调各 Server 间调用与数据传递

 

-YAML 低代码编排

• 复杂控制结构：原生支持串行、循环、条件分支
• 数十行代码实现迭代 RAG：开发者仅需编写 YAML 配置文件
• 流程可复现：YAML 作为单一事实源，确保实验可复现
• 自然语言生成 Pipeline：v3.0 内置智能开发助手，通过自然语言交互生成 Pipeline 配置

 

-可视化 RAG IDE（v3.0 核心）

• 画布模式（Canvas Mode）：UI 组件直观组装 Loop/Branch 等复杂逻辑，像搭积木
• 代码模式（Code Mode）：直接编辑 YAML，画布实时渲染更新
• 双向实时同步：画布与代码模式双向实时同步
• 一键构建：点击”Build”按钮，系统自动逻辑自检与语法验证，动态生成参数配置面板
• 逻辑即应用：YAML 定义即应用，静态代码瞬间变为交互式 Demo

 

-白盒推理可视化

• “Show Thinking”面板：像素级实时可视化模型”思考”全过程
• 全链透明：从复杂循环分支到具体工具调用，所有中间状态结构化流式呈现
• Bad Case 快速定位：直接在界面对比检索切片与最终答案，判断问题在”数据层噪声”还是”模型层幻觉”
• 长链任务追踪：DeepResearch 等复杂长流程任务实时追踪执行进度

 

-Agentic 研究循环

• State-Machine 路由：在 gathering、planning、writing 间路由任务
• 长表单研究报告：自主检索与推理循环，产出综合性长表单研究报告
• 递归收集与综合：自主智能体通过递归收集与综合发现执行多步研究

 

-统一评测与基准对比

• 标准化评测流程：内置开箱即用的主流科研 Benchmark
• 统一指标管理：通过统一指标管理与基线集成，提升实验可复现性
• RAGEval 方法：自研多维多阶段稳健式评估，提升”模型评估”稳健性
• KBAlign / RAG-DDR：自研数据构建与模型微调方法一键式系统化

 

-多模态 RAG

• 多模态嵌入：Sentence Transformers v5.4 多模态嵌入，支持文本/图像/音频/视频同时编码
• 视觉记忆图：参考 Alibaba VimRAG 的图结构记忆设计
• 跨模态检索：文本与图像映射到共享向量空间进行跨模态数据搜索
• VisRAG：内置多模态 RAG 方案

 

-知识库全生命周期管理

• 文档摄入：上传、分块、嵌入管理全流程
• 向量库集成：支持 Milvus 等外部向量库
• 文档解析：多格式文档解析（PDF/DOCX/PPTX 等）

 

-灵活部署

• 源码安装：uv 管理 Python 环境
• Docker 部署：标准化容器环境
• 本地离线运行：本地研究智能体模式，保障数据隐私与离线操作
• Web UI：http://localhost:8843 访问

 

优势亮点

• Apache-2.0 最干净许可：与 PaperQA2/Quivr 同属最宽松许可阵营，含专利授权，商用友好
• 首个 MCP 架构 RAG 框架：基于 Model Context Protocol 标准化 RAG 组件，是 MCP 生态在 RAG 领域的先行者
• YAML 低代码编排：数十行代码实现复杂迭代 RAG 逻辑，相比 LangChain 大幅降低流程编排成本
• 可视化 RAG IDE（v3.0）：画布+代码双向同步、白盒推理可视化、内置 AI 开发助手——RAG 框架中独一无二的 IDE 体验
• 白盒推理透明度：”Show Thinking”面板像素级展示每一步循环/分支/工具调用，Debug 效率革命性提升
• 科研友好：内置 THUNLP-RAG 组自研方法及其他前沿 RAG 方法，统一评测与基准对比，实验可复现性极强
• 多模态 RAG：文本/图像/音频/视频统一编码，视觉记忆图跨模态检索
• 一键逻辑到应用：YAML 定义即应用，静态代码瞬间变为交互式 Demo，告别繁琐 UI 开发
• 清华 OpenBMB 机构背书：THUNLP + NEUIR + ModelBest + AI9Stars 联合推出，学术严谨性与工业落地兼顾
• Agentic 研究循环：state-machine 路由产出长表单研究报告，DeepResearch 场景原生支持
• 原子化 Server 扩展：新功能以函数级 Tool 注册即可无缝接入，复用性极高

 

局限

• 自己不执行推理：UltraRAG 是开发框架，需要外部 LLM API（OpenAI/Deepseek/Qwen 等）或本地模型
• 外部依赖假设：架构默认假设外部 LLM API 和模型枢纽（Hugging Face），无明确的完全离线推理模式或气隙部署合规文档​
• 生产运维能力不及 R2R/FastGPT：UltraRAG 定位科研探索与工业原型 ，不具备 R2R 那样的生产级 REST API、用户管理、集合权限；也不具备 FastGPT 的业务级可视化工作流编排器
• 企业连接器不及 Onyx Cloud：数据源连接器需自行集成，不像 Onyx Cloud 内置 40+ 连接器
• 深度文档解析不及 RAGFlow：文档解析依赖集成方案，复杂布局 PDF 精准解析需额外处理
• 迁移成本：集成需要采用 MCP 协议和 YAML 工作流，与强耦合遗留系统或专有编排框架迁移成本高
• 无商业支持 SLA：部署支持社区驱动，无商业支持或保修
• 安全审计未文档化：无明确的安全审计或威胁模型文档
• 科研导向：框架集成了多个专有方法（KBAlign、RAG-DDR、VisRAG 等），充分利用需要理解其具体实现
• 性能声明基于特定领域评估：官方性能声明基于特定领域（如法律领域）评估
• 社区规模相对较小：~5.6K Stars，与 FastGPT/R2R/Quivr 等相比社区规模较小

 

适用人群

• RAG 研究人员：需要统一评测、基准对比、实验可复现性的科研工作
• 算法工程师：需要将算法原型快速转化为交互式 Demo，”逻辑即应用”
• 复杂 RAG 流程编排者：需要条件分支、循环等复杂控制结构的迭代式 RAG
• 多模态 RAG 开发者：文本/图像/音频/视频统一编码与跨模态检索需求
• DeepResearch 场景：需要自主研究智能体产出长表单研究报告
• 工业原型设计：企业研发部门快速搭建 RAG 原型验证想法
• 白盒推理需求方：需要像素级可视化推理链，Debug 复杂 RAG 流程
• MCP 生态开发者：希望在 MCP 架构上构建标准化 RAG 组件

 

安装与部署

 

1. 环境要求

• Python 3.10+
• CUDA 12.2+（GPU 模式）
• 外部 LLM API Key（OpenAI/Deepseek/Qwen 等）或本地模型
• 可选：Milvus 向量库

 

2. 源码安装（推荐 uv）

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

# 使用 uv 创建环境并安装
uv venv
source .venv/bin/activate
uv pip install -e .

# 或使用 conda
conda create -n ultrarag python=3.10
conda activate ultrarag
pip install -r requirements.txt

# 下载模型（可选）
python scripts/download_model.py

# 启动 Web UI
# 访问 http://localhost:8843
streamlit run ultrarag/webui/webui.py --server.fileWatcherType none

 

3. Docker 部署

# 标准化容器部署
docker compose up --build -d

# 访问 Web UI: http://localhost:8843

 

4. YAML 定义 Pipeline（核心用法）

# examples/sayhello.yaml 示例
# 通过 YAML 定义 RAG 流程：
# - 组件执行顺序
# - 业务逻辑（串行/循环/条件分支）
# - 参数配置

# 编译 Pipeline 文件生成参数配置
ultrarag compile examples/sayhello.yaml

# 修改参数文件后运行
ultrarag run examples/sayhello.yaml

 

5. Python API 快速使用

from ultrarag import UltraRAG

# 四行配置完成文本检索与生成
rag = UltraRAG(
    llm="gpt-4",
    embedder="sentence-transformers/all-MiniLM-L6-v2",
    retriever="faiss",
    visual_encoder="siglip2"
)

result = rag.query("台湾 AI 产业的未来发展方向是什么?")
print(result)

 

6. v3.0 可视化 IDE 使用

# 1. 启动 UltraRAG UI
# 2. 在 Canvas Mode 中通过 UI 组件直观组装 Loop/Branch 等复杂逻辑
# 3. 切换到 Code Mode 直接编辑 YAML，画布实时渲染更新
# 4. 点击"Build"按钮，系统自动逻辑自检与语法验证
# 5. 动态生成的参数配置面板就绪后，静态算法逻辑瞬间转化为交互式系统
# 6. 通过"Show Thinking"面板实时可视化推理链每一步

 

7. 部署前必检清单

• 确认仓库位于 github.com/OpenBMB/UltraRAG（官方）
• 许可：Apache-2.0 ，商用友好，含专利授权
• 严格属于 RAG 分类，“低代码 RAG 流程编排与科研原型框架”子类
• 官方定位：”A Low-Code MCP Framework for Building Complex and Innovative RAG Pipelines”
• 首发：2025-01-23；v3.0：2026-01-23
• 技术架构：MCP Server（原子化组件）+ MCP Client（YAML 调度）+ UI（一键生成）
• 核心能力：YAML 低代码编排、可视化 RAG IDE（画布+代码双向同步）、白盒推理可视化、Agentic 研究循环、统一评测与基准对比、多模态 RAG
• 部署：源码安装（uv）/ Docker / 本地离线研究智能体
• 环境要求：Python 3.10+，CUDA 12.2+（GPU）
• 外部依赖：LLM API（OpenAI/Deepseek/Qwen 等）或本地模型；无明确完全离线推理模式文档
• 社区规模：~5.6K GitHub Stars、434 Forks
• 开发方：清华大学 THUNLP + 东北大学 NEUIR + OpenBMB + AI9Stars
• 与 FastGPT（企业 Agent 平台）、RAGFlow（深度文档解析）、R2R（生产级 API 引擎）、Onyx Cloud（企业搜索）、PrivateGPT（离线隐私 RAG）、PaperQA2（科研文献 RAG）、Quivr（第二大脑）差异化明确
• 科研导向，无商业支持 SLA，无安全审计文档；生产运维能力不及 R2R/FastGPT