Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

LeRobot SO-101 教學:組裝、校準、錄製、訓練與執行

本教學依據 Hugging Face 官方 LeRobot 文件整理 SO-101 主臂與從臂的完整流程,補上製作者最常漏掉的檢查,最後延伸到 LeKiwi 移動底盤與疑難排解檢查表。所有指令對應 LeRobot v0.7.0(2026 年 11 月 5 日發布)。LeRobot 更新很快,請對照你實際安裝版本的官方文件確認參數。

你要做出什麼,以及需要準備什麼

LeRobot 是 Hugging Face 的開源機器人函式庫,用同一套指令驅動機器人、錄製示範、訓練策略和執行策略。SO-101 是它的旗艦機械臂:你用手移動主臂,從臂跟著動作,錄下的動作與相機畫面再讓神經網路學會獨立重複這項任務。

整個流程分七個階段:備齊零件並安裝軟體、為每顆伺服馬達設定 ID、組裝兩支機械臂、校準、接上相機遙操作、錄製資料集,最後訓練並執行策略。最後一個製作章節加上 LeKiwi 移動底盤,之後是疑難排解檢查表。

左右滑動可查看完整圖示。

組裝的七個階段,以及每個階段使用的指令由上到下的七個階段編號清單。1 備齊零件與軟體:pip install lerobot。2 連接埠與伺服馬達 ID:lerobot-find-port 和 lerobot-setup-motors。3 組裝兩支機械臂,用手完成。4 校準:lerobot-calibrate。5 接上相機遙操作:lerobot-find-cameras 和 lerobot-teleoperate。6 錄製資料集:lerobot-record,並用 lerobot-replay 檢查。7 訓練並執行策略:lerobot-train,然後是 lerobot-rollout。1備齊零件與軟體備齊零件,安裝 LeRobotpip install lerobot2連接埠與伺服馬達 ID一次只接一顆伺服馬達lerobot-find-portlerobot-setup-motors3組裝兩支機械臂逐個關節,兩支都要沒有指令:動手組裝4校準兩支臂的數值一致lerobot-calibrate5接上相機遙操作主臂帶動從臂lerobot-find-cameraslerobot-teleoperate6錄製資料集關節位置與影片lerobot-recordlerobot-replay7訓練並執行策略從臂執行 ACT 策略lerobot-trainlerobot-rollout
組裝的七個階段,以及每個階段使用的指令

你需要兩支機械臂(零件見下一節)、每支臂各一塊 USB 匯流排伺服馬達控制板與電源、一台安裝 Python 3.12 或更新版本的電腦、兩台 USB 相機(本教學的指令使用兩台)、一個免費的 Hugging Face 帳號(存放資料集與檢查點),以及訓練用的 GPU。本教學使用的 ACT 策略,筆電等級的 GPU 就夠用,租用雲端 GPU 也可以。

本教學整理自官方文件與社群的製作紀錄,我們沒有在每一種硬體版本上逐步實測。呼叫 control_robot.py 的舊版教學不適用於 0.7.0,因為 0.7.0 使用的是 lerobot-* 指令。

零件、列印與電源

SO-101 專案公開了零件清單與列印檔,Hugging Face 的 SO-101 頁面附有連結。一組完整的主臂加從臂需要 12 顆 Feetech STS3215 伺服馬達、兩塊控制板、兩個電源、兩條 USB-C 線、桌夾。組裝使用 M2×6 與 M3×6 螺絲;專案的零件清單沒有列出這些螺絲,請確認伺服馬達或套件隨附的內容。也可以直接購買列印好的零件和完整套件。

從臂使用六顆齒輪比 1/345 的伺服馬達。主臂使用三種不同的齒輪比,讓它既能撐住自身重量,移動時又只需很小的力。

電源必須和伺服馬達匹配。7.4 V 的 STS3215 在 6 V 時堵轉扭矩為 16.5 kg·cm(使用 5 V 電源時略低),通常使用 5 V 電源。從臂也可以改用 12 V 伺服馬達(30 kg·cm)取得更大力量,但這時需要額定 5 A 以上的 12 V 電源;主臂一律使用 7.4 V 伺服馬達。切勿把 12 V 電源接到裝有 7.4 V 伺服馬達的控制板上;請在每個電源上標明電壓和它所屬的機械臂。

左右滑動可查看完整圖示。

