# 정책

모든 정책은 `PreTrainedPolicy`를 상속하며, 이는 `torch.nn.Module`과 Hub 믹신을 결합한 것입니다. 따라서 모든 정책을 동일한 두 가지 호출을 통해 Hugging Face Hub에 push하고 로드할 수 있습니다.

각 정책에는 학습 레시피와 결과가 포함된 전용 가이드가 있습니다. [ACT](../act), [SmolVLA](../smolvla), [π₀](../pi0), [π₀.₅](../pi05) 및 기타 정책은 Policies 섹션에 나열되어 있습니다. 정책을 추가하는 방법은 [Adding a Policy](../bring_your_own_policies)를 참고하세요.

## PreTrainedPolicy[[lerobot.policies.PreTrainedPolicy]]

#### lerobot.policies.PreTrainedPolicy[[lerobot.policies.PreTrainedPolicy]]

```python
lerobot.policies.PreTrainedPolicy(config: PreTrainedConfig, *inputs, **kwargs)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L73)

정책 모델의 베이스 클래스입니다.

#### chunk_inference_spec[[lerobot.policies.PreTrainedPolicy.chunk_inference_spec]]

```python
chunk_inference_spec()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L308)

기본 현재 관찰 청크 서빙(author) 계약을 선언합니다.

이 구현을 상속하면 `predict_action_chunk`가 직접 호출자가 필요한 모든 준비 작업을 수행하고, 현재 관찰의 전체를 받아들이며, 모델 좌표계에서 `[B, chunk_size, A]`를 반환한다고 선언합니다. 해당 표준 프로세서 쌍은 전체 청크를 지원해야 합니다. `n_action_steps`는 일반적인 재생 슬라이스이며, RTC는 전체 예측 지평선을 유지합니다.

select_action 전용 준비, 다른 action 레이아웃, 또는 시간적 샘플링을 요구하는 정책은 이 메서드를 오버라이드하여 지원되지 않는 구성을 거부하거나 사용자 정의 러너를 제공해야 합니다. 메서드의 존재나 성공적인 warmup은 이 계약에 대한 증거가 아닙니다. Policy/processor 상태는 전용 세션 내에서만 허용되며, reset()은 새로운 실행을 위해 이를 초기화해야 합니다.

#### count_queued_actions[[lerobot.policies.PreTrainedPolicy.count_queued_actions]]

```python
count_queued_actions()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L263)

이미 계산되어 제공을 기다리고 있는 작업의 수.

행동 큐를 유지하지 않는 정책(즉, 청킹을 하지 않는 정책) 또는 현재 큐가 비어 있는 경우(새로운 청크를 계산하려는 경우)에는 0을 반환합니다. `drop_queued_actions`가 지우는 것과 동일한 큐를 읽으며, 해당 큐는 :attr:*_action_queue_attrs*에 이름이 지정되어 있습니다.

#### drop_queued_actions[[lerobot.policies.PreTrainedPolicy.drop_queued_actions]]

```python
drop_queued_actions()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L245)

이전 `select_action` 호출에서 사전 계산된 작업을 폐기합니다.

다음 `select_action`에서 새로운 forward pass를 강제하여, 에피소드 중간에 발생한 조건부 변경(예: 새로운 지시문)이 큐가 비워진 후에가 아니라 즉시 적용되도록 합니다. `reset`과 달리 에피소드 상태의 나머지는 유지됩니다. `select_action`를 호출하는 스레드에서 호출해야 합니다. :attr:*_action_queue_attrs*에 나열된 큐를 비웁니다. 액션 큐를 유지하지 않는 정책은 no-op를 상속받습니다.

#### forward[[lerobot.policies.PreTrainedPolicy.forward]]

```python
forward(batch: dict[str, Tensor])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L376)

**매개변수:**

batch (dict[str, Tensor]) : _설명_

**반환값:** tuple[Tensor, dict | None]

손실(loss) 및 잠재적으로 다른 정보. Tensor인 손실을 제외한 모든 항목은 로깅에 적합해야 하며, 네이티브 Python 타입이어야 합니다.

_요약_

#### from_pretrained[[lerobot.policies.PreTrainedPolicy.from_pretrained]]

```python
from_pretrained(pretrained_name_or_path: str | Path, config: PreTrainedConfig | None = None, force_download: bool = False, resume_download: bool | None = None, proxies: dict | None = None, token: str | bool | None = None, cache_dir: str | Path | None = None, local_files_only: bool = False, revision: str | None = None, strict: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L159)

