Ray 在 Azure 上的集群部署指南：Ray Cluster Launcher 与 Azure Portal 双路径实战

Ray 在 Azure 上的集群部署指南：Ray Cluster Launcher 与 Azure Portal 双路径实战

【免费下载链接】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 官方文档《Launching Ray Clusters on Azure》为核心，系统讲解在 Microsoft Azure 上启动 Ray 分布式集群的两种方式：通过 Ray Cluster Launcher（ray up/ray attach/ray down）以及通过 Azure Portal 快速部署。阅读本文后，你将掌握 Azure 环境准备、集群配置文件编写与参数含义、SSH 密钥管理，以及基于 DSVM 和 VM Scale Sets 的 Portal 部署细节，并了解 Ray autoscaler 在 Azure 上的底层实现。

概述：在 Azure 上启动 Ray 集群的两种方式

Ray 的 Azure 集群部署有两条路径，可按需选择：

• Ray Cluster Launcher：通过rayCLI 的ray up、ray down、ray attach等命令创建、销毁并连接集群。该方式由 Ray autoscaler 负责节点的弹性伸缩（包括按需实例与 Spot 实例），适合需要精细控制节点规格、镜像和伸缩策略的场景。
• Azure Portal：通过 Azure 门户直接部署模板，使用 Azure Data Science VMs (DSVM) 作为 head 节点，并由 Azure Virtual Machine Scale Sets 管理可自动伸缩的工作节点。注意此路径的伸缩由 Azure VM Scale Sets 完成，而非 Ray autoscaler。Head 节点同时开放 SSH 与 JupyterLab，适合快速上手和数据分析场景。

官方文档与仓库中的部署示例均位于 python/ray/autoscaler/azure，其中defaults.yaml是 Azure 提供的默认配置基线，example-full.yaml是功能最完整的参考示例。

方式一：使用 Ray Cluster Launcher 启动集群

安装 Ray Cluster Launcher

Ray cluster launcher 内置于rayCLI 中，安装 Ray 即可获得ray up、ray down、ray attach等命令。通过 pip 安装带有默认依赖的 Ray：

pip install -U ray[default]

更详细的安装指引可参考 Ray 安装文档。

安装并配置 Azure CLI

集群的创建依赖 Azure CLI 完成登录与资源管理，需要安装azure-cli与azure-identity两个包，并执行az login登录：

# 安装用于操作 Azure CLI 的 Python 包 pip install azure-cli azure-identity # 登录 Azure，命令会引导你在浏览器中完成认证 az login

安装 Azure SDK 库

Ray cluster launcher 在创建 Azure 基础设施（虚拟网络、网卡、虚拟机、资源组等）时需要调用 Azure SDK，请安装以下库：

pip install azure-core azure-mgmt-network azure-mgmt-common azure-mgmt-resource azure-mgmt-compute msrestazure

仓库中的head_setup_commands亦提供了 head 节点上固定的 SDK 版本组合，可作为版本兼容性参考（见 example-full.yaml）：

head_setup_commands: - pip install -U azure-core==1.35.0 azure-cli-core==2.77.0 azure-identity==1.23.1 azure-mgmt-compute==35.0.0 azure-mgmt-network==29.0.0 azure-mgmt-resource==24.0.0 azure-common==1.1.28 msrest==0.7.1 msrestazure==0.6.4.post1

准备集群配置文件

官方提供的 example-full.yaml 会创建一个 head 节点并自动伸缩至最多两个 worker 节点。若沿用文档原始示例（Standard DS2v3 on-demand head + 两个 Standard DS2v3 Spot worker），可参考仓库中更精简的 example-minimal.yaml 与 defaults.yaml；若需要 GPU 与 Docker 支持，可参考 example-gpu-docker.yaml。

在写自己的配置前，必须填写以下 Azure 专属字段：

• location：Azure 数据中心区域，如westus2、centralus；
• resource_group：集群资源所在的资源组名称；
• subscription_id：若不设置，将使用azCLI 当前登录账号的默认订阅。既可以通过命令行az account set -s <subscription_id>指定，也可以在配置文件的provider.subscription_id中显式填写。

以下是provider段落的完整字段说明（来自 example-full.yaml 与 defaults.yaml）：

provider: type: azure location: westus2 # Azure 区域，参见 Azure 全球基础设施位置列表 resource_group: ray-cluster # 资源组名称 # subscription_id: 00000000-0000-0000-0000-000000000000 # 不设置则使用 az cli 的默认订阅 # subnet_mask: 10.0.0.0/16 # 自定义子网掩码，不设置则使用随机掩码 # unique_id: RAY1 # 资源唯一 ID，不设置则基于资源组和集群名自动生成 # msi_name: ray-cluster-msi # 用户托管标识名称 # msi_resource_group: other-rg # 托管标识所在的资源组 # use_internal_ips: True # 是否使用内网 IP # use_external_head_ip: True # 是否仅为 head 节点分配公网 IP # availability_zone: "auto" # 可用区：可指定 "1,2,3"、"1"、"none"，"auto" 表示由 Azure 自动选择

