LeRobot documentation

Menambahkan Kebijakan

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Menambahkan Kebijakan

Panduan ini memandu Anda dalam mengimplementasikan kebijakan kustom dan membuatnya berfungsi dengan alat pelatihan, evaluasi, dan penerbitan LeRobot. Ada dua jalur:

  • Plugin (di luar pohon) — kirimkan kebijakan Anda sebagai paket lerobot_policy_* mandiri. Lebih cepat, tidak memerlukan PR, dan mudah untuk diiterasi. Cocok untuk eksperimen, penggunaan internal, atau ketika Anda ingin menerbitkan secara independen.
  • Di dalam pohon (disumbangkan ke LeRobot) — masukkan kebijakan Anda langsung ke src/lerobot/policies/. Memerlukan PR, tetapi menjadikan kebijakan Anda sebagai warga kelas satu dari pustaka.

Rute plugin biasanya merupakan titik awal yang tepat — naikkan ke in-tree setelah kebijakan stabil dan ada nilai yang jelas dalam menyediakannya bersama pustaka.

Bagaimanapun, komponen pembangunnya sama: kelas konfigurasi, kelas kebijakan, dan pabrik pemroses. Bagian pertama dari panduan ini membahas komponen bersama tersebut; bagian kedua membahas kerangka kerja spesifik jalur (Jalur A, Jalur B).

Catatan tentang nada: robot-learning adalah bidang yang terus berkembang secara aktif, dan “bagaimana bentuk sebuah policy” dapat berubah seiring arsitektur baru. Konvensi yang dijelaskan di sini ada karena memungkinkan lerobot-train dan lerobot-eval bekerja secara seragam di berbagai model yang sangat berbeda. Ketika policy baru benar-benar tidak sesuai dengan konvensi tersebut, sampaikan hal itu (dalam PR Anda, atau sebuah issue) — konvensi ini tidak sakral.


Anatomi sebuah kebijakan

Tiga blok bangunan membentuk setiap kebijakan. Nama di bawah ini menggunakan my_policy sebagai placeholder — ganti dengan nama kebijakan Anda. Nama tersebut bersifat krusial: ia harus cocok dengan string yang Anda lewati ke @PreTrainedConfig.register_subclass, atribut kelas MyPolicy.name, dan fungsi pabrik make_<name>_pre_post_processors (lebih lanjut tentang masing-masing di bawah).

Kelas konfigurasi

Warisi dari PreTrainedConfig dan daftarkan tipe kebijakan Anda. Berikut adalah templat — sesuaikan parameter dan metode sesuai kebutuhan arsitektur dan persyaratan pelatihan kebijakan Anda.

# configuration_my_policy.py
from dataclasses import dataclass, field
import torch
from lerobot.configs import PreTrainedConfig
from lerobot.optim import AdamWConfig
from lerobot.optim import CosineDecayWithWarmupSchedulerConfig

@PreTrainedConfig.register_subclass("my_policy")
@dataclass
class MyPolicyConfig(PreTrainedConfig):
    """Configuration class for MyPolicy.

    Args:
        n_obs_steps: Number of observation steps to use as input
        horizon: Action prediction horizon
        n_action_steps: Number of action steps to execute
        hidden_dim: Hidden dimension for the policy network
        # Add your policy-specific parameters here
    """

    dtype: torch.dtype | None = torch.bfloat16

    horizon: int = 50
    n_action_steps: int = 50
    hidden_dim: int = 256

    optimizer_lr: float = 1e-4
    optimizer_weight_decay: float = 1e-4

    def __post_init__(self):
        super().__post_init__()
        if self.n_action_steps > self.horizon:
            raise ValueError("n_action_steps cannot exceed horizon")

    def validate_features(self) -> None:
        """Validate input/output feature compatibility.

        Call this explicitly from your policy's __init__ — the base class does not.
        """
        if not self.image_features:
            raise ValueError("MyPolicy requires at least one image feature.")
        if self.action_feature is None:
            raise ValueError("MyPolicy requires 'action' in output_features.")

    def get_optimizer_preset(self) -> AdamWConfig:
        return AdamWConfig(lr=self.optimizer_lr, weight_decay=self.optimizer_weight_decay)

    def get_scheduler_preset(self):
        """Return a LRSchedulerConfig from lerobot.optim, or None."""
        return None

    @property
    def observation_delta_indices(self) -> list[int] | None:
        """Relative timestep offsets the dataset loader provides per observation.

        Return `None` for single-frame policies. For temporal policies that consume
        multiple past or future frames, return a list of offsets, e.g. `[-20, -10, 0, 10]` for
        3 past frames at stride 10 and 1 future frame at stride 10.
        """
        return None

    @property
    def action_delta_indices(self) -> list[int]:
        """Relative timestep offsets for the action chunk the dataset loader returns."""
        return list(range(self.horizon))

    @property
    def reward_delta_indices(self) -> None:
        return None