主臂與從臂的電源與 USB 連接上方的電腦用 USB-C 線分別連接主臂的控制板和從臂的控制板。每塊控制板各有自己的電源。每塊板各串接六顆伺服馬達,從 1 號伺服馬達開始,用 3 針線連接。主臂一律使用 7.4 V 伺服馬達,接 5 V 電源。從臂使用 7.4 V 伺服馬達搭配 5 V 電源,或 12 V 伺服馬達搭配額定 5 A 以上的 12 V 電源。Waveshare 控制板上的兩個跳線帽都設在 B 通道,也就是 USB 通道。電腦主臂5 V 電源控制板Waveshare 板:兩個跳線帽都放在B 通道(USB)。1234566 顆伺服馬達,7.4 V,接 5 V 電源。從臂電源:5 V,或 12 V 5 A+控制板Waveshare 板:兩個跳線帽都放在B 通道(USB)。1234567.4 V 伺服馬達接 5 V,或 12 V 伺服馬達接 12 V電源USB-C3 針伺服馬達線切勿把 12 V 電源接到裝有 7.4 V 伺服馬達的控制板上。
主臂與從臂的電源與 USB 連接

使用 PLA+ 列印:0.4 mm 噴嘴搭配 0.2 mm 層高(或 0.6 mm 噴嘴搭配 0.4 mm 層高),填充率 15%。每支機械臂的零件都在同一個檔案中,擺放方向已盡量減少支撐;水平方向的螺絲孔內不要有支撐。先列印 Gauge Zero 與 Gauge Tight 這兩個測試件,拿去和伺服馬達比對;如果 Gauge Zero 無法像專案影片中那樣嵌合,請先調整印表機設定並重新列印,再列印機械臂零件。

準備好 #0 和 #1 號十字螺絲起子,測試前先把兩個底座用桌夾固定在桌上。我們供應的相關零件連結在下方。

橫向捲動以比較所有欄位。

關節伺服馬達 ID主臂齒輪比從臂齒輪比
肩部旋轉11/1911/345
肩部抬升21/3451/345
肘部彎曲31/1911/345
腕部彎曲41/1471/345
腕部旋轉51/1471/345
夾爪61/1471/345

安裝 LeRobot 與伺服馬達支援

LeRobot 0.7.0 需要 Python 3.12 或更新版本。用 conda(miniforge)或 uv 建立獨立環境,並在每個新終端機視窗中先啟用它。影片處理在大多數平台上需要 ffmpeg(在 macOS Intel 和 32 位元 ARM Linux 上,LeRobot 會改用 PyAV,可以不裝 ffmpeg);conda 版本適用於所有 PyTorch 版本。

建立環境
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge

從 PyPI 安裝 LeRobot,並加上你需要的擴充。core_scripts 提供錄製、重播與校準所需的功能,feetech 加入 STS3215 伺服馬達支援,training 則是訓練工具。

安裝 LeRobot 與所需擴充
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'

平台注意事項:在 Apple 晶片上,PyTorch 需要 macOS 14 或更新版本,GPU(MPS)加速則需要 macOS 15 或更新版本。若要在 Linux 上使用 NVIDIA GPU,預設的 PyTorch 版本需要 580.65 或更新版本的驅動程式;驅動較舊時,請先安裝對應 CUDA 版本的 PyTorch,並從 CPU 索引安裝 torchcodec(見 Hugging Face 安裝頁面)。在 WSL 中還要安裝 evdev(conda install evdev -c conda-forge;若用 uv,則先執行 sudo apt install libevdev-dev,再執行 uv pip install evdev)。PyTorch 2.10 或更新版本可以改用系統自帶的 ffmpeg,不必用 conda 版本。

找出連接埠並設定伺服馬達 ID

新的 STS3215 伺服馬達出廠時 ID 通常是 1,而且控制器與所有伺服馬達必須使用同一個鮑率。LeRobot 會把這兩項設定一次寫入每顆伺服馬達的記憶體,所以請在組裝前完成,並且一次只接一顆伺服馬達。從別的機器人拆下來的伺服馬達很可能也需要重設。

左右滑動可查看完整圖示。

SO-101 機械臂的六個關節,以及每個關節的伺服馬達 ID機械臂的側視圖。關節 1,肩部旋轉,讓整支機械臂繞著底座上的垂直軸轉動。關節 2、3 和 4,即肩部抬升、肘部彎曲和腕部彎曲,讓機械臂在同一個平面內彎曲。關節 5,腕部旋轉,讓夾爪繞著前臂的軸線轉動。關節 6 是夾爪。每個關節的伺服馬達 ID 就是它的編號。各連桿的長度與軸線依照官方 SO-101 模型。1234561肩部旋轉2肩部抬升3肘部彎曲4腕部彎曲5腕部旋轉6夾爪伺服馬達 ID = 關節編號。設定順序:從 6 到 1。從臂側視圖,比例取自官方 SO-101 模型。主臂的關節 6 是扳機。
SO-101 機械臂的六個關節,以及每個關節的伺服馬達 ID

