在 HPC 集群上运行

在 HPC 集群上运行#

集群是加快训练和学习算法评估的好方法。尽管 Isaac Lab Docker 镜像可用于在集群上运行作业，但许多集群只支持 singularity 镜像。这是因为 singularity 专为共享多用户系统和高性能计算（HPC）环境的易用性而设计。它不需要 root 权限来运行容器，并且可以用于运行用户定义的容器。

Singularity 兼容所有 Docker 镜像。本页介绍如何将 Isaac Lab Docker 镜像 转换为 Singularity 镜像，并用它向集群提交作业。

注意

集群设置因不同的机构而异。以下说明已在使用 SLURM 工作负载管理器的 ETH Zurich Euler 集群和使用 PBS 工作负载管理器的 IIT Genoa Franklin 集群上进行了测试。

指示可能需要针对其他集群进行调整。如果您已成功地为另一个集群调整了指示，请考虑为文档做出贡献。

先决条件#

为了将 Docker 镜像导出为 singularity 镜像，需要使用 apptainer 。关于 apptainer 的安装过程的详细概述可以在其 文档 中找到。为方便起见，我们在这里总结了本地安装的步骤:

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt update
sudo apt install -y apptainer

为简单起见，我们建议在本地开发机器和集群之间建立 SSH 连接。这样的连接将简化文件传输，避免用户多次请求用户集群密码。

注意

工作流已针对以下进行了测试

  • apptainer version 1.2.5-1.el7 和 docker version 24.0.7

  • apptainer version 1.3.4 和 docker version 27.3.1

在出现问题的情况下，请尝试切换到这些版本。

集群配置#

在 docker/cluster/.env.cluster 中配置集群专用参数。文件内有各参数的说明：

###
# Cluster specific settings
###

# Job scheduler used by cluster.
# Currently supports PBS and SLURM
CLUSTER_JOB_SCHEDULER=SLURM
# Docker cache dir for Isaac Sim (has to end on docker-isaac-sim)
# e.g. /cluster/scratch/$USER/docker-isaac-sim
CLUSTER_ISAAC_SIM_CACHE_DIR=/some/path/on/cluster/docker-isaac-sim
# Isaac Lab directory on the cluster (has to end on isaaclab)
# e.g. /cluster/home/$USER/isaaclab
CLUSTER_ISAACLAB_DIR=/some/path/on/cluster/isaaclab
# Cluster login
CLUSTER_LOGIN=username@cluster_ip
# Cluster scratch directory to store the SIF file
# e.g. /cluster/scratch/$USER
CLUSTER_SIF_PATH=/some/path/on/cluster/
# Remove the temporary isaaclab code copy after the job is done
REMOVE_CODE_COPY_AFTER_JOB=false
# Python executable within Isaac Lab directory to run with the submitted job
CLUSTER_PYTHON_EXECUTABLE=scripts/reinforcement_learning/train.py

需注意以下约束：

  • CLUSTER_ISAAC_SIM_CACHE_DIR 必须以 docker-isaac-sim 结尾。它会复制到计算节点，并挂载到 Singularity 容器内，以加快仿真启动。

  • CLUSTER_ISAACLAB_DIR 必须以 isaaclab 结尾。提交时，最新本地修改复制到 ${CLUSTER_ISAACLAB_DIR}_${datetime} ，使多个作业能同时运行不同代码版本。日志写回固定的 CLUSTER_ISAACLAB_DIR 。

  • REMOVE_CODE_COPY_AFTER_JOB 只删除该代码副本，不删除日志。启用它可节省集群磁盘空间。

当一个 job 被提交时，它还会使用在 docker/.env.base 中定义的变量，尽管这些变量默认情况下应该是正确的。

导出 Apptainer 镜像#

接下来，我们需要将 Docker 镜像导出为 singularity 镜像并上传到 Cluster。这一步仅在首次提交作业或更新 Docker 镜像时需要。例如，由于升级 Isaac Sim 版本，或者项目的其他要求。

要导出为 singularity 镜像，请执行以下命令:

./docker/cluster/cluster_interface.sh push [profile]

该命令将在 docker/exports 目录下创建一个 singularity 镜像，并将其上传到集群上定义的位置。它要求您先前使用 container.py 接口构建了镜像。请注意，创建 singularity 镜像可能需要一段时间。 [profile] 是一个可选参数，用于指定要使用的容器配置文件。如果未指定配置文件，则将使用默认配置文件 base 。

备注

默认情况下，通过在 apptainer build 命令中提供 --fakeroot 标志，无需 root 访问权限即可创建 singularity 镜像。如果镜像创建失败，您可以尝试通过在 docker/cluster/cluster_interface.sh 中删除该标志以带有 root 访问权限创建它。