String yang Anda berikan ke @register_subclass harus cocok dengan MyPolicy.name (bagian berikutnya) dan merupakan apa yang pengguna berikan sebagai --policy.type di CLI. Gunakan AdamW dari lerobot.optim sebagai default untuk get_optimizer_preset kecuali Anda benar-benar membutuhkan hal lain. PreTrainedConfig sudah mendeklarasikan dtype: torch.dtype | None; untuk memberikan presisi default pada policy Anda, deklarasikan ulang dengan nilai torch.dtype (mis. dtype: torch.dtype | None = torch.bfloat16).

Kelas kebijakan

Turunkan dari PreTrainedPolicy dan atur dua atribut kelas — keduanya diperiksa oleh __init_subclass__:

# modeling_my_policy.py
import torch
import torch.nn as nn
from typing import Any

from lerobot.policies import PreTrainedPolicy
from lerobot.utils.constants import ACTION
from .configuration_my_policy import MyPolicyConfig

class MyPolicy(PreTrainedPolicy):
    config_class = MyPolicyConfig  # must match the string in @register_subclass
    name = "my_policy"

    def __init__(self, config: MyPolicyConfig, dataset_stats: dict[str, Any] = None):
        super().__init__(config, dataset_stats)
        config.validate_features()  # not called automatically by the base class
        self.config = config
        self.model = ...  # your nn.Module here

    def reset(self):
        """Reset per-episode state. Called by lerobot-eval at the start of each episode."""
        ...

    def get_optim_params(self) -> dict:
        """Return parameters to pass to the optimizer (e.g. with per-group lr/wd)."""
        return {"params": self.parameters()}

    def predict_action_chunk(self, batch: dict[str, torch.Tensor], **kwargs) -> torch.Tensor:
        """Return the full action chunk (B, chunk_size, action_dim) for the current observation."""
        ...

    def select_action(self, batch: dict[str, torch.Tensor], **kwargs) -> torch.Tensor:
        """Return a single action for the current timestep (called every step at inference)."""
        ...

    def forward(self, batch: dict[str, torch.Tensor]) -> tuple[torch.Tensor, dict | None]:
        """Compute the training loss.

        Returns `(loss, output_dict)`. `output_dict` may be `None`; everything in it must be
        logging-friendly Python natives (no tensors with gradients).

        `batch["action_is_pad"]` is a bool mask of shape (B, horizon) that marks
        timesteps padded because the episode ended before `horizon` steps; you
        can exclude those from your loss.
        """
        actions = batch[ACTION]
        action_is_pad = batch.get("action_is_pad")
        ...
        return loss, {"some_loss_component": some_loss_component.item()}

Metode yang dipanggil oleh loop train/eval:

MetodeDigunakan olehFungsinya
reset() -> Nonelerobot-evalBersihkan status per episode di awal setiap episode.
select_action(batch, **kwargs) -> Tensorlerobot-evalKembalikan aksi berikutnya (B, action_dim). Dipanggil setiap langkah.
predict_action_chunk(batch, **kwargs) -> Tensorkebijakan itu sendiriKembalikan chunk aksi (B, chunk_size, action_dim). Saat ini bersifat abstrak pada kelas dasar — lempar NotImplementedError jika kebijakan Anda tidak melakukan chunking.
forward(batch, reduction="mean") -> tuple[Tensor, dict \| None]lerobot-trainKembalikan (loss, output_dict). Terima reduction="none" jika Anda ingin mendukung penimbangan per sampel.
get_optim_params() -> dictoptimizerKembalikan self.parameters() untuk kebijakan sederhana; kembalikan dict parameter bernama untuk kebijakan multi-optimizer (lihat get_optim_params di modeling_act.py untuk contoh learning-rate per grup).
update() -> None (opsional)lerobot-trainDipanggil setelah setiap langkah optimizer jika didefinisikan. Gunakan untuk EMA, target nets, replay buffers (TDMPC menggunakan ini).

