简介

本文档为算法工程团队在强化学习训练场景中，使用分布式强化学习框架（veRL+Ray）提供基于火山引擎 VKE 集群的多节点训练环境部署方案，详细指导集群配置、存储卷创建、KubeRay 与 RayCluster 部署等步骤，并以 PPO 训练任务（Quickstart: PPO training on GSM8K dataset）为例提供数据集处理、任务提交及监控的全流程操作。

本文使用的训练框架是 veRL（Volcano Engine Reinforcement Learning for LLMs），是云平台针对大语言模型（LLMs）的强化学习框架。它不仅具备灵活、高效且可扩展的强化学习训练，还提供了名为“HybridEngine”的框架，该框架将控制流（在单进程中运行）与计算流（在分布式多进程中运行）分离，并且可以支持多种计算后端、训练与推理并行策略和性能优化技术。

前提条件

物料准备

准备好数据集和模型文件，具体可参考 Quickstart: PPO training on GSM8K dataset 中的说明。

• 下载 Qwen2.5-0.5B-Instruct 模型到本地。

  # 需要先安装好git-lfs，如：apt install git-lfs(Ubuntu), brew install git-lfs(MacOS)
  git lfs install
  git clone https://www.modelscope.cn/Qwen/Qwen2.5-0.5B-Instruct.git
  

• 在本地下载并预处理 gsm8k 数据集文件，需在配置好 verl 的环境下进行，请参考 Installation。

  git clone https://github.com/volcengine/verl
  cd verl
  python3 examples/data_preprocess/gsm8k.py --local_dir ~/data/gsm8k
  

上传模型和数据集文件

1. 创建一个 TOS 桶。
   1. 登录 对象存储控制台。
   2. 在左侧导航栏中选择 桶列表，单击 创建桶。
      
   3. 配置 TOS 桶参数，单击 确认，完成 TOS 桶创建。更多配置项说明，请参见 TOS 官方文档。
      
2. 上传文件。进入 TOS 桶 文件列表 页面，单击 上传文件，再单击 选择文件夹，将数据集和模型的整个文件夹上传。
   

创建 VKE 集群

在容器服务中创建集群，需要注意以下列举的参数配置。其余参数说明和详细的操作步骤，请参见 创建集群。

创建存储卷(PV)和存储卷声明(PVC)

1. 在 VKE 集群中创建对象存储静态存储卷，实现基于 TOS 的 VKE 集群网络存储能力。详情请参见 使用对象存储静态存储卷。
   

   配置项	说明
   存储类型	选择 对象存储。
   访问密钥	单击 创建秘钥，完成秘钥配置。其中 AccessKey ID 和 AccessKey Secret 为您火山引擎账号的 AK/SK。获取方法，请参见 API 访问密钥管理。
   存储桶	选择已创建的 TOS 桶。
   子目录	默认/即可。

2. 创建存储卷声明（PVC），关联上一步创建的 PV。
   

部署步骤

部署 KubeRay Operator

1. 登录 容器服务控制台。
2. 在左侧导航栏中选择 应用中心 > 应用模板。
3. 在 应用模板 页面，找到 kuberay-operator 应用模板，鼠标悬停在该应用模板区域，然后单击 部署。
   
4. 在 部署应用 页面，配置 kuberay-operator 服务参数。
   

   参数	说明
   基本信息
   名称	设置应用名称，同一个命名空间里名称必须唯一。
   项目	选择需要部署应用的项目。默认选择 default（默认项目）。更多项目相关操作和说明，请参见 项目管理。
   集群	选择需要部署应用的目标集群。
   命名空间	选择目标集群下的命名空间。
   编排模板
   Chart 来源	选择应用的 Chart 来源。默认来源为 应用模板，不可配置。
   Chart	选择应用的 Chart 版本，建议选择最新版本。
   配置方式	选择应用的配置方法。每个应用模板的 values.yaml 文件配置方法不同，详细说明，请参见 values.yaml 文件中的注释说明。单击 图标，编辑 values.yaml 文件。编辑完成后单击 确定。