用 USB 把一塊控制板接到電腦並接上電源,執行連接埠查找工具。依提示只拔掉這塊控制板的 USB 線,再按 Enter,腳本會印出連接埠,例如 Linux 上的 /dev/ttyACM0、macOS 上的 /dev/tty.usbmodem… 或 Windows 上的 COM3。把線插回去,再對第二塊控制板重複同樣步驟。在 Linux 上可能需要對每個連接埠用 sudo chmod 666 開放存取權限(例如 /dev/ttyACM0 與 /dev/ttyACM1)。

找出控制板的連接埠
lerobot-find-port

先對從臂執行設定腳本,再對主臂執行,兩者各用自己的連接埠。腳本一次只會指名一顆伺服馬達,所以執行前請先讀完下面的步驟。

設定從臂伺服馬達 ID
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

主臂改用遙操作裝置(teleop)的參數,而不是機器人(robot)的參數。每次提示時,請依零件一節表格中該關節所列的齒輪比挑選伺服馬達(主臂:肩部旋轉與肘部彎曲為 1/191,肩部抬升為 1/345,腕部彎曲、腕部旋轉與夾爪為 1/147),並在腳本回報某顆伺服馬達設定完成後,立刻標出它的 ID。

設定主臂伺服馬達 ID
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. 腳本一次只會點名一顆伺服馬達,從夾爪(ID 6)開始,到肩部旋轉(ID 1)結束。只把被點名的那顆接到控制板上,它不能和其他任何伺服馬達串接。
  2. 按 Enter。腳本回報 ID 已設定後,把這顆伺服馬達的線從控制板拔下,接上下一顆被點名的伺服馬達,再按一次 Enter。
  3. 每次按 Enter 之前,先檢查電源線、USB 線和 3 針線。腳本若回報錯誤,先檢查這些線材;使用 Waveshare 控制板時,兩個跳線帽都必須放在 B 通道(USB)。
  4. 腳本結束後,依序把伺服馬達串接起來,並把肩部旋轉伺服馬達(ID 1)接到控制板。

    左右滑動可查看完整圖示。

    逐顆設定伺服馬達 ID,再依序串接伺服馬達上方面板:設定 ID 時,控制板上只接一顆伺服馬達。設定腳本依 6、5、4、3、2、1 的順序指名伺服馬達。下方面板:設定完成後,伺服馬達依序串接。1 號伺服馬達接到控制板,之後每一顆接到前一顆,直到 6 號伺服馬達。設定 ID 時只接著正在設定的那顆伺服馬達。拔掉它,再接上腳本指名的下一顆。控制板?腳本要求的順序654321設定完成後依序串接伺服馬達。1 號伺服馬達接到控制板。控制板123456
    逐顆設定伺服馬達 ID,再依序串接伺服馬達

組裝主臂與從臂

兩支機械臂的大部分列印零件通用,組裝順序也相同(腕部旋轉的零件不同,主臂有把手與扳機,從臂則是可動的夾爪):底座與肩部、上臂、前臂、腕部,最後從臂裝夾爪,主臂則裝把手與扳機。Hugging Face 在 SO-101 頁面為每個關節提供了短影片,請對照影片和這些說明一起做。先清除列印零件上的所有支撐材料,並在每顆伺服馬達封入結構之前先插上一條 3 針線。

  1. 關節 1,肩部旋轉:在伺服馬達兩側裝上舵盤,上方的舵盤用一顆 M3×6 螺絲固定(下方的舵盤不需要螺絲)。把伺服馬達放進底座,用四顆 M2×6 螺絲鎖緊,再套上第一個伺服馬達固定座並用兩顆 M2×6 固定,肩部零件上方與下方各用四顆 M3×6 鎖上,最後裝上肩部伺服馬達固定座。
  2. 關節 2,肩部抬升:裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),從上方滑入伺服馬達,用四顆 M2×6 鎖緊,再把上臂用 M3×6 鎖上,每側各四顆。
  3. 關節 3,肘部:裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),放入 3 號伺服馬達並用四顆 M2×6 鎖緊,再把前臂接上,每側用四顆 M3×6 固定。
  4. 關節 4,腕部彎曲:裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),套上 4 號伺服馬達固定座,滑入 4 號伺服馬達並用四顆 M2×6 鎖緊。
  5. 關節 5,腕部旋轉:把 5 號伺服馬達放進腕部固定座,前方用兩顆 M2×6 固定,只裝一個舵盤並用一顆 M3×6 螺絲鎖緊,再依官方關節 5 影片的做法,用 M3×6 螺絲把腕部固定到 4 號伺服馬達(文字版指南寫的是兩側各四顆)。
  6. 從臂夾爪:把夾爪接到腕部伺服馬達的舵盤,用四顆 M3×6 鎖緊;裝入夾爪伺服馬達,每側用兩顆 M2×6 固定,裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),再依官方夾爪影片的做法,用 M3×6 螺絲鎖上爪片(文字版指南寫的是兩側各四顆)。
  7. 主臂把手:把主臂固定座裝到腕部,用四顆 M3×6 鎖緊,把手用一顆 M2×6 固定在上面,裝入 6 號伺服馬達,也就是扳機伺服馬達(官方指南稱之為夾爪伺服馬達),每側用兩顆 M2×6 固定,並以一顆 M3×6 螺絲裝上舵盤,最後用四顆 M3×6 裝上扳機。
  8. 接上電源之前,先用手慢慢把每個關節轉過整個活動範圍,轉到極限位置時絕不要硬扳;它應該順暢轉動,不會刮擦。在把伺服馬達封入結構之前,先標出每顆伺服馬達的 ID,並用桌夾把兩個底座固定在桌上。

