Hugging Face's logo

LeRobot 文件

實體機器人模仿學習

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

實體機器人模仿學習

本教學將說明如何訓練神經網路以自動化控制實體機器人。

你將學到：

  1. 如何記錄並視覺化你的資料集。
  2. 如何使用你的資料訓練策略，並為評估做好準備。
  3. 如何評估你的策略並視覺化結果。

遵循這些步驟，你將能夠複製各項任務，例如以高成功率抓取積木並放入容器中，如下方影片所示。

影片：拾取積木任務

本教學不限於特定機器人：我們將引導你使用適用於任何支援平台的指令與 API 片段。

在資料收集過程中，你將使用「遠端操作 (teleoperation)」設備（如主從式機械手臂或鍵盤）來操控機器人並記錄其運動軌跡。

當收集到足夠的軌跡後，你將訓練一個神經網路來模仿這些軌跡，並部署訓練好的模型，讓機器人能夠自主執行任務。

如果你在任何步驟遇到問題，歡迎加入我們的 Discord 社群尋求支援。

設置與校準

如果你尚未設置並校準你的機器人與遠端操作設備，請遵循對應的機器人教學進行設置。

遠端操作

在本範例中，我們將演示如何遠端操作 SO101 機器人。針對每個指令，我們也提供了對應的 API 範例。

請注意，與機器人關聯的 id 用於儲存校準檔案。在使用相同配置進行遠端操作、記錄與評估時，務必使用同一個 id。

指令
API 範例
lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm

遠端操作指令會自動：

  1. 識別任何缺失的校準並啟動校準程序。
  2. 連接機器人與遠端操作設備，並啟動遠端操作。

攝影機

若要將攝影機加入你的設置，請遵循此指南。

配合攝影機進行遠端操作

使用 rerun，你可以在遠端操作的同時視覺化攝影機畫面與關節位置。在此範例中，我們使用的是 Koch 機械手臂。

指令
API 範例
lerobot-teleoperate \
    --robot.type=koch_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
    --teleop.type=koch_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm \
    --display_data=true

記錄資料集

熟悉遠端操作後，你就可以記錄第一份資料集了。

我們使用 Hugging Face Hub 的功能來上傳你的資料集。如果你先前未使用過 Hub，請確保你能透過 CLI 使用具備寫入權限的 Token 進行登入，該 Token 可從 Hugging Face 設定中生成。

透過執行以下指令將 Token 加入 CLI：

hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential

接著將你的 Hugging Face 儲存庫名稱儲存至變數中：

HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

現在你可以開始記錄資料集了。若要記錄 5 個片段並將資料集上傳至 Hub，請針對你的機器人調整下方的程式碼，並執行對應指令或 API 範例。

指令
API 範例
lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem585A0076841 \
    --robot.id=my_awesome_follower_arm \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.num_episodes=5 \
    --dataset.single_task="Grab the black cube" \
    --dataset.streaming_encoding=true \
    # --dataset.vcodec=auto \
    --dataset.encoder_threads=2

資料集上傳

你的資料集在本地儲存於此資料夾：~/.cache/huggingface/lerobot/{repo-id}。資料記錄完成後，你的資料集將上傳至你的 Hugging Face 頁面（例如：https://huggingface.co/datasets/${HF_USER}/so101_test），你可以透過執行以下指令獲得：

echo https://huggingface.co/datasets/${HF_USER}/so101_test

你的資料集將自動標記為 LeRobot，以便社群能輕鬆找到它；你也可以新增自訂標籤（例如本例中的 tutorial）。

你可以在 Hub 上搜尋 LeRobot 標籤來尋找其他 LeRobot 資料集。

你也可以手動將本地資料集推送至 Hub，執行：

hf upload ${HF_USER}/record-test ~/.cache/huggingface/lerobot/{repo-id} --repo-type dataset

記錄功能

record 函數提供了一套工具，用於在機器人運作期間擷取並管理資料。

1. 資料儲存
  • 資料使用 LeRobotDataset 格式，並在記錄時直接儲存於磁碟。
  • 預設情況下，資料集會在記錄完成後推送至你的 Hugging Face 頁面。
    • 若要停用上傳，請使用 --dataset.push_to_hub=False。
2. 檢查點 (Checkpointing) 與恢復 (Resuming)
  • 記錄過程中會自動建立檢查點。
  • 如果發生問題，你可以透過使用 --resume=true 重新執行相同的指令來恢復進度。恢復記錄時，--dataset.num_episodes 必須設置為額外需要記錄的片段數量，而非資料集中目標的總片段數量！
  • 若要從頭開始記錄，請手動刪除資料集目錄。
3. 記錄參數

使用命令列參數設置資料記錄流程：

  • --dataset.episode_time_s=60 每個資料記錄片段的持續時間（預設：60 秒）。
  • --dataset.reset_time_s=60 每個片段後重置環境的持續時間（預設：60 秒）。
  • --dataset.num_episodes=50 總共需要記錄的片段數量（預設：50）。
4. 記錄過程中的鍵盤控制

使用鍵盤快捷鍵控制資料記錄流程：

  • 按下向右鍵 (→)：提前結束當前片段或重置時間，並進入下一個片段。
  • 按下向左鍵 (←)：取消當前片段並重新記錄。
  • 按下 Escape (ESC)：立即停止工作階段，進行影片編碼並上傳資料集。

資料收集技巧

一旦你熟悉了資料記錄，就可以建立更大的資料集來進行訓練。一個不錯的入門任務是在不同位置抓取物體並將其放入容器中。我們建議至少記錄 50 個片段，每個位置 10 個片段。保持攝影機固定，並在錄製過程中保持一致的抓取行為。同時，確保你操作的物體在攝影機中清晰可見。一個實用的經驗法則是：你應該能夠僅透過觀看攝影機影像來自行完成該任務。

