OpenBMB/UltraRAG · 上手攻略

仓库：OpenBMB/UltraRAG
链接：https://github.com/OpenBMB/UltraRAG
分类：ai
作者：Tom
更新：2026-08-19

是什么

UltraRAG 是由清华大学 THUNLP、东北大学 NEUIR、OpenBMB、AI9stars 联合推出的低代码 RAG 开发框架，基于 MCP（Model Context Protocol）架构设计。它将 RAG 的核心组件（检索器 Retriever、生成器 Generation、语料处理 Corpus、评估 Evaluation）拆解为独立的 MCP Server，通过 YAML 配置即可编排复杂 RAG 流水线。

核心差异点：传统 RAG 框架（如 LangChain RAG）以 Chain 为单位组合，UltraRAG 以控制流为单位——支持顺序、循环、条件分支，直接在 YAML 里写 if/else/for，不用写 Python 代码。

2026-01-23 发布 UltraRAG 3.0，主题是"Say no to black box development — make every line of reasoning logic clearly visible"，可视化和推理透明度是最大升级点。

解决什么问题

RAG 流水线的工程复杂度：实际 RAG 系统需要多步召回、重排序、查询改写、拒答判断、迭代优化，代码量动辄数百行。UltraRAG 将每一步封装为 MCP Server + YAML 配置，核心逻辑几十行即可表达。
评测标准化困难：不同论文的 RAG 评测指标各异，baseline 难以复用。UltraRAG 内置统一评测工作流和主流 Benchmark，支持标准化指标管理和 baseline 集成。
多模态 RAG 门槛高：2.x 版本开始支持多模态检索和生成（图片+文本混合），3.0 进一步完善端到端多模态 pipeline。
Pipeline 不可观测：YAML 配置的每一步可以配合 UltraRAG UI 实时调试，Canvas 画布和代码编辑器双向同步。
快速 Demo 交付：训练完算法后需要快速搭交互界面给团队演示。UltraRAG 支持一键将 Pipeline 转为可交互的 Web UI。

快速安装

方式一：uv（推荐）

# 安装 uv（如果还没有）
pip install uv==0.12.0

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

# 核心依赖（基础运行）
uv sync

# 完整安装（检索+生成+语料处理+评测全量）
uv sync --all-extras

# 按需安装
uv sync --extra retriever    # 仅检索模块
uv sync --extra generation   # 仅生成模块

# 激活环境
source .venv/bin/activate     # Linux/macOS
# Windows: .venv\Scripts\activate.bat

⚠️ Linux GPU 依赖锁定 CUDA 12.9（包含官方 vLLM cu129 wheel）。如需其他 CUDA 版本，需要手动调整 pyproject.toml。

方式二：pip（不使用 uv）

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

# 核心依赖
pip install -e .

# 全量依赖
pip install -e ".[all]"

方式三：Docker

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

# 使用官方镜像
docker pull openbmb/ultrarag:latest

# 或使用 docker-compose（推荐，包含全部依赖）
docker compose up -d

核心用法

1. 启动 UltraRAG UI（Web 可视化 IDE）

# 激活环境后
cd UltraRAG

# 启动前端 + 后端一体化服务
python -m ultra.rag.app
# 默认地址：http://localhost:8000

UI 功能：Pipeline Builder（画布拖拽 + YAML 编辑双向同步）、知识库管理、对话测试、评估面板。

2. 构建一个基础 RAG Pipeline（YAML）

# examples/simple_rag.yaml
name: simple_rag_pipeline

nodes:
  - id: corpus_loader
    type: corpus_server
    config:
      path: ./data/your_documents/
      chunk_size: 512
      chunk_overlap: 64

  - id: retriever
    type: retriever_server
    config:
      top_k: 10
      model: embedding_model_name  # ⚠️ 需替换为实际模型

  - id: reranker
    type: reranker_server
    config:
      top_n: 3

  - id: generator
    type: generation_server
    config:
      model: gpt-4o-mini  # ⚠️ 或本地模型
      api_base: https://api.openai.com/v1  # ⚠️ 按需修改

flow:
  - corpus_loader -> retriever
  - retriever -> reranker
  - reranker -> generator

  # 条件分支示例（if retrieved docs have low score, skip）
  - retanker:
      condition: "score < 0.6"
      then: skip_to_fallback
      else: generator

⚠️ 上述 YAML 为概念示意，具体 schema 以 UltraRAG 官方文档为准。配置中引用的模型名称需替换为实际可用的 embedding / generation 模型。

3. 运行 Pipeline 并对话

# 通过 UltraRAG UI 加载 YAML 并运行
# 或通过 Python API
python -c "
from ultra.rag import Pipeline
p = Pipeline.from_yaml('examples/simple_rag.yaml')
p.run('你的查询是什么？')
"

