# Políticas

Toda política herda de `PreTrainedPolicy`, que combina um `torch.nn.Module` com o mixin do Hub, de modo que qualquer política pode ser enviada e carregada do Hugging Face Hub com as mesmas duas chamadas.

Cada política possui seu próprio guia com receitas de treinamento e resultados — [ACT](../act), [SmolVLA](../smolvla), [π₀](../pi0), [π₀.₅](../pi05) e as demais estão listadas em Políticas. Para adicionar uma, consulte [Adicionando uma Política](../bring_your_own_policies).

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

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L73)

Classe base para modelos de política.

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

```python
chunk_inference_spec()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L308)

Declare o contrato padrão do autor para o fornecimento de blocos de observação atual.

A herança desta implementação declara que `predict_action_chunk` realiza todo o preparo necessário para os chamadores diretos, aceita a observação atual completa e retorna `[B, chunk_size, A]` nas coordenadas do modelo. Seu par de processadores canônico deve suportar chunks inteiros. `n_action_steps` é o slice de reprodução comum; o RTC retém o horizonte de previsão completo.

Uma política que exige preparação apenas com select_action, outros layouts de ação ou amostragem temporal deve sobrescrever este método e rejeitar configurações não suportadas ou fornecer um runner personalizado. A presença do método ou um warmup bem-sucedido não são evidência deste contrato. O estado da política/processor é permitido apenas dentro de uma sessão exclusiva e reset() deve limpá-lo para uma nova execução.

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

```python
count_queued_actions()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L263)

Número de ações já calculadas e aguardando para serem atendidas.

0 para uma política que não mantém nenhuma fila de ações (nunca faz chunking) ou cuja fila está atualmente vazia (prestes a calcular um novo chunk). Lê as mesmas filas que `drop_queued_actions` limpa, nomeadas em :attr:*_action_queue_attrs*.

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

```python
drop_queued_actions()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L245)

Descarte as ações pré-computadas por chamadas anteriores de `select_action`.

Força uma nova passagem de propagação direta no próximo `select_action`, para que uma mudança de condicionamento no meio do episódio (por exemplo, uma nova instrução) tenha efeito imediato, em vez de após o esvaziamento da fila. Diferente de `reset`, o restante do estado do episódio é mantido. Chame-o a partir da thread que chama `select_action`. Limpa as filas nomeadas em :attr:*_action_queue_attrs*; uma política que não mantém nenhuma fila de ações herda uma operação nula.

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L376)

**Parâmetros:**

batch (dict[str, Tensor]) : _descrição_

**Retorna:** tuple[Tensor, dict | None]

A perda e, potencialmente, outras informações. Além da perda, que é um Tensor, todos os outros itens devem ser compatíveis com log, tipos nativos do Python.

_resumo_

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L159)

A política é definida no modo de avaliação por padrão usando `policy.eval()` (os módulos de dropout são desativados). Para treiná-la, você deve primeiro redefinir o modo de treinamento com `policy.train()`.

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L363)

Execute a cabeça de texto da política em um lote de observações pré-processadas.

A solicitação viaja em `batch` como dados complementares (:data:*~lerobot.utils.constants.QUERY_KIND* / `QUERY_TEXT`); uma resposta de `next_subtask` é enviada diretamente para `set_task`, portanto, deve ser exatamente um subtask, não um plano ou uma lista numerada. Retorna o texto gerado e não deve mutar o estado que gera ações (filas, histórico de observações).

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

```python
get_optim_params()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L230)

Retorna os parâmetros específicos da política (parâmetros ou grupos de parâmetros) a serem passados para o otimizador.

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L389)

Retorna o chunk de ações (para políticas de chunking de ações) para uma observação dada, potencialmente em modo de lote.

Classes filhas que usam chunking de ações devem usar este método dentro de `select_action` para formar o chunk de ações em cache para seleção.

Uma política que suporta a palavra-chave `noise` inicia sua amostragem a partir desse tensor, com a forma que a política o geraria. Quando `noise` é None, a política o gera da maneira usual.

Pode retornar um `PolicyOutput` contendo o chunk e sua previsão, como no caso de `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)
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L431)

**Parâmetros:**

cfg (TrainPipelineConfig) : a configuração de treinamento; salva como *train_config.json* e usada para renderizar o cartão do modelo.

peft_model : O wrapper PEFT ao treinar adaptadores, cujos pesos substituem os pesos do modelo completo no repositório publicado. O valor padrão é None.

state_dict (dict[str, Tensor] | None) : Ignorado; os pesos agora são reunidos internamente quando a política é fragmentada. Padrão: None.

dataset_meta (LeRobotDatasetMetadata | None) : Metadados do dataset para o cartão do modelo, se disponíveis. Padrão: None.

Publique esta política no Hub.

Descontinuado: use `lerobot.common.train_utils.publish_trained_model()` em vez disso, que também publica os pré-processadores e pós-processadores junto com o modelo.

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

```python
reset()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L237)

Para ser chamado sempre que o ambiente for reiniciado.

Executa tarefas como a limpeza de caches.

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L405)

Retorne uma ação para executar no ambiente (possivelmente em modo de lote).

Quando o modelo utiliza um histórico de observações ou gera uma sequência de ações, este método trata o cache.