5. 单击 确定，完成应用部署。应用部署完成后会显示在 Helm 应用 页面。可进入详情页面查看该应用的基本信息、关联创建的工作负载、服务、其他资源等。
   

部署 RayCluster

1. 按需修改下面 yaml 文件的内容。
   • 根据节点规格修改 yaml 中 head 和 worker 的资源配置，nvidia.com/gpu为节点 GPU 数量，cpu和memory建议在预留部分资源给其他系统组件的情况下，尽量多分配，比如分配节点资源的 80%。requests和limits的值修改为一样即可。
   • persistentVolumeClaim.claimName配置为已创建的 PVC 名称。
   • rayStartParams中tracing-startup-hook为启动深度观测需要，启动脚本已提供在/workspace/verl/tracing/setup_tracing.py中，只需要执行一下几步就可完成深度观测的启动。（样例配置已包含以下配置，可直接使用）。
     • 在启动命令中添加tracing-startup-hook: "tracing.setup_tracing:setup_tracing"
     • 配置环境变量PYTHONPATH=/workspace/verl就能够完成深度观测的启动，数据会自动上报到 APMPlus。
     • 对 worker 和 header 实例添加 annotation instrumentation.apmplus.volcengine.com/inject-python: "true"。
     • 为减少系统消耗，还需要配置环境变量 OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=system_metrics。
   • 更多配置项说明，请参见 RayCluster Configuration。

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  name: raycluster-kuberay
  namespace: default
spec:
  headGroupSpec:
    serviceType: ClusterIP
    rayStartParams:
      dashboard-host: "0.0.0.0"
      tracing-startup-hook: "tracing.setup_tracing:setup_tracing"
    template:
      metadata:
        annotations:
          instrumentation.apmplus.volcengine.com/inject-python: "true"
      spec:
        containers:
        - name: ray-head
          image: ai-containers-cn-beijing.cr.volces.com/deeplearning/verl:ngc-th2.6.0-cu126-vllm0.8.4-flashinfer0.2.2-cxx11abi0-custom-v1
          imagePullPolicy: IfNotPresent
          resources:
            limits:
              cpu: "30"
              memory: 100Gi
              nvidia.com/gpu: 2
            requests:
              cpu: "30"
              memory: 100Gi
              nvidia.com/gpu: 2
          volumeMounts:
          - name: log-volume
            mountPath: /tmp/ray
          - name: tos-pv
            mountPath: /data
          env: 
          - name: PYTHONPATH
            value: /workspace/verl
          - name: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
            value: system_metrics
        volumes:
        - name: log-volume
          emptyDir: {}
        - name: tos-pv
          persistentVolumeClaim:
            claimName: verl-pvc

  workerGroupSpecs:
  - groupName: workergroup
    replicas: 1
    minReplicas: 1
    maxReplicas: 3
    rayStartParams: {}
    template:
      metadata:
        annotations:
          instrumentation.apmplus.volcengine.com/inject-python: "true"
      spec:
        containers:
        - name: ray-worker
          image: ai-containers-cn-beijing.cr.volces.com/deeplearning/verl:ngc-th2.6.0-cu126-vllm0.8.4-flashinfer0.2.2-cxx11abi0-custom-v1
          imagePullPolicy: IfNotPresent
          resources:
            limits:
              cpu: "30"
              memory: 100Gi
              nvidia.com/gpu: 2
            requests:
              cpu: "30"
              memory: 100Gi
              nvidia.com/gpu: 2
          volumeMounts:
          - name: log-volume
            mountPath: /tmp/ray
          - name: tos-pv
            mountPath: /data
          env: 
          - name: PYTHONPATH
            value: /workspace/verl
          - name: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
            value: system_metrics
        volumes:
        - name: log-volume
          emptyDir: {}
        - name: tos-pv
          persistentVolumeClaim:
            claimName: verl-pvc

2. 登录 容器服务控制台。单击目标集群名称，进入集群配置页面。
3. 在左侧导航栏中选择 工作负载 > 对象浏览器。
4. 单击 使用 Yaml 创建，选择 类型 为 自定义，填入修改后的 Yaml，单击 确定，默认部署到 default 命名空间。
   

