要約
pip install lerobotで2分以内にインストールし、事前学習済みポリシーをシミュレーション環境のFrankaアームでテスト可能lerobot.recordCLIツールを使用して、実機ロボット(例:UR5)からテレオペレーションデータを収録lerobot.trainを3行のコードで実行し、デモデータからカスタムポリシーを学習- シミュレーション(Isaac Gym)またはハードウェア(SO-100)へのデプロイを最小限のコード変更で実現
lerobot.push_to_hubを使用して、データセットやモデルをHugging Face Hubに共有
1. LeRobotのインストールとデータセットフォーマット
LeRobotのインストール
公式インストール手順から開始します。ほとんどのユーザーにとって、Pythonパッケージが最も迅速なオプションです。
pip install lerobot -U
インストールの確認
python -c "import lerobot; print(lerobot.__version__)"
期待される出力:
0.5.0
データセットフォーマットの概要
LeRobotのデータセットは、**RLDS(Robot Learning Dataset Standard)**に準拠しており、Hugging Face独自の拡張が加えられています。最小限のデータセットディレクトリ構造は以下の通りです。
my_dataset/
├── scenes/ # オプション:3Dシーン設定
│ └── table.yaml
├── trajectories/ # 収録されたデモデータ
│ ├── demo_0.h5 # HDF5形式(必須)
│ ├── demo_1.h5
│ └── ...
└── metadata.json # データセット説明(必須)
metadata.json の主要フィールド
{
"description": "UR5のピックアンドプレイスデータセット",
"robot": "ur5e",
"tasks": ["pick", "place"],
"sensors": ["rgb_camera", "joint_states"],
"version": "0.1.0"
}
一般的なエラー
metadata.jsonが欠落している場合:LeRobotはValueError: Dataset metadata not foundを発生させます。- HDF5構造が不正確な場合:各
.h5ファイルには/observationsと/actionsグループが必須です。
2. 事前学習ポリシーの読み込み
LeRobotでは、ACT(Action Chunk Transformer)、Diffusion Policy、および**SmolVLA(Small Vision-Language-Action)**の3種類の事前学習ポリシーが利用可能です。以下に読み込みとテスト方法を示します。
ACTポリシーの読み込み
from lerobot import ACTPolicy
# Frankaアーム(テーブル上操作)用の事前学習ACTモデルを読み込み
policy = ACTPolicy.from_pretrained("lerobot/act3d-franka-table")
# シミュレーションステップの実行(入力:観測値の辞書型)
observation = {
"image": torch.randn(3, 256, 256), # RGB画像
"joint_states": torch.randn(7), # アームの関節角度
"ee_pose": torch.randn(7) # エンドエフェクタの姿勢
}
action = policy(observation)
print(action.shape) # 期待値:torch.Size([7])(関節トルク)
Diffusion Policyの読み込み
from lerobot import DiffusionPolicy
# グラッピング用Diffusionポリシーを読み込み
policy = DiffusionPolicy.from_pretrained("lerobot/diffusion_policy-grasp")
# アクションのサンプリング(確率的)
action = policy.sample(observation)
print(action) # 出力:{"action": tensor([...]), "log_probs": tensor([...])}
SmolVLAの読み込み
from lerobot import SmolVLA
# 言語条件付きタスク用VLAモデルを読み込み
vla = SmolVLA.from_pretrained("lerobot/smolvla-aloha")
# テキストと画像によるクエリ
query = {
"image": torch.randn(3, 224, 224),
"text": "赤いブロックを拾う",
"joint_states": torch.randn(7)
}
action = vla(query)
print(action) # 出力:関節アクションのtensor([...])
注意点
- ACTポリシーは観測値を正規化した形式で要求します(モデルカードでスケーリングを確認)。
- Diffusionポリシーは遅延が大きい(約100ms/ステップ)ですが、サンプリング効率が高いです。
- SmolVLAはテキスト埋め込みが事前に必要です(
lerobot.tokenizersを使用)。
3. 実機アームでのテレオペレーションデータ収録
lerobot.record CLIツールを使用して、実機ロボットからデータを収録します。以下はUR5の例です。
事前準備
- ROS 2(Humble)とURドライバをインストール
sudo apt install ros-humble-ur-driver - ロボットがネットワーク上でROS 2経由でアクセス可能であることを確認
データセットの収録
lerobot record \
--robot ur5e \
--sensors rgb_camera joint_states \
--output_dir ./ur5_demos \
--max_episodes 10
期待される出力
UR5e用データセットの収録中...
エピソード 1/10:テレオペレーション入力待機中...
[ROS 2ノード開始: /lerobot_recorder]
[収録先: ./ur5_demos/trajectories/episode_0.h5]
[エピソード終了はCtrl+Cで]
テレオペレーションモード
| モード | コマンドフラグ | 説明 |
|---|---|---|
| キーボード | --teleop_mode keyboard | キーボードの矢印キーでロボットを制御。 |
| ジョイスティック | --teleop_mode joystick | python-joystick パッケージが必要。 |
| ゲームパッド | --teleop_mode gamepad | XInput互換コントローラーに対応。 |
| センサーガイド |
一般的なエラー
- ROS 2接続失敗:
ROS_DOMAIN_IDとROS_MASTER_URIの設定を確認 対処法:収録前にexport ROS_DOMAIN_ID=0を実行 - センサ校正:RGB画像が歪んでいる場合は、カメラの校正を
ros2 camera_calibrationで行う
4. デモデータからのポリシー学習
lerobot.train APIを使用して、カスタムポリシーを学習します。以下は**BC(Behavior Cloning)**の例です。
学習の実行
from lerobot import BehaviorCloningTrainer
from lerobot.datasets import load_dataset
# データセットを読み込み
dataset = load_dataset("path/to/ur5_demos")
# トレーナーの初期化
trainer = BehaviorCloningTrainer(
model="lerobot/act3d-base", # 事前学習ベースから開始
dataset=dataset,
batch_size=32,
epochs=50,
lr=1e-4
)
# 学習を実行
trainer.train()
trainer.push_to_hub("my-ur5-policy") # Hugging Face Hubに保存
ハイパーパラメータの調整
調整すべき主要パラメータ:
| パラメータ | デフォルト値 | 推奨範囲 | 説明 |
|---|---|---|---|
batch_size | 32 | 16–128 | バッチサイズを大きくすると学習が速くなります。 |
lr | 1e-4 | 1e-5 to 1e-3 | 高すぎると不安定、低すぎると遅くなります。 |
epochs | 50 | 20–200 | 検証損失が頭打ちになったら早期終了。 |
kl_weight | 0.1 | 0.01–0.5 | RLの微調整専用。 |
注意点
- 過学習:学習損失 << 検証損失の場合、モデル容量を減らすかデータ拡張を追加
- アクションスケーリング:データセット内のアクションがロボットのコマンド範囲(例:トルクの[-1, 1])と一致することを確認
5. シミュレーションおよびハードウェアでの評価
Isaac Gymでの評価
from lerobot.sim import IsaacGymEnv
from lerobot import ACTPolicy
# ポリシーと環境を読み込み
policy = ACTPolicy.from_pretrained("my-ur5-policy")
env = IsaacGymEnv(robot="ur5e", task="pick_place")
# 評価を実行
success_rate = env.evaluate(policy, episodes=10)
print(f"成功率: {success_rate * 100:.2f}%")
期待される出力
エピソード 1/10:成功 = True
エピソード 2/10:成功 = False
...
ハードウェアへのデプロイ(UR5例)
from lerobot.hardware import UR5Controller
from lerobot import ACTPolicy
# ロボットとポリシーを初期化
robot = UR5Controller()
policy = ACTPolicy.from_pretrained("my-ur5-policy")
# クローズドループ制御の実行
while True:
obs = robot.get_observations()
action = policy(obs)
robot.send_action(action)
ハードウェア対応表
| ロボット | LeRobot対応 | 備考 |
|---|---|---|
| UR5/UR10 | ✅ | ROS 2ドライバが必要です。 |
| Franka Emika | ✅ | franka_ros2 パッケージが必要です。 |
| SO-100 | ✅ | 公式対応(以下参照)。 |
| Stretch RE1 | ✅ | stretch_ros2 ドライバが必要です。 |
| Aloha | ✅ | 実験段階(2026-05)。 |
| ハードウェアドキュメント |
注意点
- 遅延:実機デプロイではループタイム <50msが必要です。
robot.set_control_rate(20)で20Hz更新を設定 - 安全性:ハードウェアモードでは力/トルク制限と緊急停止を必ず有効にしてください
6. データセットとモデルのHubへのアップロード
Hugging Face Hubを使用して、コミュニティと共有します。
データセットのアップロード
lerobot push_to_hub \
--path ./ur5_demos \
--repo_id my-username/ur5-pick-place-demos \
--private # オプション:Falseに設定して公開
モデルのアップロード
from lerobot import ACTPolicy
# 学習済みポリシーを読み込み
policy = ACTPolicy.from_pretrained("lerobot/act3d-base")
policy.train() # 学習済みと仮定
# Hubへプッシュ
policy.push_to_hub("my-username/ur5-act-policy")
Hubの機能
- モデルカード:コードから自動生成(リポジトリ内の
README.mdを編集)。 - データセット:バージョン管理と検索可能(例:
huggingface.co/datasets/my-username/ur5_demos)。 - Spaces:対話型デモのデプロイ(LeRobot Spaces を参照)。
注意点
- 大容量ファイル:データセットが10GBを超える場合は失敗する可能性があります。
lerobot push_to_hub --chunk_size 1Gを使用 - ライセンス:
metadata.jsonでライセンス(例:mitまたはapache-2.0)を必ず指定
7. ハードウェア固有のガイド
SO-100(公式対応)
LeRobotはSO-100モバイルマニピュレータにネイティブ対応しています。
SO-100ドライバのインストール
pip install lerobot[so100]
例:SO-100のテレオペレーション
lerobot record \
--robot so100 \
--sensors rgb_camera base_pose \
--output_dir ./so100_navigation
Koch Roboticsアーム
Koch K1/K2アームの場合は、ROS 2インターフェースを使用します。
from lerobot.hardware import KochArm
robot = KochArm()
robot.move_to_joint_positions([0.5, -0.3, 0.0,
