RLinf 用户常见问题

本页回答从现有 RLinf 工作负载转到 RLark 时经常遇到的问题。每个回答只说明关键结论；需要准备或操作任务时，请继续查看回答中的相关指南。

了解 RLark 与迁移

RLark 和 RLinf 是什么关系？

RLinf 提供算法、配置和训练程序；RLark 为这些工作负载准备 Worker、GPU、存储和 Ray 运行环境，并提供任务查看与排查入口。两者的职责和配置边界见 RLark 与 RLinf。

已经能运行的 RLinf 任务迁移到 RLark 时，需要重写配置吗？

不需要把 Hydra 配置改写成 RLark Job 字段；应保留原有配置，并把镜像、命令、Worker 资源、挂载和运行条件映射到 RLark Job。具体准备方法见接入现有 RLinf 工作负载。

RLark 支持哪些 RLinf 版本？

RLark 控制台不会判断 RLinf 版本是否兼容。目标环境提供版本兼容表时，请以该表为准；没有兼容表时，应固定 RLinf commit、镜像版本、Ray、CUDA 和依赖版本，并在目标环境中验证。需要记录的版本信息见 RLark 与 RLinf。

自行部署和已有 RLark 环境中的“云算力、端算力、端真机”含义相同吗？

含义相同。它们是 RLark 根据 rlark.io/node-category 显示的节点类别，不是两种部署方式各自定义的资源名称。自行部署时由本组织的平台管理员维护分类；使用由组织或服务提供方部署并维护的环境时，由该环境的管理员维护。

这些类别用于按机器在当前环境中的用途筛选 Node：云算力可以位于公有云、私有云或本地数据中心；端算力用于查找边缘计算资源；端真机用于查找机器人节点。提交任务前，还需核对节点状态、标签、GPU、设备连接和操作条件。完整定义见集群与节点。

镜像 tag 和 digest 有什么区别？

tag 是便于阅读的版本名称，例如 rlinf:v0.3.0；除非镜像仓库禁止覆盖，同一个 tag 以后仍可能指向不同内容。digest 是镜像内容的唯一指纹，例如 rlinf@sha256:...，适合精确复现。首次使用时可以填写团队确认的版本 tag，但不要使用 latest；需要复现、比较或发布可复用场景时，再记录该 tag 实际对应的 digest。示例和获取方法见选择镜像版本和执行入口。

理解任务类型、角色与资源

控制台中的“任务”是 Job 还是 Task？

是 Job。选择创建任务后，控制台会提交一个 RLark Job。Job 中包含一个或多个角色，RLark 再根据这些角色创建 Worker。控制台不是让用户直接创建一个 RLark Task。

RLark Task 是什么？普通用户需要操作吗？

Job YAML 的 spec.tasks[] 保存各角色对应的 Task 模板。Job 提交后，RLark 根据这些模板创建并管理 Task 资源，再由 Task 创建 Worker。Task 是 RLark 的编排层，不是 Kubernetes API 所说的子资源。

提交训练任务时通常不需要直接操作 Task；查看 YAML、状态或排查工作负载为什么没有创建时，才需要结合 Task。完整关系见 Job、角色、Worker 与 Task。

一个 RLark 角色等于一个 Pod 吗？

不等于。角色是一组 Worker 的配置模板；角色的已选节点数决定 RLark 尝试创建多少个 Worker Pod。一个角色可以只创建 1 个 Pod，也可以创建多个使用相同镜像、资源、挂载和准备环境的 Pod。

一个 RLark Worker、Pod 和 Ray 节点是什么关系？

在当前 Web 控制台创建的 Kubernetes 任务中，一个 RLark Worker 通常对应一个 Pod，这个 Pod 会启动一个 Ray 节点。RLinf 之后再在 Ray 集群中创建 Actor、Rollout、Env 等组件进程。RLinf 文档中的组件 Worker 或 Ray actor 不等于控制台中的 RLark Worker。

一个 RLark Worker 等于一个 PyTorch process 吗？

不等于。RLark Worker 是承载运行环境的 Pod 和 Ray 节点；RLinf 会在这些 Ray 节点上创建一个或多个 Actor、Rollout、Env 等组件进程。一个 Worker Pod 中可以同时存在多个 RLinf 组件进程，因此不能用组件 world size 直接决定 RLark 角色副本数。

