具身开发者社区

外观

教程raw.githubusercontent.com6 天前

unitree_lerobot：G1 遥操作数据转换 LeRobot 格式并训练 / 部署策略 ​

本教程按文档串起 unitree_lerobot 实操流程：安装 LeRobot 与 DDS 通信依赖，加载或整理 G1 遥操作数据，转换为 LeRobot 数据集，训练多种策略，并在真机或仿真环境中运行评测。

AI 整理
  • 数据与采集
  • 具身模型

宇树科技宇树 G1

> 本文依据以下官方文档整理：raw.githubusercontent.com/unitreerobotics/unitree_IL_lerobot。命令与版本以文档当前版本为准。

前置条件 ​

  • Unitree G1 humanoid robot；机械臂参数示例为 G1_29、G1_23；末端执行器示例为 dex3、dex1、inspire1、brainco
  • LeRobot datasets version 2.0 and above
  • conda 环境：unitree_lerobot，python=3.10
  • 依赖：pinocchio、ffmpeg=7.1.1、LeRobot、unitree_lerobot
  • DDS communication 需要安装 unitree_sdk2_python
  • 若使用数据编辑器，需要安装 PyQt5
  • 遥操作采集数据来自 avp_teleoperate，JSON 数据目录示例为 $HOME/datasets/task_name

1. 1. 安装 LeRobot 与 unitree_lerobot ​

先克隆带子模块的源码，创建 unitree_lerobot conda 环境，并安装 LeRobot 与本项目。文档中的 lerobot 目录对应训练代码，其 commit version number 为 0878c68。

bash
## Clone the source code
git clone --recurse-submodules https://github.com/unitreerobotics/unitree_lerobot.git

## If already downloaded:
git submodule update --init --recursive

## Create a conda environment
conda create -y -n unitree_lerobot python=3.10
conda activate unitree_lerobot
conda install pinocchio -c conda-forge

conda install ffmpeg=7.1.1 -c conda-forge

## Install LeRobot
cd unitree_lerobot/lerobot && pip install -e .

## Install unitree_lerobot
cd ../../ && pip install -e .

2. 2. 安装 Unitree DDS 通信依赖 ​

在 Unitree 机器人上进行 DDS communication 时，需要安装 unitree_sdk2_python。这一步独立于 LeRobot 安装，用于后续真机推理与评测相关通信。

bash
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python  && pip install -e .

3. 3. 加载并可视化示例数据集 ​

可直接使用 Hugging Face 上的 unitreerobotics/G1_Dex3_ToastedBread_Dataset。默认下载位置为 ~/.cache/huggingface/lerobot/unitreerobotics；若加载本地数据，修改 root 参数。

bash
cd unitree_lerobot/lerobot

python src/lerobot/scripts/lerobot_dataset_viz.py \
    --repo-id unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --episode-index 0

4. 4. 编辑采集后的遥操作数据 ​

采集完成后，可用项目内的数据编辑器处理质量问题：裁剪 episode 中多余片段，或删除失败 episode。启动前安装 PyQt5，再选择数据集路径，例如 test_dataset/。

bash
conda activate unitree_lerobot
pip install PyQt5
bash
cd data_editor
python data_editor_EN.py

5. 5. 排序重命名并转换为 LeRobot 格式 ​

LeRobot 数据集建议从 episode_0 开始顺序连续命名。先对 $HOME/datasets/task_name 排序重命名，再把 Unitree JSON 数据转换为 LeRobot 格式。

bash
python unitree_lerobot/utils/sort_and_rename_folders.py \
        --data_dir $HOME/datasets/task_name
bash
## --raw-dir     Corresponds to the directory of your JSON dataset
## --repo-id     Your unique repo ID on Hugging Face Hub
## --push_to_hub Whether or not to upload the dataset to Hugging Face Hub (true or false)
## --robot_type  The type of the robot used in the dataset (e.g., Unitree_Z1_Single, Unitree_Z1_Dual, Unitree_G1_Dex1, Unitree_G1_Dex3, Unitree_G1_Brainco, Unitree_G1_Inspire,Unitree_G1_Dex1_Sim)

python unitree_lerobot/utils/convert_unitree_json_to_lerobot.py \
    --raw-dir $HOME/datasets \
    --repo-id your_name/repo_task_name \
    --robot_type Unitree_G1_Dex3 \
    --push_to_hub

6. 6. 训练策略模型 ​

进入 unitree_lerobot/lerobot 后按策略类型选择训练命令。文档给出 act、diffusion、pi0、pi05、groot，示例数据集均为 unitreerobotics/G1_Dex3_ToastedBread_Dataset。

bash
cd unitree_lerobot/lerobot

