接入现有 RLinf 工作负载

按照本页把已经验证过的 RLinf 镜像、命令和配置整理成 RLark Job。页面中的结构示例不包含可直接运行的镜像、命令、算法配置或硬件参数，实际值需要来自你的工作负载和目标环境。

RLinf 配置使用 cluster.num_nodes: 1，并且一个 GPU 节点能够提供全部资源时，请先使用在单个 GPU 节点上运行 RLinf。本页适合多节点、多个 node_groups、不同 Worker 运行环境或其他需要重新规划角色的工作负载。

先整理现有工作负载

先从现有 RLinf 项目和运行记录中整理你已经使用的内容：

• 代码版本、镜像地址和明确版本，以及可以在镜像中执行的启动命令；
• Hydra 配置、命令行覆盖项、cluster.num_nodes、node_groups 和 component_placement；
• 每个 Ray 节点需要的 CPU、内存、GPU 或专用设备；
• 数据、模型、checkpoint 和输出在容器中使用的路径；
• 环境变量、准备动作和挂载需求；
• 可以判断应用已经启动、正在推进或已经失败的日志与输出。

这些信息描述工作负载本身。目标集群、节点标签、平台中的设备资源名称、StorageClass 和 Domain 等平台值，可以在后面的相应步骤从当前环境的说明或平台管理员处取得。

再取得目标环境信息

根据工作负载要求，请平台管理员或当前环境的使用说明提供：

• 可用的目标集群，以及每组 Worker 应使用的节点标签和实际匹配数量；
• 每个匹配 Node 可提供的 GPU、CPU、内存和专用设备，以及设备在控制台中的名称；
• 目标集群拉取镜像的方式；
• 需要挂载时可用的 StorageClass，或已经确认存在的节点目录；
• 任务确实需要跨集群通信、SSH 或其他访问能力时，对应的可用方式；
• 工作负载必须声明 CPU、内存或 /dev/shm 时，当前环境支持的提交方式。

创建页面会显示所选集群中的节点匹配数，但不会检查相同标签是否也会匹配其他集群。请使用管理员确认的完整节点条件；Header 角色需要只匹配 1 个 Node。

确认关键条件后再提交

• 镜像、运行命令和最终使用的 RLinf 配置已经明确；
• 各角色的 Worker 总数与 cluster.num_nodes 一致，而且 Header 角色只创建 1 个 Worker；
• 必需的资源、存储、网络和设备条件已经确认；
• 工作负载需要创建页面无法填写的字段时，当前环境已经提供其他受支持的提交方式；
• 任务连接真实机器人或其他物理设备时，已经完成安全审批和现场确认。

任一条件仍待确认时，请暂停提交并补齐所需信息。

把两类信息逐项对照，确认目标环境能够满足工作负载要求后，再填写 Job。创建 Job 后，在团队运行记录中保存 Job 名称、复核后的 Job YAML、镜像与配置版本，以及首次运行的检查结果。不要把团队记录链接写入镜像、环境变量或脚本。

RLinf 工作负载 ─┐
                ├─ 核对是否匹配 → RLark Job YAML → 首次运行记录
目标环境信息 ───┘

确定配置如何进入任务

接入前先确定每项配置的来源，以及它通过镜像、脚本、环境变量、挂载还是 Job 字段进入任务。RLark 会按 Job 内容创建并运行 Worker，但不会把表单内容写回 RLinf 或 Hydra 配置。