Batches adalah kamus datar yang dikunci oleh konstanta di lerobot.utils.constants: OBS_STATE (observation.state.<motor>), OBS_IMAGES (observation.images.<camera>), OBS_LANGUAGE, ACTION, dan sebagainya. Gunakan kembali konstanta tersebut — jangan membuat prefiks baru.

Jika model Anda cukup besar sehingga memerlukan pelatihan multi-GPU yang dipecah (sharded), deklarasikan juga unit wrap FSDP-nya — kelas blok berulang yang menjadi target operasi sharding:

class MyPolicy(PreTrainedPolicy):
    ...
    _fsdp_wrap_modules = ["MyTransformerBlock"]

Dengan satu deklarasi ini, --parallelism.dp_shard=N langsung berfungsi untuk kebijakan Anda (pengguna masih dapat menimpanya dengan --accelerator.fsdp.wrap_modules). Tanpa sumber wrap apa pun, eksekusi sharded akan gagal saat startup sesuai desain.

Fungsi Processor

LeRobot menggunakan PolicyProcessorPipeline untuk menormalisasi input dan mendenormalisasi output di sekitar kebijakan Anda. Untuk referensi konkret, lihat processor_act.py atau processor_diffusion.py.

Perhatikan dengan saksama di sini: processor adalah titik masalah reproduktibilitas yang paling umum. Ketidakcocokan dalam mode normalisasi (IDENTITY vs MEAN_STD vs MIN_MAX vs QUANTILES/QUANTILE10) atau dalam fitur mana yang dinormalisasi akan membuat pelatihan dan evaluasi berjalan tanpa error, namun secara diam-diam merusak hasil. Pastikan mode tersebut sesuai dengan cara checkpoint dilatih, bahwa statistik yang diperlukan ada (misalnya QUANTILES membutuhkan q01/q99), dan bahwa pre- dan post-processor tetap konsisten.

# processor_my_policy.py
from typing import Any
import torch

from lerobot.processor import PolicyAction, PolicyProcessorPipeline


def make_my_policy_pre_post_processors(
    config,
    dataset_stats: dict[str, dict[str, torch.Tensor]] | None = None,
) -> tuple[
    PolicyProcessorPipeline[dict[str, Any], dict[str, Any]],
    PolicyProcessorPipeline[PolicyAction, PolicyAction],
]:
    preprocessor = ...   # build your PolicyProcessorPipeline for inputs
    postprocessor = ...  # build your PolicyProcessorPipeline for outputs
    return preprocessor, postprocessor

Penting — penamaan fungsi: LeRobot menemukan prosesor Anda berdasarkan nama. Fungsi harus diberi nama make_{policy_name}_pre_post_processors (sesuai dengan string yang Anda berikan ke @PreTrainedConfig.register_subclass).

Opsional: menyesuaikan prosesor yang dimuat dari checkpoint

make_{policy_name}_pre_post_processors hanya dijalankan ketika prosesor dibangun dari awal. Setiap kali checkpoint terlibat (fine-tuning, melanjutkan, atau mengevaluasi), LeRobot memuat pipeline yang diserialisasi di samping bobot dan menerapkan override dari pemanggil.

Jika kebijakan Anda harus menyesuaikan pipeline yang dimuat tersebut, tambahkan fungsi opsional kedua ke modul yang sama, bernama make_{policy_name}_pre_post_processors_from_pretrained. LeRobot menemukannya dengan konvensi penamaan yang sama dan memanggilnya sebagai pengganti load generik. Kebijakan yang tidak memerlukan hal khusus cukup mengabaikannya.

from lerobot.processor import load_pretrained_policy_processors
from lerobot.utils.constants import (
    POLICY_POSTPROCESSOR_DEFAULT_NAME,
    POLICY_PREPROCESSOR_DEFAULT_NAME,
)


