Representasi Aksi

Panduan ini menjelaskan berbagai cara representasi aksi robot dalam LeRobot, bagaimana hubungan di antara mereka, dan kapan sebaiknya menggunakan masing-masing.

Ruang Bersama vs Ruang Efektor Ujung

Sebelum membahas representasi aksi, membantu untuk memahami dua ruang koordinat tempat aksi dapat berada.

Ruang Gabungan

Aksi ruang sendi secara langsung menentukan posisi target untuk setiap motor. Untuk lengan 6-DOF dengan gripper, aksi ruang sendi mungkin terlihat seperti:

action = [shoulder_pan: 45.0, shoulder_lift: -20.0, elbow: -30.0, wrist_pitch: 10.0, wrist_roll: 0.0, wrist_yaw: 5.0, gripper: 0.8]

Ruang sendi (joint space) adalah default di LeRobot. Ruang ini sederhana, tidak memerlukan model kinematika, dan memetakan langsung ke perintah motor. Sebagian besar setup pemula (SO-100, Koch) menggunakan aksi ruang sendi.

Ruang End-Effector (EE)

Aksi ruang ujung-efektor menentukan posisi dan orientasi yang diinginkan dari ujung alat robot (gripper) dalam koordinat Kartesius:

action = [x: 0.25, y: -0.10, z: 0.15, wx: 0.0, wy: 0.0, wz: 0.1, gripper: 0.8]

Ruang EE lebih intuitif untuk tugas seperti pick-and-place karena secara langsung menjelaskan ke mana gripper harus bergerak, tetapi memerlukan model kinematika (URDF) untuk mengonversi antara pose EE dan sudut sendi.

Mengonversi Antar Ruang

LeRobot menyediakan langkah pemroses untuk mengonversi antara ruang sendi dan ruang EE menggunakan kinematika maju dan kinematika invers. Langkah-langkah ini dibangun di atas RobotKinematics, yang memuat model URDF dari robot Anda.

from lerobot.model.kinematics import RobotKinematics
from lerobot.robots.so_follower.robot_kinematic_processor import (
    ForwardKinematicsJointsToEE,
    InverseKinematicsEEToJoints,
)

kinematics = RobotKinematics(
    urdf_path="./SO101/so101_new_calib.urdf",
    target_frame_name="gripper_frame_link",
    joint_names=["shoulder", "elbow", "wrist_pitch", "wrist_roll", "wrist_yaw"],
)

# Joints → EE (for observations: "where is my gripper?")
fk_step = ForwardKinematicsJointsToEE(kinematics=kinematics, motor_names=[...])

# EE → Joints (for actions: "move my gripper here")
ik_step = InverseKinematicsEEToJoints(kinematics=kinematics, motor_names=[...])

Lihat examples/so100_to_so100_EE/ untuk contoh lengkap yang berfungsi untuk merekam, memutar ulang, dan mengevaluasi dengan aksi ruang-EE pada lengan SO-100.

Aksi Absolut, Relatif, dan Delta

Terlepas dari apakah Anda bekerja di ruang sendi atau ruang EE, nilai aksi dapat diekspresikan dalam tiga cara yang berbeda. Terminologi mengikuti UMI (Chi et al., 2024).

Aksi Absolut (default LeRobot)

Setiap aksi menentukan posisi target secara langsung.

Contoh (ruang gabungan, chunk sebesar 4):

current_state = [45.0, -30.0, 10.0]

action_chunk = [
    [46.0, -29.0, 11.0],   # go to 46, -29, 11
    [47.5, -27.0, 12.0],   # go to 47.5, -27, 12
    [49.0, -25.0, 13.5],   # go to 49, -25, 13.5
    [50.0, -24.0, 15.0],   # go to 50, -24, 15
]

Setiap nilai adalah posisi target dalam kerangka koordinat robot. Sederhana dan langsung, tetapi memerlukan kerangka koordinat global yang konsisten. Ini adalah default di LeRobot.

Aksi Relatif (digunakan oleh OpenPI / pi0)

Setiap aksi dalam chunk adalah offset dari keadaan saat ini pada saat prediksi. Semua aksi dalam chunk berbagi titik referensi yang sama:

current_state = [45.0, -30.0, 10.0]