一个 Worker Pod 有几个容器？

基础任务至少包含一个运行训练镜像的 main 容器。选择网络域或配置 TensorBoard 时，RLark 还可能加入辅助容器。辅助容器不会增加 RLark Worker 或 Ray 节点数量；同一 Pod 中的容器共享网络和挂载的卷，但各自运行独立进程。

一个 Ray 节点就是一台物理机器吗？

不是。Ray 节点是运行 Ray runtime 的进程实例；当前 RLark 创建路径中，它运行在一个 Worker Pod 内。同一台物理机器可以同时运行多个 Worker Pod 和多个 Ray 节点，但一个 Ray 节点不会跨越多台物理机器。

首次使用 RLark 需要了解多少 Ray？

首次提交任务时，只需知道：一个 Worker 会启动一个 Ray 节点；一个 Header 角色负责 Ray Head 和运行脚本；全部 Worker 数应与 cluster.num_nodes 一致；RLINF_NODE_RANK 用于标识各 Ray 节点。运行后会查看 Worker 日志和 ray status 即可，不需要先学习 Ray 的内部服务或调度实现。

创建任务时选择的“任务类型”就是 RLinf 的任务类型或执行模式吗？

不是。“任务类型”只决定创建页面最初添加哪些角色，不会设置 RLinf 的算法、runner.task_type 或执行模式。表单字段与 Job YAML 的关系见任务创建字段。

控制台中的 Actor、Rollout 和 Environment 与 RLinf YAML 中的同名组件一一对应吗？

不对应。每个控制台角色定义一组 Worker 的节点选择、资源、镜像、脚本、环境变量和挂载；RLinf 组件仍由 component_placement 放置。是否拆分角色，取决于已有配置需要哪些 Ray 节点组，以及这些 Worker 是否需要不同的运行配置，而不是组件名称。多节点和异构任务的规划方法见规划多节点和异构 Worker。

单节点 RLinf 任务应该选择哪个角色？

当 cluster.num_nodes: 1，而且一个 GPU 节点能够提供全部资源、镜像、挂载和设备时，选择自定义任务，添加一个名为 worker 的角色，让它只匹配 1 个 Node，并把它设为 Header。GPU 填写工作负载实际需要的数量；Actor、Rollout、Env 等组件继续由 RLinf 的 component_placement 放置。完整步骤见在单个 GPU 节点上运行 RLinf。

什么时候使用一个 Pod，什么时候需要多个 Pod？

cluster.num_nodes: 1 且一台机器能够满足全部运行条件时，通常使用一个 Worker Pod。需要多个 Ray 节点、多个 node_groups，或不同 Worker 需要不同节点、设备、镜像、挂载和环境时，使用多个 Worker Pod。是否增加 Pod 取决于 Ray 节点布局和运行条件，不取决于 Actor、Rollout、Env 的名称。

多个角色选择同一批节点，会共用 Worker 或 GPU 吗？

不会。相同的节点选择只表示这些角色可以使用同一批物理节点；每个角色仍会分别创建 Worker、申请资源和获得 Ray 节点编号。RLinf 也不会按 hostname 把这些 Ray 节点合并。

例如三个角色都匹配 4 个节点时，RLark 会尝试创建 12 个 Worker，而不是 4 个。只有已有 RLinf 配置本来就需要 12 个 Ray 节点时，这个总数才合理；否则应重新规划角色，不要为了适配表单修改 cluster.num_nodes。完整示例见规划多节点和异构 Worker。

Header 和普通 Worker 有什么区别？

设为 Header 的角色负责启动 Ray Head 并执行运行脚本，其他 Worker 加入这个 Ray 集群。Header 不代表 Actor 等 RLinf 组件；该角色必须只包含 1 个 Worker，而且它的镜像、挂载和环境必须能够运行工作负载入口。相关限制见规划多节点和异构 Worker。

共享式、分离式和混合式执行模式如何映射到 RLark？