配置位置	包含的内容	接入时怎么处理
镜像	RLinf 代码、Python 和 Ray 环境、系统库、设备用户态依赖及稳定的基础文件	使用来源和版本可追溯的镜像。Worker 启动时会用 RLark Ray 脚本作为主容器命令，不要依赖镜像 ENTRYPOINT 执行初始化。
外部 RLinf/Hydra 配置	算法参数、模型和数据约定、RLinf 自身的组件或进程配置、业务输出约定	保留在工作负载所属项目中，并通过镜像或挂载提供。环境变量只有在配置或脚本显式读取时才会生效。
prepareScript	该角色的每个 Worker 在 Ray 启动前需要的环境激活、配置复制和低风险检查	脚本应能重复执行并便于检查；稳定依赖应写入镜像，不要在每次启动时临时安装。
runScript	Header 角色在 Ray 启动和集群检查之后执行的工作负载入口	只有 Header 角色对应的 Task 模板保存；该模板创建的每个 Worker 都会执行，因此必须把副本限制为 1。集群检查失败时仍会继续，运行脚本还须验证自身依赖是否就绪。
环境变量	非敏感且由程序或配置显式读取的运行参数	控制台把值写入 Pod 模板，但不验证变量名，也不会自动改写 RLinf/Hydra 文件；密钥使用组织批准的管理方式。
挂载	镜像外部的配置、数据、checkpoint 和需要持久化的输出	同时确认来源、容器路径和读写影响。挂载到已有目录可能遮蔽镜像内容；hostPath 还必须在每个匹配节点上成立。
RLark Job	角色和 Header、节点选择、副本、GPU/设备资源、镜像引用、脚本、环境变量、挂载、Domain、SSH 公钥和 TensorBoard 目录	表达调度与运行结构；提交前另外验证算法配置和镜像内容，运行后再检查训练结果或硬件行为。当前控制台不能填写 CPU 和内存请求。

同一项配置尽量只保留一个来源。例如，算法参数已经写入版本控制中的 Hydra 配置时，不要再在运行脚本中保留另一套默认值；需要覆盖时，请在本次运行记录中写明覆盖项、来源和原因。

如果现有配置包含多个 Ray 节点、多个 node_groups 或不同 Worker 运行条件，先按规划多节点和异构 Worker确定 Worker 数量、每个 Worker 的资源和节点编号。控制台字段与 Job YAML 路径见任务创建字段。

配置映射示例

下面以“一个单副本协调入口，加上一组并行采样进程，并把结果写入持久存储”为例，说明这些要求如何填写到 RLark。示例中的镜像、命令、标签、资源数量、路径和 Hydra 值都需要用本次任务的实际内容补充，不能直接提交。

工作负载要求	目标环境要确认什么	在 RLark 中填写和检查
代码 commit、镜像地址和版本、Hydra 文件、override 和解析后的最终配置	目标集群能够拉取相应镜像	为每个角色填写对应镜像，并确认 Job YAML 中的引用与本次使用的镜像一致；通过镜像或挂载提供 Hydra 配置
唯一的协调或训练入口，以及对应的 runScript	完整节点选择器在全部 Node 中恰好匹配 1 个可用 Node	选择该角色为 Header；确认对应 Task 模板的副本数为 1，而且只有这个模板包含运行脚本
需要单独一组 Ray 节点的采样或服务、准备动作和兼容镜像	每组 Worker 的选择器、匹配节点和单个 Worker 可用资源	需要不同 Worker 组或不同节点、资源、镜像、挂载、设备、环境时创建不同角色；选择器可以重叠，但副本数和资源分别累计。还需检查 Ray、Python 和通信协议兼容性
RLinf node_groups、component_placement、预期进程及节点/资源/进程编号	实际 Worker、GPU 和设备能够满足放置要求	按预期的 Worker 边界规划角色、nodeSelector、副本和资源；让 node_groups[].node_ranks 对齐 Worker 编号，component_placement 继续保留在 RLinf 配置中
env_configs 中各节点编号使用的变量和 Python 解释器	目标节点上的解释器、驱动、设备和运行限制	把 env_configs 保留在 RLinf YAML 中；只有 Ray 启动前的容器基础环境确实需要时，才另外填写角色环境变量或 prepareScript。两者的生效阶段和范围不同，也不会自动同步
输入版本、容器路径、对象前缀、checkpoint、输出和完整性规则	可用的 StorageClass，或每个匹配节点上都成立的 hostPath 条件	添加 PVC、对象存储或主机目录挂载；确认实际读写位于挂载内，并检查多 Worker 访问方式
跨集群业务端口、拓扑和通信网卡	可用的 Domain 和经过检查的端到端连通性	选择 Job Domain，并在应用配置中设置通信网卡；Domain 不会替代 RLINF_COMM_NET_DEVICES 或端口检查
预期日志、指标、checkpoint 或输出等首次成功信号	能够从平台查看哪些 Pod 和 Ray 状态	没有对应的 Job 字段；第一次运行后，把平台状态和业务结果一起写入运行记录

