Files
chenlin ceca51b0d8
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
Improve generic robot onboarding, walking controls and end-effector interaction
Default humanoid intake to command-following gait and support bounded Cartesian target dragging for arms. Carry model and actuator semantics through calibration, native verification and packaging. Document reusable intake decisions and cover them with regression tests.
2026-11-06 10:54:58 +08:00

11 KiB
Raw Permalink Blame History

命令手册

用 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、foot_sites、 penalized_contact_geoms 和 termination_contact_geoms。模型及控制路径 相对输入 JSON 解析。标定报告须对应实际 XML 和编译依赖。 可选 posture_stds 须按名称精确覆盖所有标定的位置关节,每个值均为有限正数。 生成规格时,数值写入各关节的 posture_std,顶层映射随之移除;省略时使用 0.35。

不传 --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、力矩上限和轮速动作尺度。

每个关节可选 posture_std,表示以弧度为单位的姿态容许尺度,须为有限正数,默认 0.35。它为模板中随速度变化的姿态项提供标定数据,不是奖励权重。各关节可设置 不同尺度,无需在模板中加入特定机器人的判断逻辑。

可选 foot_sites 为每个命名足部支撑指定一个 MuJoCo site,顺序须与 foot_geoms 或 foot_bodies 一致。名称须唯一、非空且不带实体路径前缀。这些 site 提供抬脚净空项 的模型测量位置。默认空列表兼容不含 site 的现有规格;非空列表的长度须等于支撑数量, 且应引用机器人模型中实际存在的 site。完整 RobotSpec 输入及生成的字面量规格都会 保留这两个字段。

仅生成 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。新接入的双足人形默认用 W/S 前进和后退, A/D 左转和右转。可在输入 JSON 的 controls_path 指定自定义布局。轮足与全向布局见 操作绑定。

训练与回放

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。

EPA horizon 溢出属于凸体碰撞求解的独立临时缓冲区限制,增加接触或约束容量 不会扩大这个缓冲区。平台的 Warp 后端在捕获仿真执行图前,至少分配 128 个 horizon 条目(MuJoCo Warp 3.11 默认是 24),保留上游更大的容量,并记录 实际大小。所有溢出仍会使运行停止。

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 绑定本机并跳过占用端口。