安装指南

安装指南#

前置要求#

硬件要求#

以下硬件配置经过充分测试：

  • GPU：每节点 8x H800

  • CPU：每节点 64 核

  • 内存：每节点 1TB

  • 网络：NVSwitch + RoCE 3.2 Tbps

  • 存储：

    • 单节点实验需要 1TB 本地存储

    • 分布式实验需要 10TB 共享存储（NAS）

软件要求#

组件

版本

操作系统

CentOS 7 / Ubuntu 22.04 或满足以下要求的任何系统

NVIDIA 驱动

550.127.08

CUDA

12.8

Git LFS

用于下载模型、数据集和 AReaL 代码。请参阅安装指南

Docker

27.5.1

NVIDIA Container Toolkit

请参阅安装指南

AReaL 镜像

ghcr.io/inclusionai/areal-runtime:v1.0.4-sglang（默认）或 v1.0.4-vllm。包含运行时依赖和 Ray 组件。

注意：本教程不涵盖 NVIDIA 驱动、CUDA 或共享存储挂载的安装，因为这些取决于您具体的节点配置和系统版本。请独立完成这些安装。

运行时环境#

对于多节点训练：确保在每个节点上挂载共享存储路径（如果使用 Docker，也要挂载到容器中）。此路径将用于保存检查点和日志。

方式 1：Docker（推荐）#

我们推荐使用 Docker 和提供的镜像。Dockerfile 位于 AReaL 仓库的顶级目录。

docker pull ghcr.io/inclusionai/areal-runtime:v1.0.4-sglang
docker run -it --name areal-node1 \
   --privileged --gpus all --network host \
   --shm-size 700g -v /path/to/mount:/path/to/mount \
   ghcr.io/inclusionai/areal-runtime:v1.0.4-sglang \
   /bin/bash
git clone https://github.com/inclusionAI/AReaL /path/to/mount/AReaL
cd /path/to/mount/AReaL
uv pip install -e . --no-deps

vLLM 变体的 Docker 镜像也可使用： ghcr.io/inclusionai/areal-runtime:v1.0.4-vllm。如果您偏好使用 vLLM 作为推理后端，请将上述命令中的镜像标签替换为该变体。

方式 2：自定义环境安装#

  1. 安装 uv。

  2. 克隆仓库：

git clone https://github.com/inclusionAI/AReaL
cd AReaL

  1. （可选）指定自定义索引 URL。

在 pyproject.toml 中添加以下内容：

