在 HPC 集群上运行

在 HPC 集群上运行#

许多 HPC 集群通过 singularity 运行容器，它适用于共享系统，无需 root 权限。以下流程可在此类集群上运行 Isaac Lab 训练和评估作业。

将 Isaac Lab Docker 镜像 转为 Singularity 镜像，上传后向集群提交作业。

注意

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

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

先决条件#

安装 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 镜像变化，例如更新 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"
目录