def make_my_policy_pre_post_processors_from_pretrained(
    config,
    pretrained_path: str,
    *,
    revision: str | None = None,
    dataset_stats: dict[str, dict[str, torch.Tensor]] | None = None,
    dataset_meta: Any | None = None,
    preprocessor_overrides: dict[str, Any] | None = None,
    postprocessor_overrides: dict[str, Any] | None = None,
    preprocessor_config_filename: str = f"{POLICY_PREPROCESSOR_DEFAULT_NAME}.json",
    postprocessor_config_filename: str = f"{POLICY_POSTPROCESSOR_DEFAULT_NAME}.json",
) -> tuple[
    PolicyProcessorPipeline[dict[str, Any], dict[str, Any]],
    PolicyProcessorPipeline[PolicyAction, PolicyAction],
]:
    preprocessor, postprocessor = load_pretrained_policy_processors(
        pretrained_path,
        revision=revision,
        preprocessor_overrides=preprocessor_overrides,
        postprocessor_overrides=postprocessor_overrides,
        preprocessor_config_filename=preprocessor_config_filename,
        postprocessor_config_filename=postprocessor_config_filename,
    )
    ...  # reconcile the loaded pipelines with the current `config`
    return preprocessor, postprocessor

Untuk contoh yang berfungsi, lihat processor_evo1.py (mengulang normalisasi statistik), processor_groot.py (menangani checkpoint hulu mentah), dan processor_molmoact2.py (mengubah nama kunci override).

Mengembalikan prediksi di samping aksi (bingkai yang dibayangkan, sub-tugas, kotak)

Sebuah kebijakan dapat mengembalikan apa yang diharapkan atau diyakininya selain tindakan yang diambil, seperti bingkai yang dibayangkan oleh model dunia, subtask yang diprediksi, atau kotak pembatas, sehingga --display_data menampilkannya secara langsung di Rerun atau Foxglove. select_action dan predict_action_chunk menerima batch dan mengembalikan tensor aksi polos (default untuk setiap kebijakan) atau PolicyOutput (lerobot.lerobot_types): sebuah batch, yang dikunci seperti batch input, dengan aksi di bawah "action" dan PolicyPrediction di bawah "prediction". Prediksi di-batch seperti aksi, satu nilai per lingkungan, dan setiap entri dikunci berdasarkan apa yang dirujuknya:

  • observation: observasi masa depan yang diprediksi, berdasarkan kunci observasi ("observation.images.top" -> [B, C, H, W] frame). Ditampilkan sebagai prediction.images.top.
  • language: satu string per lingkungan, berdasarkan gaya anotasi ("subtask", "plan", "memory"), gaya kolom bahasa dari pipeline anotasi. Ditampilkan sebagai prediction.subtask.
  • boxes: berdasarkan kunci gambar observasi yang digambar di atasnya, satu jawaban bbox per lingkungan dalam skema anotasi VQA ({"detections": [{"label", "bbox": [x1, y1, x2, y2]}]}, fraksi gambar 0 hingga 1).

Panggilan menormalisasi dua tipe pengembalian dengan policy_output_to_transition, yang mengubah PolicyOutput menjadi EnvTransition yang digunakan oleh prosesor, sehingga hanya kebijakan yang memprediksi sesuatu yang berubah. Penampil menampilkan lingkungan pertama.

from lerobot.utils.constants import ACTION, PREDICTION


class MyPolicy(PreTrainedPolicy):
    def select_action(self, batch, **kwargs) -> Tensor | PolicyOutput:
        if not self._action_queue:
            chunk, extras = self.model.sample(batch)
            self._action_queue.extend(chunk.transpose(0, 1))
            if self.config.return_prediction:  # a config field of your choosing
                # The prediction goes with the step that computed it; the others return a bare action.
                prediction = {
                    "observation": {"observation.images.top": extras.next_frames},  # [B, C, H, W]
                    "language": {"subtask": extras.subtasks},  # list[str], one per env
                    "boxes": {
                        "observation.images.top": [
                            {"detections": [{"label": "cube", "bbox": xyxy}]} for xyxy in extras.cube_xyxy
                        ]
                    },
                }
                return {ACTION: self._action_queue.popleft(), PREDICTION: prediction}
        return self._action_queue.popleft()
  • A prediction menyimpan nilai untuk langkah ini. Prediksi yang mencakup sebuah chunk, seperti klip imajiner, dikembalikan secara per bagian: setiap langkah mengembalikan bagian yang sesuai dengan aksi yang dilayaninya.
  • Setiap entri tetap ditampilkan hingga dikembalikan lagi. Kembalikan detections kosong untuk menghapus kotak dari kamera.
  • Predicting bersifat opt-in melalui config kebijakan Anda, dan seharusnya tidak menimbulkan biaya apa pun saat dinonaktifkan.
  • Prediksi tidak pernah mengubah aksi, dan hanya aksi yang melewati postprocessor. Teks yang harus mengarahkan kebijakan, seperti subtask berikutnya, melewati generate_text (di bawah).