relative_chunk = [
    [1.0,  1.0, 1.0],   # +1 from current → target 46, -29, 11
    [2.5,  3.0, 2.0],   # +2.5 from current → target 47.5, -27, 12
    [4.0,  5.0, 3.5],   # +4 from current → target 49, -25, 13.5
    [5.0,  6.0, 5.0],   # +5 from current → target 50, -24, 15
]

Konversinya sederhana: relative = absolute - current_state. Untuk memulihkan absolute: absolute = relative + current_state.

Mengapa menggunakan aksi relatif? Model belajar memprediksi offset yang berpusat di sekitar nol, yang lebih mudah dinormalisasi dan menghasilkan pelatihan yang lebih stabil. Karena setiap chunk merujuk pada keadaan saat ini yang sama, tidak ada akumulasi kesalahan antar chunk.

Delta Actions (perbedaan berurutan)

Setiap aksi adalah offset dari aksi sebelumnya (atau dari keadaan saat ini untuk langkah pertama):

current_state = [45.0, -30.0, 10.0]

delta_chunk = [
    [1.0,  1.0, 1.0],   # current → 46, -29, 11
    [1.5,  2.0, 1.0],   # previous action → 47.5, -27, 12
    [1.5,  2.0, 1.5],   # previous action → 49, -25, 13.5
    [1.0,  1.0, 1.5],   # previous action → 50, -24, 15
]

Di sini, setiap langkah bersifat relatif terhadap langkah sebelumnya. Untuk memulihkan posisi absolut, Anda harus menjumlahkan semua delta sebelumnya, yang berarti kesalahan akan terakumulasi seiring waktu. UMI secara eksplisit berargumen menentang representasi ini karena alasan tersebut.

Perbandingan Visual

Gambar di bawah (berdasarkan gambar dari UMI, Chi et al., 2024) mengilustrasikan perbedaan utama. Dengan relative trajectory, setiap aksi dalam chunk menunjuk kembali ke titik asal yang sama (state saat ini), sehingga langkah inferensi baru secara bersih mengatur ulang referensi. Dengan delta, setiap aksi bergantung pada aksi sebelumnya, sehingga kesalahan terakumulasi. Aksi Absolute memerlukan kerangka koordinat global yang konsisten.

Menggunakan Aksi Relatif di LeRobot

LeRobot menyediakan RelativeActionsProcessorStep untuk mengonversi antara aksi absolut dan relatif di dalam pipeline prosesor. Inilah cara pi0, pi0.5, dan pi0_fast mendukung aksi relatif.

Catatan: Semua model pi (pi0, pi0.5, pi0fast) menerapkan konversi relatif _sebelum normalisasi (relative → normalize), sehingga normalizer selalu melihat nilai delta (relatif). Ini berarti statistik aksi relatif diperlukan untuk semua model tersebut saat melatih dengan use_relative_actions=true. Pada pi0_fast, RelativeActionsProcessorStep hanya memodifikasi aksi — observasi state tidak berubah — sehingga NormalizerProcessorStep tetap berjalan sebelum state tokenizer dan tokenizer terus menerima state ternormalisasi seperti yang diharapkan.

Cara kerjanya

Selama pelatihan (pra-pemrosesan), aksi dikonversi dari absolut menjadi relatif sebelum model melihatnya:

raw absolute action → RelativeActionsProcessorStep → normalize → model

Selama inference (pascapemrosesan), prediksi model dikonversi kembali ke nilai absolut sebelum dikirim ke robot:

model output → unnormalize → AbsoluteActionsProcessorStep → robot

AbsoluteActionsProcessorStep membaca status saat ini yang di-cache dari RelativeActionsProcessorStep yang berpasangan, sehingga keduanya harus dihubungkan (ditangani secara otomatis oleh pabrik kebijakan).

Mengaktifkan aksi relatif untuk keluarga pi (pi0, pi0.5, pi0_fast)

Langkah 1: Hitung statistik aksi relatif untuk dataset Anda:

lerobot-edit-dataset \
    --repo_id your_dataset \
    --new_repo_id your_dataset \
    --operation.type recompute_stats \
    --operation.overwrite true \
    --operation.relative_action true \
    --operation.chunk_size 50 \
    --operation.relative_exclude_joints "['gripper']"

