9.8 KiB
命令手册
用 Python 3.10–3.13 建立环境并执行 python -m pip install -e ".[dev]"。
平台配置见环境准备。可编辑安装负责连接两个包根目录。
接入
python scripts/onboard.py --help
python scripts/onboard.py inspect <model-or-directory> --profile <profile.json>
python scripts/onboard.py build-mjcf <model-mesh-or-directory> --output <robot.xml>
python scripts/onboard.py extract-tier1 env.yaml agent.yaml --model <robot.xml> --output <metadata-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --metadata <metadata.json> --model <robot.xml> --output <policy-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --config env.yaml --config agent.yaml --overrides reviewed.json --model <robot.xml> --output <policy-dir>
python scripts/onboard.py setup-tier2 --model <robot.xml> --config <controller.json> --output <control-dir>
python scripts/onboard.py calibrate --model <robot.xml> --config <stance.json> --report <calibration.json>
python scripts/onboard.py verify --model <robot.xml> --config <probe.json> --report <verification.json>
python scripts/onboard.py scaffold-tier3 --config <robot.json> --calibration <calibration.json>
每个子命令提供 --help。inspect 可接收 --policy、--metadata、
--mesh-root。build-mjcf 会递归查找资产目录中唯一的 URDF 或 MJCF;
若没有模型,则查找唯一的 STL、OBJ 或 MSH。所选类别有多个候选时,请直接指定文件。
指定的输出路径不参与搜索。--floating-base 为 URDF 添加浮动根,
--mesh-root 提供 URDF 资产搜索位置,--mesh-scale 指定独立网格尺度,
--visual-fallback 显式为 URDF 生成近似碰撞。除非命令明确允许覆盖,否则使用新的路径。
标定和验证输出 JSON,检查失败时返回非零状态。
extract-tier1 读取选定的 YAML、JSON 或静态 Python 训练配置。
用 --overrides 提供审核过的 JSON 或 YAML 值,用 --report 单独保存提取报告。
输出目录包含 metadata.json 和 manifest.json。提取不完整时返回状态 1,
并保留这两个文件。审核各值的来源和未解决字段,确认清单标记 ready: true 后
再用元数据进行适配。也可以用多个 --config 参数与同一组审核值代替
--metadata。示例见 Tier 1 流程。
Python 接口
from mjrl.onboarding import build_mjcf, calibrate_model, inspect_asset, scaffold_task, verify_model
intake = inspect_asset(source, profile=profile)
build = build_mjcf(source, model_path)
calibration = calibrate_model(model_path, stance_config)
verification = verify_model(model_path, probe_config, base_dir=config_directory)
registration = scaffold_task(robot_config, base_dir=config_directory, calibration=calibration)
这些函数返回报告字典。机器人简介和配置通过 Python 映射传入。
base_dir 用于解析验证配置中的相对路径,验证时默认使用模型所在的目录。
生成规格时,须提供 base_dir 以解析模型和控制文件的相对路径。
可指定 tasks_root 将规格写入其他任务目录。
通过 mjrl.onboarding.extract_policy_metadata 可在程序中提取 Tier 1 元数据
并读取就绪诊断。传入一组配置文件路径,并可选提供已编译的 MuJoCo 模型及
审核值映射。
from mjrl.onboarding import extract_policy_metadata
extraction = extract_policy_metadata(
[env_config_path, agent_config_path], overrides=reviewed, model=compiled_model
)
结果在 metadata 下提供统一格式的草稿,同时包含命令行写出的就绪及来源字段。
机器人规格
使用标定时,配置提供 robot_id、family、model_path 和按位置关节名称
索引的 action_scales。可选 controls_path、velocity_joints、
penalized_contact_geoms 和 termination_contact_geoms。模型及控制路径
相对输入 JSON 解析。标定报告须对应实际 XML 和编译依赖。
不传 --calibration 时,可根据已验证的模型参数提供完整 RobotSpec,格式示例如下:
{
"robot_id": "sample_biped",
"family": "biped",
"model_path": "assets/sample_biped/robot.xml",
"base_body": "base",
"base_height": 0.32,
"foot_geoms": ["left_foot", "right_foot"],
"penalized_contact_geoms": ["left_shin", "right_shin"],
"termination_contact_geoms": ["torso"],
"position_joints": [
{"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
{"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
]
}
请使用针对该机器人标定的数值。站立根高度是 base_height,各关节默认位置是 home,
可选 armature 为该关节的附加转动惯量。提供 foot_geoms 或 foot_bodies;
每个支撑刚体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个,
多足至少五个。轮足双足还需在 velocity_joints 中提供至少两个不限位转动关节,设置 kp: 0、
正 kd、力矩上限和轮速动作尺度。
仅生成 tasks/<robot_id>/robot_spec.py,任务 ID 等于机器人 ID。
形态取值为 biped、quadruped、wheeled_biped、multipod。
运动策略的控制文件按顺序提供 lin_vel_x、lin_vel_y、ang_vel_z,
由机体系 twist 命令送入 velocity_commands。若需要操作输入,在生成规格前先生成
操作绑定,并在输入 JSON 中设置 controls_path。
轮足双足应选择 --profile differential,让 A/D 控制转向。
训练与回放
python scripts/train.py --list
python scripts/train.py --task <robot_id> --dry-run
python scripts/train.py --task <robot_id> --backend native --device cpu --num_envs 64 --headless
python scripts/train.py --task <robot_id> --resume --max-iterations 100
python scripts/play.py --task <robot_id> --checkpoint <model_N.pt> --headless --steps 300 --speed 0 --measure
GPU 路径使用 --backend warp --device cuda。指定设备不可用时会报错。
默认并行数为原生 CPU 64、Warp GPU 4096。执行检查或高内存模型可从更少环境开始。
Warp 的约束和接触容量可用正整数参数 --warp-max-constraints N 和
--warp-max-contacts N 设置。约束容量按环境限制,接触池由各环境共享,
总容量由每环境设置和环境数决定。缓冲区溢出时,程序会在使用受影响的观测前停止。
例如,G1 平地任务使用 --warp-max-constraints 300。
Warp 训练会在检查点旁的 warp-allocation.json 中记录所选容量和实际容量。
使用 Warp 续训、回放或导出时会读取该文件(如存在)。命令行参数优先,其次取已记录
容量与任务或场景要求中的较大值。若没有运行记录且未配置容量,则由 Warp 自动分配。
日志位于 logs/<model>/<robot_id>/<timestamp>/,记录器默认 TensorBoard。
--no-tensorboard 跳过启动服务器。--resume 选择最新检查点,
--checkpoint 选择指定检查点,两者恢复优化器、迭代与课程状态。
续训的 --max-iterations 指额外迭代数。
回放默认保留观测噪声,可用 --no-obs-noise 比较干净观测。
--checkpoint-command-ranges 载入训练课程范围。用
--command VX VY YAW --evaluation-out <metrics.json> 和正数 --steps
测量固定机体系命令。--measure 记录关节信号。--physics-hz 显式改变
积分频率,默认使用模板频率。内置场景可训练或回放,导入的 .map 仅用于回放。
粗糙地形使用明确的标称尺寸,不依赖隐藏的机器人模型:
--terrain-robot-height 0.25、--terrain-stance 0.40、
--terrain-foot-lift 0.04,单位均为米。使用 --scene rough 比较地形难度时,
按标定后的资产尺寸设置它们。高度与站姿跨度分别缩放垂直和水平方向的障碍,
抬脚高度决定连续粗糙度。Python 场景参数分别为 robot_height、stance、
foot_lift;所有值必须是有限正数。
导出与打包
python scripts/export.py --task <robot_id> --checkpoint <model_N.pt> --out <policy-dir>
python scripts/deploy.py --robot <robot_id> --model <robot.xml> --bundle <output-parent>
python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 100
导出写入策略、布局、检查点副本与说明,检查维度、初始姿态及 ONNX 数值一致性。
加 --native-layout 可同时导出原生回放的模型和控制器。位置与速度混合动作
自动使用原生布局。旧版 Rust 使用其位置动作布局。见
控制器设置。
仅提供模型时构建查看应用。可控制原生应用传入 --control、
--verification,若报告含设备绑定则传入 --controls。兼容 ONNX
模式另传 --policy,多个模式用 --platform-manifest。旧版 Rust
部署包由旧版部署选项构建。详见包格式。
默认值
优先级从高到低为命令行、环境变量、.env.local、.env、参数默认。可将
.env.example 复制为 .env 自定义本地默认值。空任务要求显式指定,空模型选择
已注册模型。有效默认值为:
MJRL_TASK=
MJRL_MODEL=
MJRL_SCENE=
MJRL_TERRAIN_ROW=
MJRL_TERRAIN_COL=
MJRL_BACKEND=auto
MJRL_DEVICE=auto
MJRL_NUM_ENVS=
MJRL_PLAY_NUM_ENVS=1
MJRL_CPU_THREADS=0
MJRL_STRIP_VISUAL=auto
MJRL_TENSORBOARD=on
MJRL_TB_PORT=6006
地形行列可以固定粗糙地形中的一个地块。原生 CPU 线程为 0 时自动选择。 去除可视网格可以节约每个环境的内存,也会改变相机看到的外观。 TensorBoard 绑定本机并跳过占用端口。