校準兩支機械臂

校準會記錄每個關節的活動範圍,讓主臂和從臂在相同的實際姿勢下回報相同的數值,也讓在一台機器人上訓練出的策略可以在另一台上執行。每支機械臂校準一次即可;更換或改動硬體後,或 LeRobot 提示找不到校準檔時,再校準一次。重新校準之前錄製的資料和訓練的策略,用的是舊的校準。

先校準從臂。腳本會要求你把每個關節移到活動範圍的中間位置並按 Enter,接著把每個關節轉過完整的活動範圍,所有關節都轉完後再按一次 Enter。請給每支機械臂一個獨一無二的 id,這個名字就是它的校準檔名稱。本教學的指令以 /dev/ttyACM0 代表從臂、/dev/ttyACM1 代表主臂作為範例:請換成你自己找到的連接埠,並且不要把兩支機械臂搞反。

左右滑動可查看完整圖示。

校準:先把每個關節放在活動範圍的中間,再轉過完整範圍並排的兩個面板。步驟 1:六個關節各自停在活動範圍的中間,以橫條中央的圓點表示,然後按 Enter。步驟 2:六個關節各自轉過整個活動範圍,以橫條上從最小端到最大端的雙向箭頭表示。下方:同一個實際姿勢,在主臂和從臂上得到相同的位置數值。步驟 1:中間位置把每個關節移到活動範圍的中間,再按 Enter。123456中間步驟 2:完整範圍讓每個關節轉過整個活動範圍,再按一次 Enter。123456最小最大同一個實際姿勢,主臂與從臂的位置數值相同。
校準:先把每個關節放在活動範圍的中間,再轉過完整範圍
校準從臂
lerobot-calibrate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm

再用同樣的動作校準主臂。

校準主臂
lerobot-calibrate \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

之後每個指令都要使用相同的 id,LeRobot 就是靠它找到校準檔,校準檔預設存放在 ~/.cache/huggingface/lerobot/calibration 底下。請備份,並且不要放在暫存資料夾中:有位社群製作者的校準檔在一次斷電重啟中遺失,重新校準時沒有把每個關節都放在活動範圍的中間,結果有些關節的歸零偏移是錯的。

用主臂遙操作從臂

遙操作把兩支機械臂連起來:從臂會模仿主臂。若找不到校準檔,指令會先啟動校準程序。從小幅度、慢速的動作開始,手要避開從臂的關節,電源也要放在伸手可及的地方。

遙操作
lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

接著加上相機。用相機查找工具列出相機,它會印出每台相機的識別碼,並把每台相機的測試畫面存到 outputs/captured_images;打開這些畫面,就能看出哪個索引是哪台相機。重新開機或重新插拔相機後,索引可能會改變。

列出相機
lerobot-find-cameras opencv

再次遙操作,這次接上相機並用 Rerun 顯示即時畫面。你在這裡取的相機名稱,例如 top 和 wrist,之後會成為資料集的鍵名,所以從現在起請一直使用相同的名稱與設定。

接上相機並開啟即時畫面遙操作
lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm \
    --display_data=true

擺好相機,讓策略學得會

策略只看得到相機畫面和關節位置,所以相機設置比高解析度更重要。對大多數任務來說,640×480、每秒 30 幀就夠了,錄製與訓練也會比較快。

左右滑動可查看完整圖示。