这张表用于确认每个值从哪里取得、填入哪个 Job 字段，以及运行后到哪里验证。RLark 角色用于组织计划的 Worker 分组，不必与 RLinf Node Group 或组件同名；提交前还要确认 Worker 数量、节点编号和可见资源能够满足 RLinf 的放置配置。

Job YAML 结构示例

提交前替换全部占位符

所有尖括号内容都需要使用已经确认的工作负载要求和目标环境条件填写，再与控制台生成的 YAML 逐项核对。请勿删除占位符后凭经验猜值。

apiVersion: rlinf.io/v1alpha1
kind: Job
metadata:
  name: <JOB_DNS_NAME_FROM_REVIEW>
spec:
  # 可选；仅在目标 Domain 和端到端连通性已经确认时保留。
  domain: <OPTIONAL_CONFIRMED_DOMAIN_NAME>
  tasks:
    - name: <HEAD_TASK_NAME>
      head: true
      agentType: Kubernetes
      role: <ACTOR_OR_ROLLOUT_OR_ENV>
      nodeSelector:
        <ADMIN_VERIFIED_LABEL_KEY>: <ADMIN_VERIFIED_SINGLE_VALUE>
      prepareScript: |-
        <REVIEWED_HEAD_PREPARE_SCRIPT_OR_EMPTY>
      runScript: |-
        <REVIEWED_RLINF_ENTRYPOINT>
      kubernetes:
        workload:
          kind: StatefulSet
          replicas: <MUST_RESOLVE_TO_EXACTLY_1_FOR_HEAD_TASK>
          template:
            spec:
              containers:
                - name: main
                  image: <VERIFIED_IMMUTABLE_IMAGE_REFERENCE>
                  env:
                    - name: <NON_SECRET_VARIABLE_NAME>
                      value: <NON_SECRET_REVIEWED_VALUE>
                    - name: RLARK_TASK_ROLE
                      value: <HEADER_ROLE_DISPLAY_NAME_GENERATED_BY_UI>
                  resources:
                    requests:
                      <CONFIRMED_RESOURCE_NAME>: <CONFIRMED_PER_WORKER_QUANTITY>
                    limits:
                      <CONFIRMED_RESOURCE_NAME>: <CONFIRMED_PER_WORKER_QUANTITY>
                  volumeMounts:
                    - name: <GENERATED_VOLUME_NAME>
                      mountPath: <REVIEWED_CONTAINER_PATH>
              volumes:
                - name: <GENERATED_VOLUME_NAME>
                  <HOST_PATH_OR_PERSISTENT_VOLUME_CLAIM_BLOCK>: <GENERATED_MOUNT_SOURCE>
    - name: <NON_HEAD_TASK_NAME>
      head: false
      agentType: Kubernetes
      role: <ACTOR_OR_ROLLOUT_OR_ENV>
      nodeSelector:
        <ADMIN_VERIFIED_LABEL_KEY>: <ADMIN_VERIFIED_SINGLE_VALUE>
      prepareScript: |-
        <REVIEWED_WORKER_PREPARE_SCRIPT_OR_EMPTY>
      kubernetes:
        workload:
          kind: StatefulSet
          replicas: <MATCH_COUNT_CONFIRMED_ACROSS_ALL_NODES>
          template:
            spec:
              containers:
                - name: main
                  image: <VERIFIED_IMMUTABLE_IMAGE_REFERENCE>
                  env:
                    - name: RLARK_TASK_ROLE
                      value: <NON_HEADER_ROLE_DISPLAY_NAME_GENERATED_BY_UI>
                  resources:
                    requests:
                      <CONFIRMED_RESOURCE_NAME>: <CONFIRMED_PER_WORKER_QUANTITY>
                    limits:
                      <CONFIRMED_RESOURCE_NAME>: <CONFIRMED_PER_WORKER_QUANTITY>
              volumes: []

