LeRobot documentation
정책
정책
모든 정책은 PreTrainedPolicy를 상속하며, 이는 torch.nn.Module과 Hub 믹신을 결합한 것입니다. 따라서 모든 정책을 동일한 두 가지 호출을 통해 Hugging Face Hub에 push하고 로드할 수 있습니다.
각 정책에는 학습 레시피와 결과가 포함된 전용 가이드가 있습니다. ACT, SmolVLA, π₀, π₀.₅ 및 기타 정책은 Policies 섹션에 나열되어 있습니다. 정책을 추가하는 방법은 Adding a Policy를 참고하세요.
PreTrainedPolicy
정책 모델의 베이스 클래스입니다.
기본 현재 관찰 청크 서빙(author) 계약을 선언합니다.
이 구현을 상속하면 predict_action_chunk가 직접 호출자가 필요한 모든 준비 작업을 수행하고, 현재 관찰의 전체를 받아들이며, 모델 좌표계에서 [B, chunk_size, A]를 반환한다고 선언합니다. 해당 정규 프로세서 쌍은 전체 청크를 지원해야 합니다. n_action_steps는 일반적인 재생 슬라이스이며, RTC는 전체 예측 지평선을 유지합니다.
select_action 전용 준비, 다른 action 레이아웃, 또는 temporal sampling을 요구하는 정책은 이 메서드를 오버라이드하여 지원되지 않는 구성을 거부하거나 커스텀 runner를 제공해야 합니다. 메서드의 존재나 warmup의 성공은 이 계약에 대한 증거가 되지 않습니다. Policy/processor 상태는 전용 세션 내에서만 허용되며, reset()은 새로운 실행을 위해 이를 초기화해야 합니다.
이미 계산되어 제공을 기다리고 있는 작업의 수.
행동 큐를 유지하지 않는 정책(즉, 청킹을 하지 않는 정책) 또는 현재 큐가 비어 있는 경우(새로운 청크를 계산하려는 경우)에는 0을 반환합니다. drop_queued_actions가 지우는 것과 동일한 큐를 읽으며, 해당 큐는 :attr:_action_queue_attrs에 이름이 지정되어 있습니다.
이전 select_action 호출에서 사전 계산된 작업을 폐기합니다.
다음 select_action에서 새로운 forward pass를 강제하여, 에피소드 중간에 conditioning이 변경된 경우(예: 새로운 instruction) 큐가 비워진 후가 아니라 즉시 적용되도록 합니다. reset과 달리 에피소드 상태의 나머지는 유지됩니다. select_action를 호출하는 스레드에서 호출해야 합니다. :attr:_action_queue_attrs에 명시된 큐를 지우며, action queue를 유지하지 않는 policy는 no-op를 상속받습니다.
forward
< source >( batch: dict[str, Tensor] ) → tuple[Tensor, dict | None]
요약
from_pretrained
< source >( pretrained_name_or_path: str | Pathconfig: PreTrainedConfig | None = Noneforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Nonestrict: bool = False**kwargs )
policy.eval()을 사용하여 기본적으로 정책이 평가 모드로 설정됩니다(드롭아웃 모듈은 비활성화됨). 학습하려면 먼저 policy.train()을 사용하여 학습 모드로 되돌려야 합니다.
policy의 텍스트 헤드를 전처리된 관찰 배치에 실행합니다.
요청은 batch에 보완 데이터(:data:~lerobot.utils.constants.QUERY_KIND / QUERY_TEXT)로 실립니다. next_subtask 응답은 set_task에 바로 전달되므로, 계획이나 번호 매겨진 목록이 아닌 정확히 하나의 서브태스크여야 합니다. 생성된 텍스트를 반환하며, 액션 생성 상태(큐, 관찰 히스토리)를 변경해서는 안 됩니다.
옵티마이저에 전달할 정책별 매개변수(매개변수 또는 매개변수 그룹)를 반환합니다.
observation에 대해 (action chunking 정책을 사용하는 경우) action chunk를 반환합니다. 배치 모드일 수 있습니다.
액션 청킹을 사용하는 하위 클래스는 선택을 위해 캐시된 액션 청크를 형성하려면 select_action 내에서 이 메서드를 사용해야 합니다.
noise 키워드를 지원하는 정책은 해당 텐서를 시작점으로 삼아 샘플링을 시작합니다. 이때 텐서의 형태는 정책이 샘플을 추출할 때 사용하는 형태와 동일합니다. noise가 None인 경우, 정책은 평소와 같이 샘플을 추출합니다.
select_action과 마찬가지로, 청크와 그 예측을 포함하는 PolicyOutput을 반환할 수 있습니다.
push_model_to_hub
< source >( cfg: TrainPipelineConfigpeft_model = Nonestate_dict: dict[str, Tensor] | None = Nonedataset_meta: LeRobotDatasetMetadata | None = None )
매개변수
- cfg (TrainPipelineConfig) — 학습 설정입니다. train_config.json으로 저장되며 모델 카드 렌더링에 사용됩니다.
- peft_model — 어댑터 학습 시 PEFT 래퍼로, 공개된 저장소에서 전체 모델 가중치를 대체하는 가중치를 포함합니다. 기본값은 None입니다.
- state_dict (dict[str, Tensor] | None) — 정책이 샤드된 경우 가중치는 내부적으로 수집되므로 무시됩니다. 기본값은 None입니다.
- dataset_meta (LeRobotDatasetMetadata | None) — 사용 가능한 경우 모델 카드에 사용할 데이터셋 메타데이터입니다. 기본값은 None입니다.
이 정책을 Hub에 게시합니다.
비추천: 모델과 함께 전/후처리기도 함께 게시하는 lerobot.common.train_utils.publish_trained_model()을 대신 사용하세요.
환경에서 실행할 하나의 액션을 반환합니다(배치 모드일 수 있음).
모델이 관찰의 이력을 사용하거나 동작의 시퀀스를 출력하는 경우, 이 메서드는 캐싱을 처리합니다.
빈 action 텐서를 반환하거나, PolicyOutput를 반환합니다: 입력 배치와 동일한 키 구조를 가진 배치로, "action" 아래에 action을, 정책이 기대하거나 믿는 나머지 정보는 "prediction" 아래에 (PolicyPrediction) 포함합니다. prediction은 action과 마찬가지로 배치화되어 각 환경별로 하나의 값을 가지며, 각 항목은 해당 항목이 가리키는 대상의 키로 구분됩니다. 예측된 프레임은 예측 대상 observation 키로, 언어는 어노테이션 스타일(“subtask”, “plan”, “memory”)로, 박스(어노테이션 VQA 스키마)는 그려진 카메라로 키가 지정됩니다. 호출자는 lerobot.processor.policy_output_to_transition를 사용하여 두 가지 반환 유형을 정규화합니다. —display_data는 첫 번째 환경의 prediction을 표시합니다.
예측(prediction)은 이 단계의 값을 보유합니다. 청크(예: 상상된 클립)를 가로지르는 예측은 각 조각이 속한 액션과 함께 조각별로 반환됩니다. 각 항목은 다시 반환될 때까지 표시 상태로 유지됩니다. 예측은 정책이 선택한 config 필드를 통해 선택적으로 활성화되며, 액션을 변경해서는 안 됩니다. 정책을 유도해야 하는 텍스트는 generate_text를 통해 전달됩니다.
이 정책이 실시간 청킹 추론 의미를 구현하는지 여부.
이 정책이 generate_text를 구현하는지 여부(둘을 함께 오버라이드).
기본적으로 정확한 shape를 사용하여 서빙 전에 canonical inputs를 검증합니다.
resize 또는 누락된 입력을 mask하는 정책을 명시적으로 사용하는 경우, 이 계약이 재정의될 수 있습니다. 이러한 예외는 전송(transport)이 아닌 정책(policy)에 속합니다. 협상된 wire schema는 여전히 제공된 모든 feature의 shape을 고정합니다.
wrap_with_peft
< source >( peft_config = Nonepeft_cli_overrides: dict | None = None )
PEFT 어댑터로 이 정책을 감싸서 매개변수 효율적인 미세 조정을 수행합니다.
이 메서드는 PEFT 통합의 단일 진입점입니다. 하위 클래스는 기본 대상 모듈을 제공하기 위해 _get_default_peft_targets()를, 정책별 검증을 위해 _validate_peft_config()를 오버라이드해야 합니다.
PreTrainedConfig
class lerobot.configs.PreTrainedConfig
< source >( n_obs_steps: int = 1input_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>output_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>device: str | None = Nonedtype: torch.dtype | None = Noneuse_amp: bool = Falseuse_peft: bool = Falsepush_to_hub: bool = Truerepo_id: str | None = Noneprivate: bool | None = Nonetags: list[str] | None = Nonelicense: str | None = Nonepretrained_path: pathlib.Path | None = Nonepretrained_revision: str | None = None )
매개변수
- n_obs_steps — 정책(policy)에 전달할 환경 스텝 수만큼의 관측 값(현재 스텝과 그 이전의 추가 스텝을 포함).
- input_features — 정책의 입력 데이터에 대한 PolicyFeature를 정의하는 사전입니다. 키는 입력 데이터 이름을 나타내며, 값은 FeatureType과 shape 속성으로 구성된 PolicyFeature입니다.
- output_features — 정책의 출력 데이터에 대한 PolicyFeature를 정의하는 사전입니다. 키는 출력 데이터 이름을 나타내며, 값은 FeatureType과 shape 속성으로 구성된 PolicyFeature입니다.
- normalization_mapping — FeatureType의 str 값(예: “STATE”, “VISUAL”)을 해당하는 NormalizationMode(예: NormalizationMode.MIN_MAX)로 매핑하는 사전
정책 모델의 기본 구성 클래스입니다.
make_policy
lerobot.policies.make_policy
< source >( cfg: PreTrainedConfigds_meta: LeRobotDatasetMetadata | None = Noneenv_cfg: EnvConfig | None = Nonerename_map: dict[str, str] | None = Nonedefer_weight_load: bool = Falsepretrained_path: str | Path | None = None ) → PreTrainedPolicy
매개변수
- cfg (PreTrainedConfig) — 생성할 정책의 구성입니다.
cfg.pretrained_path가 설정되어 있으면 해당 경로에서 가중치를 로드하여 정책을 불러옵니다. - ds_meta (LeRobotDatasetMetadata | None) — feature의 shape과 type을 추론하는 데 사용되는 Dataset metadata. 정규화 레이어에 필요한 통계 정보도 제공합니다.
- env_cfg (EnvConfig | None) — feature의 shape와 type을 추론하는 데 사용되는 환경 구성입니다.
ds_meta또는env_cfg중 하나는 제공되어야 합니다. - rename_map (dict[str, str] | None) — 데이터셋 또는 환경의 feature 키를 정책의 예상 feature 이름과 일치시키기 위한 선택적 매핑 (예:
"left"→"camera1"). - defer_weight_load (bool) —
from_pretrained가 생성하는 것과 동일한 정책을 빌드합니다. 동일한 config 해석, 동일한 통계 기반 버퍼, 동일한 디바이스 배치 및 eval 모드를 사용하지만 safetensors 가중치 로딩을 건너뜁니다. DCP 체크포인트에서 재개할 때 사용하며, 이 경우 샤드된 가중치는accelerator.prepare()이후에 스트리밍됩니다(분산 체크포인트 엔진이 무작위 초기화를 덮어씀). PEFT 정책의 경우 어댑터 가중치만 건너뛰고, 베이스 가중치는 정상적으로 로드됩니다. - pretrained_path (str | Path | None) — 정책이 구축된 후에도 정책이 파인튜닝된 모델의 이름을 유지하는
cfg.pretrained_path대신 여기서 가중치(또는 PEFT 어댑터)를 로드합니다. 체크포인트에서 재개할 때 사용됩니다.
반환값
PreTrainedPolicy
인스턴스화되고 디바이스에 배치된 정책 모델.
다음 예외를 발생시킵니다
ValueError 또는 NotImplementedError
ValueError—ds_meta와env_cfg둘 다 제공되거나, 둘 다 제공되지 않은 경우.NotImplementedError— 지원되지 않는 policy-backend 조합을 사용하려고 할 때 (예: ‘mps’와 VQBeT).
정책 모델을 인스턴스화합니다.
이 팩토리 함수는 정책 생성 로직을 처리하며, 이를 위해 입력 및 출력 특징의 형태를 결정해야 합니다. 이러한 형태는 LeRobotDatasetMetadata 객체 또는 EnvConfig 객체에서 파생할 수 있습니다. 이 함수는 새 정책을 처음부터 초기화하거나 사전 학습된 정책을 로드할 수 있습니다.