检查运行状态

在左侧导航栏中选择 工作负载 > 容器组，查看 head 和 worker 的状态（容器组名称分别为raycluster-kuberay-head-xxxx和raycluster-kuberay-workergroup-worker-xxxx），显示Running即完成启动，这里花费时间相对较长。

执行训练任务

提交训练任务

1. 在左侧导航栏中选择 工作负载 > 容器组，选择 raycluster-kuberay-head-xxxx 容器组，单击右上角 控制台，进入指定容器组的控制台。
   
2. 在控制台中输入以下命令，进入到 verl 目录，并提交训练任务。

cd /workspace/verl
ray job submit --address="http://127.0.0.1:8265" \
    --runtime-env=verl/trainer/runtime_env.yaml \
    --no-wait \
    -- \
    python3 -m verl.trainer.main_ppo \
    data.train_files=/data/data/gsm8k/train.parquet \
    data.val_files=/data/data/gsm8k/test.parquet \
    data.train_batch_size=256 \
    data.max_prompt_length=512 \
    data.max_response_length=256 \
    actor_rollout_ref.model.path=/data/Qwen2.5-0.5B-Instruct \
    actor_rollout_ref.actor.optim.lr=1e-6 \
    actor_rollout_ref.actor.ppo_mini_batch_size=64 \
    actor_rollout_ref.actor.ppo_micro_batch_size_per_gpu=4 \
    actor_rollout_ref.rollout.log_prob_micro_batch_size_per_gpu=8 \
    actor_rollout_ref.rollout.tensor_model_parallel_size=1 \
    actor_rollout_ref.rollout.gpu_memory_utilization=0.4 \
    actor_rollout_ref.ref.log_prob_micro_batch_size_per_gpu=4 \
    critic.optim.lr=1e-5 \
    critic.model.path=/data/Qwen2.5-0.5B-Instruct \
    critic.ppo_micro_batch_size_per_gpu=4 \
    algorithm.kl_ctrl.kl_coef=0.001 \
    trainer.logger=['console'] \
    trainer.default_hdfs_dir=null \
    trainer.n_gpus_per_node=2 \
    trainer.nnodes=2 \
    trainer.save_freq=10 \
    trainer.test_freq=10 \
    trainer.total_epochs=15

训练任务提交成功后，预期输出如下图所示。

查看训练任务状态

创建路由规则，对外暴露 ray dashboard 服务。

1. 在左侧导航栏中选择 服务与路由 > 路由规则，单击 创建路由规则，配置路由规则。
   

   需要注意以下列举的参数配置。其余参数说明和详细的操作步骤，请参见 通过控制台创建 ALB Ingress。

   配置项	说明
   Ingress类型	选择 应用型负载均衡 ALB
   协议	选择 HTTP。
   路径	配置为/。
   服务	配置为raycluster-kuberay-head-xxxxxx:8265。

   
   

2. 创建完成后，在浏览器地址栏直接输入路由规则的 VIP，即可进入 dashboard，查看训练任务日志和集群状态。
   
   
   
   

默认情况下，训练出的 Checkpoint 保存在 raycluster-kuberay-head-xxxx 容器组的/tmp/ray/session_xxxxx/runtime_resources/working_dir_files/_ray_pkg_xxxxx/checkpoints/verl_examples/gsm8k目录中。

开启观测配置

基础观测

开启观测配置

1. 登录 容器服务控制台。

2. 在左侧导航栏中选择 云原生观测 > 概览，按照 接入指引，开启云原生观测和容器监控。包括：

   • 开启云原生观测。

   • 绑定托管 Prometheus 工作区。

   • 安装Prometheus-agent 组件。
     

     说明

     更多配置详情，请参考 开启观测。

3. 创建采集配置。
   整体采集架构如下图所示，主要采集 Ray head node 和 worker node 的指标。
   

首先请确认集群里是否已经创建 ray 的 PodMonitor，如果没有需要创建。
确认方式：在容器服务控制台左侧导航栏中，选择 工作负载 > 对象浏览器，搜索 podmonitor，点击进入后，搜索是否有 ray 相关的采集配置。