spec.tasks[] 中的两个条目都是 Task 模板，不是已经创建的 Task 资源。创建页面还会根据挂载类型生成具体的 volumeMounts、volumes 和可选 pvcStorageMap。上面的示例没有展开 SSH 公钥和 TensorBoard 字段。请以控制台为本次任务生成的完整 YAML 为准，并逐项对照任务创建字段。非 Header 模板没有 runScript，因为创建页面只把公共运行脚本写入 Header 角色对应的模板。

Step 1 固化外部工作负载

在打开创建表单前，整理并复核以下工作负载信息：

1. 镜像地址、明确版本、构建来源和联系人。
2. 启动命令及其明确的工作目录。
3. 配置文件、输入数据和输出目录。
4. 启动前需要执行的准备动作。
5. 启动成功、正常运行和运行失败时，日志或输出中分别会出现什么。

先在工作负载原有环境中验证这些内容，再把调度和运行配置填入 RLark 表单。算法配置、镜像内容或镜像入口存在问题时，请先在原有环境修复，不要通过提交 Job 试错。

按照提交训练任务前检查，分别检查表单结构、RLinf 工作负载和目标环境资源。如果尚未为工作负载定义不会占用资源的检查方法，不要把直接启动 RLinf 命令当作预检查。

Step 2 规划角色和 Header

先从已经验证的 RLinf 配置确定需要多少个 Ray 节点、怎样分组，以及每个节点需要哪些资源。通常把节点选择、单个 Worker 资源、镜像、挂载和启动环境相同的 Worker 放在一个角色中；需要不同 Worker 组或不同运行配置时，再拆成不同角色。同一组 Worker 中的 RLinf 组件由 component_placement 决定资源是共享还是分离，不要据此拆分角色。

不同角色可以使用重叠的节点选择条件。此时，同一个 Node 会在各角色中分别计入匹配数量，各角色也会分别创建 Worker 和申请资源。请把各角色的 Worker 数之和与已有的 cluster.num_nodes 对照，并核对共享节点上的合计资源需求；数量不一致时回到角色规划，不要通过修改 cluster.num_nodes 适配意外增加的 Worker。

先按规划多节点和异构 Worker确定需要哪些 Worker，以及每个 Worker 使用哪些资源，再选择 Header。RLinf 的 component_placement 继续随工作负载配置进入镜像或挂载，不会由控制台角色生成。

多角色任务优先使用同一镜像版本或同一构建链路生成的镜像。若角色确实需要不同镜像，逐对确认 Ray 版本和通信兼容性，并核对 Python、RLinf、配置格式、驱动和设备依赖。控制台允许填写不同镜像，但不会执行兼容性检查。

选择一个 Header 角色。当前控制台会把该角色标记为 head: true，并只在这个任务模板中写入运行脚本；但数据面会让该模板的每个副本都启动 Ray Head 并执行运行脚本。提交前确认 YAML 中只有一个任务模板的 head 为 true，且该模板副本数恰好为 1。

控制台允许编辑显示名称，但 Job YAML 中的 role 仍是 Actor、Rollout 或 Env。自定义名称不会自动产生新的运行时语义；必须在 YAML 预览中检查每个模板的 name、role 和 RLARK_TASK_ROLE 环境变量是否符合预期。

Step 3 选择集群、节点和资源

逐个角色完成以下配置：

1. 选择目标集群。
2. 使用当前节点标签构造节点选择器。每个键只能使用一个值；不要使用界面提供的同键多值组合。
3. 让平台管理员在控制面的全局 Node 清单中应用完整选择器，记录所有匹配 Node 的名称和命名空间，并证明结果只属于目标集群。创建任务弹窗只显示所选集群内的匹配结果，不能替代这一步。
4. 确认表单显示的匹配节点数至少为 1，并确认副本数与管理员记录的目标集群匹配数一致。
   • 对 Header 角色，匹配节点数和副本数必须恰好为 1。
5. 填写 GPU 和其他设备资源。控制台会把非零 GPU 和设备同时写入 requests 与 limits。
6. 记录工作负载所需的 CPU 和内存。当前控制台没有对应输入项；如果必须设置非空请求，停止本流程，不要把缺失字段当作平台默认值。
7. 确认选择器命中的节点确实能够拉取镜像、访问存储并提供所需设备。多个角色命中同一个 Node 时，还要确认该节点能够同时满足这些角色合计的 GPU、设备和其他资源需求。