Kebijakan yang mampu memproses teks

Kebijakan bahasa berbagi perenderan resep antara dua langkah pemroses:

  • RenderTrainingMessagesStep mengonversi anotasi bahasa dataset menjadi pesan yang dirender.
  • RenderRuntimeMessagesStep mengubah prompt pengguna menjadi pesan yang dirender.

Pemroses khusus kebijakan kemudian menerapkan format chat dan tokenisasi.

Konfigurasi kebijakan menyimpan recipe: TrainingRecipe | None yang telah di-resolve (dari lerobot.datasets.recipe). recipe_path opsional dapat memuat resep YAML; resolve-kan sebelum membangun prosesor. Resep yang telah di-resolve mengaktifkan pelatihan resep, dan None membuat renderer pelatihan menjadi no-op. Serialisasi resep yang telah di-resolve dalam konfigurasi dan prosesor agar deployment tidak bergantung pada jalur YAML lokal. Rendering berbasis resep memerlukan ekstra dataset karena resep saat ini berada di bawah lerobot.datasets.

Letakkan kedua renderer sebelum format chat dan tokenisasi yang asli dari kebijakan:

input_steps = [
    RenderRuntimeMessagesStep(config.recipe),
    RenderTrainingMessagesStep(config.recipe),
    # observation transforms
    # policy-native roles, image placement, chat template, and tokenization
    # device placement
]

Pipeline yang sama disimpan dan dimuat untuk pelatihan dan inferensi. Rendering runtime hanya berjalan untuk query_kind yang eksplisit. Rendering pelatihan melewati query runtime dan, ketika resep dikonfigurasi, memproses sampel dengan anotasi mentah atau target aksi. Input observasi biasa dilewatkan apa adanya. Pelatihan teks beranotasi tanpa tensor aksi didukung. Pelatihan tanpa anotasi memerlukan target aksi untuk mengaktifkan fallback tugas.

Pabrik bersama hanya membangun atau memuat prosesor. Fine-tuning resep bahasa membangunnya dari konfigurasi aktif dan statistik dataset sehingga prosesor yang disimpan tidak dapat menimpa resep baru. Resume dan inferensi memuat pipeline yang disimpan, termasuk resep dan statistiknya. Pelatihan non-bahasa mempertahankan perilaku pembangunan dan pemuatan checkpoint yang ada. Pabrik baru menurunkan pengaturan normalisasi dan aksi relatifnya sendiri. Pabrik baru menggunakan perangkat yang dikonfigurasi; pra-pemrosesan batch dataset yang ada menerapkan peta penamaan ulang pelatihan.

messages_rendered berisi pesan semantik yang telah diperluas oleh resep, sebelum pemformatan chat native atau tokenisasi. Sisi pelatihan mengindeks daftar yang sama ini. Helper pesan berada di lerobot.utils.language.

Rollout interaktif menambahkan query_kind dan query_text. Rendering runtime mendukung:

  • vqa: simpan pertanyaan pemanggil sebagai pesan pengguna.
  • next_subtask: render resep checkpoint hingga, tetapi tidak termasuk, giliran asisten yang mengawasi ${subtask}.

Kebijakan kemudian mengekspos dekodernya melalui API kebijakan yang sudah ada:

class MyPolicy(PreTrainedPolicy):
    def supports_text_generation(self) -> bool:
        return True

    def generate_text(self, batch) -> str:
        token_ids = self.model.generate(**batch)
        return self.tokenizer.decode(token_ids, skip_special_tokens=True)

generate_text mengonsumsi keluaran pemroses yang siap untuk model; fungsi ini tidak boleh membangun ulang atau melakukan retokenisasi prompt dari pemanggil. Selama pelatihan, tokenizer asli kebijakan menggunakan target_message_indices untuk mengawasi hanya rentang asisten yang dipilih. Simpan resep di konfigurasi kebijakan bahasa agar diserialisasi bersama checkpoint dan deployment merekonstruksi prompt yang digunakan untuk pelatihan.


Path A: Plugin di luar pohon

Cara tercepat untuk merilis kebijakan: kemas sebagai distribusi Python mandiri dan instal berdampingan dengan LeRobot. Tidak perlu PR, Anda yang mengontrol siklus rilis, dan Anda dapat menerbitkan ke PyPI di bawah namespace Anda sendiri.

