LeRobot documentation
Políticas
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, SmolVLA, π₀, π₀.₅ e as demais estão listadas em Políticas. Para adicionar uma, consulte Adicionando uma Política.
PreTrainedPolicy
Classe base para modelos de política.
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ônicos 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.
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.
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, de modo 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
< source >( batch: dict[str, Tensor] ) → tuple[Tensor, dict | None]
resumo
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 )
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().
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 alterar o estado que gera ações (filas, histórico de observações).
Retorna os parâmetros específicos da política (parâmetros ou grupos de parâmetros) a serem passados para o otimizador.
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
cacheado 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 desenharia. Quando noise é None, a política o desenha como de costume.
Pode retornar um PolicyOutput contendo o chunk e sua previsão, como no caso de select_action.
push_model_to_hub
< source >( cfg: TrainPipelineConfigpeft_model = Nonestate_dict: dict[str, Tensor] | None = Nonedataset_meta: LeRobotDatasetMetadata | None = None )
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 está fragmentada. O valor 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.
Para ser chamado sempre que o ambiente for reiniciado.
Executa tarefas como a limpeza de caches.
Retorne uma ação para executar no ambiente (possivelmente em modo de lote).
Quando o modelo usa um histórico de observações, ou produz uma sequência de ações, este método lida com 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, um valor
por ambiente, e cada entrada é chaveada pelo que ela se refere: quadros previstos pela
chave de observação que eles 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 mostra
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 escolhido pela política, e não deve alterar as ações; o texto que deve orientar a política passa por generate_text.
Se esta política implementa a semântica de inferência de Real-Time Chunking.
Se esta política implementa generate_text (substitua ambos juntos).
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
< source >( peft_config = Nonepeft_cli_overrides: dict | None = None )
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.) Essas substituições são mescladas 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 validação específica de política.
PreTrainedConfig
classe 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 )
Parâmetros
- n_obs_steps — Número de passos de ambiente de observações a passar para a política (considera o passo atual e passos adicionais anteriores).
- input_features — Um dicionário que define a PolicyFeature dos dados de entrada para a policy. 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 policy. A chave representa o nome dos dados de saída e o valor é a PolicyFeature, que consiste nos atributos FeatureType e shape.
- normalization_mapping — Um dicionário que mapeia um valor str de FeatureType (por exemplo, “STATE”, “VISUAL”) para o NormalizationMode correspondente (por exemplo, NormalizationMode.MIN_MAX)
Classe de configuração base para modelos de política.
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
Parâmetros
- cfg (PreTrainedConfig) — A configuração da política a ser criada. Se
cfg.pretrained_pathestiver 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 tipos dos recursos. Também fornece estatísticas para as camadas de normalização.
- env_cfg (EnvConfig | None) — Configuração do ambiente usada para inferir as formas e
tipos dos recursos. É necessário fornecer um de
ds_metaouenv_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_pretrainedconstruiria — 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 apósaccelerator.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 deds_metaeenv_cfgforem fornecidos.NotImplementedError— Se 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.