Langkah 2: Latih dengan aksi relatif diaktifkan:

lerobot-train \
    --dataset.repo_id=your_dataset \
    --policy.type=pi0 \
    --policy.use_relative_actions=true \
    --policy.relative_exclude_joints='["gripper"]'

Parameter relative_exclude_joints menentukan sendi yang harus tetap berada di ruang absolut. Sebagai contoh, perintah gripper biasanya biner (buka/tutup) dan tidak diuntungkan oleh pengkodean relatif.

Untuk konfigurasi kebijakan yang mendefinisikan action_feature_names, make_policy mengisi daftar ini dari metadata names fitur aksi dataset. Nama dapat berupa urutan datar atau kamus yang nilainya semuanya berupa daftar atau tuple. Sebagai contoh, {"arm": ["shoulder", "elbow"], "hand": ["gripper"]} menjadi ["shoulder", "elbow", "gripper"], bukan kunci grup. Urutan penyisipan grup dan urutan dalam grup dipertahankan, sehingga deklarasikan nama dalam urutan yang sama dengan vektor aksi. Pemetaan nama-ke-indeks lama mempertahankan perilaku urutan kuncinya.

Menggabungkan aksi relatif dengan RTC

RTC menjalankan inferensi kebijakan pada frekuensi tinggi dan mengirimkan aksi ke robot saat diprediksi, bukan menunggu seluruh chunk selesai. Aksi relatif dan RTC sepenuhnya kompatibel: karena setiap chunk dalam mode relatif merujuk pada state saat ini yang sama (diambil pada awal inferensi), setiap aksi yang diprediksi dalam chunk tetap menjadi offset yang valid meskipun robot sudah bergerak. Tidak diperlukan penanganan khusus — RelativeActionsProcessorStep meng-cache state sekali per panggilan inferensi dan AbsoluteActionsProcessorStep menerapkannya ke setiap aksi dalam output yang di-stream.

Menggabungkan aksi relatif dengan ruang EE

Aksi relatif bekerja di ruang sendi (joint space) maupun ruang EE. Misalnya, jika dataset Anda menyimpan aksi EE, pengkodean relatif mengubahnya menjadi offset dari pose EE saat ini:

current_ee_state = [x: 0.25, y: -0.10, z: 0.15, gripper: 0.8]

absolute_ee_chunk = [
    [0.26, -0.09, 0.16, 0.8],
    [0.28, -0.07, 0.18, 0.8],
]

relative_ee_chunk = [
    [0.01,  0.01, 0.01, 0.0],   # offset from current EE pose
    [0.03,  0.03, 0.03, 0.0],   # offset from current EE pose
]

Ringkasan Pipeline Pemrosesan

Berikut adalah cara berbagai prosesor dikomposisikan. Setiap panah adalah langkah prosesor, dan mereka dapat dirangkai dalam RobotProcessorPipeline atau PolicyProcessorPipeline:

                    ┌─────────────────────────────────────────┐
   Action Space     │   Joint Space  ←──IK──→  EE Space      │
                    │   ForwardKinematicsJointsToEE           │
                    │   InverseKinematicsEEToJoints           │
                    └─────────────────────────────────────────┘

                    ┌─────────────────────────────────────────┐
   Representation   │   Absolute  ←────→  Relative            │
                    │   RelativeActionsProcessorStep (pre)    │
                    │   AbsoluteActionsProcessorStep (post)   │
                    └─────────────────────────────────────────┘

                    ┌─────────────────────────────────────────┐
   Normalization    │   Raw  ←────→  Normalized               │
                    │   NormalizerProcessorStep (pre)         │
                    │   UnnormalizerProcessorStep (post)      │
                    └─────────────────────────────────────────┘

A typical training preprocessor might chain: raw absolute joint actions → relative → normalize. A typical inference postprocessor: unnormalize → absolute → (optionally IK to joints).

Referensi

• Universal Manipulation Interface (UMI) - Chi et al., 2024. Mendefinisikan representasi aksi trajektori relatif dan membandingkannya dengan aksi absolut dan delta.
• Pengenalan Prosesor - Cara kerja pipeline prosesor di LeRobot.
• examples/so100_to_so100_EE/ - Contoh lengkap untuk merekam dan mengevaluasi dengan aksi ruang EE.