Struktur paket

Buat paket dengan awalan lerobot_policy_ (PENTING!) diikuti oleh nama kebijakan Anda:

lerobot_policy_my_policy/
├── pyproject.toml
└── src/
    └── lerobot_policy_my_policy/
        ├── __init__.py
        ├── configuration_my_policy.py
        ├── modeling_my_policy.py
        └── processor_my_policy.py

pyproject.toml

[project]
name = "lerobot_policy_my_policy"
version = "0.1.0"
dependencies = [
    # your policy-specific dependencies
]
requires-python = ">= 3.12"

[build-system]
build-backend = # your-build-backend
requires = # your-build-system

Paket __init__.py

Paparkan kelas Anda di __init__.py paket dan lindungi dari lerobot yang tidak ada:

# __init__.py
"""Custom policy package for LeRobot."""

try:
    import lerobot  # noqa: F401
except ImportError:
    raise ImportError(
        "lerobot is not installed. Please install lerobot to use this policy package."
    )

from .configuration_my_policy import MyPolicyConfig
from .modeling_my_policy import MyPolicy
from .processor_my_policy import make_my_policy_pre_post_processors

__all__ = [
    "MyPolicyConfig",
    "MyPolicy",
    "make_my_policy_pre_post_processors",
]

Instal dan gunakan

cd lerobot_policy_my_policy
pip install -e .

# Or install from PyPI if published
pip install lerobot_policy_my_policy

Setelah diinstal, kebijakan Anda secara otomatis terintegrasi dengan alat pelatihan dan evaluasi LeRobot:

lerobot-train \
    --policy.type my_policy \
    --dataset.repo_id lerobot/pusht \
    --env.type pusht \
    --steps 200000 \
    --policy.push_to_hub false

Path B: Kontribusi in-tree

Ketika kebijakan Anda telah stabil dan ada nilai yang jelas untuk mengirimkannya bersama pustaka, Anda dapat langsung menerapkannya di LeRobot. Baca panduan kontribusi dan template PR terlebih dahulu — di sanalah Anda akan menemukan ekspektasi pengujian/kualitas yang harus dipenuhi oleh setiap PR (pre-commit run -a, pytest, aturan review komunitas, dll.). Yang ada di bawah ini adalah lapisan spesifik kebijakan di atasnya.

Tata letak in-tree

src/lerobot/policies/my_policy/
├── __init__.py                    # re-exports config + modeling + processor factory
├── configuration_my_policy.py     # MyPolicyConfig + @register_subclass
├── modeling_my_policy.py          # MyPolicy(PreTrainedPolicy)
├── processor_my_policy.py         # make_my_policy_pre_post_processors
└── README.md                      # symlink → ../../../../docs/source/policy_my_policy_README.md

Dua catatan:

  • symlink pada README.md di samping sumber mengarah ke docs/source/policy_<name>_README.md — file aslinya berada di bawah docs/. Kebijakan yang sudah ada (act, smolvla, diffusion, …) semuanya melakukan hal ini; salin salah satu symlink tersebut. README kebijakan secara konvensi dibuat minimal: tautan paper + sitasi BibTeX.
  • Tutorial yang ditujukan untuk pengguna — apa yang harus diinstal, cara melatih, hiperparameter, angka benchmark — disimpan secara terpisah di docs/source/<my_policy>.mdx dan didaftarkan di _toctree.yml di bawah “Policies”.

Nama file bersifat krusial: pabrik melakukan impor secara lambat berdasarkan nama, dan prosesor ditemukan melalui konvensi make_<policy_name>_pre_post_processors.

Koneksi

Dua tempat perlu mengetahui kebijakan Anda. Semua berdasarkan nama.

  1. policies/__init__.py — re-export MyPolicyConfig dan tambahkan ke __all__. Impor inilah yang mendaftarkan policy Anda: @PreTrainedConfig.register_subclass("my_policy") dijalankan, dan sejak saat itu factory menyelesaikan semuanya berdasarkan konvensi. Jangan re-export kelas modeling; ia dimuat secara lazy melalui factory (sehingga import lerobot tetap cepat).
  2. templates/lerobot_modelcard_template.md dan README.md di root — template ini adalah yang dirender oleh publisher akhir pelatihan menjadi model card untuk setiap checkpoint yang dilatih dengan kebijakan Anda: tambahkan deskripsi satu baris tentang kebijakan Anda di cabang model_name, petakan di policy_docs agar kartu tautan ke panduan MDX Anda, dan secara opsional tambahkan gambar arsitektur ke diagrams. Kemudian tambahkan kebijakan Anda ke tabel model di README.md root, di bawah kategori yang tepat, dengan tautan ke halaman dokumentasi Anda.

