最佳实践：从模型开发到仿真评测全链路

1.1 创建模型开发机

1. 在模型开发页面，单击新建开发环境。

2. 选择 gr00t1.7 官方镜像和 GPU 规格（推荐 ADB.MLTensor.2）。

3. 配置 SSH 公钥，单击确定。

4. 等待状态变为运行中后，通过 SSH 登录：

   ssh -i ~/.ssh/id_rsa root@<SSH地址>

1.2 确认环境

登录后确认目录结构：

ls /mnt/workspace    # 工作目录（持久化）
ls /data             # 数据集挂载
ls /official-models  # 官方预训练模型

1.3 适配机器人数据

这是整个流程中最关键的一步——告诉模型如何理解您的机器人数据。需要准备两个配置文件。

modality.json：定义 state/action 数组中各模态的切片范围、视频和标注字段的键映射关系。以宇树 G1 + 夹爪（16 维 state/action）为例：

{
    "state": {
        "left_arm":      {"start": 0,  "end": 7},
        "right_arm":     {"start": 7,  "end": 14},
        "left_gripper":  {"start": 14, "end": 15},
        "right_gripper": {"start": 15, "end": 16}
    },
    "action": {
        "left_arm":      {"start": 0,  "end": 7},
        "right_arm":     {"start": 7,  "end": 14},
        "left_gripper":  {"start": 14, "end": 15},
        "right_gripper": {"start": 15, "end": 16}
    },
    "video": {
        "cam_left_high":  {"original_key": "observation.images.cam_left_high"},
        "cam_left_wrist": {"original_key": "observation.images.cam_left_wrist"},
        "cam_right_wrist":{"original_key": "observation.images.cam_right_wrist"}
    },
    "annotation": {
        "human.task_description": {"original_key": "task_index"}
    }
}

配置要点：

• start/end 遵循 Python 切片规则 [start:end]，根据机器人关节自由度填写。

• video > original_key 必须与 parquet 文件中的列名完全一致。

• 文件可放在数据集的 meta/ 目录下（优先级最高），也可通过 --modality-json 参数指定。

*_config.py：定义模型如何处理数据（相机选择、动作表示、预测步数等）。

from gr00t.configs.data.embodiment_configs import register_modality_config
from gr00t.data.embodiment_tags import EmbodimentTag
from gr00t.data.types import (
    ActionConfig, ActionFormat, ActionRepresentation, ActionType, ModalityConfig,
)

config = {
    "video": ModalityConfig(
        delta_indices=[0],
        modality_keys=["cam_left_high", "cam_left_wrist", "cam_right_wrist"],
    ),
    "state": ModalityConfig(
        delta_indices=[0],
        modality_keys=["left_arm", "right_arm", "left_gripper", "right_gripper"],
    ),
    "action": ModalityConfig(
        delta_indices=list(range(16)),
        modality_keys=["left_arm", "right_arm", "left_gripper", "right_gripper"],
        action_configs=[
            ActionConfig(rep=ActionRepresentation.RELATIVE, type=ActionType.NON_EEF,
                         format=ActionFormat.DEFAULT, state_key="left_arm"),
            ActionConfig(rep=ActionRepresentation.RELATIVE, type=ActionType.NON_EEF,
                         format=ActionFormat.DEFAULT, state_key="right_arm"),
            ActionConfig(rep=ActionRepresentation.ABSOLUTE, type=ActionType.NON_EEF,
                         format=ActionFormat.DEFAULT, state_key="left_gripper"),
            ActionConfig(rep=ActionRepresentation.ABSOLUTE, type=ActionType.NON_EEF,
                         format=ActionFormat.DEFAULT, state_key="right_gripper"),
        ],
    ),
    "language": ModalityConfig(
        delta_indices=[0],
        modality_keys=["annotation.human.task_description"],
    ),
}

register_modality_config(config, embodiment_tag=EmbodimentTag.NEW_EMBODIMENT)

配置要点：

• modality_keys 必须与 modality.json 中对应 section 的键名一致。

• 手臂关节建议使用 RELATIVE，夹爪使用 ABSOLUTE。

• 文件末尾必须调用 register_modality_config(..., EmbodimentTag.NEW_EMBODIMENT)。

1.4 本地调试训练

在开发机上先用少量 step 验证代码可以正常跑通：

python /home/code/Isaac-GR00T/gr00t/experiment/launch_finetune.py \
    --base_model_path /official-models/GR00T-N1.7-3B \
    --backbone_model_name_or_path /official-models/Cosmos-Reason2-2B \
    --dataset-path /data/<数据集名称> \
    --embodiment_tag new_embodiment \
    --modality_config_path /mnt/workspace/gr00t_config/my_robot_config.py \
    --modality_json /mnt/workspace/gr00t_config/modality.json \
    --output_dir /mnt/workspace/checkpoints/debug_run \
    --max_steps 100 \
    --save_steps 50 \
    --global_batch_size 4 \
    --num_gpus 1 \
    --report_to tensorboard