python src/lerobot/scripts/lerobot_train.py \
    --dataset.repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --policy.push_to_hub=false \
    --policy.type=act
bash
cd unitree_lerobot/lerobot

python src/lerobot/scripts/lerobot_train.py\
    --dataset.repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --policy.push_to_hub=false \
    --policy.type=diffusion
bash
cd unitree_lerobot/lerobot

python src/lerobot/scripts/lerobot_train.py \
    --dataset.repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --policy.push_to_hub=false \
    --policy.type=pi0
bash
cd unitree_lerobot/lerobot

python src/lerobot/scripts/lerobot_train.py \
    --dataset.repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --policy.type=pi05 \
    --output_dir=./outputs/pi05_training \
    --job_name=pi05_training \
    --policy.pretrained_path=lerobot/pi05_base \
    --policy.compile_model=true \
    --policy.gradient_checkpointing=true \
    --policy.dtype=bfloat16 \
    --policy.device=cuda \
    --policy.push_to_hub=false
bash
cd unitree_lerobot/lerobot

python src/lerobot/scripts/lerobot_train.py \
    --dataset.repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --output_dir=./outputs/groot_training \
    --policy.push_to_hub=false \
    --policy.type=groot \
    --policy.tune_diffusion_model=false \
    --job_name=groot_training

7. 7. 在真机或仿真中评测部署 ​

训练后用 eval_robot 下脚本评测。真机测试使用 eval_g1.py；仿真环境使用 eval_g1_sim.py，并可设置 --save_data、--task_dir、--max_episodes。

bash

## --policy.path: Specifies the path to the pre-trained model, used for evaluating the policy.
## --repo_id: The repository ID of the dataset, used to load the dataset required for evaluation.
## --root: The root directory path of the dataset, defaults to an empty string.
## --episodes: The number of evaluation episodes; setting it to 0 uses the default value.
## --frequency: The evaluation frequency (in Hz), used to control the time step of the evaluation.
## --arm: The model of the robotic arm, (e.g., G1_29, G1_23).
## --ee: The type of end-effector, (e.g., dex3, dex1, inspire1, brainco).
## --visualization: Whether to enable visualization; setting it to true enables it.
## --send_real_robot: Whether to send commands to the real robot.

python unitree_lerobot/eval_robot/eval_g1.py  \
    --policy.path=unitree_lerobot/lerobot/outputs/train/2025-03-25/22-11-16_diffusion/checkpoints/100000/pretrained_model \
    --repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --root="" \
    --episodes=0 \
    --frequency=30 \
    --arm="G1_29" \
    --ee="dex3" \
    --visualization=true \
bash
## --save_data: Allows recording data while running inference. At present, this option is limited to the sim environment.
## --task_dir: the directory where data is stored
## --max_episodes: the maximum number of inference runs per task; if exceeded, the task is considered failed by default

python unitree_lerobot/eval_robot/eval_g1_sim.py  \
    --policy.path=unitree_lerobot/lerobot/outputs/train/2025-03-25/22-11-16_diffusion/checkpoints/100000/pretrained_model \
    --repo_id=unitreerobotics/G1_Dex3_ToastedBread_Dataset \
    --root="" \
    --episodes=0 \
    --frequency=30 \
    --arm="G1_29" \
    --ee="dex3" \
    --visualization=true \
    --save_data=false \
    --task_dir="./data" \
    --max_episodes=1200

验证是否跑通 ​

可通过 lerobot_dataset_viz.py 打开 unitreerobotics/G1_Dex3_ToastedBread_Dataset 的 episode 可视化确认数据可读；数据编辑器能选择数据集路径并执行裁剪或删除；转换脚本完成后可用训练命令读取 --dataset.repo_id；评测时 --visualization=true 用于启用可视化。

文档里点名的注意事项 ​

  • Hugging Face 数据集默认下载位置是 ~/.cache/huggingface/lerobot/unitreerobotics；加载本地数据时需要修改 root 参数。
  • 生成 LeRobot 数据集时，建议确保数据命名从 episode_0 开始顺序且连续。
  • --push_to_hub 用于控制是否上传数据集到 Hugging Face Hub，取值为 true 或 false。
  • Unitree_G1_Dex1_Sim 是 unitree_sim_isaaclab 中用于数据采集的 robot type，头部配备单视点相机。
  • 真机测试前，文档要求打开 image_server。
  • --episodes=0 表示使用默认值。
  • --save_data 目前仅限 sim environment。
  • --max_episodes 超过后，任务默认被视为 failed。

来源

本页事实对应的公开页面，以原文为准。

  1. raw.githubusercontent.com/unitreerobotics/unitree_IL_lerobot/main/README.md访问 2026-10-22