Isaac Lab 使用 `uv run` 零配置启动 RL 训练与评估(Kit-less 实验特性)完整指南
Isaac Lab 使用 uv run 零配置启动 RL 训练与评估(Kit-less 实验特性)完整指南
导读
本文基于 Isaac Lab 官方文档的 uv_run 章节,系统讲解如何利用 Rust 生态的包管理器 uv,在不创建虚拟环境、不手动激活环境的情况下,一条命令直接启动强化学习(RL)训练与评估——包括完全脱离 Isaac Sim 的 Kit-less Newton 后端训练流程。读完本文,你将掌握 uv run train / uv run play 的完整命令语法、--extra ov --extra rtx 可选依赖的取舍逻辑、五种受支持 RL 库的切换方式,以及该机制背后由仓库根目录 pyproject.toml 驱动的自动依赖解析原理。
实验性特性警告:该特性处于实验阶段,后续版本可能发生变化。当前仓库中该文档的原始标注为 "This feature is experimental and subject to change in future releases"。
uv run 模式:为何能做到"克隆即训练"
传统上,运行 Isaac Lab 需要先创建 conda/uv 虚拟环境、激活环境、安装扩展(./isaaclab.sh -i)等一串前置步骤。而 uv run 模式把这一步彻底简化:
- 你只需要安装
uv并克隆仓库; - 每条训练/评估命令执行时,
uv都会依据仓库根目录的 pyproject.toml 自动解析、创建并复用隔离环境,无需任何手动环境管理; - 环境解析结果会被缓存,后续命令复用,因此首次运行略慢、之后即可快速启动。
从仓库源码看,这一机制之所以可行,是因为仓库根目录的 pyproject.toml 定义了名为 isaaclab-dev 的开发环境元数据,并通过 [tool.uv.sources] 把 source/ 下所有 Isaac Lab 子包(isaaclab、isaaclab-assets、isaaclab-newton、isaaclab-rl、isaaclab-tasks 等)以 editable(可编辑) 方式挂载到环境中,同时通过 [tool.uv.index] 配置了 pypi.nvidia.com 与 PyTorch 专属索引。这意味着 uv run 每次调用都能精确复现这套开发依赖组合。
前置准备:安装 uv
uv 是 Astral 出品的 Python 包/环境管理器,安装方式遵循官方一键脚本:
curl -LsSf https://astral.sh/uv/install.sh | sh
安装完成后,在仓库根目录下即可直接使用 uv run 系列命令。仓库还提供了独立的 uv 环境创建入口:./isaaclab.sh -u(即 command_setup_uv,位于 source/isaaclab/isaaclab/cli/commands/envs.py),它会校验 uv 是否可用、按 Isaac Sim 对应版本确定 Python 版本,并向激活脚本注入 ISAACLAB_PATH、isaaclab 别名等环境钩子——这是把 uv 环境当作"传统虚拟环境"使用时的可选路径,而 uv run 模式本身不需要这一步。
克隆仓库后直接开始训练
文档给出的核心命令为(省略了仓库克隆命令的生成占位,实际操作时先克隆仓库到本地,例如 git clone https://gitcode.com/GitHub_Trending/is/IsaacLab 后进入目录):
# Newton 后端训练,无需 Isaac Sim
uv run train --rl_library rsl_rl \
--task Isaac-Cartpole-Direct-v0 physics=newton_mjwarp
这条命令等价于把整个"环境准备 + 训练启动"压缩成一次调用:
uv run解析 pyproject.toml 中的项目与依赖,自动构建隔离环境(默认 Python 版本约束为>=3.12,<3.13);train子命令被路由到uv run项目所依赖的 CLI 入口(在常规安装中对应isaaclab.sh train),其底层实现为 scripts/reinforcement_learning/train.py,统一分发到所选 RL 库的专属训练脚本;--rl_library rsl_rl指定训练框架;--task Isaac-Cartpole-Direct-v0指定任务;physics=newton_mjwarp是 Hydra 风格的配置覆盖,把物理后端切换为 Newton 的 MuJoCo-Warp 求解器(详见下文)。
各参数逐一解读
| 参数 | 含义 | 可选值 / 默认行为 |
|---|---|---|
train |
统一训练入口 | 对应 scripts/reinforcement_learning/train.py 中的 main() |
--rl_library |
选择 RL 训练框架 | rsl_rl、rl_games、skrl、sb3、rlinf(必填) |
--task |
要训练的任务名 | 例如 Isaac-Cartpole-Direct-v0(可通过 list_envs 脚本枚举) |
physics=... |
Hydra 覆盖:物理后端/求解器预设 | newton_mjwarp(MuJoCo-Warp)、physx(Isaac Sim PhysX)等 |
此外,train 入口还支持一组通用 CLI 参数(来自 scripts/reinforcement_learning/common.py 的 add_common_train_args),可与上述命令自由组合:
--num_envs N:覆盖场景中的并行环境数量(env_cfg.scene.num_envs);--max_iterations N:RL 策略最大训练迭代数;--seed N:环境随机种子;--agent PATH:指定 agent 配置入口;--video/--video_length/--video_interval:训练中录制视频(开启后会自动启用相机渲染,默认录制长度 200 步、间隔 2000 步);--distributed:多 GPU / 多节点训练(与 CPU 设备互斥,源码中会显式校验);--export_io_descriptors:导出 IO 描述符(仅 manager-based 环境支持)。
值得注意的优先级规则:这些 --param 形式的旧式 CLI 参数优先于等价的 Hydra 覆盖参数(详见 docs/source/features/hydra.rst),也就是说 --num_envs=16 会覆盖 physics=... 之外任何来自配置文件或 Hydra 链上对 scene.num_envs 的设定。
按需启用 ov / rtx 可选依赖
并非所有工作流都需要图形与 OV 运行时。文档明确建议:只在流程确实需要时才追加额外依赖:
# 需要 OVRTX / OVPhysX 扩展时,追加 --extra
uv run --extra ov --extra rtx train --rl_library rsl_rl \
--task Isaac-Cartpole-Direct-v0 physics=newton_mjwarp
这里的 --extra 参数直接对应当前仓库 pyproject.toml 中 [project.optional-dependencies] 声明的 extras:
| Extra 名 | 安装内容 | 用途 |
|---|---|---|
ov |
isaaclab-ovphysx[ovphysx] |
OVPhysX 物理运行时 |
rtx |
isaaclab-ov[ovrtx] |
OVRTX 渲染后端 |
newton |
isaaclab-newton[all]、isaaclab-physx[newton]、isaaclab-visualizers[newton] |
Newton 物理与可视化器 |
rl / rl-all |
isaaclab-rl[rsl-rl] 或全部 RL 框架 |
RL 框架依赖 |
mimic |
isaaclab-mimic |
模仿学习工具 |
all |
上述主要组合 | 全量开发依赖 |
注意:文档给出的 physics=newton_mjwarp 基础训练命令不依赖 ov / rtx,因为 Newton 的 MuJoCo-Warp 求解器是纯 GPU 张量计算路径;只有当你需要 OVRTX 渲染或 OVPhysX 后端时,才需要这两个 extras。这与 Kit-less 安装中"OV 运行时默认不装、按需请求"的设计一致(详见 docs/source/setup/installation/include/selective_install.rst)。
--rl_library 支持的框架与源码分发逻辑
uv run 训练模式下,--rl_library 的合法取值与常规 isaaclab.sh train 完全一致,文档明确列出五种:rsl_rl、rl_games、skrl、sb3、rlinf。
这一分发的底层实现在 scripts/reinforcement_learning/train.py 的 LIBRARY_ENTRYPOINTS 映射表中:
--rl_library |
实际执行入口 |
|---|---|
rl_games |
scripts/reinforcement_learning/rl_games/train_rl_games.py |
rlinf |
scripts/reinforcement_learning/rlinf/train_rlinf.py |
rsl_rl |
scripts/reinforcement_learning/rsl_rl/train_rsl_rl.py |
sb3 |
scripts/reinforcement_learning/sb3/train_sb3.py |
skrl |
scripts/reinforcement_learning/skrl/train_skrl.py |
分发函数 dispatch_library_entrypoint(scripts/reinforcement_learning/common.py)先解析 --rl_library,再把剩余参数原样转发给对应库的 run()。这也解释了为什么不同框架的参数写法会有差异——例如设置随机种子时,rsl_rl / skrl / sb3 用 agent.seed=2024,而 rl_games 用 agent.params.seed=2024(两者都是 Hydra 覆盖语法,见 docs/source/features/hydra.rst)。
对应地,play 入口的框架分发由 scripts/reinforcement_learning/play.py 以同样的映射表实现。
Play / 评估:加载策略进行推理
训练完成后,使用 play 子命令加载已训练策略进行评估与可视化:
uv run play --rl_library rsl_rl --task <any_task>
<any_task> 替换为任意已注册任务名(如 Isaac-Cartpole-Direct-v0)。与 train 相同的规则在这里同样适用:
uv run复用同一套自动解析的环境;--rl_library取值范围与训练完全一致(五种库);- 可以叠加
physics=...、--num_envs、--seed等参数控制回放时的物理后端与场景规模; - 从源码看,play 分发同样支持视频录制等通用参数,便于在评估时录制策略表现。
无需 Isaac Sim:Kit-less 训练路径的本质
uv run 训练命令之所以能做到"无 Isaac Sim",是因为仓库提供了 Kit-less 模式:Newton 后端(含 MuJoCo-Warp 求解器)不依赖 Isaac Sim 的 Kit 运行时即可完成 GPU 加速仿真与训练。这一点在 docs/source/setup/installation/kitless_installation.rst 中有明确的功能边界划分:
Kit-less 模式(无需 Isaac Sim)可用:
- Newton 物理仿真(GPU 加速,含 MuJoCo-Warp 求解器);
- 所有支持 Newton 的 manager-based / direct RL 环境;
- 基于 SKRL、RSL-RL 等框架的 RL 训练;
- 兼容 Newton 的机器人资产;
- ovphysx 与 ovrtx 后端。
仍然需要 Isaac Sim 的功能:
- Isaac Sim PhysX 物理后端(区别于 ovphysx);
- Isaac Sim RTX 渲染(区别于 ovrtx);
- Kit 可视化器;
- URDF / MJCF 导入器(GUI 交互);
- Surface gripper(仅 Isaac Sim PhysX);
- PhysX Deformable 仿真;
- 遥操作与模仿学习工作流。
因此,如果你的任务(如 Isaac-Cartpole-Direct-v0)只依赖 Newton 后端,那么 uv run train ... physics=newton_mjwarp 就是最短路径;一旦涉及上述需要 Isaac Sim 的功能,则仍需走完整的 Isaac Sim 安装流程(pip 安装方式,参见 docs/source/setup/installation/kitless_installation.rst 中指向的 pip 安装文档)。
关于 physics=newton_mjwarp 预设
newton_mjwarp 是任务配置上暴露的物理预设,对应 Newton 后端的主求解器——Google DeepMind 的 MuJoCo-Warp。在代码层面,它把 SimulationCfg.physics 设置为 NewtonCfg(替代 PhysX 路径的 PhysxCfg),并在其中携带 MJWarpSolverCfg 的求解器参数(详见 docs/source/overview/core-concepts/physical-backends/newton/mjwarp-solver.rst)。对性能与仿真行为影响显著的关键参数包括:
njmax:每个环境预分配的约束行数,过大拖慢仿真,过小可能丢失约束;nconmax:预分配的最大接触点数;ls_iterations:每次求解迭代的最大线搜索次数(越低越快);cone:摩擦锥近似方式,可选pyramidal/elliptic;ls_parallel:并行化线搜索(提速但降低稳定性,开启时建议ls_iterations提高约 50%);impratio:摩擦与法向约束阻抗比,控制切向力的显著性。
这些参数属于求解器级配置,通过 Hydra 覆盖即可在命令行微调(例如 physics.solver_cfg.ls_iterations=20 之类,具体层级以任务配置为准),是后续做性能调优时的入手点。
底层原理:uv run 如何自动解析环境
要让"克隆即训练"成立,仓库根目录的 pyproject.toml 提供了完整的工程化支撑,值得逐条理解:
[project]元数据:项目名isaaclab-dev,Python 版本约束>=3.12,<3.13,并在dependencies中直接声明了isaaclab、isaaclab-assets、isaaclab-newton[all]、isaaclab-rl[rsl-rl]、torch==2.10.0等核心依赖;[tool.uv.sources]:把source/下 14 个 Isaac Lab 子包统一以editable = true方式挂载,保证uv run中直接 import 到的是仓库内的源码;[tool.uv.index]:注册pypi.nvidia.com作为默认索引、PyTorch 的cu128/cu130专属索引,并按平台标记(x86_64 / aarch64、Linux / Windows)自动选择对应 PyTorch 轮子;[tool.uv]全局策略:index-strategy = "unsafe-best-match"、prerelease = "allow"(兼容只发布预发布轮子的 NVIDIA 包)、python-preference = "only-managed"(由 uv 自行管理 Python 解释器,这也是无需用户手动准备 Python 环境的关键)。
正是这套配置,让每次 uv run train/play ... 都能在正确的索引与平台约束下解析出一致、可复现的开发环境——uv 的缓存机制保证了后续调用几乎零成本。
使用注意事项
- 实验性特性:
uv run训练/评估模式在当前文档中被明确标注为实验性,接口与行为可能在后续版本调整; - 适用范围:
physics=newton_mjwarp的 Kit-less 路径仅覆盖 Newton 后端能力;涉及 Isaac Sim 专属功能(PhysX 后端、Kit 可视化、URDF/MJCF 导入等)时,需要按完整安装流程配置 Isaac Sim; - 平台与版本前提:仓库要求 Python
3.12(>=3.12,<3.13),Linux / Windows 均支持,但如teleop等可选子模块仅在特定平台提供;首次uv run会因环境解析与依赖下载耗时较长,属正常现象; - 与常规 CLI 的一致性:
uv run train/play与isaaclab.sh train/play走的是同一套训练/评估入口(source/isaaclab/isaaclab/cli/init.py 中train/play命令均指向 scripts/reinforcement_learning/ 下的统一脚本),因此参数语义完全对齐,本文介绍的所有参数与框架切换规则可无缝迁移。
延伸阅读
- pyproject.toml:
uv run环境解析的元数据源头(dependencies、extras、uv index/sources); - docs/source/setup/installation/kitless_installation.rst:Kit-less 模式的能力边界与安装方式;
- docs/source/setup/installation/include/selective_install.rst:模块化安装 token(
newton、rl[rsl-rl]、ov[ovrtx]等)与uv run --extra的对应关系; - scripts/reinforcement_learning/train.py 与 scripts/reinforcement_learning/common.py:训练/评估的统一入口与参数解析实现;
- docs/source/features/hydra.rst:
physics=/agent.seed=等 Hydra 覆盖语法详解; - docs/source/overview/core-concepts/physical-backends/newton/mjwarp-solver.rst:MuJoCo-Warp 求解器参数与调优说明。