相機擺放:固定視角、均勻光線,以及成為資料集鍵名的相機名稱工作區的側視圖。從臂伸手去拿目標容器旁的物體。桌子上方支架上的頂部相機向下拍攝整個工作區,以陰影表示的視野涵蓋機械臂、物體和目標。夾爪上的腕部相機沿著兩片夾爪的方向拍攝。左上方的柔光板讓場景光線均勻。錄製與執行之間,相機都保持固定。相機名稱會成為資料集的鍵名:observation.images.top 和 observation.images.wrist。漫射光物體目標頂部相機腕部相機牢牢固定:錄製與執行之間不要移動相機。相機名稱就是資料集鍵名:observation.images.topobservation.images.wrist
相機擺放:固定視角、均勻光線,以及成為資料集鍵名的相機名稱
  1. 用柔和的漫射光把場景照亮。避免陽光直射、強烈反光和會移動的陰影:錄製與執行時的光線不一樣,策略就可能失敗。
  2. 把相機牢牢固定,錄製和執行之間絕對不要移動。有位社群製作者的第一個策略只會在桌面上亂啄,原因有好幾個,其中之一是相機在錄製和測試之間輕微位移了。
  3. 把任務完整取景:物體、夾爪和目標至少要在一台相機中看得到。可以這樣測試:只看相機畫面,你自己能完成這項任務嗎?同一位社群製作者示範時只盯著相機畫面;如果你也要這樣做,請把電源放在伸手可及的地方。
  4. 同一位製作者把側面相機(抓取時看不清夾爪尖端)換成了放在前方相機旁邊的俯視相機,減少了遮擋;腕部相機在那篇貼文中只是下一步的計畫。如果要整天錄製,請在網路攝影機本身的設定中固定曝光與白平衡;LeRobot 的 RealSense 相機設定也接受 exposure、gain 和 white_balance。
  5. 在 Ubuntu 上使用兩台相同型號的網路攝影機時,USB 位址可能會對調,錄製可能會因相機錯誤而中斷。同一位製作者用 udev 規則依實體 USB 連接埠辨識每台相機,解決了這個問題,所以請讓每台相機一直插在同一個連接埠;否則請在每次重新開機後再執行一次相機查找工具。

錄製資料集

資料集使用 LeRobotDataset 格式,並上傳到 Hugging Face Hub。請建立免費帳號,在 Hugging Face 設定中建立具有寫入權限的權杖,然後登入,並把你的使用者名稱存進變數。請先把 HUGGINGFACE_TOKEN 設為你的權杖,或單獨執行 hf auth login,並在提示時貼上權杖。

登入 Hugging Face
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

先錄製五個回合來測試整個設置。使用與遙操作時相同的機器人 id、連接埠和相機設定,並用白話描述任務。

錄製資料集
lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_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

LeRobot 會在資料集名稱後面加上日期和時間,所以 ${HF_USER}/record-test 會存成 ${HF_USER}/record-test_YYYYMMDD_HHMMSS,之後的指令請使用這個完整名稱;可以用 ls ~/.cache/huggingface/lerobot/${HF_USER} 查到它,或加上 --dataset.no_stamp=true 保留你傳入的名稱。資料集存放在 ~/.cache/huggingface/lerobot,錄製結束時會推送到 Hub。從個人帳號推送的資料集可能是公開的,所以請到 Hub 上確認可見度,如果要設為私人,請加上 --dataset.private=true;加上 --dataset.push_to_hub=False 就只保留在本機。要繼續中斷的錄製,請用相同指令加上 --resume=true、帶有時間戳記的完整 --dataset.repo_id、設為資料集本機資料夾的 --dataset.root,以及設為追加回合數(不是總數)的 --dataset.num_episodes。

每個回合的時間與重置時間預設都是 60 秒(--dataset.episode_time_s 與 --dataset.reset_time_s),預設回合數為 50。錄製時用鍵盤控制流程,按鍵見下表。

第一個有用的資料集請選簡單的任務,例如從幾個不同位置抓起物體並放進箱子。至少錄製 50 個回合,每個位置約 10 個,相機和你的抓取方式要保持一致,變化要慢慢增加。失敗的回合要重錄。固定位置的 50 個回合只是起點;預期策略主要在你錄過的位置附近有效。LeRobot 會在每個保留下來的回合之後印出一行頻率,並在錄製結束時印出摘要。如果頻率遠低於 30 Hz 的目標,資料集仍然宣稱是 30 Hz,所以動作看起來會比實際更快。請找出拖慢迴圈的原因(文件範例中是讀取相機),並重錄受影響的回合,不要直接拿來訓練。