定义作业参数#

作业参数需要根据集群使用的作业调度器进行定义。您只需要更新适用于您的调度器的适当脚本。

SLURM#

作业参数在 docker/cluster/submit_job_slurm.sh 中定义。典型的 SLURM 操作需要指定 CPU 和 GPU 的数量，内存和时间限制。有关更多信息，请查看 SLURM 文档 。

默认配置如下:

12#SBATCH --cpus-per-task=8
13#SBATCH --gpus=rtx_3090:1
14#SBATCH --time=23:00:00
15#SBATCH --mem-per-cpu=4048
16#SBATCH --mail-type=END
17#SBATCH --mail-user=name@mail
18#SBATCH --job-name="training-$(date +"%Y-%m-%dT%H:%M")"

集群的一个重要要求是计算节点始终可以访问互联网。这是从 Nucleus 服务器加载资产所需的。对于某些集群体系结构，必须加载额外的模块才能允许访问互联网。

例如，在 ETH Zurich Euler 集群上，需要加载 eth_proxy 模块。这可以通过向 submit_job_slurm.sh 脚本添加以下行来完成:

3# in the case you need to load specific modules on the cluster, add them here
4# e.g., `module load eth_proxy`

PBS#

作业参数在 docker/cluster/submit_job_pbs.sh 中定义。典型的 PBS 操作需要指定 CPU 和 GPU 的数量以及时间限制。有关更多信息，请查看 PBS 官方网站 。

默认配置如下:

11#PBS -l select=1:ncpus=8:mpiprocs=1:ngpus=1
12#PBS -l walltime=01:00:00
13#PBS -j oe
14#PBS -q gpu
15#PBS -N isaaclab
16#PBS -m bea -M "user@mail"

提交作业#

要在集群上提交作业，可以使用以下命令:

./docker/cluster/cluster_interface.sh job [profile] "argument1" "argument2" ...

此命令将会将您代码的最新更改复制到集群并提交一个作业。请确保您的 Python 可执行文件的输出存储在 isaaclab/logs 下，因为该目录将再次从计算节点复制到 CLUSTER_ISAACLAB_DIR 。

[profile] 是一个可选参数，用于指定使用哪个与容器配置文件对应的 singularity 镜像。如果未指定配置文件，将使用默认配置文件 base 。该配置文件必须紧跟在 job 命令之后定义。所有其他参数都会传递给 Python 可执行文件。如果未定义配置文件，则所有参数都会传递给 Python 可执行文件。

训练参数将传递给 Python 可执行文件。例如，标准的 ANYmal 粗糙地形运动训练可以使用以下命令执行:

./docker/cluster/cluster_interface.sh job --rl_library rsl_rl --task IsaacContrib-Velocity-Rough-AnymalC --video

上述命令还会渲染训练进度的视频，并将其存储在 isaaclab/logs 目录下。

提交到 OSMO#

NVIDIA OSMO 是调度机器人负载的云原生编排平台。与上述 SLURM、PBS 工作流不同，它直接运行 Isaac Lab Docker 镜像，无需转换为 Singularity，也不复制代码；镜像本身就是部署单元。

工作流定义位于 docker/cluster/osmo_multi_gpu_workflow.yaml 。它申请单个节点，并通过 train_multigpu 在节点内多个 GPU 上扩展训练。提交时可覆盖以下参数：

参数

描述

image

要运行的 Isaac Lab 容器镜像，默认为已发布的 nvcr.io/nvidia/isaac-lab:3.0.0-rc1 。该仓库不发布 latest 标签，必须指定明确版本。

rl_library

训练使用的强化学习库，默认为 rsl_rl 。

num_gpu

用于训练的 GPU 数量。设为 1 时，使用单进程 train 入口，而非 train_multigpu 。

num_cpu

为节点申请的 CPU 数量，通过 OMP_NUM_THREADS 平均分配到各 GPU 工作进程。

memory

为节点申请的内存，单位为 GiB。

storage

为节点申请的临时存储空间，单位为 GiB。

platform

作业调度到的 OSMO 平台（节点类型），例如 dgx-h100 。

master_port

torchrun 汇合使用的端口，仅在 num_gpu 大于 1 时相关。

args

转交给训练脚本的参数，例如 --task <task-name> --num_envs 4096 。工作流不请求可视化器，因此训练以无界面模式运行。

通过 osmo 命令行提交作业：

osmo workflow submit docker/cluster/osmo_multi_gpu_workflow.yaml \
  --set num_gpu=4 \
  --set args="--task Isaac-Reorient-KukaAllegro --num_envs 4096"
目录