Python——Ray-多节点集群启动

整体说明

  • Ray 集群的启动有多种方法，本文简单总结这些方法
  • 核心概念补充：
    • 头节点（Head Node） ：集群的主节点，负责管理整个集群的资源、任务调度和元数据存储
    • 工作节点（Worker Node） ：通过连接头节点加入集群，提供计算资源（CPU/GPU/内存等）

配置文件启动

  • 设置配置文件 cluster.yaml

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    cluster_name: my-ray-cluster
    max_workers: 2

    # 头节点配置
    head_node:
        InstanceType: m5.large
        ImageId: ami-0abcdef1234567890  # 选择包含Ray的镜像

    # 工作节点配置
    worker_nodes:
        InstanceType: m5.xlarge

    # 启动命令（可选，自定义节点初始化）
    setup_commands:
        - pip install pandas  # 安装依赖

  • 主节点启动 ray up cluster.yaml

  • 其他节点加入集群 ray attach cluster.yaml

  • 停止容器 ray down cluster.yaml

Kubernetes 部署

  • 待补充

Python 程序内启动

  • 主节点使用：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    import ray

    # 启动本地集群（自动创建头节点和工作进程）
    ray.init(
        num_cpus=4,    # 模拟4核CPU
        num_gpus=1,    # 模拟1块GPU
        port=6380,  # 手动指定通信端口
        dashboard_host="0.0.0.0"  # 允许外部访问Dashboard
    )

    # 验证集群
    print("集群节点数:", len(ray.nodes()))  # 输出1（单节点模拟）

    # 关闭集群
    ray.shutdown()

  • 其他节点加入使用

    1
    2
    3
    4
    5
    6
    # 头节点启动Ray
    import ray
    ray.init()

    # 工作节点连接到头节点
    ray.init(address='头节点地址:6380')

使用 ray start 命令启动

  • ray start 是启动 Ray 集群节点的常用命令
  • 可分别分别使用 ray start 用于初始化头节点（Head Node）和工作节点（Worker Node）

启动头节点

  • 头节点是集群的入口，必须先启动

  • 基本命令格式：

    1
    ray start --head [其他可选参数]

  • 关键参数包括：

    参数 说明 示例
    --head 声明当前节点为头节点（必选） -
    --port 指定 Ray 内部通信端口（默认 6379，若被占用会自动切换） --port=6380
    --dashboard-host 允许外部访问 Ray dashboard 的主机地址（默认仅本地访问） --dashboard-host=0.0.0.0
    --dashboard-port Dashboard 端口（默认 8265） --dashboard-port=8266
    --num-cpus 手动指定该节点可用的 CPU 核心数（默认自动检测） --num-cpus=16
    --num-gpus 手动指定该节点可用的 GPU 数量（默认自动检测） --num-gpus=2
    --memory 限制节点可用内存（单位：字节，如 1000000000 表示 1GB） --memory=8000000000
    --object-store-memory 对象存储的内存上限（默认总内存的 30%） --object-store-memory=2000000000
    --block 启动后阻塞终端（不后台运行，便于调试） -
    --log-dir 指定日志目录（默认 ~/raylogs） --log-dir=/path/to/logs

  • 示例：启动一个允许外部访问 Dashboard、指定 CPU/GPU 资源的头节点：

    1
    2
    3
    4
    5
    6
    ray start --head \
        --port=6379 \
        --dashboard-host=0.0.0.0 \
        --dashboard-port=8265 \
        --num-cpus=12 \
        --num-gpus=1

启动工作节点

  • 工作节点需通过头节点的地址加入集群，命令格式：

    1
    ray start --address=<IP>:<port> [其他可选参数]

  • 关键参数说明：

    • --address：头节点的地址（必填，格式为 <IP>:<port>，即头节点启动时输出的地址）
    • 其他参数（如 --num-cpus、--num-gpus 等）与头节点相同，用于限制工作节点的资源

  • 示例：连接到 IP 为 192.168.1.100、端口为 6379 的头节点，同时指定工作节点的资源：

    1
    2
    3
    ray start --address='192.168.1.100:6379' \
        --num-cpus=8 \
        --num-gpus=0