[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple/"  # 更改为您首选的镜像站
default = true

如果网络连接稳定，可以跳过此步骤。

  1. 使用 uv sync 安装依赖：

# 在 Linux 上使用 CUDA 时添加 `--extra cuda` 以获得完整功能
uv sync --extra cuda
# 或者不带 CUDA 支持
# uv sync
# 或者包含开发和测试的额外包
# uv sync --group dev

这将安装 CUDA 依赖的训练包（Megatron、Torch Memory Saver）以及 SGLang 作为默认推理后端。这些包需要 Linux x86_64 和 CUDA 12.x 及兼容的 NVIDIA 驱动。

使用 vLLM 替代 SGLang#

SGLang 和 vLLM 锁定了互不兼容的 torch / torchao 版本，因此它们位于独立的 pyproject 文件中。默认的 pyproject.toml 使用 SGLang；若需使用 vLLM，请使用 pyproject.vllm.toml：

cp pyproject.vllm.toml pyproject.toml
cp uv.vllm.lock uv.lock
uv sync --extra cuda

也可以不替换 pyproject.toml：

uv pip install -r pyproject.vllm.toml --extra cuda

Flash Attention 预编译 Wheel#

Flash Attention v2 包含在 --extra cuda 中，但 PyPI 仅提供源码分发包，从源码编译耗时约 30 分钟。为跳过编译，请在运行 uv sync 之前安装预编译 wheel。

Flash Attention wheel 在编译时与特定 PyTorch 版本绑定。SGLang（默认 pyproject.toml）使用 torch 2.9，vLLM（pyproject.vllm.toml）使用 torch 2.10，请选择对应的 wheel。将 cpXYZ 替换为您的 Python 版本（3.11 对应 cp311，3.12 对应 cp312）。

SGLang（默认，torch 2.9）：

# Python 3.12
uv pip install "https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.9-cp312-cp312-linux_x86_64.whl"
# Python 3.11
# uv pip install "https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.9-cp311-cp311-linux_x86_64.whl"

uv sync --extra cuda

vLLM（torch 2.10，需要 pyproject.vllm.toml）：

cp pyproject.vllm.toml pyproject.toml
cp uv.vllm.lock uv.lock
# Python 3.12
uv pip install "https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.10-cp312-cp312-linux_x86_64.whl"
# Python 3.11
# uv pip install "https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.10-cp311-cp311-linux_x86_64.whl"

uv sync --extra cuda

浏览所有可用 wheel： mjun0812/flash-attention-prebuild-wheels。

同样的 uv sync 命令也适用于 macOS 和不带 CUDA 支持的 Linux。CUDA 包（包括 flash-attn） 会通过平台标记自动跳过。但是，需要 CUDA 的训练和推理功能将不可用。此配置仅适用于开发、测试和非 GPU 工作流。

您也可以单独安装各个 extra，而不是完整的 cuda 捆绑包：

  • sglang：SGLang 推理引擎（在 pyproject.toml 中）

  • vllm：vLLM 推理引擎（在 pyproject.vllm.toml 中）

  • megatron：Megatron 训练后端

  • tms：Torch Memory Saver

  • flash-attn：Flash Attention v2

  • kernels：Hugging Face Kernels 运行时

  • cuda-train：仅训练包（megatron + tms + kernels，不含推理后端）

  • cuda：cuda-train + 推理后端 + flash-attn

在训练中使用 Hugging Face Kernels#

安装 kernels extra 只会让 Hugging Face Kernels 运行时可用；训练仍然保持现有默认值，除非您在配置中显式启用。

对训练引擎配置（例如 actor、critic 或 teacher）使用以下字段：

  • attn_impl：选择注意力后端。除了 sdpa、flash_attention_2 等内置后端外，还可以填写 Hugging Face kernels 仓库 ID，例如 kernels-community/flash-attn 或 kernels-community/flash-attn@main:flash_attn_varlen_func。

  • use_kernels：设为 true 后，会在模型创建完成后对模型执行 kernelize。

示例：

actor:
  attn_impl: kernels-community/flash-attn
  use_kernels: true

为了获得可预测的行为，建议显式指定 kernels 仓库 ID，而不是依赖 flash_attention_* 的自动回退。

额外的 CUDA 包（可选，手动安装）#

Docker 镜像包含 pyproject.toml 中没有的额外编译包。这些包需要 CUDA，必须从源码编译。如果使用自定义环境（非 Docker）且需要这些包的优化（例如 FP8 训练、融合 Adam 内核），请在运行 uv sync --extra cuda 后手动安装：

包

用途

安装命令

grouped_gemm

Megatron 中的 MoE 模型支持

uv pip install --no-build-isolation git+https://github.com/fanshiqing/grouped_gemm@v1.1.4

NVIDIA apex

Megatron 中的融合 Adam 等

NVCC_APPEND_FLAGS="--threads 4" APEX_PARALLEL_BUILD=8 APEX_CPP_EXT=1 APEX_CUDA_EXT=1 uv pip install --no-build-isolation git+https://github.com/NVIDIA/apex.git

TransformerEngine

Megatron 中的 FP8 训练、优化 GEMM

uv pip install --no-build-isolation git+https://github.com/NVIDIA/TransformerEngine.git@stable

flash-attn-3

Flash Attention v3（Hopper）

从源码构建，请参阅 Dockerfile

重要：这些包需要 --no-build-isolation，因为它们需要访问已安装的 PyTorch 进行 CUDA 编译。先通过 uv sync --extra cuda 安装 PyTorch，然后再尝试安装这些包。

DeepSeek-V3 优化包（可选）#

为了以最佳性能运行 DeepSeek-V3 风格的 MoE 模型，Docker 镜像还包含以下包。这些包有复杂的构建要求和 GPU 架构约束。请参阅 Dockerfile 获取确切的安装命令和环境变量。

包

用途

GPU 要求

FlashMLA

Multi-head Latent Attention 内核

SM90+ (Hopper)

DeepGEMM

MoE 的 FP8 GEMM 库

SM90+ (Hopper)

DeepEP

Expert Parallelism 通信库

SM80+ (Ampere)

flash-linear-attention

使用 Triton 内核的线性注意力

任意 GPU

NVSHMEM

DeepEP 节点间通信必需

任意 GPU

注意：

  • FlashMLA 和 DeepGEMM 需要 Hopper（H100/H800）或更新的 GPU。

  • DeepEP 需要 NVSHMEM 用于节点间和低延迟功能。Docker 镜像通过 pip 安装 nvidia-nvshmem-cu12，DeepEP 会自动检测。

  • flash-linear-attention 使用纯 Triton 内核，可在任意 GPU 上运行。

  • 这些包在 Docker 构建期间从 GitHub 克隆和编译。手动安装时，确保为 FlashMLA 和 DeepGEMM 初始化 git 子模块（git submodule update --init --recursive），因为它们依赖 CUTLASS。

  1. 验证 AReaL 安装：

我们提供了一个脚本来验证 AReaL 安装。只需运行：

uv run python3 areal/tools/validate_installation.py

验证通过后，您就可以开始使用了！

（可选）安装 SkyPilot#

SkyPilot 帮助您在 17 种以上不同云平台或您自己的 Kubernetes 基础设施上轻松运行 AReaL。有关 SkyPilot 的更多详细信息，请参阅 SkyPilot 文档。以下是 在 GCP 或 Kubernetes 上设置 SkyPilot 的最小步骤。

使用 pip 安装 SkyPilot#

# 在您的 conda 环境中
# 注意：SkyPilot 需要 3.7 <= python <= 3.13
pip install -U "skypilot[gcp,kubernetes]"

GCP 设置#

# 安装 Google Cloud SDK
conda install -y -c conda-forge google-cloud-sdk

# 初始化 gcloud 并选择您的账户/项目
gcloud init

#（可选）显式选择项目
gcloud config set project <PROJECT_ID>

# 创建应用程序默认凭据
gcloud auth application-default login

Kubernetes 设置#

请参阅 SkyPilot Kubernetes 设置指南，了解如何为 SkyPilot 设置 Kubernetes 集群的详细指南。

验证#

sky check

如果显示 GCP: enabled 或 Kubernetes: enabled，您就可以将 SkyPilot 与 AReaL 一起使用了。请参阅 SkyPilot 示例 获取运行 AReaL 的详细指南。更多选项和详细信息，请参阅官方 SkyPilot 安装指南。

（可选）为分布式训练启动 Ray 集群#

在第一个节点上，启动 Ray Head：

ray start --head

在所有其他节点上，启动 Ray Workers：

# 替换为第一个节点的实际 IP 地址
RAY_HEAD_IP=xxx.xxx.xxx.xxx
ray start --address $RAY_HEAD_IP

运行 ray status 时应该可以看到 Ray 资源状态。

在 AReaL 的训练命令中适当设置 n_nodes 参数，AReaL 将自动检测资源并将 worker 分配到集群。

下一步#

查看快速入门部分启动您的第一个 AReaL 任务。