其中availability_zone支持在 provider 层统一设置，也可在单个节点类型内覆盖。仓库中的 example-availability-zones.yaml 演示了 head 节点禁用可用区、worker 继承 provider 配置、以及ray.worker.specific_zone强制指定 zone 2 三种用法。

SSH 密钥配置：自动生成与手动指定

自动生成 SSH 密钥（推荐）

如果配置中未指定任何密钥，Ray 会自动生成 SSH 密钥对，无需手动管理密钥。example-full.yaml的默认配置即为自动生成模式：

auth: ssh_user: ubuntu # SSH keys are auto-generated if not specified # Uncomment and specify custom paths if you want to use existing keys: # ssh_private_key: /path/to/your/key.pem # ssh_public_key: /path/to/your/key.pub

（可选）手动配置 SSH 密钥

如需使用自己已有的密钥对，取消auth段中注释并同时指定私钥与公钥两个路径。以ed25519密钥为例：

auth: ssh_user: ubuntu ssh_private_key: ~/.ssh/id_ed25519 ssh_public_key: ~/.ssh/id_ed25519.pub

RSA 密钥同理：

auth: ssh_user: ubuntu ssh_private_key: ~/.ssh/id_rsa ssh_public_key: ~/.ssh/id_rsa.pub

无论自动生成还是手动指定，Ray 都会通过 Azure ARM 模板将公钥直接注入 VM 的~/.ssh/authorized_keys，从而免密 SSH 登录 head 节点。仓库测试配置 azure-cluster.yaml 中展示了显式指定密钥路径并借助file_mounts将公钥同步到节点的完整做法，可作为自定义密钥场景的参考。

配置节点类型与 Azure ARM 参数

Ray autoscaler 通过available_node_types定义允许的节点类型及其资源。以 example-full.yaml 为例：

available_node_types: ray.head.default: # 该节点类型提供的资源 resources: {"CPU": 4} node_config: azure_arm_parameters: vmSize: Standard_D4s_v3 # 在 Azure 中查找镜像：az vm image list imagePublisher: microsoft-dsvm imageOffer: ubuntu-2204 imageSku: 2204-gen2 imageVersion: latest ray.worker.default: min_workers: 0 max_workers: 2 resources: {"CPU": 4} node_config: azure_arm_parameters: vmSize: Standard_D4s_v3 imagePublisher: microsoft-dsvm imageOffer: ubuntu-2204 imageSku: 2204-gen2 imageVersion: latest # 可选：使用 Spot 实例 priority: Spot # 可选：设置 Spot 实例最高出价 # billingProfile: # maxPrice: -1 head_node_type: ray.head.default

azure_arm_parameters中值得注意的参数：

• vmSize：Azure VM 规格，例如Standard_D2s_v3（2 vCPU）、Standard_D4s_v3（4 vCPU）；
• imagePublisher / imageOffer / imageSku / imageVersion：镜像三元组与版本，用于精确定位 VM 镜像；microsoft-dsvm+ubuntu-2204是仓库默认组合；
• imageId：若使用 Azure Compute Gallery 中的自定义镜像，可填写完整imageId（/subscriptions/.../resourceGroups/.../providers/Microsoft.Compute/galleries/...），此时镜像三元组会被忽略；
• osDiskSize：可选，自定义系统盘大小（单位 GB）；
• priority: Spot：将 worker 节点标记为 Spot 实例，配合billingProfile.maxPrice控制出价上限（-1表示按当前价格付费）。

节点配置的更细粒度定制可通过 ARM 模板azure-vm-template.json完成，但需要注意：对模板的修改在部署 head 节点时生效，而 worker 节点是在 head 节点上完成部署的，因此模板改动必须包含在setup_commands所使用的 wheel 包中，这一约束在配置文件的注释中有明确说明。

启动、连接与销毁集群

配置就绪后即可执行集群生命周期操作：

# 创建或更新集群。命令执行完成后会打印 SSH 连接 head 节点的命令。 ray up example-full.yaml # 在 head 节点上获得远程交互终端 ray attach example-full.yaml # 现在可以在终端中运行 Ray 程序了 # 销毁集群 ray down example-full.yaml

Ray 在 head 节点上默认执行的启动命令（见 example-full.yaml）为：

head_start_ray_commands: - ray stop - ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml worker_start_ray_commands: - ray stop - ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076