使用 ray 命令验证集群状态

  • 可在任意节点执行下面脚本查看节点列表

    1
    ray status
    • 输出会显示集群中的所有节点及资源使用情况

  • 通过头节点的 http://<头节点IP>:8265（或其他指定端口） 查看集群监控、任务状态等

使用 ray 命令停止集群

  • 停止单个节点（包括工作节点或头节点）：

    1
    ray stop

  • 特别注意：若头节点停止，整个集群会自动解散

附录：ray start 命令的其他高级配置

  • 可通过 --runtime-env 指定环境配置文件（如依赖安装、环境变量等）：

    1
    ray start --head --runtime-env=runtime_env.yaml

  • 可通过 --redis-password 设置密码，防止未授权节点加入：

    1
    2
    3
    4
    5
    # 头节点
    ray start --head --redis-password='mysecret'

    # 工作节点
    ray start --address=<IP:port> --redis-password='mysecret'

  • 可通过 --log-dir 指定日志目录（默认 ~/raylogs）：

    1
    ray start --head --log-dir=/path/to/logs

附录：通过 ray job submit 向已经启动的 Ray 集群提交任务

  • ray job submit 命令用于将作业提交到 Ray 集群

基本语法

  • 用法说明：

    1
    ray job submit [options] -- <entrypoint> [<entrypoint_args>]
    • [options] 是命令的可选参数
    • -- 之后的 <entrypoint> 是要执行的入口点脚本或命令
      • 可以是 -- python my_script.py 或 bash my_shell.sh
    • <entrypoint_args> 是传递给 <entrypoint> 的参数

常用参数

  • --address：指定 Ray 集群的地址，通常是集群头节点的地址和端口，如http://127.0.0.1:8265
  • --working-dir：指定作业的工作目录
    • 该目录下的文件会被同步到集群节点上，默认为当前目录
    • 启动脚本会有一些文件依赖，这里上传所有文件可以保证本地能访问的文件，集群也能访问
  • --runtime-env：用于指定作业的运行时环境，可以是一个 JSON 格式的字符串或 YAML 文件路径
    • 例如，可以通过该参数指定需要安装的 Python 包，如--runtime-env='{"pip": ["requests"]}'
  • --no-wait：提交作业后不等待作业完成，立即返回
    • 如果不指定该参数，命令会等待作业完成，并输出作业的日志和结果
  • --submission-id：指定作业的提交 ID
    • 如果不指定，Ray 会自动生成一个唯一的 ID

用法示例

  • 假设要提交一个 Python 脚本 my_script.py 到 Ray 集群，指定集群地址为 http://127.0.0.1:8265，工作目录为当前目录：

    1
    RAY_ADDRESS='http://127.0.0.1:8265' ray job submit --working-dir. -- python my_script.py

  • 假设提交一个 Python 脚本 train.py，并传递参数 --epochs 10 --batch-size 32，同时指定运行时环境需要安装 torch 和 numpy 包：

    1
    ray job submit --address=http://your-ray-cluster-address:8265 --runtime-env='{"pip": ["torch", "numpy"]}' -- python train.py --epochs 10 --batch-size 32

其他高级配置

  • py_modules ：指定需要导入的自定义 Python 模块路径，支持将本地模块添加到 Python 路径（sys.path），示例如下：

    1
    runtime_env={"py_modules": ["./my_utils"]}  # 同步 my_utils 模块并添加到路径

  • env ：指定预定义的环境名称（如 Ray 集群中已配置的共享环境），避免重复配置，示例如下：

    1
    runtime_env={"env": "shared-training-env"}  # 使用集群中预定义的环境

  • 特别说明：runtime_env 还支持其他非官方扩展，比如 verl 库中就为英伟达显卡配置了 nsight 工具的参数传入

    1
    2
    ./verl/trainer/main_ppo.py
    runner = TaskRunner.options(runtime_env={"nsight": nsight_options}).remote()