LeRobot documentation

Eylem Temsilleri

LeRobot

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.6.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Eylem Temsilleri

Bu kılavuz, robot eylemlerinin LeRobot içindeki farklı temsil biçimlerini, bu biçimlerin birbirleriyle ilişkisini ve her birinin ne zaman kullanılacağını açıklar.

Ortak Uzay ve Uç Etkileyici Uzayı

Eylem temsillerini tartışmadan önce, eylemlerin var olabileceği iki koordinat uzayını anlamak faydalıdır.

Ortak Uzay

Ortak uzay eylemleri, her motor için hedef konumları doğrudan belirtir. 6-DOF'lu bir kolu ve kavrayıcı içeren bir sistemde ortak uzay eylemi şu görünüme sahip olabilir:

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]

Ortak uzay, LeRobot'ta varsayılandır. Basittir, kinematik model gerektirmez ve doğrudan motor komutlarına eşlenir. Çoğu başlangıç kurulumu (SO-100, Koch) ortak uzay eylemlerini kullanır.

Uç Etkileyici (EE) Uzayı

End-effector-space actions, robotun uç noktasının (gripper) Kardezyen koordinatlardaki istenen konumunu ve yönelimini belirtir:

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

EE uzayı, gripper'ın nereye gitmesi gerektiğini doğrudan tanımladığı için pick-and-place gibi görevler için daha sezgiseldir; ancak EE pozları ile eklem açıları arasındaki dönüşümü gerçekleştirmek için bir kinematik model (URDF) gerektirir.

Uzaylar Arası Dönüştürme

LeRobot, ileri ve ters kinematik kullanarak eklem ve EE uzayları arasında dönüşüm yapmak için işlemci adımları sağlar. Bunlar, robotunuzun URDF modelini yükleyen RobotKinematics üzerine inşa edilmiştir.

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=[...])

SO-100 kolunda EE uzayında eylemlerle kayıt, oynatma ve değerlendirme için tam işlevsel bir örnek için examples/so100_to_so100_EE/ adresine bakın.

Mutlak, Göreli ve Delta Eylemleri

Ortak uzayda mı yoksa EE uzayında mı çalıştığınızdan bağımsız olarak, eylem değerleri üç farklı şekilde ifade edilebilir. Terminoloji UMI (Chi et al., 2024) ile uyumludur.

Mutlak Eylemler (LeRobot varsayılanı)

Her eylem, hedef konumu doğrudan belirtir.

Örnek (ortak uzay, 4'lük parça):

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
]

Her değer, robotun koordinat çerçevesindeki bir hedef konumudur. Basit ve doğrudan bir yöntemdir ancak tutarlı bir küresel koordinat çerçevesi gerektirir. Bu, LeRobot'ta varsayılandır.

Göreceli Eylemler (OpenPI / pi0 tarafından kullanılır)

Parçadaki her eylem, tahmin anındaki mevcut durumdan bir ofsettir. Parçadaki tüm eylemler aynı referans noktasını paylaşır:

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
]

Dönüşüm basittir: relative = absolute - current_state. Mutlak değeri geri almak için: absolute = relative + current_state.

Göreli eylemler neden kullanılır? Model, sıfırın etrafında merkezlenen ofsetleri tahmin etmeyi öğrenir; bu, normalleştirmeyi kolaylaştırır ve daha kararlı bir eğitime yol açar. Her parça aynı mevcut durumu referans aldığı için parçalar arasında hata birikimi oluşmaz.

Delta Eylemleri (ardışık farklar)

Her eylem, önceki eylemden (veya ilk adım için mevcut durumdan) bir ofsettir:

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
]

Burada her adım, kendinden önceki adıma göre görelidir. Mutlak konumları geri getirmek için tüm önceki deltaları toplamak gerekir; bu da hataların zamanla birikmesi anlamına gelir. UMI, bu nedenle bu temsil biçimine açıkça karşı çıkar.

Görsel Karşılaştırma

Aşağıdaki şekil (UMI, Chi et al., 2024 makalesindeki bir şekle dayanmaktadır) temel farkı göstermektedir. relative trajectory kullanıldığında, chunk içindeki her eylem aynı başlangıç noktasına (mevcut duruma) işaret eder, bu da yeni bir çıkarım adımının referans çerçevesini temiz bir şekilde sıfırlamasını sağlar. delta kullanıldığında ise her eylem bir öncekine bağlıdır, bu nedenle hatalar birikir. Absolute eylemler tutarlı bir küresel koordinat çerçevesi gerektirir.

Relative Trajectory as Action Representation (UMI, Chi et al., 2024)

LeRobot'ta Göreli Eylemlerin Kullanımı

