文档中心

Appearance

✨费用中心控制台

使用 MPI hostfile 启动任务 ​

本页适用于已经依赖 OpenMPI、MPICH、Horovod 或 MPI 模式 DeepSpeed 的训练和计算任务。重点是使用平台生成的 /etc/mpi/hostfile 启动进程，并让 启动命令 正确反映 MPI 任务成败。

如果训练代码只是标准 PyTorch DDP 或 torchrun，优先参考编写 PyTorch DDP torchrun 启动脚本。

在创建页选择 MPI ​

在创建训练任务时，选择 Worker 规格 和 Worker 数量，并在 分布式框架 中选择 MPI。完整创建步骤请参考使用包年包月资源提交训练任务。

选择 MPI 后，平台会创建 MPI launcher 和 Worker，并在任务启动时生成 hostfile。您的 启动命令 应从 launcher 发起 mpirun 或 mpiexec，由 MPI 框架按 hostfile 启动远端进程。

检查平台生成的 hostfile ​

平台会在 /etc/mpi/hostfile 写入本次 MPI 任务可用的节点和 slot。--np 可以显式指定，也可以从 hostfile 中的 slots 总数计算。训练脚本要求固定进程数时，显式设置 NP；希望进程数跟随创建页选择的资源变化时，再从 hostfile 计算。

平台还会注入以下环境变量：

  • OMPI_MCA_orte_default_hostfile=/etc/mpi/hostfile：OpenMPI 默认 hostfile 路径。
  • MPICH_HOSTFILE=/etc/mpi/hostfile：MPICH 默认 hostfile 路径。

运行中登录 launcher 后，可以检查 hostfile：

language-bash
cat /etc/mpi/hostfile

输出可能类似：

language-text
jo-da4r6pellvvq4tmz-launcher-0 slots=1
jo-da4r6pellvvq4tmz-worker-0 slots=1

编写 launch_mpi.sh ​

以下示例使用 OpenMPI。它默认把 hostfile 中的 slots 总数作为 -np，打印本次 MPI 启动形状，并把 OUTPUT_DIR 传给 MPI 进程。这是一个可复用写法，不是唯一写法；如果训练代码已经固定要求 8、16 或 32 个 MPI 进程，可以在 启动命令 中显式设置 NP。

language-bash
#!/usr/bin/env bash
set -euo pipefail

HOSTFILE=${HOSTFILE:-/etc/mpi/hostfile}
MPI_BIN=${MPI_BIN:-mpirun}
TRAIN_SCRIPT=${TRAIN_SCRIPT:-/mnt/public/project-a/train_mpi.py}
OUTPUT_DIR=${OUTPUT_DIR:-/mnt/public/project-a/outputs/mpi-smoke}
mkdir -p "$OUTPUT_DIR"

NP=${NP:-$(awk -F'slots=' '/slots=/{sum += $2} END {print sum + 0}' "$HOSTFILE")}
if [[ "$NP" -le 0 ]]; then
  echo "No MPI slots found in $HOSTFILE"
  cat "$HOSTFILE"
  exit 1
fi

export NCCL_DEBUG=${NCCL_DEBUG:-INFO}

echo "MPI launch: np=${NP} hostfile=${HOSTFILE}"
cat "$HOSTFILE"

"$MPI_BIN" --allow-run-as-root \
  --hostfile "$HOSTFILE" \
  -np "$NP" \
  -x OUTPUT_DIR \
  -x NCCL_DEBUG \
  python "$TRAIN_SCRIPT" \
  --output_dir "$OUTPUT_DIR"

如果镜像使用 MPICH，把 MPI_BIN 改为 mpiexec，并根据镜像内 mpiexec 的语法调整环境变量传递方式。OpenMPI 常用 -x VAR，MPICH 常用 -env VAR VALUE 或 -genv VAR VALUE。

填写启动命令 ​

在创建页的 启动命令 中调用 MPI 启动脚本：

language-bash
set -euo pipefail

export TRAIN_SCRIPT=/mnt/public/project-a/train_mpi.py
export OUTPUT_DIR=/mnt/public/project-a/outputs/${RUN_ID:-mpi-run}
mkdir -p "$OUTPUT_DIR"

bash /mnt/public/project-a/launch_mpi.sh > >(tee -i "$OUTPUT_DIR/launch_mpi.log") 2>&1

如果需要固定进程数，可以在 启动命令 中显式设置 NP，例如 export NP=16。如果没有设置 NP，上面的脚本会使用 hostfile 中的 slot 总数。

验证 MPI 已经正常启动 ​

第一次提交 MPI 任务时，建议先运行一个小规模脚本或少量 step。日志中至少应能确认：

  • launch_mpi.sh 打印了 /etc/mpi/hostfile。
  • np 符合 hostfile 中的 slots 总数，或符合您显式设置的 NP。
  • 每个 MPI 进程都能读取训练数据和输出目录。
  • 训练已经进入第一个 batch、第一轮计算或预期的 MPI 通信阶段。
  • checkpoint、日志和结果写入共享存储路径。

定位 MPI 启动失败 ​

  • mpirun 找不到 hostfile：检查创建页是否选择 MPI，以及 /etc/mpi/hostfile 是否存在。
  • --np 与资源不匹配：检查是否硬编码了错误的 NP，以及 hostfile 中 slots 总数是多少。
  • OpenMPI 拒绝以 root 运行：检查镜像是否以 root 运行，以及命令是否包含 --allow-run-as-root。
  • 远端进程缺少环境变量：检查 OpenMPI 是否用 -x 传递变量，MPICH 是否按对应语法传递变量。
  • 任务显示成功但训练失败：检查 启动命令 是否隐藏了 mpirun 的退出码，尤其是 tee、上传结果、失败后 sleep 等收尾逻辑。

运行中需要进一步排查时，可在任务详情页登录 Worker 的 Web Terminal，或使用 atlctl 命令行调试工具下发检查命令。