当前调度使用标签选择器，不保证落到某个固定节点。请勿使用逗号分隔的同键多值：这种写法在 Task 所属集群、实际调度和创建向导预览中的处理方式可能不一致。

选择条件重叠时，按照 Step 2 的规划核对 Worker 总数、RLINF_NODE_RANK 和共享节点上的合计资源；相同的节点选择不会合并不同角色创建的 Worker。

核对节点标签的全局匹配范围

创建任务弹窗中的集群只用于筛选候选 Node，实际运行位置由节点标签决定。提交前，请让平台管理员确认标签组合只匹配预期集群和 Node，并确认 Header 角色只匹配 1 个 Node；匹配范围过大时，请先补充更精确的节点标签。

Step 4 配置镜像和运行环境

为每个角色填写已经验证、来源明确的镜像地址和版本。可以直接使用团队提供的版本 tag；不要使用 latest 或会被重复覆盖的开发 tag。需要精确复现时，记录该版本实际对应的 digest。团队已经提供 digest 时也可以直接填写。详细说明见选择镜像版本和执行入口。不要把未经当前工作负载验证的镜像标签或表单占位命令当作可运行示例。当前控制台只验证镜像字段非空，不验证镜像来源、内容或多角色兼容性。

RLark 会用 bash 启动 Ray Head 或 Worker 脚本，并以这段脚本替代镜像的 ENTRYPOINT。因此，每个角色镜像都必须提供 bash 和 Ray CLI，Header 角色使用的镜像还必须提供名为 python 的可执行文件供 Ray 节点检查使用；依赖入口完成的环境激活、目录切换或配置生成必须改为镜像构建步骤，或显式放入对应的准备脚本和 Header 角色的运行脚本。

按需填写：

• prepareScript：该角色的每个 Worker 在 Ray 启动前执行的准备动作；保持可重复和低副作用，稳定依赖应固化进镜像。
• 环境变量：非敏感、可审计且由程序或配置显式读取的运行参数；平台保留名称与作用域参见运行环境与环境变量。
• 主机目录挂载：目标节点上已确认存在、权限和影响范围清楚的路径。
• 对象存储挂载：目标集群中已经存在并已确认可用的存储类；需要连接新的 Bucket 时，参见创建和管理存储类。

挂载目标如果与镜像中已有的代码或配置目录重叠，容器看到的内容可能被挂载覆盖。提交前应明确哪些文件来自镜像、哪些来自外部配置或数据。需要在 Pod 重建或后续任务中使用的输出应写入经过验证的对象存储；只有管理员确认任务会回到保留相同目录的节点时，才依赖主机目录。

选择挂载方式、取得 StorageClass 和规划容器内挂载路径的步骤见在训练任务中使用存储；对象存储、PVC 和容器挂载的底层关系见存储。

控制台会把环境变量值写入 Pod 模板。凭据和其他敏感值必须使用组织批准的 Secret 或密钥管理方式，不要直接填写到表单中。

主机目录

主机目录把节点文件系统暴露给工作负载。只有在平台管理员确认路径、权限、读写影响和清理方案后才能使用；不清楚影响时改用受管理的存储，或暂停接入。

Step 5 配置公共行为

在公共配置中：

1. 再次确认唯一 Header 角色，并确认其全局匹配记录和 YAML 副本数都为 1。
2. 仅当平台管理员已经确认目标 Domain 和端到端连通性，且工作负载确实需要跨集群通信时，选择 Domain。
3. 仅当需要远程访问并且公钥已经在 SSH 公钥管理中登记时，选择公钥。
4. 填写已经在镜像中验证的运行脚本，并显式进入所需工作目录。该脚本由 Header 角色创建的每个 Worker 在 Ray 启动和集群检查之后执行，因此当前必须确保只有 1 个副本；由于检查失败时仍会继续，运行脚本还必须验证自身依赖是否就绪。不要依赖镜像 ENTRYPOINT。
5. 只有在工作负载确实写出兼容事件文件且目录已确认时，填写 TensorBoard 目录。