訓練前先檢查資料。在 Hugging Face 的 LeRobot 資料集視覺化工具中打開你的資料集,並在機器人上重播一個回合,確認動作能重現。重播會在沒有你操作的情況下移動機械臂,所以請清空工作區,讓機械臂從接近該回合第一個姿勢的位置開始,並把電源放在伸手可及的地方。

重播一個回合
lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --dataset.episode=0

橫向捲動以比較所有欄位。

按鍵動作
向右鍵或 n提前結束這個回合或重置時段,繼續下一步
向左鍵或 r捨棄目前的回合並重新錄製
Esc 或 q停止這次錄製:進行中的回合會先儲存,再編碼影片並上傳資料集(要捨棄該回合,請先按向左鍵或 r)

訓練 ACT 策略

ACT(Action Chunking Transformer)是 LeRobot 教學中使用的策略:它會自動適應資料集中記錄的伺服馬達與相機。硬體指南把輕量策略(ACT、VQ-BeT、TD-MPC)在批次大小 8 時的 GPU 記憶體需求列為約 2 到 6 GB,僅供參考。請用 NVIDIA GPU(cuda)訓練;在 Apple 晶片上,請把指令改成 --policy.device=mps,這需要 macOS 15 或更新版本(在 macOS 14 上 LeRobot 會退回 CPU,不適合訓練)。

用完整的資料集名稱開始訓練。

訓練 ACT 策略
lerobot-train \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --policy.type=act \
    --output_dir=outputs/train/act_so101_test \
    --job_name=act_so101_test \
    --policy.device=cuda \
    --trackio.enable=true \
    --policy.repo_id=${HF_USER}/my_policy \
    --steps=20000

沒有設定 --steps 時,訓練會跑 100,000 步,這通常比小型資料集需要的多:模仿學習一般在把資料看 5 到 10 遍之內就會收斂。50 個回合、每回合 30 秒、每秒 30 幀的資料集大約有 45,000 幀,批次大小 8 時每遍約 5,600 步,所以 5 到 10 遍大約是 28,000 到 56,000 步。上面的指令使用 --steps=20000,約三遍半,是簡短的第一次試跑;如果策略訓練不足,就調高它,而如果把它降得很低,也要把 --policy.scheduler_decay_steps 設得接近 --steps。硬體指南估計,ACT 在批次大小 8 時,於 RTX 3090 或 4090 上跑五遍約需 30 到 60 分鐘,在 L4 或 A10G 上約 1 到 2 小時,在 M1、M2 或 M3 Max 上以批次大小 4 約需 6 到 14 小時;指南稱這些數字僅供參考,實際執行可能相差約 50%。

沒有合適的 GPU 時,可以在 Google Colab 用 ACT 筆記本訓練,或先執行 hf auth login,再在同一條指令加上 Hugging Face Jobs 的規格,例如 --job.target=a10g-small。因為該指令啟用了 Trackio,Job 還需要 --trackio.space_id=<user>/<space>(加上 --trackio.private=true 可讓 Space 保持私人),或者移除 --trackio.enable=true。Jobs 按秒計費,除非設定 --job.timeout,否則上限為 48 小時;它會替你把只存在本機的資料集上傳到私人儲存庫,並在結束時推送訓練好的模型;hf jobs hardware 會列出可用規格。

檢查點會寫入 outputs/train/act_so101_test/checkpoints。中斷的訓練可以從最後一個檢查點繼續。因為訓練指令設定了 --policy.repo_id=${HF_USER}/my_policy,訓練好的模型會在結束時推送到該儲存庫(--policy.push_to_hub=false 可關閉,--policy.private=true 可設為私人);如果要自己上傳檢查點,請使用相同的儲存庫名稱,這樣 --policy.path=${HF_USER}/my_policy 才找得到。

繼續訓練並上傳模型
lerobot-train \
    --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
    --resume=true

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

LeRobot 的訓練腳本不會評估真機策略,所以請留一些回合不參與訓練,包括你沒有錄過的起始位置,再用它們測試策略。有位社群製作者用 50 個訓練回合(五個起始位置區域各 10 個)訓練,在這些區域的新回合上成功率為 60%,但在訓練時排除的區域的回合上只有 10%。把資料增加到每個區域 25 個回合後,同一位製作者達到了 90% 和 75%。這些樣本很小,並以該製作者自己的腳本評分。

在從臂上執行策略

用 lerobot-rollout 部署訓練好的策略。機器人 id、相機名稱、相機設定與任務文字,都要和錄製時相同;如果之後重新開機或重新插拔過,請再執行一次連接埠查找工具。--duration 的單位是秒;沒有設定它時,策略會一直執行到你停止為止。