`policy.eval()`을 사용하여 기본적으로 정책이 평가 모드로 설정됩니다(드롭아웃 모듈은 비활성화됨). 학습하려면 먼저 `policy.train()`을 사용하여 학습 모드로 되돌려야 합니다.

#### generate_text[[lerobot.policies.PreTrainedPolicy.generate_text]]

```python
generate_text(batch: dict[str, Any])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L363)

policy의 텍스트 헤드를 전처리된 관찰 배치에 실행합니다.

요청은 `batch`에 보완 데이터(:data:*~lerobot.utils.constants.QUERY_KIND* / `QUERY_TEXT`)로 실립니다. `next_subtask` 응답은 `set_task`에 바로 전달되므로, 계획이나 번호 매겨진 목록이 아닌 정확히 하나의 서브태스크여야 합니다. 생성된 텍스트를 반환하며, 액션 생성 상태(큐, 관찰 히스토리)를 변경해서는 안 됩니다.

#### get_optim_params[[lerobot.policies.PreTrainedPolicy.get_optim_params]]

```python
get_optim_params()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L230)

옵티마이저에 전달할 정책별 매개변수(매개변수 또는 매개변수 그룹)를 반환합니다.

#### predict_action_chunk[[lerobot.policies.PreTrainedPolicy.predict_action_chunk]]

```python
predict_action_chunk(batch: dict[str, Tensor], **kwargs: Unpack[ActionSelectKwargs])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L389)

observation에 대해 (action chunking 정책을 사용하는 경우) action chunk를 반환합니다. 배치 모드일 수 있습니다.

액션 청킹을 사용하는 하위 클래스는 `select_action` 내에서 이 메서드를 사용하여 선택을 위해 캐시된 액션 청크를 형성해야 합니다.

`noise` 키워드를 지원하는 정책은 해당 텐서를 시작점으로 삼아 샘플링을 시작하며, 이 텐서의 모양은 정책이 샘플을 추출할 때 사용하는 모양과 동일합니다. `noise`가 None인 경우, 정책은 평소와 같이 샘플을 추출합니다.

`select_action`과 마찬가지로, 청크와 그 예측을 포함하는 `PolicyOutput`을 반환할 수 있습니다.

#### push_model_to_hub[[lerobot.policies.PreTrainedPolicy.push_model_to_hub]]

```python
push_model_to_hub(cfg: TrainPipelineConfig, peft_model = None, state_dict: dict[str, Tensor] | None = None, dataset_meta: LeRobotDatasetMetadata | None = None)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L431)

**매개변수:**

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()`을 대신 사용하세요.

#### 초기화[[lerobot.policies.PreTrainedPolicy.reset]]

```python
reset()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L237)

환경이 리셋될 때마다 호출됩니다.

캐시 정리와 같은 작업을 수행합니다.

#### select_action[[lerobot.policies.PreTrainedPolicy.select_action]]

```python
select_action(batch: dict[str, Tensor], **kwargs: Unpack[ActionSelectKwargs])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L405)

환경에서 실행할 하나의 액션을 반환합니다(배치 모드일 수 있음).

모델이 관찰의 이력을 사용하거나 동작의 시퀀스를 출력하는 경우, 이 메서드는 캐싱을 처리합니다.

bare action tensor 또는 *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*를 통해 전달됩니다.

#### supports_rtc[[lerobot.policies.PreTrainedPolicy.supports_rtc]]

```python
supports_rtc()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L280)

이 정책이 실시간 청킹 추론 의미를 구현하는지 여부.

#### supports_text_generation[[lerobot.policies.PreTrainedPolicy.supports_text_generation]]

```python
supports_text_generation()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L359)

이 정책이 `generate_text`를 구현하는지 여부(둘을 함께 오버라이드).

#### validate_chunk_input_features[[lerobot.policies.PreTrainedPolicy.validate_chunk_input_features]]

```python
validate_chunk_input_features(features: tuple[FeatureSpec, ...])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L284)

기본적으로 정확한 shape를 사용하여 서빙 전에 canonical inputs를 검증합니다.

resize 또는 누락된 입력을 mask하는 정책을 명시적으로 사용하는 경우, 이 계약이 재정의될 수 있습니다. 이러한 예외는 전송(transport)이 아닌 정책(policy)에 속합니다. 협상된 wire schema는 여전히 제공된 모든 feature의 shape을 고정합니다.

#### wrap_with_peft[[lerobot.policies.PreTrainedPolicy.wrap_with_peft]]