RLinf 命令和日志路径必须来自本次使用的代码、镜像和配置；不要使用未经当前工作负载验证的模板值。

Step 6 检查 YAML 后再提交

在 YAML 预览中至少检查：

• apiVersion 为 rlinf.io/v1alpha1，kind 为 Job，名称符合预期。
• spec.tasks 中每个预期角色恰好有一个任务模板。
• 只有预期模板为 head: true，runScript 只出现在该模板，且该模板的副本数恰好为 1。
• 每个模板的 nodeSelector 非空且只含单值条件，并与管理员提供的全局匹配记录一致；副本数不为零。
• kubernetes.workload 的副本数、Pod 模板、容器镜像、GPU 和设备资源与确认结果一致；镜像引用与提交前确认的地址和版本一致。创建向导没有 CPU 或内存输入项，因此生成的 YAML 也不会包含这两项请求。
• 不同角色的选择条件存在重叠时，Worker 总数已经按角色分别累计，共享节点也能够满足各角色的合计资源需求。
• 环境变量、volume、volumeMount 和 pvcStorageMap 没有意外路径或敏感值。
• 不同角色的镜像、Ray 和工作负载依赖已按兼容性记录完成核对，挂载没有意外遮蔽镜像内容。
• 可选的 Domain、SSH 公钥和 TensorBoard 目录只在确有需要时出现。

本流程只提交 Kubernetes StatefulSet 工作负载。Docker 和 Raw 运行时没有对应的控制台接入步骤，请勿用于本流程。

YAML 预览是将要提交的 RLark 资源定义，不是 RLinf 算法配置。预览正确也不能证明镜像内的配置、命令或训练逻辑正确。

Step 7 把“已提交”和“已运行”分开验证

提交成功只表示 API 接受了 Job。随后还需要分别确认：

1. Job 和各 Task 已创建，并记录当前状态与消息。当前 StatefulSet Task 不会上报 Succeeded 或 Failed，因此没有失败状态不等于运行正常。
2. Task 实际观察到的节点和 Pod 符合选择器与副本设计。
3. 镜像拉取、挂载和进程启动均成功。
4. 任务自己的成功信号、日志、指标和输出符合所属项目的验收标准；不要等待 Job 自动进入成功或失败终态。

需要保留或恢复训练时，在停止前按保留并恢复 RLinf 训练验证 checkpoint 完整性；需要 TensorBoard、W&B 或 SwanLab 时，按配置实验追踪配置 RLark 入口和外部服务，并分别验证两端结果。

如果运行失败，请保留提交时的 YAML、API 错误、Job/Task 状态和第一条失败消息。一次只修改一个已经确认的问题，再重新执行对应检查；不要同时修改镜像、命令、资源和选择器后反复重试。

第一次运行没有达到预期时，使用首次运行问题排查整理必要信息，找到最早出现问题的环节。原因不明确时，不要通过编辑、停止、克隆或删除任务反复试错。

如果工作负载意外启动或产生非预期影响，先使用平台的停止操作，并确认相关 Task 和 Pod 不再运行。删除 Job 记录不会自动停止外部设备，也不会自动清理存储中的数据。

接入真机任务前完成安全确认

Env 角色、机器人节点类别、设备资源或 Raw 运行时用于表达任务所需资源，不能代替真实机器人的安全控制。

任何可能连接或驱动真实机器人的任务，都必须先由设备团队和安全审批人确认：

• 设备、固件、驱动、SDK、控制模式和镜像版本的兼容性。
• 现场操作员、隔离区域、人员进入控制和明确的安全责任人。
• 已测试的急停、断能、复位和通信中断处理。
• 速度、力、行程和工作空间限制，以及异常动作的停止条件。
• 数据和控制命令的审批、审计与恢复方案。

任一项尚未确认时，请暂停接入并继续使用仿真或隔离测试环境。全部确认后，再把安全审批结果和停止方案写入本次运行记录，然后进入提交检查。完整要求见使用真实设备前的安全要求。