如果集群中未创建 ray 的 PodMonitor，请按照以下步骤创建 PodMonitor。

1. 在集群管理页面的左侧导航栏中，单击 工作负载 > 对象浏览器。
2. 单击 使用 Yaml 创建，复制如下代码，创建对应的 PodMonitor。

   • Head node 的采集配置 PodMonitor。

     apiVersion: monitoring.coreos.com/v1
     kind: PodMonitor
     metadata:
       labels:
         volcengine.vmp: "true"
       name: ray-head-monitor
       namespace: default
     spec:
       jobLabel: ray-head
       # Only select Kubernetes Pods in the "default" namespace.
       namespaceSelector:
         matchNames:
           - default
       # Only select Kubernetes Pods with "matchLabels".
       selector:
         matchLabels:
           ray.io/node-type: head
       # A list of endpoints allowed as part of this PodMonitor.
       podMetricsEndpoints:
         - port: metrics
           relabelings:
             - action: replace
               sourceLabels:
                 - __meta_kubernetes_pod_label_ray_io_cluster
               targetLabel: ray_io_cluster
         - port: as-metrics # autoscaler metrics
           relabelings:
             - action: replace
               sourceLabels:
                 - __meta_kubernetes_pod_label_ray_io_cluster
               targetLabel: ray_io_cluster
         - port: dash-metrics # dashboard metrics
           relabelings:
             - action: replace
               sourceLabels:
                 - __meta_kubernetes_pod_label_ray_io_cluster
               targetLabel: ray_io_cluster
     

   • Worker Node 的采集配置 PodMonitor。

     apiVersion: monitoring.coreos.com/v1
     kind: PodMonitor
     metadata:
       name: ray-workers-monitor
       namespace: default
       labels:
         volcengine.vmp: "true"
     spec:
       jobLabel: ray-workers
       # Only select Kubernetes Pods in the "default" namespace.
       namespaceSelector:
         matchNames:
           - default
       # Only select Kubernetes Pods with "matchLabels".
       selector:
         matchLabels:
           ray.io/node-type: worker
       # A list of endpoints allowed as part of this PodMonitor.
       podMetricsEndpoints:
       - port: metrics
         relabelings:
         - sourceLabels: [__meta_kubernetes_pod_label_ray_io_cluster]
           targetLabel: ray_io_cluster
     

     说明

     请关注和修改以下配置：

     • namespace：PodMonitor 所在的 namespace，理论上可创建在任意的 namespace 里。
     • namespaceSelector：选择匹配哪些 namespace 下的 ray cluster pod。请修改为 ray 所在的 namespace。

     

查看监控面板

采集规则配置完成后，ray 的指标就被采集到托管 Prometheus 工作区了，您可以使用托管 Prometheus 的 Explore 功能查询对应的指标。

您可以使用托管 Prometheus 预置面板查看 ray 监控（ray 监控查看需要开白）。

1. 登录 VMP 服务控制台。
2. 在左侧导航栏中选择 监控看板。搜索 ray，即可查看 ray 相关看板。
   

您也可以使用自建 Grafana 查看 ray 的监控图表。

1. 在容器服务器集群中搭建 Grafana 服务，详情请参见 在容器服务集群中部署 Grafana 并接入工作区
2. 登陆自建 Grafana ，导入如下看版。
   
   

   ray_default_dashboard.json

   113.80KB

   
3. 导入数据源选 VMP。
   
   导入后效果如图所示：
   
   

深度观测

开启观测配置

1. 部署 APMPlus 观测组件。
   在 VKE 集群控制台界面，进入组件管理，在栏目选择监控，找到 apmplus-opentelemetry-collector，apmplus-server-agent 两个组件并进行安装。安装好的页面如下图，确认两个组件都是已安装状态且无异常提示。
   

2. 开启添加深度观测。给 ray 相关实例增加以下注解。

   key	value
   instrumentation.apmplus.volcengine.com/inject-python	true