文档中心

Appearance

✨费用中心控制台

提交 Ray Driver 入口命令 ​

本页适用于已经使用 Ray Train、Ray Tune、Ray Data 或 Ray Core 的任务。重点是：平台会托管 Ray Head 和 Worker，您的 启动命令 只需要启动 Driver 脚本，不要再手动 ray start 或 ray job submit。

连接平台托管的 Ray 集群 ​

创建页选择 Ray 后，平台会先启动 Ray Head 和 Worker，并等待 Worker 加入集群。您的 Python 脚本作为 Driver 在 Head 中运行，通常只需要连接当前已经存在的 Ray 集群：

language-python
import ray

ray.init()
print(ray.cluster_resources())

也可以使用 ray.init(address="auto")。一般不要在脚本中硬编码 Head 地址、端口或任务 ID；这些信息由平台管理。

在创建页选择 Ray ​

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

Ray 任务提交后，Head 和 Worker 数量在本次任务生命周期内固定。当前任务内不支持 Ray Autoscaler，也不支持单独配置 CPU-only Head 和 GPU Worker。需要不同资源形状时，建议拆成多个任务。

填写 Driver 启动命令 ​

在创建页的 启动命令 中运行 Driver 脚本。不要在这里写 ray start 或 ray job submit：

language-bash
set -euo pipefail

export OUTPUT_DIR=/mnt/public/project-a/outputs/${RUN_ID:-ray-run}
mkdir -p "$OUTPUT_DIR"

python /mnt/public/project-a/train_ray.py > >(tee -i "$OUTPUT_DIR/ray-driver.log") 2>&1

如果 Driver 脚本失败，启动命令 也应以失败状态结束。需要日志转存、结果上传或失败后保留现场时，请按编写可靠启动命令中的模式处理。

让 Ray 并行度匹配任务资源 ​

Ray 代码中的并行度应根据任务实际资源设置。提交前先明确两件事：

  • 创建页中的 Worker 数量 和每个 Worker 的 CPU/GPU 数量。
  • Ray 代码中的 num_workers、num_cpus、num_gpus 或 Placement Group 是否会超过任务资源。

例如，创建页选择 2 个 Worker、每个 Worker 4 张 GPU 时，Ray 集群总共可见 8 张 GPU。Ray Train 任务如果希望每张 GPU 跑一个训练 worker，可按总 GPU 数设置训练 worker 数：

language-python
from ray.train import ScalingConfig

scaling_config = ScalingConfig(
    num_workers=8,
    use_gpu=True,
)

Ray 中的 worker、actor 或 task 是 Ray 的执行单元；创建页中的 Worker 是平台提供的计算单元。两者名称相同，但层级不同。排查资源不足时，先看 ray.cluster_resources() 打印的 CPU/GPU 数量。

管理 Ray 依赖和运行环境 ​

Ray 任务的运行环境由镜像和 runtime_env 共同决定：

  • 镜像负责 Python、Ray、CUDA、NCCL、系统库和大型依赖。
  • runtime_env 适合补充轻量 pip 依赖、working_dir、py_modules 和环境变量。
  • 训练数据、checkpoint 和模型输出应放在共享存储中，不要只写入 /tmp、/root 或 /workspace 等容器本地路径。

如果依赖较大或安装时间较长，优先提前制作并验证镜像，避免 Ray Driver 启动后才在 GPU 任务中安装依赖。

验证 Ray 作业已经启动 ​

第一次提交 Ray 任务时，建议先跑小数据或少量 step。日志中至少应能确认：

  • Driver 脚本已经执行，并打印 ray.cluster_resources()。
  • 可见 CPU/GPU 数量符合创建页中选择的 Worker 规格 和 Worker 数量。
  • Ray Train、Tune、Data 或自定义 Actor 已经开始执行，而不是只停留在 Driver 初始化。
  • 任务详情页能看到 Ray Dashboard 入口。
  • 输出、checkpoint 或评估结果写入共享存储路径。

理解平台托管的差异 ​

与本地或物理机 Ray 集群相比，平台上的 Ray 任务有几个固定差异：

  • 一个平台任务会创建一个 Ray 集群；任务结束后 Ray 集群和容器本地文件系统会被回收。
  • 平台负责启动 Head/Worker、等待节点就绪并暴露 Dashboard。
  • 本次任务的集群规模固定，任务运行中不会自动扩容或缩容。
  • Head 和 Worker 使用创建页选择的同一规格。
  • Driver 入口命令运行在 Head 中，Worker 负责执行 Ray task、actor 或训练 worker。

这些差异通常不需要改 Ray API，但会影响资源规划、输出路径和 启动命令 写法。

定位 Ray 启动失败 ​

  • Driver 找不到 Ray 集群：检查创建页是否选择 Ray，以及脚本是否手动覆盖了 Ray 地址。
  • 任务一直等不到 Driver 日志：检查 Ray Head/Worker 是否就绪，以及镜像中的 Ray 版本是否可用。
  • Ray 报资源不足：检查 ray.cluster_resources() 是否小于代码中的 num_workers、num_gpus 或 Placement Group 需求。
  • Driver 成功但 Ray worker 报错：分别查看 Head 和 Worker 日志，确认依赖和数据路径在所有 Worker 上可访问。
  • 任务结束后找不到结果：检查输出路径是否位于挂载的共享存储，而不是容器本地路径。

运行中需要进一步排查时，可在任务详情页查看 Ray Dashboard、任务日志 和 Worker 日志，也可登录 Worker 的 Web Terminal 使用 atlctl 命令行调试工具。