在機械臂上執行策略
lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --task="Grab the black cube" \
    --duration=60

執行模式(strategy)決定執行期間會做什麼,見下表。會錄製資料集的模式,儲存庫名稱要在你的使用者名稱之後以 rollout_ 開頭,例如 --dataset.repo_id=${HF_USER}/rollout_so101_test;系統會再加上時間戳記。像 sentry 這類錄製模式使用 --dataset.single_task,而不是 --task;各模式的參數請見 LeRobot 文件。

在 LeRobot v0.5.x 及更早版本中沒有 lerobot-rollout,請依 v0.5.1 文件的說明,改用 lerobot-record。本教學的訓練參數適用於目前的版本。

第一次執行請用很短的時間(例如 15 秒)、清空工作區,並先想好要怎麼讓機械臂停下來;切斷電源會讓伺服馬達鬆開,所以沒有靠在東西上的機械臂可能會掉下來。如果機械臂在桌面上亂啄或伸過頭,先檢查設置再怪模型:校準 id 是否相同、相機位置是否沒動且名稱與解析度一致、光線是否相同,以及物體是否放在資料集涵蓋的位置。

橫向捲動以比較所有欄位。

模式作用
base自主執行,不錄製,適合快速測試
sentry持續錄製並自動上傳
highlight保留一個環形緩衝區,按鍵時存檔
dagger人在迴路中的資料收集
episodic逐回合錄製,回合之間有重置階段

用 LeKiwi 延伸製作

LeKiwi 是三輪移動底盤,上面載著一支 SO-101 從臂。由樹莓派(或其他 5 V 的電腦,USB 連接埠數量要夠接相機和伺服馬達控制板,LeKiwi 頁面寫的是兩個或更多)控制機器人,你在筆電上用主臂和鍵盤操控它。有線版本的所有程式都在筆電上執行,可以略過樹莓派的步驟。零件清單、列印檔與底盤組裝說明來自 Hugging Face LeKiwi 頁面連結的 LeKiwi 專案。

左右滑動可查看完整圖示。

LeKiwi:筆電透過網路遙控機器人,樹莓派負責驅動伺服馬達左側是筆電,接著主臂和鍵盤,並執行腳本 teleoperate.py。右側是 LeKiwi 機器人:樹莓派執行 lekiwi_host,並用 USB 連接伺服馬達控制板和相機。控制板驅動機械臂伺服馬達(ID 6 到 1)和輪子伺服馬達(ID 9、8、7)。筆電與樹莓派在同一個網路上透過 ZeroMQ 通訊,連接埠 5555 傳送指令,連接埠 5556 傳送觀測資料。在有線版本中,所有程式都在筆電上執行。筆電主臂(USB)鍵盤teleoperate.py執行範例腳本,並把 remote_ip設為樹莓派的位址。同一網路ZeroMQ5555, 5556LeKiwi 機器人樹莓派(主程式)lekiwi_host控制板相機機械臂伺服馬達ID 6 – 1輪子伺服馬達ID 9, 8, 7有線版本:沒有樹莓派,所有程式都在筆電上執行。
LeKiwi:筆電透過網路遙控機器人,樹莓派負責驅動伺服馬達