共享式组件使用同一组 GPU；分离式组件使用互不重叠的 GPU；混合式中一部分组件共享 GPU，另一部分组件分开使用。GPU 可以位于同一个 RLark Worker，也可以分布在不同 Worker 中，因此执行模式不能直接决定 RLark 角色数量。组件放置仍由 RLinf component_placement 表达。三种模式的映射示例见规划多节点和异构 Worker。

component_placement 中的 0-7 是 Worker 编号、GPU 编号还是进程编号？

在 actor: 0-7 这类写法中，0-7 是资源编号范围，通常表示 GPU，也可能表示机器人或节点等其他资源；它不是 Worker 或节点编号。写成 env: 0-3:0-7 时，前面的 0-3 是资源编号，冒号后的 0-7 才是组件进程编号。Worker 的节点编号由 RLINF_NODE_RANK 和 node_groups[].node_ranks 表达。三种编号的含义见规划多节点和异构 Worker。

cluster.num_nodes 和组件的 world size 是同一个数量吗？

不是。cluster.num_nodes 是 RLinf 使用的 Ray 节点数，应与 RLark 创建的 Worker Pod 总数一致；Actor、Rollout、Env 等组件的 world size 是该组件的进程数；local world size 是其中位于一个 Ray 节点上的进程数。一个 Worker Pod 可以承载多个组件进程，所以这些数量不能直接相加或互相替代。

应该创建多少个 Worker，每个 Worker 填多少张 GPU？

RLark 计划创建的 Worker 总数是各角色已选节点数之和，不是去重后的物理节点数，并且应与已有的 cluster.num_nodes 对齐。GPU 字段填写单个 Worker 的申请数量；控制台不能指定物理 GPU 编号。具体计算和检查方法见规划多节点和异构 Worker。

实际 Ray 节点多于 cluster.num_nodes 时会怎样？

RLinf 不会按物理机器合并多余的 Ray 节点。当前行为可能是记录警告后只采用节点编号最靠前的部分节点；没有被采用的 Worker 和资源仍可能继续存在。因此不要把这种截取行为当作自动纠错，应让 RLark 创建的 Worker 总数与 cluster.num_nodes 一致。出现数量不一致时，按训练任务与 Worker 排障检查角色和副本数。

设备资源名称和机器人或摄像头 ID 是一回事吗？

不是同一个值。rlinf.io/device-franka 这类设备资源名称用于让调度器分配一种资源及其数量；franka-robot-1、video0 这类 ID 由 Worker 所连接的设备运行时报告，供 RLinf 配置或设备程序引用。创建任务时申请资源，Worker 启动后再查看实际 ID。具体步骤见查看机器人和摄像头资源。

可以在控制台查看整个环境中的所有机器人和摄像头吗？

控制台可以按端真机、型号和资源摘要查找相关 Node。任务取得设备资源后，可以在获授权的 Worker 中使用当前环境提供的只读命令查看该控制器报告的设备 ID 和状态；查询范围通常是 Worker 所在节点。查询设备状态和控制设备使用不同的授权与安全流程，执行设备动作前请完成现场确认。

处理数据、运行状态与恢复

主机目录、对象存储路径和容器路径有什么区别？

主机目录的源路径位于 Worker 实际运行的计算节点，对象存储通过 StorageClass 挂载，而 RLinf 程序通过容器内挂载路径读写数据。路径对应关系和选择方法见在训练任务中使用存储。

Job 显示“运行中”是否表示训练已经正常开始？

不表示。还需要检查实际 Pod、Ray 成员、RLinf 最终配置、业务进展，以及已经写入持久存储且能够重新读取的输出。完整检查项见确认 RLinf 任务是否正常运行。

停止后再次启动任务，会自动从 checkpoint 继续吗？

不会。启动会重新创建 Pod 和 Ray 进程；只有 RLinf 命令明确读取经过验证的持久化 checkpoint 时，训练才会恢复。停止前保存和恢复后的检查方法见保留并恢复 RLinf 训练。

Job 长时间 Pending 或没有 Worker 时，先检查什么？

先确认 Job 已创建，再依次查看 Task 是否生成、节点选择是否匹配，以及调度资源、镜像和存储是否就绪；出现 Worker 后再检查 Ray 是否正常启动。不要反复停止和启动任务。完整排查顺序见首次运行问题排查。