RLark Web 控制台文档

主题

创建训练任务 ​

RLark 通过四步弹窗把角色配置转换为一个 rlinf.io/v1alpha1 Job。每个角色会生成一个 Task，匹配节点数决定该角色的 Worker 副本数。

本文统一使用 Header 角色表示控制台中选中的角色；提交后，该角色对应 head: true 的 Head Task。Header 角色不是某个具体 Node 或自动选出的第一个 Worker。完整术语见术语表。

准备创建信息 ​

创建前确认：

  • 任务名称唯一，并符合小写 DNS 名称规则；
  • 每个角色要使用的集群，以及经管理员从全局 Node 清单验证、只命中该集群的单值标签组合；
  • Header 角色的完整选择器经全局验证后恰好匹配 1 个 Node；
  • 每个 Worker 需要的 GPU 或 rlinf.io/* 设备数量；
  • 每个角色来源明确、集群能够拉取的镜像引用，以及准备脚本和运行脚本；
  • 环境变量与主机目录或对象存储挂载；
  • 可选的网络域、SSH 公钥和 TensorBoard 日志目录。

先填写启动清单，再取得管理员确认的部署参数，并让两份记录相互引用。启动清单记录应用输入与预期信号；部署参数记录集群、选择器、资源、存储和网络约束。RLark 没有保存这两类记录的专用字段，请在团队运行记录中把它们与 Job 名称和最终提交的 YAML 关联起来。

固定镜像和执行入口 ​

提交前先固定本次运行使用的镜像：

  • 优先使用镜像 digest。若组织流程使用版本标签，应确认标签不可变并记录其实际 digest；需要重复运行训练时，不要使用 latest 或会被覆盖的标签。
  • 确认镜像内存在 RLark 启动所需的 bash、Ray CLI 和名为 python 的可执行文件，以及该角色使用的代码、Python 环境、系统库和设备依赖。Head 包装脚本会直接执行 python 检查 Ray 节点；控制台只保存镜像字符串，不检查镜像内容。
  • RLark 会把主容器的启动命令替换为 Ray Head 或 Worker 脚本，因此不要依赖镜像 ENTRYPOINT 完成环境激活、目录切换或配置生成。需要这些动作时，请明确写入准备脚本或 Head Task 的运行脚本。
  • 多角色任务优先使用同一 digest 或同一构建流程生成的镜像。确需使用不同镜像时，请分别确认各角色的 Ray 版本和通信协议兼容，并核对 Python、RLinf、配置格式、驱动及设备依赖；RLark 不会执行这些兼容性检查。

准备脚本会在该角色的每个 Worker 启动 Ray 前执行。运行脚本只写入 Head Task，但该 Task 的每个副本都会在 Ray 启动和集群检查后执行它。集群检查失败时，启动脚本会记录警告并继续，因此运行脚本仍需确认它依赖的 Worker 或服务已经就绪。若命令依赖特定工作目录，请在对应脚本中明确执行 cd。

第一步：角色和资源 ​

  1. 在左侧导航中选择任务，然后选择创建任务。

  2. 输入任务名称。名称必须为 1–63 位小写字母、数字或连字符，不能以连字符开头或结尾。

  3. 选择任务类型：

    类型初始角色
    强化学习任务Actor、Rollout、Environment
    数据采集任务Environment
    评测任务Rollout、Environment
    自定义任务无，需手动添加

  4. 修改、添加或删除角色。角色名称不能为空，且忽略大小写后不能重复。

  5. 选择一个 Header 角色。该角色后续必须只匹配 1 个 Worker。

第二步：Worker 配置 ​

逐个角色完成以下设置：

  1. 选择集群。该选择用于筛选表单中的候选节点、设备和存储配置，不会作为独立字段写入 Job。
  2. 在节点选择中选择标签或手动输入 key=value：
    • 必须选择至少一个能够把目标限定在预期集群内的标签；
    • 每个标签键只允许一个值，不要使用同键多值；
    • 可以组合多个不同键的单值条件；提交前，请平台管理员使用完整组合执行全局验证；
    • 已选节点数是只读值，并会作为该角色的副本数；至少要匹配一个节点。
    • 对 Header 角色，已选节点数必须为 1，并与管理员提供的全局匹配记录一致。
  3. 填写每个 Worker 的 GPU 数量。界面只有在计算出的最大值大于 0 时才会阻止超额值；没有显示可用上限时，不要保留模板默认值，先填 0，除非管理员已经确认匹配节点提供所需 GPU。
  4. 如集群上报了 rlinf.io/* 可分配资源，可在设备资源中选择名称和数量。界面不会验证设备数量是否超过节点容量，提交前请平台管理员核对实际容量。
  5. 填写镜像。此项必填；填写已确认的 digest 或不可变版本引用，并确认所选集群能够拉取。不要把表单占位值当作推荐镜像。
  6. 按需填写准备脚本（Ray 启动前）和环境变量。准备脚本应可重复执行，并且只承担该角色在 Ray 启动前确实需要的激活、检查或文件准备；长期依赖应写入镜像。
  7. 按需添加存储挂载：
    • 主机目录需要填写源路径和挂载到 Worker的目标路径；
    • 对象存储需要从所选集群的可用存储类中选择，并填写目标路径。

创建弹窗不能配置 CPU 和内存请求

Job CRD 的 Pod 模板可以包含 CPU 和内存 requests，但创建弹窗没有对应输入项。任务必须声明这些请求时，请勿通过此表单提交，也不要把 YAML 中缺少字段理解为平台已经提供默认保障；请向平台管理员确认可用的配置方式。

集群和节点选择器

Task 模板没有独立的 cluster 字段；任务放置只依据 nodeSelector，并使用全局匹配到的第一个 Node 所在的命名空间。选择器为空时，表单虽然按所选集群显示匹配数量，生成的 YAML 却不会包含集群选择，任务可能落到默认命名空间。创建器也无法发现其他集群中的同标签节点。提交前，请平台管理员从全局 Node 清单列出完整单值选择器匹配到的所有 Node 和命名空间，并确认结果只属于目标集群；否则不要提交。

Header 角色只能有一个副本

Head 标记作用于整个 Task。该 Task 的每个 Pod 都会启动 Ray Head 并执行同一运行脚本，脚本不会只保留第一个副本。Header 角色的全局匹配数或 YAML 副本数不等于 1 时，不得提交。

主机目录与副本范围

主机目录必须在每个匹配节点上存在并具有正确权限。提交前应同时检查 nodeSelector、已选节点数和挂载适用范围。

第三步：公共配置 ​

  1. 在选择 Head 节点区域确认 Header 角色。这里选择的是角色，不是某个具体节点；必须通过该角色的选择器把副本数限制为 1。
  2. 按需选择跨集群网络域。
  3. 按需选择SSH 公钥注入。选中的公钥会写入所有角色 Pod 的 authorized_keys；若列表为空，请先在SSH 公钥页面添加。
  4. 填写运行脚本（Ray 集群检查后，由 Head Task 执行）。运行脚本不能为空；明确写入工作目录切换和启动命令，不要依赖镜像 ENTRYPOINT 的副作用，并再次确认 Head Task 只有 1 个副本。
  5. 如需 TensorBoard，填写容器内的TensorBoard 日志目录。

第四步：YAML 预览并提交 ​

在任务 YAML 预览中至少核对：

  • metadata.name；
  • spec.tasks 中的角色名称、head、只含单值条件的 nodeSelector 和副本数，并与管理员提供的全局匹配记录对照；
  • 主容器镜像与启动清单中的 digest 或不可变版本一致，各角色运行时相互兼容；
  • 环境变量、设备请求和挂载，并确认挂载没有意外遮蔽镜像中的代码或配置目录；
  • Head Task 的副本数恰好为 1，以及它的准备脚本、运行脚本和 TensorBoard 目录；
  • 可选的网络域和 SSH 公钥。

确认无误后选择提交。创建成功后弹窗关闭，任务列表会重新加载。先按检查 RLinf 任务是否正常运行核对第一个有效信号；没有达到预期时，请按首次运行问题排查逐项检查。Job 显示 Running 只代表调度状态，不能代替首次运行检查。

环境变量的作用域、平台保留名称和 RAY_TEMP_DIR 使用方式参见运行环境与环境变量。