Cerminkan kebijakan yang sudah ada yang secara struktural mirip dengan milik Anda; perbedaannya kecil.

Dependensi berat / opsional

Kebanyakan kebijakan membutuhkan tulang punggung yang berat (transformers, diffusers, SDK VLM tertentu). Di mana pun salah satu dari itu tersedia, lebih baik memuatnya, misalnya dari transformers atau diffusers, daripada mengimplementasikan ulang arsitekturnya di dalam pohon kode.

Konvensinya adalah gating dua langkah: impor yang dijaga oleh TYPE_CHECKING di bagian atas modul, dan pemeriksaan runtime require_package di konstruktor. modeling_diffusion.py adalah referensi kanoniknya:

from typing import TYPE_CHECKING
from lerobot.utils.import_utils import _diffusers_available, require_package

if TYPE_CHECKING or _diffusers_available:
    from diffusers.schedulers.scheduling_ddim import DDIMScheduler
else:
    DDIMScheduler = None  # keeps the symbol bindable at import time

class DiffusionPolicy(PreTrainedPolicy):
    def __init__(self, config):
        require_package("diffusers", extra="diffusion")
        super().__init__(config)
        ...

Dengan cara ini:

  • import lerobot.policies tetap berfungsi tanpa instalasi tambahan (simbolnya hanya diikat ke None).
  • Pemeriksa tipe melihat simbol asli.
  • Instansiasi kebijakan tanpa tambahan tersebut memicu ImportError yang jelas, mengarah ke pip install 'lerobot[diffusion]'.

Tambahkan extra yang sesuai ke pyproject.toml di [project.optional-dependencies] dan sertakan dalam extra all agar pip install 'lerobot[all]' tetap menginstal semuanya.

Hindari menyalin file pemodelan — turunkan kelasnya

Jika kebijakan Anda perlu memodifikasi backbone yang sudah ada di transformers (kondisioning kustom, input tambahan, sub-modul yang diganti), jangan membuat salinan vendor dari modeling_*.pynya. Sebaliknya, subclass unit upstream terkecil dan override hanya bagian yang berubah. pi_gemma.py adalah referensi kanonik: file ini menyuntikkan kondisioning AdaRMS ke PaliGemma/Gemma dalam ~370 baris dengan cara subclassing GemmaModel/PaliGemmaModel dan overriding forward dari decoder-layer, alih-alih mem-fork file modeling sepanjang ~2.000 baris. Operasi pembedahan model pada model native yang dimuat juga tidak masalah (truncation layer, ekspansi tokenizer, penangkapan hidden-state — lihat evo1/internvl3_embedder.py, eo1/modeling_eo1.py, groot/groot_n1_7.py untuk contoh yang berfungsi). Reviewer akan meminta pola ini ketika PR tiba dengan file modeling yang disalin; pengecualian satu-satunya yang diterima adalah model yang sama sekali tidak ada di transformers.

Benchmarks dan checkpoint yang dipublikasikan

Kebijakan baru jauh lebih mudah ditinjau — dan jauh lebih berguna — ketika dirilis bersama checkpoint yang berfungsi dan setidaknya satu angka yang dapat direproduksi.

Pilih setidaknya satu benchmark in-tree. LeRobot menyediakan benchmark simulasi dengan image Docker per benchmark (LIBERO, LIBERO-plus, Meta-World, RoboTwin 2.0, RoboCasa365, RoboCerebra, RoboMME, VLABench, dan lainnya). Pilih yang sesuai dengan modalitas policy Anda — VLA biasanya menggunakan LIBERO atau VLABench; BC berbasis gambar saja menggunakan LIBERO atau Meta-World. Daftar lengkapnya ada di Benchmarks pada sidebar dokumentasi.