用鍵盤驅動底盤需要全域按鍵後端,所以它能在 X11、Windows 桌面,或已對終端機授予輸入監控權限的 macOS 上運作,但不能在 Wayland 或無頭機器上運作。

  1. 依照前面的章節做出兩支 SO-101 機械臂:一支裝在底盤上,一支當主臂。然後組裝底盤。
  2. 安裝 Raspberry Pi OS,啟用 SSH,並確認可以用 ssh <user>@<pi-ip> 登入。依照安裝一節的做法,在樹莓派和筆電上都安裝 LeRobot,再加上 LeKiwi 擴充,它會帶入伺服馬達驅動與 ZeroMQ。
    安裝 LeKiwi 擴充
    pip install 'lerobot[lekiwi]'
  3. 用一條指令設定所有伺服馬達:它會給機械臂伺服馬達設定 ID 6 到 1,輪子設定 9、8 和 7;輪子的 ID 必須與 LeKiwi 文件所示的安裝位置一致。LeKiwi 只使用一塊控制板。
    設定 LeKiwi 的伺服馬達 ID
    lerobot-setup-motors \
        --robot.type=lekiwi \
        --robot.port=/dev/ttyACM0
  4. 在樹莓派上校準從臂,在筆電上校準主臂。LeKiwi 頁面對主臂寫的是 --teleop.type=so100_leader;請查看 examples/lekiwi/teleoperate.py 建立的是哪個主臂類別,並用相同的類型和 --teleop.id 來校準。輪子的伺服馬達不需要校準。
    校準 LeKiwi 機械臂
    lerobot-calibrate \
        --robot.type=lekiwi \
        --robot.id=my_awesome_kiwi
  5. 在樹莓派上先啟用 LeRobot 環境,再啟動主程式。它預設 30 秒後停止,除非你調高 --host.connection_time_s(例如設為 600),較長的操作,例如錄製資料,就需要這樣做。
    在樹莓派上啟動 LeKiwi 主程式
    python -m lerobot.robots.lekiwi.lekiwi_host \
        --robot.id=my_awesome_kiwi \
        --host.connection_time_s=600
  6. 在筆電上編輯 LeRobot 原始碼儲存庫中的 examples/lekiwi/teleoperate.py:把 remote_ip 設為樹莓派的位址,並把主臂的 port 和 id 設成你自己的值,然後執行它。在 record.py 中還要設定 HF_REPO_ID 和 TASK_DESCRIPTION;在 replay.py 中要設定 remote_ip、port、資料集 id 和回合索引。要執行訓練好的策略,LeKiwi 頁面使用 examples/lekiwi/evaluate.py(設定 remote_ip、port 和模型);上一節的 lerobot-rollout 指令是為獨立的 SO-101 寫的。速度有三檔,用 R 和 F 切換:快速 0.3 m/s 與 90°/s,中速 0.2 m/s 與 60°/s,慢速 0.1 m/s 與 30°/s。

橫向捲動以比較所有欄位。

按鍵動作
W前進
A向左移動
S後退
D向右移動
Z向左轉
X向右轉
R加快速度
F放慢速度

疑難排解檢查表

許多問題都出在電源、線材、連接埠,或是錄製與執行之間設置有了變動。改程式之前,先逐項查這張表。

關於 LeRobot 本身的問題,Hugging Face 文件連結了它的 Discord 社群。關於本店供應的零件,請使用 WhatsApp 按鈕或支援表單。

橫向捲動以比較所有欄位。

症狀檢查或處理
找不到連接埠,或存取被拒絕控制板接上電源與 USB 線後,再執行一次連接埠查找工具。在 Linux 上用 sudo chmod 666 開放該連接埠的權限。重新開機或重新插拔後連接埠可能會改變,所以請再執行一次連接埠查找工具。
ID 設定腳本找不到伺服馬達檢查電源、USB 線和 3 針線。只能接著正在設定的那顆伺服馬達。使用 Waveshare 控制板時,兩個跳線帽必須放在 B 通道(USB)。
重複使用的伺服馬達找不到或沒有回應如 SO-101 指南所述,它們的 ID 和鮑率很可能和新機器人不一致。重新執行伺服馬達設定,一次只接一顆。
校準失敗,或校準後機械臂動作不對再校準一次:先把每個關節放在活動範圍的中間並按 Enter,再讓每個關節轉過完整的活動範圍。有位社群製作者沒有把每個關節都放到中間,結果歸零偏移是錯的。之後請使用相同的機器人 id。
相機斷線或索引改變每次重新開機或重新插拔後,都再執行一次相機查找工具。兩台相同的網路攝影機在 Linux 上可能對調 USB 位址;有位社群製作者用依實體 USB 連接埠辨識的 udev 規則解決了這個問題。
錄製的按鍵沒有反應請在互動式終端機中啟動指令,並讓視窗保持焦點;字母鍵 n、r、q 和方向鍵、Esc 鍵一樣有效。只有像 LeKiwi 那樣用鍵盤驅動機器人,才需要 X11、Windows 桌面或 macOS 權限。
訓練找不到資料集請使用完整的資料集名稱,包含日期與時間後綴。
錄製的頻率遠低於 30 Hz請看錄製時印出的頻率行。如果讀取相機佔了大部分時間,請降低解析度或減少相機數量,然後重新錄製:策略在執行時預期相同的相機設置,而遠低於 30 Hz 錄下的回合,會被當成以 30 Hz 錄製來儲存。
策略在桌面上亂啄或伸過頭把校準 id、相機位置、名稱與光線,和錄製時的情況逐項比對,並確認物體的起始位置在資料集中有範例。
LeKiwi 連不上,或主程式在 30 秒後停止用 hostname -I 找出樹莓派的位址,從筆電 ping 它,並測試 ssh <user>@<pi-ip>;必要時在 sudo raspi-config 中啟用 SSH。除非設定 --host.connection_time_s,否則主程式會在 30 秒後停止。

專案資料來源

聯絡我們