Files
UniversalTrain-ai/docs/USAGE.zh.md
T
chenlin d5e9004f6c
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
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

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