CLI 参考¶
UniLab 为常见的训练与回放路由提供软件包命令，同时保留底层脚本以便调试 Hydra 组合。
统一命令¶
目标 |
命令形式 |
路由到的脚本 |
|---|---|---|
PPO |
|
|
APPO |
|
|
SAC |
|
|
FlashSAC |
|
|
示例：
uv run train --algo ppo --task go2_joystick_flat --sim mujoco
uv run train --algo appo --task g1_motion_tracking --sim mujoco training.no_play=true
uv run train --algo sac --task g1_walk_flat --sim mujoco training.no_play=true
uv run train --algo flashsac --task go2_joystick_flat --sim mujoco
CLI 会根据 --algo、--task、--sim 以及可选的 --profile 构造出 owner YAML
路径。定义路由的取值必须使用 CLI flag；命令之后的 Hydra override 用于设置诸如
algo.max_iterations、algo.num_envs 和 training.no_play 等字段。
中断训练¶
发送一次 Ctrl+C 表示请求协作退出。训练入口、collector、数据并行 sibling
rank 以及 torch elastic worker 会先执行既有清理路径，然后进程按惯例返回退出码
130。再发送一次 Ctrl+C 会强制 CLI 子进程终止；强制终止不保证优雅清理。
torch elastic 的正常关机提示仍可能出现，但用户取消不会被报告为训练失败。
uni-cumps 负责 CUDA MPS 的显式用户态 daemon 生命周期。它提供只读
host/topology 诊断，只启动和停止 UniLab record 记录的 user-owned daemon，并输出
launcher 环境而不修改调用方 shell：
# 单 GPU 主机；默认参数已经完整。
uv run uni-cumps start
eval "$(uv run uni-cumps env)"
uv run uni-cumps doctor
uv run uni-cumps stop
# 多 GPU 或需要显式命名的部署。
uv run uni-cumps doctor --gpus <gpu-index-or-uuid>
uv run uni-cumps start --gpus <gpu-index-or-uuid> --name <name>
uv run uni-cumps env --name <name>
uv run uni-cumps stop --name <name>
ownership、并发和拓扑限制见 tensor runtime 生产指南。训练仍必须显式设置
training.cuda_process_sharing=mps。
各环境的调用方式¶
CLI 前缀取决于安装方案：
ROCm：先执行一次
make sync-rocm，之后使用uv run ...。Intel XPU：使用
uv run --no-sync ...。
Tab 自动补全¶
补全脚本是可选项，只补全 uv run train / uv run eval 的入口、flag 和部分
choices，不改变命令行为。在新 checkout 上，可用一条 setup 命令完成环境同步和补全
安装：
# 完整默认环境：
make setup
make setup 会同步默认环境（uv sync --extra mujoco，含内置 RL 栈），随后运行
uv run --no-sync unilab-complete install。一个环境只选择一条安装路径。
安装命令会按 $SHELL / 平台选择 Bash 或 Zsh，只写入用户级 rc 文件。当前终端不会被自动
激活，重新打开终端或 source 对应 rc 文件后生效。
如果系统没有 make，可直接执行：
uv sync --extra mujoco
uv run --no-sync unilab-complete install
Linux / WSL 的 Bash 用户也可手动把下面内容写入 ~/.bashrc：
source scripts/completions/unilab.bash
macOS 默认 Zsh 用户可把下面内容写入 ~/.zshrc：
autoload -Uz compinit
compinit
source scripts/completions/unilab.zsh
重新打开终端或 source 对应 rc 文件后，可用 uv run <TAB>、
uv run train --algo <TAB>、uv run train --sim <TAB> 查看候选项。
评估¶
uv run eval 会设置 training.play_only=true，并可选地将 --load-run 映射到
algo.load_run。
uv run eval --algo ppo --task go2_joystick_flat --sim mujoco --load-run -1
uv run eval --algo ppo --task go2_joystick_flat --sim mujoco --load-run -1 \
--render-mode record
支持的渲染模式为 auto、interactive、record、viser 和 none。其中 MuJoCo 交互模式
（--sim mujoco --render-mode interactive）直接路由到 play_interactive.py，并始终只
rollout 一个环境。
具备 physics-state playback 的后端（mujoco、mjwarp、newton、drake、superdex）
还支持 --render-mode viser：通过基于浏览器的 viser viewer 展示回放，不需要本地显示，
在 macOS 上也不需要 mjpython。eval 会路由到独立的 play_viser.py viewer；train 则在
训练后回放阶段运行同一 viewer。viser 是必选依赖；viser.* 配置组
（viser.port、viser.max_envs、viser.display_mode、viser.env_idx）用于调整服务器与场景。
演示¶
uv run demo dance
uv run demo dance --refresh --device cpu
可用的 demo：teaser、dance。
每个 demo 在首次运行时会从 unilabsim/unilab-checkpoints 这个 Hugging Face
数据集拉取预训练检查点，并缓存到 src/unilab/assets/checkpoints/<demo>/model_0.pt。
传入 --refresh 可重新下载。
中国大陆用户：当 huggingface.co 无法访问时，请在运行 demo 前切到社区镜像：
export HF_ENDPOINT=https://hf-mirror.com
demo 入口由 src/unilab/demo.py 实现，并从 src/unilab/cli.py 路由。
底层脚本¶
当你需要检查 Hydra 配置组或复现脚本层面的问题时，底层脚本仍然可用。在正常使用 中，请将定义路由的取值保留在上面的统一 CLI flag 中。
对于 off-policy 路由，--algo 选择按算法划分的 owner 树 src/unilab/conf/<algo>/；
不要在 --task 中包含算法名称。
常用 Override¶
training.no_play=true
algo.max_iterations=10
algo.num_envs=128
algo.load_run=-1
training.logger=wandb
回放时使用 uv run eval ... --load-run ...，渲染行为则使用
--render-mode record 或 --render-mode none。
后端选择属于 CLI 的 --sim 选项以及由此得到的 owner YAML。不要将
training.sim_backend=<backend> 当作独立的切换开关使用。