4. 使用 MCP Server 扩展（高级）

UltraRAG 的各组件以 MCP Server 形式暴露，可以被其他 MCP Client（如 Claude Desktop、其他 Agent 框架）调用：

# 启动单个 Retriever MCP Server
python -m ultra.rag.servers.retriever --port 8001

# 启动 Generator MCP Server
python -m ultra.rag.servers.generator --port 8002

# 其他 MCP Client 通过标准 MCP 协议调用

5. 评测流程

# 使用内置评测工作流
python -m ultra.rag.evaluate \
  --pipeline examples/simple_rag.yaml \
  --benchmark ultra_benchmark \
  --metrics recall@10 precision@5

# 查看评测报告（HTML 输出）
# 报告路径在 output/evaluate/ 下

⚠️ 评测模块需要提前准备 benchmark 数据集（如 UltraRAG_Benchmark，发布在 ModelScope：https://modelscope.cn/datasets/UltraRAG/UltraRAG_Benchmark）。

典型适用场景

场景	为什么用 UltraRAG
快速构建 RAG 原型：在论文里需要验证某个新检索策略	YAML 配置代替 Python 代码，几十分钟完成 baseline
RAG 算法研究：需要公平对比不同召回/重排策略的效果	内置统一评测框架 + 标准指标，消除工程差异
多模态文档问答：图片+PDF 混合的文档知识库	2.x+ 原生多模态，Retriever 和 Generator 均支持图片
团队 RAG 平台搭建：为团队搭内部知识库 UI	UltraRAG UI 一键生成交互界面
DeepResearch 实现：构建本地化深度研究 pipeline	官方提供了轻量 DeepResearch pipeline 教程（2025-09）

坑与注意

CUDA 版本锁定问题：Linux 全量安装锁定 cu129（CUDA 12.9）。如果显卡驱动是 CUDA 11.x 或 12.1，会出现版本不匹配。建议在 conda/venv 环境里指定 CUDA 版本，或使用 Docker 避免冲突。
模型依赖需自行配置：Embedding 模型、重排序模型、生成模型都需要显式配置 API 或本地路径，没有内置默认模型，新手可能在这里卡住。
中文文档质量：英文文档相对完整，部分中文文档（docs/README_zh.md）的翻译质量不如英文，部分关键配置项只有英文说明。
MCP Server 稳定性：基于 MCP 的 Server 间通信是实验性功能，MCP 协议本身也在演进，生产环境使用前建议充分测试。
UltraRAG UI 内存占用：Pipeline Builder 是 React/Vite 重前端，启动时加载较多资源，老旧设备可能卡顿。
版本升级兼容性：从 v1/v2 升级到 v3.0 有 breaking change，旧版 YAML 配置不一定直接兼容，需要检查 release note。
国内访问：ModelScope 和清华/北邮源在国内可高速访问，海外用户可能需要额外配置 pip mirror。

与同类对比

特性	UltraRAG	LangChain RAG	LlamaIndex	Dify
核心架构	MCP Server + YAML 流程编排	Chain / LangGraph	Node/Query Engine	可视化 DAG
低代码程度	YAML 配置，Canvas 可视化	需要 Python 代码	需要 Python 代码	Web UI 拖拽
多模态 RAG	✅ 原生支持（2.x+）	✅ 通过 multimodal chains	✅	✅
评测框架	✅ 内置统一评测	❌	⚠️ 基础评测	❌
学术研究支持	✅ Benchmark 数据集	❌	⚠️	❌
YAML 流程控制	✅ if/for/loop	⚠️ LangGraph 支持	❌	✅
团队	清华+东北大学+OpenBMB	LangChain Inc	Jerry Liu（独立）	YaaS Labs
Stars	~5.7k（2026-08 队列）	55k+（LangChain）	32k+（LlamaIndex）	35k+
上手门槛	中（YAML + Python 混合）	低~中	中	低

一句话总结：如果你做 RAG 算法研究，需要快速对比多种召回/重排策略的效果，UltraRAG 的 YAML 编排 + 内置评测是最高效的组合；如果你需要给团队搭一个拖拽式知识库问答产品，Dify 更成熟；如果你已经有 LangChain 工作流，迁移到 UltraRAG 收益有限。

OpenBMB/UltraRAG · 上手攻略

OpenBMB/UltraRAG · 上手攻略

是什么

解决什么问题

快速安装

方式一：uv（推荐）

方式二：pip（不使用 uv）

方式三：Docker

核心用法

1. 启动 UltraRAG UI（Web 可视化 IDE）

2. 构建一个基础 RAG Pipeline（YAML）

3. 运行 Pipeline 并对话

4. 使用 MCP Server 扩展（高级）

5. 评测流程

典型适用场景

坑与注意

与同类对比

推荐结论

相关 · 按语义匹配