使用 Ray Cluster Launcher 在 GCP 上启动 Ray 集群的完整指南

使用 Ray Cluster Launcher 在 GCP 上启动 Ray 集群的完整指南【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray本指南讲解如何借助 Ray 自带的集群启动器Cluster Launcher在 Google Cloud PlatformGCP上创建、连接并销毁 Ray 集群。你将掌握ray up/ray attach/ray down三个核心命令的完整使用流程理解 GCP 专属集群配置YAML中每一项参数的含义并学会通过 Service Account、抢占式实例、GPU 与 TPU 等配置按需定制集群同时结合本仓库源码python/ray/autoscaler/gcp 与 python/ray/autoscaler/_private/gcp深入理解其底层实现原理。核心概念Ray Cluster Launcher 与 GCPRay 集群启动器是rayCLI 的组成部分。它读取一个 YAML 配置文件通过调用云厂商 API在 GCP 上即 Google API Client自动完成实例创建、SSH 密钥注入、Ray 运行时部署等一整套工作。常用命令包括ray up config.yaml创建或更新集群结束后打印 SSH 登录头节点head node的命令ray attach config.yaml在头节点上打开一个远程交互终端ray down config.yaml销毁集群。在 GCP 场景下启动器通过google-api-python-client与 Compute Engine、Cloud Resource Manager、IAM 等 API 交互完成从「项目校验」「Service Account 创建」「SSH 密钥注入」到「实例调度」的全流程具体逻辑集中在 python/ray/autoscaler/_private/gcp/config.py 与 python/ray/autoscaler/_private/gcp/node_provider.py 中。第一步安装 Ray Cluster Launcher集群启动器随rayPython 包分发使用ray[default]安装即可获得完整功能包含 autoscaler 所需依赖# 安装 ray pip install -U ray[default]更详细的安装方式conda、源码编译等可参考 Ray 安装文档。本仓库在 python/ray/autoscaler/gcp/defaults.yaml 中给出了各节点初始化阶段的自动安装命令which ray || pip install -U ray[default] ...说明在首次启动节点时若节点上未安装 Ray启动器也会自动补齐。第二步安装与配置 Google API Client准备 GCP 项目如果你还没有创建过 Google APIs Console 项目需要先前往 Google Cloud 控制台的「管理项目」页面创建一个新项目。Ray 启动器要求项目 IDproject_id全局唯一该值将在集群配置中作为必填项使用。安装 Google API Client启动器通过 Google API Client 与 GCP 的各类 REST API 通信安装命令如下# Install the Google API Client. pip install google-api-python-client关于凭据的加载从 python/ray/autoscaler/_private/gcp/config.py#L314-L376 的construct_clients_from_provider_config可以看到两条路径若集群配置的provider段未提供gcp_credentials则回退到标准环境变量GOOGLE_APPLICATION_CREDENTIALS自动发现凭据若提供了gcp_credentials则要求其包含type与credentials两个字段type为service_account时credentials必须是合法 JSON 格式的服务账号密钥type为credentials_token时则直接作为 OAuth token 使用。无论哪种方式最终都会构建出四个 API 客户端Cloud Resource Managercrm、IAM、Computecompute以及可选的 TPU 客户端。第三步理解 GCP 集群配置文件官方在 python/ray/autoscaler/gcp 目录下提供了多份可直接使用的示例配置其中 example-full.yaml 是最常用的一份它创建一个按需on-demand的n1-standard-2头节点并配置为最多自动扩容到两个n1-standard-2抢占式preemptible工作节点。使用前你必须将其中的project_id替换为自己的项目 ID。下面逐节解析该配置文件与 defaults.yaml 对比可看到哪些是默认值、哪些是可覆盖项集群元信息cluster_name: default # 头节点与工作节点共用的集群唯一标识 max_workers: 2 # 除头节点外最多启动的工作节点数 upscaling_speed: 1.0 # 扩容速度因子 0越大扩容越快 idle_timeout_minutes: 5 # 节点空闲超过该分钟数将被回收其中upscaling_speed控制扩容节奏autoscaler 会按upscaling_speed * 当前运行节点数的增量分批扩容避免一次性创建过多实例。Docker 容器化运行可选docker: image: rayproject/ray-ml:latest-gpu # 可改为 latest-cpu 以加快启动 container_name: ray_container pull_before_run: True run_options: - --ulimit nofile65536:65536开启后所有命令都在容器内执行Ray 所需的端口也会自动开放。pull_before_run: True表示每次启动前都拉取最新镜像run_options可向docker run追加额外参数。你还可以用head_image/worker_image分别指定头节点与工作节点的不同镜像例如 GPU 头节点 CPU 工作节点。provider 段GCP 关键配置provider: type: gcp region: us-west1 availability_zone: us-west1-a project_id: null # 全局唯一的项目 ID必填type: gcp让 Ray 加载 node_provider.py 中的GCPNodeProvider。从 config.py#L409-L413 可以看到project_id为空时启动器会直接断言报错project_id must be set in the provider section因此这一项无法省略。region与availability_zone决定了实例的创建位置也用于后续子网subnet自动探测。auth 段SSH 认证auth: ssh_user: ubuntu # 默认自动生成密钥对也可指定自有私钥 # ssh_private_key: /path/to/your/key.pem默认情况下 Ray 会生成新的密钥对并写入项目级元数据commonInstanceMetadata中的ssh-keys源码位于 config.py#L482-L610 的_configure_key_pair。如果你设置了自己的ssh_private_key则需要在头/工作节点的node_config中同步配置对应的KeyName并预先将公钥加入项目级元数据。available_node_types 段节点类型定义available_node_types: ray_head_default: resources: {CPU: 2} node_config: machineType: n1-standard-2 disks: - boot: true autoDelete: true type: PERSISTENT initializeParams: diskSizeGb: 50 sourceImage: projects/deeplearning-platform-release/global/images/common-cpu-v20240922 ray_worker_small: min_workers: 1 max_workers: 2 resources: {CPU: 2} node_config: machineType: n1-standard-2 disks: - boot: true autoDelete: true type: PERSISTENT initializeParams: diskSizeGb: 50 sourceImage: projects/deeplearning-platform-release/global/images/common-cpu-v20240922 # 默认工作节点使用抢占式实例去掉该段即为按需 scheduling: - preemptible: true要点说明resources声明该节点类型提供的 Ray 资源如{CPU: 2}、{GPU: 1}用于调度任务min_workers/max_workers控制该类型工作节点的伸缩区间max_workers优先级更高node_config直接对应 GCP Compute Engine 的instances.insert请求体支持machineType、disks、networkInterfaces、guestAccelerators、metadata、scheduling等字段scheduling: [{preemptible: true}]让工作节点以抢占式实例运行成本更低但随时可能被回收适合容错型批处理任务若同时为头节点和工作节点都显式配置了networkInterfaces则使用手动网络配置否则 Ray 会从当前 region 自动探测并选用一个已有子网逻辑见 config.py#L613-L664 的_configure_subnet。文件同步与初始化命令head_node_type: ray_head_default file_mounts: {} # 远程路径 - 本地路径 映射复制到所有节点 cluster_synced_files: [] # 从头节点同步到工作节点的文件 rsync_exclude: [**/.git, **/.git/**] initialization_commands: [] # Docker 启用时在容器外执行的命令 setup_commands: [] # 节点通用安装命令 head_setup_commands: # 头节点专用安装命令 - pip install google-api-python-client1.7.8 worker_setup_commands: [] head_start_ray_commands: # 头节点启动命令一般无需修改 - ray stop - ray start --head --port6379 --object-manager-port8076 --autoscaling-config~/ray_bootstrap_config.yaml worker_start_ray_commands: # 工作节点启动命令 - ray stop - ray start --address$RAY_HEAD_IP:6379 --object-manager-port8076head_node_type指定头节点使用哪一种节点类型。file_mounts用「远程路径 : 本地路径」字典将本地文件/目录在启动时同步到所有节点。启动命令段默认会关闭旧进程ray stop再以指定端口启动其中--autoscaling-config指向 Ray 生成的最终 bootstrap 配置$RAY_HEAD_IP由 autoscaler 注入工作节点用于定位头节点地址。第四步集群的完整生命周期ray up / attach / down配置文件准备就绪后在本地机器上执行以下命令即可完成一次完整的集群生命周期验证# 下载示例配置也可直接从仓库 python/ray/autoscaler/gcp/example-full.yaml 获取 wget https://raw.githubusercontent.com/ray-project/ray/master/python/ray/autoscaler/gcp/example-full.yaml # 编辑 example-full.yaml 中的 project_id # vi example-full.yaml # 创建或更新集群命令结束时将打印可用于 SSH 登录头节点的命令 ray up example-full.yaml # 在头节点上打开远程终端 ray attach example-full.yaml # 尝试运行一个 Ray 程序 python -c import ray; ray.init() exit # 销毁集群 ray down example-full.yaml执行ray up时后台会依次发生对应 config.py#L379-L397 的bootstrap_gcp流程_configure_project校验项目存在且生命周期状态为ACTIVE不存在则尝试创建_configure_iam_role确保默认服务账号ray-autoscaler-sa-v1project-id.iam.gserviceaccount.com存在并绑定 IAM 角色见下文同时把头节点的serviceAccounts注入配置_configure_key_pair创建/复用 SSH 密钥对并写入项目元数据_configure_subnet探测可用子网并填充networkInterfaces之后由GCPNodeProvider调用 node.py 中GCPCompute.create_instance等 API 创建实例并执行各阶段命令。ray attach实际是在 SSH 通道上为头节点打开交互式 shellray down则逐个销毁实例并释放资源避免持续产生费用。第五步为工作节点配置 Service AccountGCP 专属配置默认情况下只有头节点会以 Service Accountray-autoscaler-sa-v1project-id.iam.gserviceaccount.com运行该账号由启动器自动创建并绑定角色。要让工作节点也使用同一 Service Account例如需要访问 Google Cloud Storage 或 GCR 时请在对应工作节点类型的node_config中加入serviceAccounts配置available_node_types: ray.worker.default: node_config: ... serviceAccounts: - email: ray-autoscaler-sa-v1YOUR_PROJECT_ID.iam.gserviceaccount.com scopes: - https://www.googleapis.com/auth/cloud-platform在 example-full.yaml 的工作节点段中这段配置以注释形式给出取消注释并替换project_id即可启用。从源码 config.py#L40-L47 可以看到该服务账号默认绑定四个 IAM 角色roles/storage.objectAdmin管理 GCS 对象存储roles/compute.admin创建/管理 Compute Engine 实例工作节点由头节点拉起所必需roles/iam.serviceAccountUser允许头节点以该服务账号身份创建工作节点roles/iam.roleViewer允许头节点执行bootstrap_gcp读取角色信息。若配置中包含 TPU 节点还会额外追加roles/tpu.admin见 config.py#L46-L47。此外scopes中的cloud-platform全平台 scope 只是访问边界最终实际权限仍以 IAM 角色为准见 config.py#L468-L477 的注释说明。进阶场景一GPU 集群若需要 GPU 加速参考 example-gpu-docker.yaml。关键差异点如下node_config: machineType: n1-standard-2 sourceImage: projects/ml-images/global/images/c0-deeplearning-common-cu121-v20231209-debian-11 guestAccelerators: - acceleratorType: nvidia-tesla-t4 acceleratorCount: 1 metadata: items: - key: install-nvidia-driver value: True scheduling: - onHostMaintenance: TERMINATEguestAccelerators声明 GPU 型号与数量对应resources: {GPU: 1}启用 GPU 时必须将scheduling.onHostMaintenance设为TERMINATEGPU 不支持热迁移配置镜像需选用带 CUDA 的深度学习镜像initialization_commands中会等待nvidia-smi可用确认驱动安装完成Docker 镜像使用rayproject/ray:latest-gpu纯 Ray或rayproject/ray-ml:latest-gpu含 ML 依赖拉取更慢。底层创建实例时node.py#L486-L522 的_convert_resources_to_urls会自动把machineType规范化为zones/zone/machineTypes/type全路径把acceleratorType规范化为projects/project/zones/zone/acceleratorTypes/type因此配置中可直接写简写形式。进阶场景二TPU 集群Ray 的 GCP 支持同时覆盖 Compute 与 TPU 两种资源node.py#L109-L122 中的GCPNodeType枚举配置示例见 example-tpu-pod.yamlavailable_node_types: ray_head_default: min_workers: 0 max_workers: 0 resources: {CPU: 0} node_config: machineType: n1-standard-4 # ... 普通 Compute 头节点 ray_tpu: min_workers: 1 max_workers: 1 resources: {TPU: 1} # 代码中通过自定义资源 TPU 使用 node_config: acceleratorType: v4-16 runtimeVersion: tpu-vm-v4-baseTPU 节点类型不写machineType而用acceleratorType如v4-16或acceleratorConfigtype topology 组合见 example-tpu-pod-topology.yaml例如type: V4topology: 2x2x1会生成 v4-8TPU作为自定义资源写入resources供应用层调度节点名以-tpu后缀结尾启动器据此区分资源类型node.py#L124-L131从源码 node_provider.py#L279-L320 可以看出TPU pod 还会自动填充TPU-type-head资源用于支持 pod 的扩容调度。需要注意TPU pod 中所有 host 必须执行同一程序因此当前仓库对 TPU pod 的「严格自动伸缩」并不完全适用相关 warning 见 config.py#L187-L194。另外配置文件会开启enableExternalIps以保证 SSH 可达node.py#L776-L781。进阶场景三最小化配置如果只想快速验证example-minimal.yaml 仅需四组字段即可启动auth: ssh_user: ubuntu cluster_name: minimal provider: availability_zone: us-west1-a project_id: null # TODO: 设置你的 GCP 项目 ID region: us-west1 type: gcp其余字段节点类型、资源、命令等都会由启动器从 defaults.yaml 自动补全。可见 Ray 在 GCP 上的「默认即可用」设计只要填好项目与区域启动器就能自行完成密钥注入、子网探测与服务账号创建。底层实现速览从配置到实例的调用链结合源码可以梳理出一次ray up在 GCP 侧的完整调用链ray up解析 YAML 后调用GCPNodeProvider.bootstrap_confignode_provider.py#L275-L277最终落到bootstrap_gcpconfig.py#L379-L397依次完成项目、IAM 角色、密钥对、子网四项配置GCPNodeProvider.create_nodenode_provider.py#L170-L209根据节点配置判断类型Compute 或 TPU批量调用GCPCompute.create_instances/GCPTPU.create_instance实例创建后wait_for_operation以轮询方式默认最多 12 次、间隔 5 秒见 node.py#L46-L53等待 GCP 操作完成TPU 的轮询上限放大为 96 次以适配其慢启动特性节点命名遵循[名称]-[8位UUID]-[compute|tpu]格式node.py#L92-L106autoscaler 通过后缀反推节点所属资源集群关闭或缩容时terminate_node默认直接删除实例若在 provider 中开启cache_stopped_nodes则会改为停止stop实例以便复用node_provider.py#L231-L254。常见问题与注意事项project_id 必填且全局唯一未填写时ray up会在配置校验阶段直接报错config.py#L410-L413凭据来源二选一推荐使用GOOGLE_APPLICATION_CREDENTIALS环境变量或在配置的provider.gcp_credentials中内嵌服务账号 JSON注意 JSON 需格式正确否则启动器会抛出「formatted improperly」错误抢占式实例的取舍preemptible: true能显著降低成本但实例可能随时被回收适合无状态、可重试的分布式任务端口与文件描述符示例配置中默认使用--port6379与--object-manager-port8076部分示例在启动前通过ulimit -n 65536提高文件描述符上限见 defaults.yaml 的启动命令段费用控制测试结束后务必执行ray down避免头节点与工作节点持续计费对于不再需要的集群也可以直接手动在 GCP 控制台删除对应实例。至此你已经掌握了在 GCP 上以配置驱动方式启动、连接与销毁 Ray 集群的完整方法并理解了从 YAML 配置到 GCP API 调用的底层实现链路可以据此按需组合抢占式实例、GPU、TPU 与 Service Account 等能力构建适合自己工作负载的 Ray 集群。【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考