你要做出什麼,以及需要準備什麼
LeRobot 是 Hugging Face 的開源機器人函式庫,用同一套指令驅動機器人、錄製示範、訓練策略和執行策略。SO-101 是它的旗艦機械臂:你用手移動主臂,從臂跟著動作,錄下的動作與相機畫面再讓神經網路學會獨立重複這項任務。
整個流程分七個階段:備齊零件並安裝軟體、為每顆伺服馬達設定 ID、組裝兩支機械臂、校準、接上相機遙操作、錄製資料集,最後訓練並執行策略。最後一個製作章節加上 LeKiwi 移動底盤,之後是疑難排解檢查表。
左右滑動可查看完整圖示。
你需要兩支機械臂(零件見下一節)、每支臂各一塊 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 伺服馬達的控制板上;請在每個電源上標明電壓和它所屬的機械臂。
左右滑動可查看完整圖示。
使用 PLA+ 列印:0.4 mm 噴嘴搭配 0.2 mm 層高(或 0.6 mm 噴嘴搭配 0.4 mm 層高),填充率 15%。每支機械臂的零件都在同一個檔案中,擺放方向已盡量減少支撐;水平方向的螺絲孔內不要有支撐。先列印 Gauge Zero 與 Gauge Tight 這兩個測試件,拿去和伺服馬達比對;如果 Gauge Zero 無法像專案影片中那樣嵌合,請先調整印表機設定並重新列印,再列印機械臂零件。
準備好 #0 和 #1 號十字螺絲起子,測試前先把兩個底座用桌夾固定在桌上。我們供應的相關零件連結在下方。
橫向捲動以比較所有欄位。
| 關節 | 伺服馬達 ID | 主臂齒輪比 | 從臂齒輪比 |
|---|---|---|---|
| 肩部旋轉 | 1 | 1/191 | 1/345 |
| 肩部抬升 | 2 | 1/345 | 1/345 |
| 肘部彎曲 | 3 | 1/191 | 1/345 |
| 腕部彎曲 | 4 | 1/147 | 1/345 |
| 腕部旋轉 | 5 | 1/147 | 1/345 |
| 夾爪 | 6 | 1/147 | 1/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 則是訓練工具。
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 會把這兩項設定一次寫入每顆伺服馬達的記憶體,所以請在組裝前完成,並且一次只接一顆伺服馬達。從別的機器人拆下來的伺服馬達很可能也需要重設。
左右滑動可查看完整圖示。
用 USB 把一塊控制板接到電腦並接上電源,執行連接埠查找工具。依提示只拔掉這塊控制板的 USB 線,再按 Enter,腳本會印出連接埠,例如 Linux 上的 /dev/ttyACM0、macOS 上的 /dev/tty.usbmodem… 或 Windows 上的 COM3。把線插回去,再對第二塊控制板重複同樣步驟。在 Linux 上可能需要對每個連接埠用 sudo chmod 666 開放存取權限(例如 /dev/ttyACM0 與 /dev/ttyACM1)。
lerobot-find-port先對從臂執行設定腳本,再對主臂執行,兩者各用自己的連接埠。腳本一次只會指名一顆伺服馬達,所以執行前請先讀完下面的步驟。
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0主臂改用遙操作裝置(teleop)的參數,而不是機器人(robot)的參數。每次提示時,請依零件一節表格中該關節所列的齒輪比挑選伺服馬達(主臂:肩部旋轉與肘部彎曲為 1/191,肩部抬升為 1/345,腕部彎曲、腕部旋轉與夾爪為 1/147),並在腳本回報某顆伺服馬達設定完成後,立刻標出它的 ID。
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- 腳本一次只會點名一顆伺服馬達,從夾爪(ID 6)開始,到肩部旋轉(ID 1)結束。只把被點名的那顆接到控制板上,它不能和其他任何伺服馬達串接。
- 按 Enter。腳本回報 ID 已設定後,把這顆伺服馬達的線從控制板拔下,接上下一顆被點名的伺服馬達,再按一次 Enter。
- 每次按 Enter 之前,先檢查電源線、USB 線和 3 針線。腳本若回報錯誤,先檢查這些線材;使用 Waveshare 控制板時,兩個跳線帽都必須放在 B 通道(USB)。
- 腳本結束後,依序把伺服馬達串接起來,並把肩部旋轉伺服馬達(ID 1)接到控制板。
左右滑動可查看完整圖示。
逐顆設定伺服馬達 ID,再依序串接伺服馬達
組裝主臂與從臂
兩支機械臂的大部分列印零件通用,組裝順序也相同(腕部旋轉的零件不同,主臂有把手與扳機,從臂則是可動的夾爪):底座與肩部、上臂、前臂、腕部,最後從臂裝夾爪,主臂則裝把手與扳機。Hugging Face 在 SO-101 頁面為每個關節提供了短影片,請對照影片和這些說明一起做。先清除列印零件上的所有支撐材料,並在每顆伺服馬達封入結構之前先插上一條 3 針線。
- 關節 1,肩部旋轉:在伺服馬達兩側裝上舵盤,上方的舵盤用一顆 M3×6 螺絲固定(下方的舵盤不需要螺絲)。把伺服馬達放進底座,用四顆 M2×6 螺絲鎖緊,再套上第一個伺服馬達固定座並用兩顆 M2×6 固定,肩部零件上方與下方各用四顆 M3×6 鎖上,最後裝上肩部伺服馬達固定座。
- 關節 2,肩部抬升:裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),從上方滑入伺服馬達,用四顆 M2×6 鎖緊,再把上臂用 M3×6 鎖上,每側各四顆。
- 關節 3,肘部:裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),放入 3 號伺服馬達並用四顆 M2×6 鎖緊,再把前臂接上,每側用四顆 M3×6 固定。
- 關節 4,腕部彎曲:裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),套上 4 號伺服馬達固定座,滑入 4 號伺服馬達並用四顆 M2×6 鎖緊。
- 關節 5,腕部旋轉:把 5 號伺服馬達放進腕部固定座,前方用兩顆 M2×6 固定,只裝一個舵盤並用一顆 M3×6 螺絲鎖緊,再依官方關節 5 影片的做法,用 M3×6 螺絲把腕部固定到 4 號伺服馬達(文字版指南寫的是兩側各四顆)。
- 從臂夾爪:把夾爪接到腕部伺服馬達的舵盤,用四顆 M3×6 鎖緊;裝入夾爪伺服馬達,每側用兩顆 M2×6 固定,裝好兩個舵盤,並用一顆 M3×6 螺絲鎖緊上方的舵盤(下方的舵盤不需要螺絲),再依官方夾爪影片的做法,用 M3×6 螺絲鎖上爪片(文字版指南寫的是兩側各四顆)。
- 主臂把手:把主臂固定座裝到腕部,用四顆 M3×6 鎖緊,把手用一顆 M2×6 固定在上面,裝入 6 號伺服馬達,也就是扳機伺服馬達(官方指南稱之為夾爪伺服馬達),每側用兩顆 M2×6 固定,並以一顆 M3×6 螺絲裝上舵盤,最後用四顆 M3×6 裝上扳機。
- 接上電源之前,先用手慢慢把每個關節轉過整個活動範圍,轉到極限位置時絕不要硬扳;它應該順暢轉動,不會刮擦。在把伺服馬達封入結構之前,先標出每顆伺服馬達的 ID,並用桌夾把兩個底座固定在桌上。
校準兩支機械臂
校準會記錄每個關節的活動範圍,讓主臂和從臂在相同的實際姿勢下回報相同的數值,也讓在一台機器人上訓練出的策略可以在另一台上執行。每支機械臂校準一次即可;更換或改動硬體後,或 LeRobot 提示找不到校準檔時,再校準一次。重新校準之前錄製的資料和訓練的策略,用的是舊的校準。
先校準從臂。腳本會要求你把每個關節移到活動範圍的中間位置並按 Enter,接著把每個關節轉過完整的活動範圍,所有關節都轉完後再按一次 Enter。請給每支機械臂一個獨一無二的 id,這個名字就是它的校準檔名稱。本教學的指令以 /dev/ttyACM0 代表從臂、/dev/ttyACM1 代表主臂作為範例:請換成你自己找到的連接埠,並且不要把兩支機械臂搞反。
左右滑動可查看完整圖示。
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 幀就夠了,錄製與訓練也會比較快。
左右滑動可查看完整圖示。
- 用柔和的漫射光把場景照亮。避免陽光直射、強烈反光和會移動的陰影:錄製與執行時的光線不一樣,策略就可能失敗。
- 把相機牢牢固定,錄製和執行之間絕對不要移動。有位社群製作者的第一個策略只會在桌面上亂啄,原因有好幾個,其中之一是相機在錄製和測試之間輕微位移了。
- 把任務完整取景:物體、夾爪和目標至少要在一台相機中看得到。可以這樣測試:只看相機畫面,你自己能完成這項任務嗎?同一位社群製作者示範時只盯著相機畫面;如果你也要這樣做,請把電源放在伸手可及的地方。
- 同一位製作者把側面相機(抓取時看不清夾爪尖端)換成了放在前方相機旁邊的俯視相機,減少了遮擋;腕部相機在那篇貼文中只是下一步的計畫。如果要整天錄製,請在網路攝影機本身的設定中固定曝光與白平衡;LeRobot 的 RealSense 相機設定也接受
exposure、gain和white_balance。 - 在 Ubuntu 上使用兩台相同型號的網路攝影機時,USB 位址可能會對調,錄製可能會因相機錯誤而中斷。同一位製作者用 udev 規則依實體 USB 連接埠辨識每台相機,解決了這個問題,所以請讓每台相機一直插在同一個連接埠;否則請在每次重新開機後再執行一次相機查找工具。
錄製資料集
資料集使用 LeRobotDataset 格式,並上傳到 Hugging Face Hub。請建立免費帳號,在 Hugging Face 設定中建立具有寫入權限的權杖,然後登入,並把你的使用者名稱存進變數。請先把 HUGGINGFACE_TOKEN 設為你的權杖,或單獨執行 hf auth login,並在提示時貼上權杖。
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=trueLeRobot 會在資料集名稱後面加上日期和時間,所以 ${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,不適合訓練)。
用完整的資料集名稱開始訓練。
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_modelLeRobot 的訓練腳本不會評估真機策略,所以請留一些回合不參與訓練,包括你沒有錄過的起始位置,再用它們測試策略。有位社群製作者用 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 專案。
左右滑動可查看完整圖示。
用鍵盤驅動底盤需要全域按鍵後端,所以它能在 X11、Windows 桌面,或已對終端機授予輸入監控權限的 macOS 上運作,但不能在 Wayland 或無頭機器上運作。
- 依照前面的章節做出兩支 SO-101 機械臂:一支裝在底盤上,一支當主臂。然後組裝底盤。
- 安裝 Raspberry Pi OS,啟用 SSH,並確認可以用
ssh <user>@<pi-ip>登入。依照安裝一節的做法,在樹莓派和筆電上都安裝 LeRobot,再加上 LeKiwi 擴充,它會帶入伺服馬達驅動與 ZeroMQ。安裝 LeKiwi 擴充 pip install 'lerobot[lekiwi]' - 用一條指令設定所有伺服馬達:它會給機械臂伺服馬達設定 ID 6 到 1,輪子設定 9、8 和 7;輪子的 ID 必須與 LeKiwi 文件所示的安裝位置一致。LeKiwi 只使用一塊控制板。
設定 LeKiwi 的伺服馬達 ID lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - 在樹莓派上校準從臂,在筆電上校準主臂。LeKiwi 頁面對主臂寫的是
--teleop.type=so100_leader;請查看examples/lekiwi/teleoperate.py建立的是哪個主臂類別,並用相同的類型和--teleop.id來校準。輪子的伺服馬達不需要校準。校準 LeKiwi 機械臂 lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - 在樹莓派上先啟用 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 - 在筆電上編輯 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 秒後停止。 |