主题
规划多节点和异构 Worker
以下任一情况适用于当前工作负载时，再按照本页规划角色和 Worker：
cluster.num_nodes大于1；- 配置包含多个
node_groups； - 不同 Worker 需要不同的节点、GPU 或专用设备；
- 不同 Worker 需要不同的镜像、挂载、环境变量或准备动作；
- 需要在同一台物理机器上有意运行多个 Ray 节点。
从已经验证的 RLinf 配置确定需要多少个 Ray 节点、怎样分组，以及每个节点需要哪些资源，再把这些运行要求映射成 RLark 角色。控制台预填的 Actor、Rollout、Environment 不能用来反推训练拓扑。
在当前 Kubernetes 运行方式下，一个 RLark Worker 对应一个 Pod，并在 Pod 中启动一个 Ray 节点。一个角色定义一组按相同节点选择、资源、镜像、脚本、环境变量和挂载创建的 Worker。
单节点任务从快速开始进入
RLinf 配置使用 cluster.num_nodes: 1，并且一个 GPU 节点能够提供任务所需的资源、镜像、挂载和设备时，请直接按照在单个 GPU 节点上运行 RLinf操作，不需要继续阅读本页的多节点编号和异构资源规划。
角色不是 RLinf 组件
RLark 的角色列表沿用了 Actor、Rollout、Environment 这些名称，但角色实际表示一组 Worker 的创建配置。RLinf 组件仍由 component_placement 放置。
同一组 Ray 节点中的组件即使使用不同 GPU，也不需要仅因组件名称不同而拆分角色。只有需要不同的 Worker 组，或者各组需要不同的节点选择、单个 Worker 资源、镜像、挂载、设备或启动环境时，才建立不同角色。
Step 1 记录 RLinf 的节点和资源要求
从本次实际使用的 RLinf 配置中记录：
cluster.num_nodes：RLinf 需要使用的 Ray 节点总数；node_groups[].node_ranks：哪些 Ray 节点属于同一节点组；component_placement：组件使用哪些资源，以及资源是否重叠；- 每个 Ray 节点需要的 GPU、机器人或其他设备数量；
- 各节点组使用的镜像、数据、挂载、环境变量和启动依赖。
如果这些内容尚未确定，请先回到目标版本的 RLinf 中文文档和已有运行记录。控制台的任务类型只会预填角色，不会设置 RLinf 算法、runner.task_type 或执行模式。
Step 2 把 Ray 节点布局分成角色
先决定需要哪些 RLark Worker，再填写角色：
- 让所有角色的 Worker 数之和等于
cluster.num_nodes。 - 通常把节点选择、单个 Worker 的 GPU/设备、镜像、挂载和启动环境相同的 Worker 放在同一角色中。
- 需要不同节点组或不同运行配置时，再建立其他角色。
- 为 Ray Head 和运行脚本保留一个只创建 1 个 Worker 的 Header 角色。该角色的镜像、挂载和环境必须能够运行 Ray Head 及工作负载入口。
如果一个同构 Worker 组包含多个 Worker，也需要从中划出 1 个 Worker 作为 Header，并相应减少非 Header 角色的 Worker 数。这个拆分只满足当前 Header 单副本要求，不会改变 RLinf 的组件放置。
相同节点选择不会合并 Worker
不同角色可以选择同一批物理节点，但 RLark 会分别计算每个角色的 Worker 和资源：
- 计划创建的 Worker 总数 = 所有角色的已选节点数之和；
- 某个角色的 GPU 申请量 = 该角色的已选节点数 × 单个 Worker GPU 数。
例如，三个角色各匹配 4 个节点时，RLark 会尝试创建 4 + 4 + 4 = 12 个 Worker，而不是按物理节点合并成 4 个。如果每个 Worker 申请 2 张 GPU，总申请量就是 24 张 GPU。三个角色还都不符合 Header 的单 Worker 要求，因此这份配置不能直接提交。
同一台物理机器可以运行多个 Worker，但这些 Worker 仍是不同的 Pod 和 Ray 节点，并分别申请 GPU、获得 RLINF_NODE_RANK。相同物理机器不表示相同 Worker，也不表示共享 GPU。
Step 3 区分节点、资源和进程编号
下表用于判断 RLinf 配置中的编号应与 RLark 的哪个结果对齐。
| 编号 | 在 RLinf 中表示什么 | 在 RLark 中如何核对 |
|---|---|---|
RLINF_NODE_RANK | 当前 Ray 节点在本次运行中的连续编号 | 当前控制台创建路径中，每个 Worker 获得一个编号；按 Job YAML 中角色对应模板的顺序和副本数分配 |
node_groups[].node_ranks | 一个节点组包含哪些 Ray 节点 | 与各角色产生的 Worker 数和连续编号范围对齐 |
| Resource rank | component_placement 选择的 GPU、机器人或节点等资源编号 | 核对每个 Worker 可见的资源能组成所需范围；它不是 RLINF_NODE_RANK |
| Process rank | Actor、Rollout、Env 等组件内部的进程编号 | 由 RLinf 创建和管理，不对应 RLark 角色或 Worker |
例如，env: 0-3:0-7 表示 Env 进程 0–7 使用资源 0–3，不表示创建 8 个 Worker，也不表示使用节点编号 0–3。
同一角色包含多个 Worker 时，Worker 序号与具体物理节点的对应关系并不固定。配置需要把某个节点编号绑定到机器人、相机或指定机器时，请使用当前环境确认过的单节点选择方式，并在任务运行后核对实际落点。
Step 4 根据已有配置选择映射方式
下面三个示例展示不同的 Ray 节点布局如何映射到 RLark。示例中的数量只用于说明方法，实际值应来自已经验证的 RLinf 配置和目标环境。
单节点配置不需要拆成多个角色
cluster.num_nodes: 1 的共享式或混合式配置即使同时包含 Actor、Env 和 Rollout，通常也只需要一个 RLark Worker。component_placement 中的多行配置描述组件怎样使用这个 Worker 中的资源，不表示需要创建同名角色。具体填写步骤见在单个 GPU 节点上运行 RLinf。
使用四个配置相同的 Ray 节点
假设已经验证的 RLinf 配置使用 cluster.num_nodes: 4，四个节点需要相同的镜像、GPU、挂载和环境。
在 RLark 中：
- 一个 Header 角色只匹配 1 个节点；
- 一个或多个非 Header 角色合计匹配另外 3 个节点；
- 所有角色的 Worker 数之和为 4；
- 使用相同 Worker 配置时，各角色可以填写相同的镜像、资源和挂载；
- 在 YAML 预览中确认 Header 副本数为 1，总副本数为 4。
四节点任务需要从合适的 Worker 组中划出一个只匹配 1 个节点的 Header 角色，其余非 Header 角色合计创建 3 个 Worker。这样总数仍为 4，不会额外增加 Worker。需要分别匹配 Header 节点和其余节点时，请让平台管理员提供经过核对的标签条件。
使用不同的节点组运行异构任务
下面的配置使用两个 Ray 节点组：
yaml
cluster:
num_nodes: 2
node_groups:
- label: train
node_ranks: 0
- label: rollout
node_ranks: 1
component_placement:
actor:
node_group: train
placement: all
rollout:
node_group: rollout
placement: all如果两个节点组需要不同的节点、资源或运行配置，可以在 RLark 中建立两个各包含 1 个 Worker 的角色：
- 选择能够运行 Ray Head 和运行脚本的角色作为 Header；
- 让另一个角色作为非 Header Worker 加入 Ray 集群；
- 按 YAML 中角色对应模板的顺序，使节点编号 0 和 1 与
node_groups对齐； - 角色显示名称不需要与 Actor 或 Rollout 同名。
两个角色也可以匹配同一台物理机器。此时 RLark 仍会创建两个 Worker，并分别申请资源；只有目标机器能同时满足两份资源申请，而且 RLinf 配置本来就按两个 Ray 节点规划时，才采用这种放置方式。
理解执行模式对角色规划的影响
执行模式描述 RLinf 组件如何使用 GPU，不直接决定 RLark 角色数量。
| RLinf 执行模式 | 资源关系 | 规划 RLark 角色时注意 |
|---|---|---|
| 共享式（Collocated） | 相关组件使用同一组 GPU | 按 Worker 布局规划角色；确保承担这些组件的 Worker 能看到完整 GPU 集合，并保留已有 offload 配置 |
| 分离式（Disaggregated） | 相关组件使用互不重叠的 GPU | 不重叠资源可以位于同一个 Worker，也可以分布在不同 Worker；只有 Worker 组或运行配置不同才拆角色 |
| 混合式（Hybrid） | 一部分组件共享 GPU，另一部分分开使用 | 继续由 component_placement 表达重叠关系；角色仍按 Worker 布局和运行配置划分 |
保留经过验证的显存管理配置
RLark 只为 Worker 申请 GPU，不会替 Actor、Env 或 Rollout 设置卸载、重新加载或组件常驻方式。共享式和混合式任务应继续使用目标 RLinf 配方中经过验证的 offload 等配置。
没有一种执行模式或角色数量适合所有任务。优先保持已经验证的 RLinf 节点布局和组件放置，再根据目标环境调整节点选择；不要为了适配控制台预填角色而改变 cluster.num_nodes 或 component_placement。
Step 5 在创建页面填写角色
进入创建训练任务后，按规划结果填写：
- 任务类型：只用于预填角色，不会设置 RLinf 执行模式；
- 角色列表：按计划的 Worker 组增删，不按 RLinf 组件名称增删；
- 节点选择：让每个角色的已选节点数等于该组预期 Worker 数；
- GPU和设备资源：填写单个 Worker 的申请数量；
- Header 角色：选择只包含 1 个 Worker，且能运行 Ray Head 和运行脚本的角色。
在 YAML 预览中确认：
- 所有角色的副本数之和等于
cluster.num_nodes。 - 只有一个 Task 模板的
head为true，而且副本数为 1。 - 模板顺序和副本数产生的节点编号范围与
node_groups[].node_ranks一致。 - 每个 Worker 的 GPU、设备、镜像和挂载符合规划。
component_placement仍保留在 RLinf 配置中，没有被角色名称代替。
表单与 YAML 的具体对应关系见任务创建字段。
Step 6 核对实际运行结果
提交后确认：
- 实际 Worker Pod 总数与
cluster.num_nodes一致。 - 每个 Worker 启动一个 Ray 节点，并获得预期范围内的
RLINF_NODE_RANK。 - Ray 集群包含全部预期节点，没有多余节点。
- RLinf 输出的最终
node_groups和component_placement与本次配置一致。 - Actor、Env、Rollout 等组件进程使用的资源符合已有运行方案。
完成资源规划并提交任务后，请按照确认 RLinf 任务是否正常运行核对业务进展、checkpoint 和持久输出；节点数量或资源不一致时，参见训练任务与 Worker 排障。