LeRobot, işlemci hattı içinde mutlak ve göreli eylemler arasında dönüşüm yapmak için RelativeActionsProcessorStep sağlar. pi0, pi0.5 ve pi0_fast, göreli eylemleri bu şekilde destekler.

Note: All pi models (pi0, pi0.5, pi0fast) apply relative conversion _before normalization (relative → normalize), so the normalizer always sees delta (relative) values. This means relative action stats are required for all of them when training with use_relative_actions=true. In pi0_fast the RelativeActionsProcessorStep only modifies the action — the state observation is unchanged — so NormalizerProcessorStep still runs before the state tokenizer and the tokenizer continues to receive normalized state as expected.

Nasıl çalışır

Eğitim (ön işleme) sırasında, model eylemleri görmesinden önce mutlak değerlerden göreli değerlere dönüştürülür:

raw absolute action → RelativeActionsProcessorStep → normalize → model

Çıkarım (son işleme) sırasında, model tahminleri robota gönderilmeden önce mutlak değerlere geri dönüştürülür:

model output → unnormalize → AbsoluteActionsProcessorStep → robot

AbsoluteActionsProcessorStep, eşleştirilmiş RelativeActionsProcessorStep'ten önbelleğe alınmış mevcut durumu okur; bu nedenle ikisi birlikte bağlanmalıdır (bu işlem politika fabrikası tarafından otomatik olarak ele alınır).

pi ailesi (pi0, pi0.5, pi0_fast) için göreli eylemleri etkinleştirme

1. Adım: Veri setiniz için göreli eylem istatistiklerini önceden hesaplayın:

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']"

2. Adım: Göreceli eylemler etkinleştirilerek eğitim:

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

relative_exclude_joints parametresi, mutlak uzayda kalması gereken eklem noktalarını belirtir. Örneğin, kavrama komutları genellikle ikili (aç/kapa) olup göreli kodlamadan fayda sağlamaz.

action_feature_names tanımlayan politika yapılandırmaları için make_policy, bu listeyi veri seti eylem özelliğinin names meta verisinden doldurur. İsimler düz bir dizi veya değerleri tümüyle liste veya demet olan bir sözlük olabilir. Örneğin, {"arm": ["shoulder", "elbow"], "hand": ["gripper"]} grup anahtarları değil, ["shoulder", "elbow", "gripper"] olur. Grup ekleme sırası ve grup içi sıra korunduğundan, isimleri eylem vektörüyle aynı sırada tanımlayın. Eski nesil isim-dizin eşlemeleri, anahtar sırası davranışlarını korur.

Göreceli eylemleri RTC ile birleştirme

RTC, politika çıkarımını yüksek frekansta çalıştırır ve tam bir parça beklemek yerine, eylemleri tahmin edildikçe robota gönderir. Göreli eylemler ve RTC tamamen uyumludur: göreli modda her parça, aynı mevcut durumu (çıkarımın başlangıcında yakalanan) referans aldığından, robot zaten hareket etmiş olsa bile parçadaki her tahmin edilen eylem geçerli bir ofset olarak kalır. Özel bir işlem gerekmez — RelativeActionsProcessorStep durumunu her çıkarım çağrısı için bir kez önbelleğe alır ve AbsoluteActionsProcessorStep bunu, akışlanan çıktıdaki her eyleme uygular.

Göreceli eylemleri EE uzayıyla birleştirme

Göreceli eylemler hem eklem uzayında hem de EE uzayında çalışır. Örneğin, veri setiniz EE eylemlerini saklıyorsa, göreceli kodlama bunları mevcut EE duruşundan sapmalara dönüştürür:

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
]

İşleme Hattı Özeti

İşte farklı işleyicilerin nasıl bir araya geldiği. Her ok bir işleyici adımını temsil eder ve bunlar RobotProcessorPipeline veya PolicyProcessorPipeline içinde zincirlenebilir:

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

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

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

Tipik bir eğitim ön işleyicisi şu zinciri oluşturabilir: raw absolute joint actions → relative → normalize. Tipik bir çıkarım son işleyicisi: unnormalize → absolute → (optionally IK to joints).

Referanslar

Universal Manipulation Interface (UMI) - Chi et al., 2024. Göreli yörünge eylem temsilini tanımlar ve bunu mutlak ile delta eylemleriyle karşılaştırır.
İşleyicilere Giriş - LeRobot'ta işleyici hatlarının nasıl çalıştığı.
examples/so100_to_so100_EE/ - EE uzayında eylemlerle kayıt ve değerlendirme için tam bir örnek.

Update on GitHub

←Ortam İşleyicileri SO-101→