Retorna um tensor de ação simples ou um *PolicyOutput*: um lote, com chaves semelhantes ao lote de entrada, contendo a ação sob `"action"` e o que a política espera ou acredita além disso sob `"prediction"` (um *PolicyPrediction*). A previsão é loteada como a ação, com um valor por ambiente, e cada entrada é chaveada pelo que ela se refere: quadros previstos pela chave de observação que preveem, linguagem pelo estilo de anotação ("subtask", "plan", "memory"), caixas (esquema de anotação VQA) pela câmera em que são desenhadas. Os chamadores normalizam os dois tipos de retorno com *lerobot.processor.policy_output_to_transition*; *--display_data* exibe a previsão do primeiro ambiente.

Uma previsão contém valores para esta etapa: um que abrange um bloco (por exemplo, um clipe imaginado) é retornado peça por peça, com a ação à qual cada peça pertence. Cada entrada permanece exibida até ser retornada novamente. A previsão é opcional, ativada por um campo de configuração à escolha da política, e não deve alterar as ações; o texto que deve orientar a política passa por *generate_text*.

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

```python
supports_rtc()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L280)

Se esta política implementa a semântica de inferência de Real-Time Chunking.

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

```python
supports_text_generation()
```

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L359)

Se esta política implementa `generate_text` (substitua ambos juntos).

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L284)

Valide as entradas canônicas antes de servir, com formas exatas por padrão.

Políticas que redimensionam ou mascaram explicitamente entradas ausentes podem sobrescrever esse contrato. Tais exceções pertencem à política, nunca ao transporte. O esquema de fio negociado ainda fixa a forma de cada recurso fornecido.

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

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py#L471)

**Parâmetros:**

peft_config : Configuração opcional do adaptador PEFT (por exemplo, LoraConfig). Se fornecida, é usada diretamente (com as substituições da CLI aplicadas).

peft_cli_overrides : Dicionário opcional de substituições de CLI (method_type, target_modules, r, etc.). Esses valores são mesclados com os padrões da política para construir a configuração final.

Envolva esta política com adaptadores PEFT para ajuste fino eficiente em parâmetros.

Este método é o único ponto de entrada para a integração do PEFT. As subclasses devem sobrescrever `_get_default_peft_targets()` para fornecer os módulos de destino padrão e `_validate_peft_config()` para a validação específica da política.

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/configs/policies.py#L42)

**Parâmetros:**

n_obs_steps : Número de passos de ambiente de observações a passar para a política (inclui o passo atual e passos adicionais anteriores).

input_features : Um dicionário que define a PolicyFeature dos dados de entrada para a política. A chave representa o nome dos dados de entrada e o valor é a PolicyFeature, que consiste nos atributos FeatureType e shape.

output_features : Um dicionário que define a PolicyFeature dos dados de saída para a política. A chave representa o nome dos dados de saída e o valor é PolicyFeature, que consiste nos atributos FeatureType e shape.

normalization_mapping : Um dicionário que mapeia de um valor str de FeatureType (por exemplo, "STATE", "VISUAL") para um NormalizationMode correspondente (por exemplo, NormalizationMode.MIN_MAX)

Classe de configuração base para modelos de política.

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

[Fonte](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/factory.py#L255)

**Parâmetros:**

cfg (PreTrainedConfig) : A configuração da política a ser criada. Se `cfg.pretrained_path` estiver definido, a política será carregada com pesos a partir desse caminho.

ds_meta (LeRobotDatasetMetadata | None) : Metadados do dataset usados para inferir as formas e os tipos dos recursos. Também fornece estatísticas para as camadas de normalização.

env_cfg (EnvConfig | None) : Configuração de ambiente usada para inferir formas e tipos de recursos. É necessário fornecer um de `ds_meta` ou `env_cfg`.

rename_map (dict[str, str] | None) : Mapeamento opcional de chaves de recursos do conjunto de dados ou do ambiente para corresponder aos nomes esperados dos recursos da política (por exemplo, `"left"` → `"camera1"`).

defer_weight_load (bool) : Constrói a política exata que `from_pretrained` construiria — mesma resolução de configuração, mesmos buffers derivados de estatísticas, mesmo posicionamento de dispositivo e modo de avaliação — mas ignora o carregamento dos pesos em safetensors. Usado ao retomar de um checkpoint DCP, cujos pesos particionados são carregados em fluxo após `accelerator.prepare()` (o mecanismo de checkpoint distribuído sobrescreve a inicialização aleatória). Para uma política PEFT, apenas os pesos do adaptador são ignorados; os pesos da base são carregados normalmente.

pretrained_path (str | Path | None) : Carrega os pesos (ou adaptador PEFT) daqui em vez de `cfg.pretrained_path`, que mantém o nome do modelo a partir do qual a política foi ajustada uma vez que a política é construída. Usado ao retomar de um checkpoint.

**Retorna:** `PreTrainedPolicy`

Um modelo de política instanciado e posicionado em um dispositivo.

**Exceções:** ``ValueError`` ou ``NotImplementedError``

- ``ValueError`` -- Se ambos ou nenhum de `ds_meta` e `env_cfg` forem fornecidos.
- ``NotImplementedError`` -- Se você tentar usar uma combinação de política e backend não suportada (por exemplo, VQBeT com 'mps').

Instanciar um modelo de política.

Esta função de fábrica trata da lógica de criação de uma política, o que requer determinar as formas das características de entrada e saída. Essas formas podem ser derivadas de um objeto `LeRobotDatasetMetadata` ou de um objeto `EnvConfig`. A função pode inicializar uma nova política do zero ou carregar uma pré-treinada.