关键参数说明：

1.5 本地推理验证

训练完几个步后，可先在开发机上启动推理服务验证模型输出是否合理：

python /home/code/Isaac-GR00T/gr00t/eval/run_http_server.py \
    --model-path /mnt/workspace/checkpoints/debug_run \
    --embodiment-tag new_embodiment \
    --modality_config_path /mnt/workspace/gr00t_config/my_robot_config.py \
    --modality_json /mnt/workspace/gr00t_config/modality.json \
    --port 8100

• --model-path 会自动选择目录下最新的 checkpoint。

• --port 对应开发机创建时配置的服务端口。

在另一个终端中验证推理服务是否正常：

curl http://localhost:8100/health
# 返回 {"status": "ok"} 即表示服务就绪

1.6 制作镜像

验证通过后，将开发环境打包为自定义镜像并推送到 ACR，用于后续的训练和评测。

2.1 创建训练模板

1. 在模型训练页面，单击开始训练。

2. 切换训练来源为自定义模型。

3. 配置训练参数：

   • 训练镜像：选择阶段一制作的自定义镜像。

   • 数据集路径查询：查看数据集存储路径（需自行配置到启动命令或环境变量中）。

   • 资源规格：选择 GPU 规格。

   • 启动命令：填写完整的训练命令。

   • TensorBoard 日志路径：填写日志目录路径。

4. 开启保存为模板，填写模板名称。

5. 单击确定。

2.2 监控训练

在模型训练列表中：

• 查看训练状态（训练中 / 已完成 / 失败）。

• 通过 Ray Dashboard 查看训练日志和资源使用情况。训练指标（Loss 曲线、学习率等）通过训练任务列表的更多 > 查看指标查看。

2.3 下载训练结果

训练完成后：

• 小于 200 MB 的模型文件可直接通过浏览器下载。

• 更大的文件建议导出到 OSS，再使用 ossutil 下载到本地。

官方模型一键部署

1. 在模型部署页面，找到训练完成的模型（状态为空闲）。

2. 单击部署推理服务。

3. 部署自动完成，记录推理服务 URL，后续仿真评测需要使用。

自定义模型手动部署

1. 在开发机中手动启动推理服务。

2. 通过端口映射对外暴露服务端口。

3. 记录推理服务的访问地址。

4.1 创建仿真开发机

1. 在仿真开发页面，单击新建仿真环境。

2. 选择 unitree 官方仿真镜像（包含 Isaac Sim 5.1 + xpra）。

3. 选择 GPU 规格，配置 SSH 公钥。

4. 单击确定，等待环境就绪后通过 SSH 登录。

4.2 安装仿真资产

1. 在仿真资产页面，确认所需的宇树 G1 机器人模型已安装。

2. 如未安装，单击目标资产的安装按钮。

3. 安装完成后，资产自动挂载到仿真开发机中。

4.3 仿真任务与机器人配置对应关系

根据您的机器人和训练配置，选择匹配的仿真任务：

4.4 在开发机中验证评测流程

在仿真开发机中执行以下命令发起评测，验证仿真环境和推理服务的连通性：

python /home/code/unitree_sim_isaaclab/adb/evaluate.py \
    --serve_url http://<推理服务地址>:8100 \
    --task Isaac-PickPlace-RedBlock-G129-Dex1-Joint \
    --task_desc "Pick up the red cup on the table." \
    --robot_type g129 \
    --enable_dex1_dds \
    --n_episodes 5 \
    --max_steps 500 \
    --output_dir /mnt/workspace/eval_output \
    --device cuda:0 \
    --enable_cameras

关键参数说明：

4.5 查看评测报告

评测完成后，报告保存在 --output_dir 指定目录下的 eval_report.json，包含以下关键指标：

4.6 制作仿真镜像

验证通过后，将仿真环境打包为自定义镜像，用于后续的自动化评测。

5.1 创建评测模板

1. 在仿真评测页面，单击新建评测。

2. 配置评测参数：

   • 推理服务 URL：阶段三获取的推理服务地址。

   • 仿真镜像：选择阶段四制作的自定义仿真镜像。

   • 资源规格：选择 GPU 规格。

   • 启动命令：填写评测脚本命令。

   • Headless：必须开启。平台一键评测必须使用 --headless 模式。

3. 开启存为模板。

4. 单击确定。

5.2 监控评测

在仿真评测列表中查看任务状态，通过 Ray Dashboard 监控执行详情。

5.3 查看评测报告

评测完成后，下载评测结果文件，分析模型在仿真环境中的表现。根据评测结果决定是否需要迭代优化：

• 成功率不达标：返回阶段一调整数据或训练参数。

• 成功率达标：进入真机部署阶段。