--autoscaling-config指向ray up生成的ray_bootstrap_config.yaml，Ray autoscaler 依据该文件中的min_workers/max_workers、idle_timeout_minutes（默认 5 分钟空闲回收）与upscaling_speed（默认 1.0，控制扩容速率）等参数动态调整节点数量。

底层实现：Ray 的 Azure Node Provider

Ray autoscaler 在 Azure 上的能力由专门实现的 Node Provider 提供。从源码结构看，相关实现位于 python/ray/autoscaler/_private/_azure/node_provider.py，配置解析逻辑位于 python/ray/autoscaler/_private/_azure/config.py。其工作流程大致为：

1. ray up读取 YAML 配置并调用 Azure 配置解析逻辑，将azure_arm_parameters等字段映射为 ARM 部署参数；
2. Node Provider 通过 Azure SDK 创建资源组、虚拟网络、网卡与虚拟机，并等待 VM 就绪；
3. 集群运行时，autoscaler 定期检查节点负载与任务队列，依据upscaling_speed和idle_timeout_minutes决定扩容或回收节点；
4. ray down通过 Node Provider 释放全部资源（cache_stopped_nodes: False时直接删除 VM，见 azure-cluster.yaml）。

需要注意的是，DSVM 镜像（Ubuntu 22.04）预置了若干 venv，但其中包含与 Ray 不兼容的 Python 模块，因此setup_commands中通常需要新建干净的 conda 环境（如ray-env，Python 3.10）并安装 Ray，这一模式在 defaults.yaml 与 azure-cluster.yaml 中均有体现。

方式二：使用 Azure Portal 部署集群

如果不想编写 YAML 配置，也可以通过 Azure Portal 直接部署。该路径使用 DSVM 作为 head 节点，并由 Azure Virtual Machine Scale Sets 管理可自动伸缩的节点；head 节点同时提供 SSH 与 JupyterLab 访问。

部署后的连接与使用

模板部署成功后，在部署的Outputs页面会提供：

• 连接 head 节点的 SSH 命令；
• JupyterHub 的访问链接（使用模板输入中指定的用户名/密码登录）。

在 Jupyter notebook 中（使用模板输入指定的 conda 环境，默认py38_tensorflow）连接 Ray 集群仅需两行：

import ray ray.init()

底层机制：azure-init.sh 初始化脚本

Portal 部署的背后由 doc/azure/azure-init.sh 脚本驱动，该脚本按顺序执行以下动作：

1. 激活 DSVM 上可用的 conda 环境之一（由模板参数传入）；
2. 安装 Ray 以及用户指定的其他依赖（通过 wheel 包安装）；
3. 配置 systemd 任务（/lib/systemd/system/ray.service），使 Ray 以 head 或 worker 模式开机自启。

结合 azure-init.sh 源码，脚本实际生成的组件包括：

• ray-head.sh：head 节点启动脚本，自动探测 GPU 数量（nvidia-smi -L | wc -l），执行ray start --head --port=6379 --object-manager-port=8076 --num-gpus=$NUM_GPUS --block --dashboard-host 0.0.0.0，并将文件描述符上限提升至 65536；
• ray-worker.sh：worker 节点启动脚本，通过ray start --address=$RAY_HEAD_IP:6379加入集群；若 Ray 进程退出，会在 1 秒后自动重启，保证 worker 的持续可用；
• tensorboard.sh：head 节点上的 TensorBoard 服务，绑定ray_results日志目录；
• ray.service/tensorboard.service：systemd 单元文件，分别由ray.sh或ray-worker.sh决定启动模式，并通过systemctl enable/start注册为开机自启服务。

由此可以看出 Portal 路径与 Cluster Launcher 路径的核心差异：前者依赖系统级 systemd 常驻进程保证集群可用性，伸缩交给 Azure VM Scale Sets；后者则由 Ray autoscaler 全权管理节点生命周期。

小结

在 Azure 上启动 Ray 集群的两种方式各有适用场景：

• Ray Cluster Launcher适合需要按自定义规格、镜像、可用区与 Spot 策略精细管理集群的场景，配置模板可参考 example-full.yaml、example-minimal.yaml 与 defaults.yaml；
• Azure Portal / DSVM + VM Scale Sets适合快速获得带 JupyterLab 的交互式环境，初始化逻辑可参见 doc/azure/azure-init.sh 与 doc/azure/azure-ray-template.json。

两种方式都要求先完成 Azure CLI 登录与订阅配置。生产环境建议在配置中显式指定location、resource_group、subscription_id，并按需调整节点类型、Spot 优先级与空闲回收策略（idle_timeout_minutes），以获得可控的成本与稳定的集群运行体验。

【免费下载链接】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