```python
wrap_with_peft(peft_config = None, peft_cli_overrides: dict | None = None)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/pretrained.py#L471)

**매개변수:**

peft_config : 선택 사항인 PEFT 어댑터 구성(예: LoraConfig). 제공되면 CLI 오버라이드가 적용된 상태로 직접 사용됩니다.

peft_cli_overrides : 선택 사항. CLI 오버라이드(예: method_type, target_modules, r 등)를 담는 dict입니다. 정책 기본값과 병합되어 최종 구성을 생성합니다.

PEFT 어댑터로 이 정책을 감싸서 매개변수 효율적인 미세 조정을 수행합니다.

이 메서드는 PEFT 통합의 단일 진입점입니다. 하위 클래스는 기본 대상 모듈을 제공하기 위해 `_get_default_peft_targets()`를, 정책별 검증을 위해 `_validate_peft_config()`를 오버라이드해야 합니다.

## PreTrainedConfig[[lerobot.configs.PreTrainedConfig]]

#### lerobot.configs.PreTrainedConfig[[lerobot.configs.PreTrainedConfig]]

```python
lerobot.configs.PreTrainedConfig(n_obs_steps: int = 1, input_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>, output_features: dict[str, lerobot.configs.types.PolicyFeature] | None = <factory>, device: str | None = None, dtype: torch.dtype | None = None, use_amp: bool = False, use_peft: bool = False, push_to_hub: bool = True, repo_id: str | None = None, private: bool | None = None, tags: list[str] | None = None, license: str | None = None, pretrained_path: pathlib.Path | None = None, pretrained_revision: str | None = None)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/configs/policies.py#L42)

**매개변수:**

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

#### lerobot.policies.make_policy[[lerobot.policies.make_policy]]

```python
lerobot.policies.make_policy(cfg: PreTrainedConfig, ds_meta: LeRobotDatasetMetadata | None = None, env_cfg: EnvConfig | None = None, rename_map: dict[str, str] | None = None, defer_weight_load: bool = False, pretrained_path: str | Path | None = None)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/policies/factory.py#L255)

**매개변수:**

cfg (PreTrainedConfig) : 생성할 정책의 구성입니다. `cfg.pretrained_path`가 설정되어 있으면 해당 경로에서 가중치를 로드하여 정책을 로드합니다.

ds_meta LeRobotDatasetMetadata | None: feature의 shape과 type을 추론하는 데 사용되는 Dataset 메타데이터. 정규화 레이어에 필요한 통계 정보도 제공합니다.

env_cfg (EnvConfig | None) : 기능의 형태와 타입을 추론하는 데 사용되는 환경 구성입니다. `ds_meta` 또는 `env_cfg` 중 하나는 제공되어야 합니다.

rename_map (dict[str, str] | None) : 데이터셋 또는 환경의 특징 키를 예상되는 정책 특징 이름과 일치시키기 위한 선택적 매핑 (예: `"left"` → `"camera1"`).

defer_weight_load (bool) : `from_pretrained`가 생성하는 것과 동일한 정책을 빌드합니다 — 동일한 config 해석, 동일한 stats 기반 버퍼, 동일한 device 배치 및 eval mode — 하지만 safetensors 가중치 로딩은 건너뜁니다. DCP 체크포인트에서 재개할 때 사용되며, 이 경우 샤드된 가중치는 `accelerator.prepare()` 이후에 스트리밍됩니다(분산 체크포인트 엔진이 랜덤 초기화를 덮어씀). PEFT 정책의 경우 어댑터 가중치만 건너뛰고, 베이스 가중치는 정상적으로 로드됩니다.

pretrained_path (str | Path | None) : 정책이 구축된 후 정책이 파인튜닝된 모델의 이름을 유지하는 `cfg.pretrained_path` 대신, 여기서 가중치(또는 PEPT 어댑터)를 로드합니다. 체크포인트에서 재개할 때 사용됩니다.

**반환값:** `PreTrainedPolicy`

인스턴스화되고 디바이스에 배치된 정책 모델.

**예외:** ``ValueError`` 또는 ``NotImplementedError``

- ``ValueError`` -- `ds_meta`와 `env_cfg` 둘 다 제공되거나, 둘 다 제공되지 않은 경우.
- ``NotImplementedError`` -- 지원되지 않는 정책-백엔드 조합을 사용하려고 할 때 (예: VQBeT와 'mps').

정책 모델을 인스턴스화합니다.

이 팩토리 함수는 정책 생성 로직을 처리하며, 이를 위해 입력 및 출력 특징의 형태를 결정해야 합니다. 이러한 형태는 `LeRobotDatasetMetadata` 객체 또는 `EnvConfig` 객체에서 파생할 수 있습니다. 이 함수는 새 정책을 처음부터 초기화하거나 사전 학습된 정책을 로드할 수 있습니다.