# Политики

Каждая политика наследует `PreTrainedPolicy`, которая объединяет `torch.nn.Module` с миксином Hub, поэтому любую политику можно отправить в Hugging Face Hub и загрузить из него с помощью тех же двух вызовов.

У каждой политики есть собственное руководство с рецептами обучения и результатами — [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)

Объявите контракт по умолчанию для обслуживания чанков текущих наблюдений.

Наследование этой реализации означает, что `predict_action_chunk` выполняет всю подготовку, необходимую для прямых вызовов, принимает полное текущее наблюдение и возвращает `[B, chunk_size, A]` в координатах модели. Его каноническая пара процессоров должна поддерживать целые чанки. `n_action_steps` — это обычный срез воспроизведения; RTC сохраняет полный горизонт предсказания.

Политика, требующая подготовки только select_action, другие раскладки действий или временную выборку, должна переопределить этот метод и отклонять неподдерживаемые конфигурации или предоставлять собственный раннер. Наличие метода или успешный warmup не являются подтверждением этого контракта. Состояние политики/процессора допускается только в рамках эксклюзивной сессии, а 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`, чтобы изменение условий в середине эпизода (например, новая инструкция) вступило в силу немедленно, а не после опустошения очереди. В отличие от `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]

Потери и, возможно, другую информацию. Помимо потерь, которые являются объектом 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()` (модули dropout отключаются). Для обучения её необходимо сначала вернуть в режим обучения с помощью `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)

Запустите текстовую головку политики на предварительно обработанной партии наблюдений.

Запрос передаётся в `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)

Возвращает блок действий (для политик с разбиением действий на блоки) для данного наблюдения, потенциально в режиме батча.

Дочерние классы, использующие чанкинг действий, должны вызывать этот метод внутри `select_action`, чтобы сформировать кэшированный чанк действий для выбора.

Политика, поддерживающая ключевое слово `noise`, начинает выборку с этого тензора, имеющего форму, которую политика использовала бы для его генерации. Если `noise` равно None, политика генерирует его в обычном порядке.

Может возвращать `PolicyOutput`, содержащий фрагмент и его предсказание, как в случае с `select_action`.

#### 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)

Возвращает одно действие для выполнения в среде (возможно, в режиме пакетной обработки).

Когда модель использует историю наблюдений или выводит последовательность действий, этот метод занимается кэшированием.

Возвращает «голый» тензор действия или *PolicyOutput*: батч, структурированный аналогично входному батчу, содержащий действие под ключом `"action"` и то, что политика ожидает или считает верным помимо него, под ключом `"prediction"` (объект *PolicyPrediction*). Прогноз батчится так же, как и действие, по одному значению на окружение, и каждый элемент ключируется по тому, на что он ссылается: предсказанные кадры — по ключу наблюдения, которое они предсказывают; язык — по стилю аннотации ("subtask", "plan", "memory"); рамки (схема аннотации VQA) — по камере, на которой они нарисованы. Вызывающий код нормализует два типа возвращаемых значений с помощью *lerobot.processor.policy_output_to_transition*; *--display_data* показывает прогноз для первого окружения.

Предсказание содержит значения для текущего шага: одно значение, охватывающее чанк (например, воображаемый клип), возвращается по частям, вместе с действием, к которому относится каждая часть. Каждая запись остаётся отображённой, пока не будет возвращена снова. Предсказание включается опционально через поле конфигурации, определяемое политикой, и не должно изменять действия; текст, который должен направлять политику, передаётся через *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)

Определяет, реализует ли данная политика семантику инференса с Real-Time Chunking.

#### 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)

Валидуйте канонические входные данные перед обслуживанием, по умолчанию с точными формами.

Политики, которые явно изменяют размер или маскируют отсутствующие входные данные, могут переопределять этот контракт. Подобные исключения относятся к политике, а не к транспорту. Согласованная схема передачи по-прежнему фиксирует форму каждой переданной характеристики.

#### 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 и т. д.). Они объединяются с параметрами по умолчанию из политики для формирования итогового конфигурационного файла.

Оберните эту политику адаптерами 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 : Количество шагов среды, наблюдения с которых передаются в политику (текущий шаг и дополнительные шаги, идущие назад).

input_features : Словарь, определяющий PolicyFeature входных данных для политики. Ключ представляет имя входных данных, а значением является PolicyFeature, состоящий из атрибутов FeatureType и shape.

output_features : Словарь, определяющий PolicyFeature выходных данных для политики. Ключ представляет имя выходных данных, а значением является PolicyFeature, состоящий из атрибутов FeatureType и shape.

normalization_mapping : словарь, сопоставляющий значение str типа FeatureType (например, "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) : Метаданные набора данных, используемые для определения форм и типов признаков. Также предоставляют статистику для слоёв нормализации.

env_cfg (EnvConfig | None) : Конфигурация окружения, используемая для определения форм и типов признаков. Необходимо указать один из `ds_meta` или `env_cfg`.

rename_map (dict[str, str] | None) : Необязательное сопоставление ключей признаков набора данных или среды с ожидаемыми именами признаков политики (например, `"left"` → `"camera1"`).

defer_weight_load (bool) : Построить точную политику, которую построил бы `from_pretrained` — с тем же разрешением конфигурации, теми же буферами, производными от статистики, тем же размещением на устройстве и режимом eval, — но пропустить загрузку весов из safetensors. Используется при возобновлении из контрольной точки DCP, где разбитые на части веса загружаются потоком после `accelerator.prepare()` (движок распределённых контрольных точек перезаписывает случайную инициализацию). Для PEFT-политики пропускается загрузка только весов адаптеров, базовые веса загружаются как обычно.

pretrained_path (str | Path | None) : Загружать веса (или адаптер PEFT) отсюда, а не из `cfg.pretrained_path`, который сохраняет имя модели, из которой была обучена политика, после её построения. Используется при возобновлении обучения из контрольной точки.

**Возвращает:** `PreTrainedPolicy`

Модель политики, инициализированная и размещённая на устройстве.

**Исключения:** ``ValueError`` или ``NotImplementedError``

- ``ValueError`` -- если указаны оба параметра `ds_meta` и `env_cfg` или ни один из них.
- ``NotImplementedError`` -- Если попытаться использовать неподдерживаемую комбинацию политики и бэкенда (например, VQBeT с 'mps').

Создайте модель политики.

Эта фабричная функция управляет логикой создания политики, для чего необходимо определить формы входных и выходных признаков. Эти формы можно получить либо из объекта `LeRobotDatasetMetadata`, либо из объекта `EnvConfig`. Функция может как инициализировать новую политику с нуля, так и загрузить предобученную.