Bạn sẽ xây dựng gì và cần chuẩn bị gì
LeRobot là thư viện robot mã nguồn mở của Hugging Face. Cùng một bộ lệnh dùng để điều khiển robot, ghi lại các thao tác mẫu, huấn luyện chính sách (policy) và chạy chính sách đó. SO-101 là tay máy chủ lực của thư viện: bạn di chuyển tay leader bằng tay, tay follower sao chép theo, và chuyển động được ghi lại cùng hình ảnh camera sẽ dạy một mạng nơ-ron tự lặp lại tác vụ.
Quy trình gồm bảy giai đoạn: chuẩn bị linh kiện và cài phần mềm, gán ID cho từng động cơ, lắp ráp cả hai tay, hiệu chuẩn, điều khiển từ xa với camera, ghi bộ dữ liệu, rồi huấn luyện và chạy chính sách. Phần xây dựng cuối cùng bổ sung đế di động LeKiwi, tiếp theo là một danh sách kiểm tra khi gặp sự cố.
Vuốt ngang để xem toàn bộ hình.
Bạn cần hai tay máy (linh kiện ở phần sau), một bo mạch điều khiển servo bus qua USB và một bộ nguồn cho mỗi tay, một máy tính cài Python 3.12 trở lên, hai camera USB (các lệnh trong hướng dẫn này dùng hai camera), một tài khoản Hugging Face miễn phí để lưu bộ dữ liệu và checkpoint, và một GPU để huấn luyện. GPU cấp laptop là đủ cho chính sách ACT dùng ở đây, và GPU thuê cũng dùng được.
Chúng tôi biên soạn hướng dẫn này từ tài liệu chính thức và các báo cáo lắp ráp của cộng đồng, và chưa thử nghiệm thực tế từng bước trên mọi phiên bản phần cứng. Các hướng dẫn cũ gọi control_robot.py không áp dụng cho 0.7.0, phiên bản dùng các lệnh lerobot-*.
Linh kiện, in 3D và nguồn điện
Dự án SO-101 công bố danh mục vật tư và các tệp in, và trang SO-101 của Hugging Face có liên kết tới cả hai. Một cặp tay leader và follower hoàn chỉnh cần 12 servo Feetech STS3215, hai bo mạch điều khiển, hai bộ nguồn, hai cáp USB-C và kẹp bàn. Việc lắp ráp dùng vít M2×6 và M3×6; danh mục vật tư của dự án không liệt kê chúng, vì vậy hãy kiểm tra những gì đi kèm servo hoặc bộ kit của bạn. Chi tiết in sẵn và bộ kit hoàn chỉnh cũng được bán.
Tay follower dùng sáu servo với tỷ số truyền 1/345. Tay leader dùng ba tỷ số truyền khác nhau, nhờ đó vừa tự giữ được trọng lượng của mình vừa di chuyển chỉ cần lực nhỏ.
Chọn bộ nguồn phù hợp với servo. Servo STS3215 7,4 V có mô-men xoắn kẹt trục 16,5 kg·cm ở 6 V (thấp hơn một chút với nguồn 5 V) và thường được chạy bằng nguồn 5 V. Tay follower có thể dùng servo 12 V (30 kg·cm) để mạnh hơn, nhưng khi đó cần nguồn 12 V có dòng định mức từ 5 A trở lên; tay leader luôn dùng servo 7,4 V. Tuyệt đối không nối nguồn 12 V với bo mạch đang gắn servo 7,4 V; hãy ghi trên mỗi bộ nguồn điện áp của nó và tay máy mà nó dành cho.
Vuốt ngang để xem toàn bộ hình.
In bằng PLA+ với đầu phun 0,4 mm, độ dày lớp 0,2 mm (hoặc đầu phun 0,6 mm với độ dày lớp 0,4 mm) và mật độ infill 15%. Các chi tiết của mỗi tay được cung cấp dưới dạng một tệp duy nhất, đã định hướng để cần ít support; không để support trong các lỗ vít nằm ngang. Hãy in trước hai chi tiết thử Gauge Zero và Gauge Tight rồi đối chiếu với một servo; nếu Gauge Zero không vừa như trong video của dự án, hãy chỉnh lại thiết lập máy in và in lại trước khi in các tay máy.
Chuẩn bị tua vít Phillips #0 và #1, và kẹp từng đế vào bàn trước khi thử. Các linh kiện chúng tôi cung cấp cho bản dựng này được liên kết bên dưới.
Cuộn ngang để so sánh tất cả các cột.
| Khớp | ID động cơ | Tỷ số truyền của leader | Tỷ số truyền của follower |
|---|---|---|---|
| Xoay vai | 1 | 1/191 | 1/345 |
| Nâng vai | 2 | 1/345 | 1/345 |
| Gập khuỷu tay | 3 | 1/191 | 1/345 |
| Gập cổ tay | 4 | 1/147 | 1/345 |
| Xoay cổ tay | 5 | 1/147 | 1/345 |
| Bộ kẹp | 6 | 1/147 | 1/345 |
Cài LeRobot và hỗ trợ động cơ
LeRobot 0.7.0 cần Python 3.12 trở lên. Tạo một môi trường riêng bằng conda (từ miniforge) hoặc uv, và kích hoạt môi trường đó ở mỗi terminal mới. Cần có ffmpeg để xử lý video trên hầu hết các nền tảng (trên macOS Intel và Linux ARM 32-bit, LeRobot chuyển sang dùng PyAV và bạn có thể bỏ qua nó); gói conda hoạt động với mọi phiên bản PyTorch.
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forgeCài LeRobot từ PyPI cùng các gói bổ sung bạn cần. core_scripts thêm những gì việc ghi, phát lại và hiệu chuẩn sử dụng, feetech thêm hỗ trợ servo STS3215, và training thêm các công cụ huấn luyện.
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'Lưu ý theo nền tảng: trên Apple silicon, PyTorch cần macOS 14 trở lên, và macOS 15 trở lên để tăng tốc GPU (MPS). Để dùng GPU NVIDIA trên Linux, các bản PyTorch mặc định cần trình điều khiển 580.65 trở lên; với trình điều khiển cũ hơn, hãy cài trước một bản PyTorch CUDA phù hợp và lấy torchcodec từ chỉ mục CPU (xem trang cài đặt của Hugging Face). Trong WSL, cài thêm evdev (conda install evdev -c conda-forge, hoặc với uv thì sudo apt install libevdev-dev rồi uv pip install evdev). Với PyTorch 2.10 trở lên, bạn có thể dùng ffmpeg của hệ thống thay cho bản conda.
Tìm cổng và đặt ID động cơ
Các servo STS3215 mới thường xuất xưởng với ID 1, và bộ điều khiển cùng mọi servo phải dùng chung một tốc độ baud. LeRobot ghi cả hai giá trị này vào bộ nhớ của từng servo một lần, vì vậy hãy làm bước này trước khi lắp ráp và chỉ kết nối từng servo một. Servo tái sử dụng từ robot khác có lẽ cũng cần làm bước này.
Vuốt ngang để xem toàn bộ hình.
Kết nối một bo mạch điều khiển với máy tính qua USB, cấp nguồn cho bo, rồi chạy công cụ tìm cổng. Khi được yêu cầu, chỉ rút cáp USB của bo đó và nhấn Enter; script sẽ in ra cổng, chẳng hạn /dev/ttyACM0 trên Linux, /dev/tty.usbmodem… trên macOS hoặc COM3 trên Windows. Cắm lại cáp, rồi lặp lại với bo thứ hai. Trên Linux, bạn có thể phải cấp quyền truy cập bằng sudo chmod 666 cho từng cổng (ví dụ /dev/ttyACM0 và /dev/ttyACM1).
lerobot-find-portChạy script thiết lập cho tay follower, rồi cho tay leader, mỗi lần với cổng riêng của nó. Script nêu tên từng động cơ một, vì vậy hãy đọc các bước dưới đây trước khi chạy.
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0Tay leader dùng các tùy chọn dành cho thiết bị điều khiển từ xa (teleoperator) thay cho các tùy chọn của robot. Ở mỗi lần script nêu tên, hãy lấy động cơ có tỷ số truyền ghi cho khớp đó trong bảng ở phần linh kiện (trên tay leader là 1/191 cho xoay vai và gập khuỷu tay, 1/345 cho nâng vai và 1/147 cho gập cổ tay, xoay cổ tay và bộ kẹp), và đánh dấu ID lên từng động cơ ngay khi script báo đã đặt xong.
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- Script nêu tên từng động cơ một, bắt đầu từ bộ kẹp (ID 6) và kết thúc ở khớp xoay vai (ID 1). Chỉ kết nối đúng động cơ đó với bo mạch điều khiển; không được nối chuỗi với bất kỳ động cơ nào khác.
- Nhấn Enter. Khi script báo đã đặt xong ID, rút cáp của động cơ đó khỏi bo, kết nối động cơ tiếp theo mà script nêu và nhấn Enter lần nữa.
- Kiểm tra cáp nguồn, cáp USB và cáp 3 chân trước mỗi lần nhấn Enter. Nếu script báo lỗi, hãy kiểm tra các cáp này trước, và trên bo Waveshare cả hai jumper phải nằm ở kênh B (USB).
- Khi script hoàn tất, nối chuỗi các động cơ theo thứ tự và kết nối động cơ xoay vai (ID 1) với bo mạch điều khiển.
Vuốt ngang để xem toàn bộ hình.
Đặt ID động cơ từng servo một, rồi nối chuỗi các servo theo thứ tự
Lắp ráp tay leader và tay follower
Hai tay dùng chung phần lớn các chi tiết in và được lắp theo cùng một thứ tự (chi tiết xoay cổ tay khác nhau, và tay leader có tay cầm và cò ở chỗ tay follower có ngàm kẹp chuyển động): đế và vai, cánh tay trên, cẳng tay, cổ tay, sau đó là bộ kẹp ở tay follower hoặc tay cầm và cò ở tay leader. Hugging Face đăng một video ngắn cho từng khớp trên trang SO-101 của mình; hãy xem video song song với các ghi chú này. Trước hết hãy gỡ toàn bộ support khỏi các chi tiết in, và cắm cáp 3 chân vào từng servo trước khi bạn đóng servo vào trong.
- Khớp 1, xoay vai: lắp cả hai tay servo vào động cơ và cố định tay servo phía trên bằng một vít M3×6 (tay servo phía dưới không cần vít). Đặt động cơ vào đế bằng bốn vít M2×6, trượt giá giữ động cơ đầu tiên vào bằng hai vít M2×6, gắn vai bằng bốn vít M3×6 ở phía trên và bốn vít ở phía dưới, rồi thêm giá giữ động cơ vai.
- Khớp 2, nâng vai: lắp cả hai tay servo và cố định tay servo phía trên bằng một vít M3×6 (tay servo phía dưới không cần), trượt động cơ vào từ phía trên, cố định bằng bốn vít M2×6, rồi gắn cánh tay trên bằng bốn vít M3×6 ở mỗi bên.
- Khớp 3, khuỷu tay: lắp cả hai tay servo và cố định tay servo phía trên bằng một vít M3×6 (tay servo phía dưới không cần), đưa động cơ 3 vào bằng bốn vít M2×6 và nối cẳng tay với nó bằng bốn vít M3×6 ở mỗi bên.
- Khớp 4, gập cổ tay: lắp cả hai tay servo và cố định tay servo phía trên bằng một vít M3×6 (tay servo phía dưới không cần), trượt giá giữ động cơ 4 vào, trượt động cơ 4 vào và cố định bằng bốn vít M2×6.
- Khớp 5, xoay cổ tay: đặt động cơ 5 vào giá giữ cổ tay bằng hai vít M2×6 ở phía trước, lắp một tay servo đơn bằng một vít M3×6, rồi cố định cổ tay vào động cơ 4 bằng các vít M3×6 như trong video Khớp 5 chính thức (hướng dẫn bằng văn bản ghi là bốn vít ở cả hai bên).
- Bộ kẹp của tay follower: gắn bộ kẹp vào tay servo của động cơ cổ tay bằng bốn vít M3×6, lắp động cơ bộ kẹp bằng hai vít M2×6 ở mỗi bên, lắp cả hai tay servo và cố định tay servo phía trên bằng một vít M3×6 (tay servo phía dưới không cần), rồi cố định ngàm kẹp bằng các vít M3×6 như trong video bộ kẹp chính thức (hướng dẫn bằng văn bản ghi là bốn vít ở cả hai bên).
- Tay cầm của tay leader: gắn giá giữ leader vào cổ tay bằng bốn vít M3×6, cố định tay cầm vào đó bằng một vít M2×6, lắp động cơ 6, tức động cơ cò (tài liệu chính thức gọi là động cơ bộ kẹp), bằng hai vít M2×6 ở mỗi bên và một tay servo bằng một vít M3×6, rồi gắn cò bằng bốn vít M3×6.
- Trước khi cấp nguồn cho bất cứ thứ gì, hãy dùng tay xoay chậm từng khớp qua toàn bộ biên độ của nó và không bao giờ ép nó vượt quá điểm chặn; khớp phải chuyển động mà không bị cọ. Ghi ID lên từng động cơ trước khi bạn đóng nó vào trong, và kẹp cả hai đế vào bàn.
Hiệu chuẩn cả hai tay
Hiệu chuẩn ghi lại biên độ của từng khớp để tay leader và tay follower báo về cùng các giá trị ở cùng một tư thế vật lý. Nó cũng cho phép chính sách được huấn luyện trên một robot chạy được trên robot khác. Hãy thực hiện một lần cho mỗi tay, và thực hiện lại sau khi thay đổi phần cứng hoặc khi LeRobot báo thiếu hiệu chuẩn. Các bản ghi và chính sách được tạo trước khi hiệu chuẩn lại đã dùng hiệu chuẩn cũ.
Hiệu chuẩn tay follower trước. Script yêu cầu bạn đưa mọi khớp về giữa biên độ của nó rồi nhấn Enter, sau đó di chuyển từng khớp qua toàn bộ biên độ chuyển động và nhấn Enter lần nữa khi mọi khớp đã đi qua hết. Đặt cho mỗi tay một id riêng; tên đó là nhãn của tệp hiệu chuẩn. Các lệnh trong hướng dẫn này dùng /dev/ttyACM0 cho tay follower và /dev/ttyACM1 cho tay leader làm ví dụ: hãy thay chúng bằng các cổng bạn đã tìm được, và đừng đổi chỗ hai tay.
Vuốt ngang để xem toàn bộ hình.
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_armSau đó hiệu chuẩn tay leader bằng các thao tác tương tự.
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_armHãy dùng cùng id đó trong mọi lệnh sau; LeRobot dựa vào đó để tìm tệp hiệu chuẩn, được lưu mặc định trong ~/.cache/huggingface/lerobot/calibration. Hãy sao lưu tệp này và đừng để nó trong các thư mục tạm: một người lắp ráp trong cộng đồng đã mất các tệp hiệu chuẩn sau một lần tắt rồi bật lại nguồn, rồi hiệu chuẩn lại mà không đưa mọi khớp về giữa biên độ, khiến một số khớp bị homing offset sai.
Điều khiển từ xa tay follower bằng tay leader
Điều khiển từ xa (teleoperation) nối hai tay với nhau: tay follower sao chép tay leader. Nếu thiếu hiệu chuẩn, lệnh sẽ khởi động quy trình hiệu chuẩn trước. Hãy bắt đầu bằng các chuyển động nhỏ và chậm, tránh xa các khớp của tay follower, và để bộ nguồn trong tầm với.
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_armTiếp theo là thêm camera. Liệt kê camera bằng công cụ tìm camera, công cụ này in ra mã định danh của từng camera và lưu một khung hình thử của mỗi camera vào outputs/captured_images; hãy mở các khung hình đó để biết chỉ số nào ứng với camera nào. Các chỉ số có thể thay đổi sau khi khởi động lại hoặc khi bạn cắm lại camera.
lerobot-find-cameras opencvĐiều khiển từ xa lần nữa với camera đã gắn và xem trực tiếp trong Rerun. Tên camera bạn chọn ở đây, chẳng hạn top và wrist, về sau trở thành khóa của bộ dữ liệu, vì vậy từ giờ hãy dùng đúng các tên và thiết lập này.
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Đặt camera để chính sách có thể học
Chính sách chỉ nhìn thấy hình ảnh camera và vị trí các khớp, nên bố trí camera tốt quan trọng hơn độ phân giải cao. 640×480 ở 30 fps là đủ cho hầu hết tác vụ và giữ cho việc ghi và huấn luyện nhanh.
Vuốt ngang để xem toàn bộ hình.
- Chiếu sáng đều cho cảnh bằng ánh sáng khuếch tán. Tránh ánh nắng trực tiếp, phản chiếu mạnh và bóng đổ di chuyển: ánh sáng khác nhau giữa lúc ghi và lúc chạy có thể khiến chính sách thất bại.
- Cố định camera thật chắc và không bao giờ di chuyển chúng giữa lúc ghi và lúc chạy. Chính sách đầu tiên của một người lắp ráp trong cộng đồng chỉ biết mổ xuống mặt bàn, và một trong nhiều nguyên nhân là camera đã xê dịch nhẹ giữa lúc ghi và lúc thử.
- Căn khung hình theo tác vụ: vật thể, bộ kẹp và đích đến đều phải nhìn thấy được trong ít nhất một camera. Một phép thử tốt là xem bạn có tự làm được tác vụ chỉ dựa vào hình ảnh camera hay không. Chính người lắp ráp đó đã thao tác mẫu khi chỉ nhìn vào hình ảnh camera; nếu bạn thử cách này, hãy để bộ nguồn trong tầm với.
- Cũng người lắp ráp đó đã thay camera bên hông, vốn có tầm nhìn tới đầu bộ kẹp kém khi gắp, bằng một camera đặt phía trên cạnh camera phía trước, nhờ vậy giảm bị che khuất; camera gắn ở cổ tay trong bài viết đó chỉ xuất hiện như một bước tiếp theo. Nếu bạn ghi suốt cả ngày, hãy cố định độ phơi sáng và cân bằng trắng trong phần cài đặt riêng của webcam; cấu hình camera RealSense của LeRobot cũng nhận
exposure,gainvàwhite_balance. - Với hai webcam giống hệt nhau trên Ubuntu, địa chỉ USB có thể bị hoán đổi và quá trình ghi có thể dừng với lỗi camera. Cũng người lắp ráp đó đã khắc phục bằng quy tắc udev nhận diện từng camera theo cổng USB vật lý của nó, vì vậy hãy luôn cắm mỗi camera vào cùng một cổng; nếu không, hãy chạy lại công cụ tìm camera sau mỗi lần khởi động lại.
Ghi bộ dữ liệu
Bộ dữ liệu dùng định dạng LeRobotDataset và được tải lên Hugging Face Hub. Tạo một tài khoản miễn phí, tạo một token có quyền ghi trong phần cài đặt Hugging Face, rồi đăng nhập và lưu tên người dùng của bạn trong một biến. Hãy đặt HUGGINGFACE_TOKEN thành token của bạn trước, hoặc chạy riêng hf auth login rồi dán token khi được hỏi.
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_USERTrước tiên hãy ghi năm episode để kiểm tra thiết lập. Dùng cùng id robot, cổng và thiết lập camera như khi điều khiển từ xa, và mô tả tác vụ bằng lời đơn giản.
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 nối thêm ngày và giờ vào tên bộ dữ liệu, nên ${HF_USER}/record-test được lưu thành ${HF_USER}/record-test_YYYYMMDD_HHMMSS. Hãy dùng tên đầy đủ đó trong các lệnh sau; tìm nó bằng ls ~/.cache/huggingface/lerobot/${HF_USER}, hoặc thêm --dataset.no_stamp=true để giữ nguyên tên bạn đã truyền vào. Bộ dữ liệu được lưu trong ~/.cache/huggingface/lerobot và được đẩy lên Hub khi kết thúc ghi. Bộ dữ liệu đẩy lên từ tài khoản cá nhân có thể ở chế độ công khai, vì vậy hãy kiểm tra chế độ hiển thị của nó trên Hub và thêm --dataset.private=true nếu muốn để riêng tư; thêm --dataset.push_to_hub=False để giữ nó ở máy. Để tiếp tục một phiên bị dừng, hãy chạy lại lệnh với --resume=true, --dataset.repo_id đầy đủ có dấu thời gian, --dataset.root đặt thành thư mục cục bộ của bộ dữ liệu, và --dataset.num_episodes đặt thành số episode bổ sung, không phải tổng số.
Thời gian mỗi episode và thời gian đặt lại mặc định là 60 giây (--dataset.episode_time_s và --dataset.reset_time_s), và số episode mặc định là 50. Bàn phím điều khiển luồng thao tác trong khi ghi, như bảng dưới đây.
Với bộ dữ liệu hữu ích đầu tiên, hãy chọn một tác vụ đơn giản, chẳng hạn gắp một vật từ nhiều vị trí và đặt vào thùng. Ghi ít nhất 50 episode, khoảng 10 episode cho mỗi vị trí, giữ camera và cách gắp của bạn nhất quán, và thêm sự đa dạng từ từ. Ghi lại các episode thất bại. Năm mươi episode ở các vị trí cố định chỉ là điểm khởi đầu; hãy kỳ vọng một chính sách chủ yếu chỉ hoạt động quanh những vị trí bạn đã ghi. LeRobot in một dòng nhịp ghi sau mỗi episode được giữ lại và một bản tóm tắt khi kết thúc ghi. Nếu nhịp thấp hơn nhiều so với mục tiêu 30 Hz, bộ dữ liệu vẫn tự nhận là 30 Hz, nên chuyển động trông nhanh hơn thực tế. Hãy tìm ra thứ làm chậm vòng lặp (trong ví dụ của tài liệu đó là việc đọc camera) và ghi lại các episode bị ảnh hưởng thay vì huấn luyện trên chúng.
Kiểm tra dữ liệu trước khi huấn luyện. Mở bộ dữ liệu trong trình xem bộ dữ liệu LeRobot trên Hugging Face, và phát lại một episode trên robot để kiểm tra chuyển động có lặp lại được không. Phát lại sẽ tự di chuyển tay máy mà không cần bạn điều khiển, vì vậy hãy dọn trống không gian làm việc, đặt tay máy gần tư thế đầu tiên của episode và để bộ nguồn trong tầm với.
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=0Cuộn ngang để so sánh tất cả các cột.
| Phím | Hành động |
|---|---|
| Mũi tên phải hoặc n | Kết thúc sớm episode hoặc thời gian đặt lại và chuyển tiếp |
| Mũi tên trái hoặc r | Bỏ episode hiện tại và ghi lại |
| Esc hoặc q | Dừng phiên ghi: episode đang ghi được lưu lại, sau đó video được mã hóa và bộ dữ liệu được tải lên (nhấn Mũi tên trái hoặc r trước để bỏ episode đó) |
Huấn luyện chính sách ACT
ACT (Action Chunking Transformer) là chính sách được dùng trong hướng dẫn LeRobot: nó thích ứng với các động cơ và camera được lưu trong bộ dữ liệu của bạn. Hướng dẫn phần cứng ước tính các chính sách nhẹ (ACT, VQ-BeT, TD-MPC) cần khoảng 2 đến 6 GB bộ nhớ GPU ở batch size 8, như một con số mang tính tham khảo. Huấn luyện trên GPU NVIDIA (cuda); trên Apple silicon hãy đổi lệnh thành --policy.device=mps, cần macOS 15 trở lên (trên macOS 14, LeRobot chuyển sang dùng CPU, không phù hợp để huấn luyện).
Bắt đầu huấn luyện với tên bộ dữ liệu đầy đủ.
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=20000Nếu không có --steps, quá trình huấn luyện chạy 100.000 bước, thường nhiều hơn mức một bộ dữ liệu nhỏ cần: học bắt chước thường hội tụ trong khoảng 5 đến 10 lượt duyệt qua dữ liệu. Một bộ dữ liệu 50 episode, mỗi episode dài 30 giây ở 30 fps, chứa khoảng 45.000 khung hình, tương đương khoảng 5.600 bước mỗi lượt ở batch size 8, nên 5 đến 10 lượt là khoảng 28.000 đến 56.000 bước. Lệnh ở trên dùng --steps=20000, khoảng ba lượt rưỡi, như một lần chạy thử ngắn đầu tiên; hãy tăng lên nếu chính sách chưa được huấn luyện đủ, và nếu bạn giảm xuống thấp hơn nhiều thì cũng hãy đặt --policy.scheduler_decay_steps gần bằng --steps. Hướng dẫn phần cứng ước tính khoảng 30 đến 60 phút cho năm lượt ACT ở batch size 8 trên RTX 3090 hoặc 4090 và 1 đến 2 giờ trên L4 hoặc A10G, còn 6 đến 14 giờ ở batch size 4 trên M1, M2 hoặc M3 Max; tài liệu gọi các con số này là mang tính tham khảo và nói rằng các lần chạy thực tế có thể chênh lệch khoảng 50%.
Nếu không có GPU phù hợp, hãy huấn luyện trên Google Colab bằng notebook ACT, hoặc chạy hf auth login và thêm một loại phần cứng (flavor) của Hugging Face Jobs như --job.target=a10g-small vào cùng lệnh. Vì lệnh đó bật Trackio, một job còn cần --trackio.space_id=<user>/<space> (thêm --trackio.private=true để giữ Space ở chế độ riêng tư), hoặc bỏ --trackio.enable=true. Jobs được tính phí theo giây và bị giới hạn tối đa 48 giờ trừ khi bạn đặt --job.timeout, tự tải bộ dữ liệu chỉ có ở máy lên một kho riêng tư cho bạn, và đẩy mô hình đã huấn luyện lên khi kết thúc; hf jobs hardware liệt kê các flavor.
Các checkpoint được ghi vào outputs/train/act_so101_test/checkpoints. Hãy tiếp tục một lần chạy bị gián đoạn từ checkpoint cuối cùng. Vì lệnh huấn luyện đặt --policy.repo_id=${HF_USER}/my_policy, mô hình hoàn chỉnh sẽ được đẩy lên kho đó khi kết thúc (--policy.push_to_hub=false tắt việc này, --policy.private=true để đặt riêng tư); nếu tự tải một checkpoint lên, hãy dùng cùng tên kho để --policy.path=${HF_USER}/my_policy tìm thấy nó.
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_modelScript huấn luyện của LeRobot không đánh giá chính sách trên robot thật, vì vậy hãy để riêng một số episode ngoài quá trình huấn luyện, gồm cả các vị trí xuất phát bạn chưa ghi, và thử chính sách trên đó. Một người lắp ráp trong cộng đồng đã huấn luyện trên 50 episode (10 episode cho mỗi vùng trong năm vùng vị trí xuất phát) và thấy tỷ lệ thành công 60% trên các episode mới thuộc những vùng đó nhưng chỉ 10% trên các episode thuộc một vùng bị loại khỏi huấn luyện. Sau khi tăng dữ liệu lên 25 episode mỗi vùng, chính người đó đạt 90% và 75%. Đây là các mẫu nhỏ, được chấm bằng script riêng của người lắp ráp đó.
Chạy chính sách trên tay follower
Triển khai chính sách đã huấn luyện bằng lerobot-rollout. Dùng cùng id robot, tên camera, thiết lập camera và nội dung mô tả tác vụ như khi bạn ghi, và chạy lại công cụ tìm cổng nếu từ đó bạn đã khởi động lại hoặc cắm lại thiết bị. --duration tính bằng giây; nếu không có nó, chính sách chạy cho đến khi bạn dừng.
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=60Chiến lược (strategy) quyết định điều xảy ra trong lúc chạy, như bảng dưới đây. Chiến lược có ghi bộ dữ liệu cần một tên kho bắt đầu bằng rollout_ sau tên người dùng của bạn, ví dụ --dataset.repo_id=${HF_USER}/rollout_so101_test; dấu thời gian sẽ được thêm vào đó. Các chiến lược ghi dữ liệu như sentry nhận --dataset.single_task thay cho --task; hãy xem tài liệu LeRobot để biết các tham số của từng chiến lược.
Trên LeRobot v0.5.x trở về trước không có lerobot-rollout; hãy dùng lerobot-record như mô tả trong tài liệu v0.5.1. Các tham số huấn luyện trong hướng dẫn này nhắm tới bản phát hành hiện tại.
Lần chạy đầu tiên, hãy dùng thời lượng ngắn (ví dụ 15 giây), không gian làm việc thoáng và một kế hoạch về cách bạn sẽ dừng tay máy; ngắt nguồn sẽ nhả các động cơ, nên tay máy không có gì đỡ bên dưới có thể rơi xuống. Nếu tay máy mổ xuống mặt bàn hoặc với quá xa, hãy kiểm tra thiết lập trước khi đổ lỗi cho mô hình: cùng id hiệu chuẩn, camera ở cùng vị trí với cùng tên và độ phân giải, cùng ánh sáng, và các vật thể ở những vị trí mà bộ dữ liệu có bao phủ.
Cuộn ngang để so sánh tất cả các cột.
| Chiến lược | Chức năng |
|---|---|
| base | Chạy tự động mà không ghi, để thử nhanh |
| sentry | Ghi liên tục và tự động tải lên |
| highlight | Giữ một bộ đệm vòng và lưu lại khi bạn nhấn một phím |
| dagger | Thu thập dữ liệu có con người tham gia (human-in-the-loop) |
| episodic | Ghi theo từng episode, có các giai đoạn đặt lại ở giữa |
Mở rộng bản dựng với LeKiwi
LeKiwi là đế di động ba bánh mang một tay follower SO-101. Một Raspberry Pi, hoặc máy tính 5 V khác có đủ cổng USB cho các camera và bo mạch điều khiển động cơ (trang LeKiwi ghi là từ hai cổng trở lên), điều khiển robot, và bạn lái nó từ laptop bằng một tay leader và bàn phím. Ở bản có dây, mọi thứ chạy trên laptop và có thể bỏ qua các bước trên Pi. Danh mục linh kiện, tệp in và hướng dẫn lắp đế lấy từ dự án LeKiwi được liên kết trên trang LeKiwi của Hugging Face.
Vuốt ngang để xem toàn bộ hình.
Lái đế bằng bàn phím cần một backend phím toàn cục, nên hoạt động trên X11, trên desktop Windows, hoặc trên macOS khi đã cấp quyền Input Monitoring cho terminal, nhưng không hoạt động trên Wayland hay máy không có màn hình.
- Lắp hai tay SO-101 theo các phần ở trên: một tay gắn lên đế và một tay làm tay leader. Sau đó lắp đế.
- Cài Raspberry Pi OS, bật SSH và kiểm tra bạn đăng nhập được bằng
ssh <user>@<pi-ip>. Cài LeRobot trên Pi và trên laptop như trong phần cài đặt, rồi thêm gói bổ sung LeKiwi, gói này kéo theo trình điều khiển servo và ZeroMQ.Cài gói bổ sung LeKiwi pip install 'lerobot[lekiwi]' - Thiết lập tất cả động cơ bằng một lệnh. Lệnh này gán cho các động cơ của tay máy ID từ 6 đến 1 và cho các bánh xe 9, 8 và 7; ID của bánh xe phải khớp với vị trí lắp được nêu trong tài liệu LeKiwi. LeKiwi dùng một bo mạch điều khiển duy nhất.
Đặt ID động cơ cho LeKiwi lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - Hiệu chuẩn tay follower trên Pi, và tay leader trên laptop. Trang LeKiwi ghi
--teleop.type=so100_leadercho tay leader; hãy kiểm traexamples/lekiwi/teleoperate.pytạo lớp leader nào, và hiệu chuẩn với cùng loại đó và cùng--teleop.id. Các động cơ bánh xe không cần hiệu chuẩn.Hiệu chuẩn tay máy LeKiwi lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - Trên Pi, kích hoạt môi trường LeRobot rồi khởi động host. Nó tự dừng sau 30 giây trừ khi bạn tăng
--host.connection_time_s(ví dụ lên 600), điều cần thiết cho các phiên dài hơn như ghi dữ liệu.Khởi động host LeKiwi trên Pi python -m lerobot.robots.lekiwi.lekiwi_host \ --robot.id=my_awesome_kiwi \ --host.connection_time_s=600 - Trên laptop, chỉnh sửa
examples/lekiwi/teleoperate.pytrong kho mã nguồn LeRobot: đặtremote_ipthành địa chỉ của Pi và đặtportcùng id của tay leader theo giá trị của bạn, rồi chạy nó. Trongrecord.py, hãy đặt thêmHF_REPO_IDvàTASK_DESCRIPTION; trongreplay.py, hãy đặtremote_ip,port, id bộ dữ liệu và chỉ số episode. Để chạy một chính sách đã huấn luyện, trang LeKiwi dùngexamples/lekiwi/evaluate.py(đặtremote_ip,portvà mô hình); lệnhlerobot-rolloutở phần trước được viết cho một SO-101 độc lập. Tốc độ có ba chế độ, đổi bằng R và F: nhanh 0,3 m/s và 90°/s, trung bình 0,2 m/s và 60°/s, chậm 0,1 m/s và 30°/s.
Cuộn ngang để so sánh tất cả các cột.
| Phím | Hành động |
|---|---|
| W | Tiến lên |
| A | Sang trái |
| S | Lùi lại |
| D | Sang phải |
| Z | Xoay trái |
| X | Xoay phải |
| R | Tăng tốc độ |
| F | Giảm tốc độ |
Danh sách kiểm tra khi gặp sự cố
Nhiều sự cố đến từ nguồn điện, cáp, cổng, hoặc một thiết lập đã thay đổi giữa lúc ghi và lúc chạy. Hãy xem lần lượt bảng này trước khi sửa bất kỳ đoạn mã nào.
Với các câu hỏi về chính LeRobot, tài liệu của Hugging Face có liên kết tới cộng đồng Discord. Với linh kiện mua từ cửa hàng của chúng tôi, hãy dùng nút WhatsApp hoặc biểu mẫu hỗ trợ.
Cuộn ngang để so sánh tất cả các cột.
| Triệu chứng | Cần kiểm tra |
|---|---|
| Không tìm thấy cổng nối tiếp hoặc bị từ chối truy cập | Chạy lại công cụ tìm cổng khi bo mạch đã được cấp nguồn và cáp USB đã cắm. Trên Linux, cấp quyền truy cập bằng sudo chmod 666 cho cổng đó. Cổng có thể thay đổi sau khi khởi động lại hoặc cắm lại, vì vậy hãy chạy lại công cụ tìm cổng. |
| Script đặt ID không tìm thấy động cơ | Kiểm tra bộ nguồn, cáp USB và cáp 3 chân. Chỉ được kết nối động cơ đang được đặt ID. Trên bo Waveshare, cả hai jumper phải ở kênh B (USB). |
| Servo tái sử dụng không được tìm thấy hoặc không phản hồi | Nhiều khả năng ID và tốc độ baud của chúng không khớp với robot mới, như hướng dẫn SO-101 có ghi chú. Chạy lại bước thiết lập động cơ, từng servo một. |
| Hiệu chuẩn thất bại, hoặc tay máy chuyển động sai sau khi hiệu chuẩn | Hiệu chuẩn lại: trước hết đưa mọi khớp về giữa biên độ của nó và nhấn Enter, rồi di chuyển từng khớp qua toàn bộ biên độ. Một người lắp ráp trong cộng đồng không đưa mọi khớp về giữa đã bị homing offset sai. Sau đó hãy dùng cùng id robot. |
| Camera ngắt kết nối hoặc chỉ số của nó thay đổi | Chạy lại công cụ tìm camera sau mỗi lần khởi động lại hoặc cắm lại. Hai webcam giống hệt nhau có thể hoán đổi địa chỉ USB trên Linux; một người lắp ráp trong cộng đồng đã khắc phục bằng quy tắc udev dựa trên cổng USB vật lý. |
| Các phím khi ghi không có tác dụng | Khởi động lệnh từ một terminal tương tác và giữ cho cửa sổ đó luôn được chọn; các phím chữ n, r và q hoạt động như các phím mũi tên và Esc. Chỉ việc lái robot bằng bàn phím, như trên LeKiwi, mới cần X11, desktop Windows hoặc quyền trên macOS. |
| Huấn luyện không tìm thấy bộ dữ liệu | Dùng tên bộ dữ liệu đầy đủ, gồm cả hậu tố ngày và giờ. |
| Nhịp ghi thực tế thấp hơn nhiều so với 30 Hz | Đọc các dòng nhịp mà quá trình ghi in ra. Nếu việc đọc camera chiếm phần lớn thời gian, hãy hạ độ phân giải hoặc dùng ít camera hơn, rồi ghi lại: chính sách mong đợi cùng thiết lập camera lúc chạy, và các episode được ghi ở nhịp thấp hơn nhiều so với 30 Hz vẫn được lưu như thể chúng chạy ở 30 Hz. |
| Chính sách mổ xuống mặt bàn hoặc với quá xa | So sánh id hiệu chuẩn, vị trí camera, tên và ánh sáng với phiên ghi, và kiểm tra các vật thể bắt đầu ở nơi bộ dữ liệu có ví dụ. |
| LeKiwi không kết nối được, hoặc host dừng sau 30 giây | Tìm địa chỉ của Pi bằng hostname -I, ping nó từ laptop và thử ssh <user>@<pi-ip>; bật SSH trong sudo raspi-config nếu cần. Host dừng sau 30 giây trừ khi bạn đặt --host.connection_time_s. |