在接下來的章節中，你將訓練你的神經網路。在達到可靠的抓取表現後，你可以開始在資料收集過程中加入更多變數，例如更多的抓取位置、不同的抓取技術，以及改變攝影機位置。

避免過快增加太多變數，否則可能會影響你的結果。

如果你想深入了解這個重要主題，可以查看我們撰寫的部落格文章，探討什麼是好的資料集。

疑難排解：

  • 在 Linux 上，如果左右方向鍵與 ESC 鍵在資料記錄期間無效，請確保你已設定 $DISPLAY 環境變數。請參閱 pynput 的限制。

視覺化資料集

如果你已使用 --control.push_to_hub=true 將資料集上傳至 Hub，你可以透過貼上由以下指令獲得的儲存庫 ID，在線上視覺化你的資料集：

echo ${HF_USER}/so101_test

重播片段

一個有用的功能是 replay 函數，它允許你重播任何你記錄的片段或來自任何現有資料集的片段。此功能有助於測試機器人動作的可重複性，並評估不同機器人型號之間的轉移性。

你可以使用下方的指令或 API 範例，在你的機器人上重播第一個片段：

指令
API 範例
lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.episode=0 # choose the episode you want to replay

你的機器人應該會複製與你所記錄相似的動作。例如，請參閱此影片，我們在 Trossen Robotics 的 Aloha 機器人上使用了 replay。

訓練策略 (Policy)

要訓練控制機器人的策略，請使用 lerobot-train 指令碼。需要幾個參數，以下是一個指令範例：

lerobot-train \
  --dataset.repo_id=${HF_USER}/so101_test \
  --policy.type=act \
  --output_dir=outputs/train/act_so101_test \
  --job_name=act_so101_test \
  --policy.device=cuda \
  --wandb.enable=true \
  --policy.repo_id=${HF_USER}/my_policy

讓我們解釋一下該指令：

  1. 我們使用 --dataset.repo_id=${HF_USER}/so101_test 作為參數提供了資料集。
  2. 我們使用 policy.type=act 指定了策略。這會從 configuration_act.py 載入設定。重要的是，此策略會自動適應你資料集中儲存的馬達狀態數量、馬達動作數量以及攝影機數量（例如 laptop 和 phone）。
  3. 我們提供了 policy.device=cuda，因為我們在 Nvidia GPU 上訓練，但你也可以使用 policy.device=mps 在 Apple Silicon 上訓練。
  4. 我們提供了 wandb.enable=true 以使用 Weights and Biases 來視覺化訓練圖表。這是選用功能，但若要使用，請確保透過執行 wandb login 進行了登入。

訓練需要幾個小時。你可以在 outputs/train/act_so101_test/checkpoints 中找到檢查點。

若要從檢查點恢復訓練，以下是從 act_so101_test 策略的 last 檢查點恢復的指令範例：

lerobot-train \
  --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true

如果你不想在訓練後將模型推送至 Hub，請使用 --policy.push_to_hub=false。

此外，你可以透過添加以下內容來提供額外的 tags、指定模型的 license，或將模型儲存庫設為 private：--policy.private=true --policy.tags=\[ppo,rl\] --policy.license=mit

使用 Google Colab 訓練

如果你的本地電腦沒有強大的 GPU，你可以按照 ACT 訓練筆記本，利用 Google Colab 來訓練你的模型。

上傳策略檢查點

訓練完成後，使用以下指令上傳最新檢查點：

hf upload ${HF_USER}/act_so101_test \
  outputs/train/act_so101_test/checkpoints/last/pretrained_model

你也可以透過以下指令上傳中間檢查點：

CKPT=010000
hf upload ${HF_USER}/act_so101_test${CKPT} \
  outputs/train/act_so101_test/checkpoints/${CKPT}/pretrained_model

執行推理並評估你的策略

你可以使用 lerobot-record 中的 record 指令碼，並將策略檢查點作為輸入，來執行推理並評估你的策略。例如，執行此指令或 API 範例以執行推理並記錄 10 個評估片段：

指令
API 範例
lerobot-record  \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyACM1 \
  --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video10, width: 640, height: 480, fps: 30}, side: {type: intelrealsense, serial_number_or_name: 233522074606, width: 640, height: 480, fps: 30}}" \
  --robot.id=my_awesome_follower_arm \
  --display_data=false \
  --dataset.repo_id=${HF_USER}/eval_so100 \
  --dataset.single_task="Put lego brick into the transparent box" \
  --dataset.streaming_encoding=true \
  --dataset.encoder_threads=2 \
  # --dataset.vcodec=auto \
  # <- Teleop optional if you want to teleoperate in between episodes \
  # --teleop.type=so100_leader \
  # --teleop.port=/dev/ttyACM0 \
  # --teleop.id=my_awesome_leader_arm \
  --policy.path=${HF_USER}/my_policy

如你所見，這與之前用來記錄訓練資料集的指令幾乎相同。只有兩處變更：

  1. 增加了一個 --control.policy.path 參數，指明策略檢查點的路徑（例如 outputs/train/eval_act_so101_test/checkpoints/last/pretrained_model）。如果你已將模型檢查點上傳至 Hub，也可以使用模型儲存庫（例如 ${HF_USER}/act_so101_test）。
  2. 資料集名稱以 eval 開頭，以反映你正在執行推理（例如 ${HF_USER}/eval_act_so101_test）。
在 GitHub 上更新

←安裝 引入你自己的策略→
© . This site is unofficial and not affiliated with Hugging Face, Inc.