Push checkpoint & processors ke Hub di bawah lerobot/<policy>_<benchmark> (atau namespace Anda jika tidak memiliki akses tulis; maintainer dapat memirror-nya). Cara termudah adalah dengan melatih menggunakan --policy.repo_id=<namespace>/<repo> dan --policy.push_to_hub=true: lerobot-train akan menerbitkan model, kedua processors, dan model card di akhir run. Untuk menerbitkan checkpoint yang sudah ada setelahnya, unggah direktori pretrained_model/ (misalnya hf upload), atau gunakan lerobot-convert-dcp --push_to_hub=... untuk checkpoint dalam format sharded.

Laporkan hasil dalam MDX kebijakan Anda, dengan perintah lerobot-eval dan perangkat keras yang tepat agar siapa pun dapat menjalankannya kembali:

## Results

Evaluated on LIBERO with `lerobot/<policy>_libero`:

| Suite          | Success rate | n_episodes |
| -------------- | -----------: | ---------: |
| libero_spatial |        87.5% |         50 |
| libero_object  |        93.0% |         50 |
| libero_goal    |        81.5% |         50 |
| libero_10      |        62.0% |         50 |
| **average**    |    **81.0%** |        200 |

Reproduce: `lerobot-eval --policy.path=lerobot/<policy>_libero --env.type=libero --env.task=libero_spatial --eval.n_episodes=50` (1× A100 40 GB).

Gunakan n_episodes ≥ 50 per suite untuk estimasi tingkat keberhasilan yang stabil.

Jika kebijakan Anda hanya untuk robot nyata dan tidak ada benchmark simulasi yang berlaku, ganti evaluasi simulasi dengan: dataset pelatihan publik di Hub, perintah lerobot-train, checkpoint, dan tingkat keberhasilan robot nyata selama ≥10 episode melalui lerobot-rollout --policy.path=....

Daftar periksa PR

Harapan umum terdapat di CONTRIBUTING.md dan template PR. Di atas itu, reviewer akan mencari:

  • MyPolicy dan MyPolicyConfig mencakup permukaan di atas; __init_subclass__ menerima kelas tersebut.
  • policies/__init__.py mengekspor ulang konfigurasi (hal ini mendaftarkan kebijakan; pabrik menyelesaikan modeling/processor berdasarkan konvensi penamaan).
  • make_my_policy_pre_post_processors mengikuti konvensi penamaan.
  • Dep opsional berada di balik extra [project.optional-dependencies] dan guard TYPE_CHECKING + require_package.
  • tests/policies/ diperbarui; artefak kompatibilitas mundur di-commit & tes spesifik kebijakan.
  • src/lerobot/policies/<name>/README.md yang disambungkan secara simbolik ke docs/source/policy_<name>_README.md; docs/source/<name>.mdx yang ditujukan untuk pengguna ditulis dan ditambahkan ke _toctree.yml.
  • lerobot-train --policy.type my_policy ... berjalan end-to-end untuk setidaknya beberapa langkah + menyimpan checkpoint yang dapat dimuat dan dijalankan oleh lerobot-eval atau lerobot-rollout.
  • templates/lerobot_modelcard_template.md memiliki entri deskripsi dan tautan policy_docs untuk kebijakan Anda.
  • Tabel model di README.md root mencantumkan kebijakan Anda di kategori yang tepat, dengan tautan ke halaman dokumen Anda.
  • Minimal satu benchmark eval yang dapat direproduksi dalam MDX kebijakan dengan checkpoint yang dipublikasikan (benchmark simulasi, atau dataset robot nyata + checkpoint).

Cara tercepat untuk mendapatkan PR yang bersih adalah menyalin direktori kebijakan yang ada yang paling mirip dengan milik Anda, mengubah namanya, dan mengganti isinya per metode. Jangan menunggu sampai semuanya sempurna — buka PR draf lebih awal dan iterasi bersama kami; para reviewer lebih suka memberikan umpan balik pada cabang yang setengah jadi daripada cabang yang sudah sepenuhnya digabungkan.


Contoh dan kontribusi komunitas

Lihat implementasi kebijakan contoh berikut:

Terima kasih telah meluangkan waktu untuk membawa kebijakan baru ke LeRobot. Setiap arsitektur yang masuk ke main — dan setiap plugin yang diterbitkan oleh komunitas — membuat pustaka ini sedikit lebih berguna bagi orang berikutnya, dan sedikit lebih merepresentasikan ke mana pembelajaran robotika sedang bergerak. Kami menantikan apa yang akan Anda rilis. 🤗

Update on GitHub