环境部署

UltraRAG 提供了两种安装方式：本地源码安装（推荐使用 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：
uv sync
全量安装：如果您希望完整体验 UltraRAG 的检索、生成、语料处理及评测功能，请运行：
uv sync --all-extras

按需安装：如果您只需运行定模块，按需保留对应 --extra，例如：

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/sayhello.yaml

看到以下输出即代表安装成功：

Hello, UltraRAG v3!

开始使用

RAG Servers

RAG Client

开发指南

典型实现

源码安装

Docker 容器部署

验证安装

​源码安装

​Docker 容器部署

​验证安装

源码安装

Docker 容器部署

验证安装