Hugging Face's logo

LeRobot documentation

Processadores

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Processadores

Processadores são a camada de transformação de dados entre um robô, um conjunto de dados e uma política. Um pipeline é uma cadeia de ProcessorSteps; cada etapa declara como transforma tanto os dados quanto o contrato de recursos.

Consulte Introdução aos Processadores de Robôs para os conceitos, Implemente seu próprio processador para escrever uma etapa e Depure seu pipeline de processador quando um pipeline se comportar de forma inesperada.

ProcessorStep

classe lerobot.processor.ProcessorStep

< >

( )

Classe base abstrata para uma etapa única em um pipeline de processamento de dados.

Cada etapa deve implementar o método __call__ para executar sua transformação em uma transição de dados e o método transform_features para descrever como ele altera a forma ou o tipo dos recursos de dados.

Subclasses podem, opcionalmente, ser com estado ao implementar state_dict e load_state_dict.

get_config

< >

( )

Retorna a configuração da etapa para serialização.

load_state_dict

< >

( state: dict[str, torch.Tensor] )

Parâmetros

  • state — Um dicionário de tensores de estado.

Carrega o estado da etapa a partir de um dicionário de estado.

reset

< >

( )

Redefine o estado interno da etapa do processador, se houver.

save_artifacts

< >

( save_directory: Path )

Salve ativos não tensoriais e mapeie os argumentos do construtor para caminhos relativos.

state_dict

< >

( )

Retorna o estado da etapa (por exemplo, parâmetros aprendidos, médias em execução).

transform_features

< >

( features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

Parâmetros

  • features — Um dicionário descrevendo os recursos de entrada para observações, ações, etc.

Define como esta etapa modifica a descrição dos recursos do pipeline.

Este método é usado para rastrear alterações nas formas dos dados, nos dtypes ou nas modalidades à medida que os dados fluem pelo pipeline, sem a necessidade de processar dados reais.

DataProcessorPipeline

classe lerobot.processor.DataProcessorPipeline

< >

( steps: Sequence[ProcessorStep] = <factory>name: str = 'DataProcessorPipeline'to_transition: Callable[[TInput], EnvTransition] = <factory>to_output: Callable[[EnvTransition], TOutput] = <factory>before_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory>after_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory> )

Parâmetros

  • steps — Uma sequência de objetos ProcessorStep que compõem o pipeline.
  • name — Um nome descritivo para o pipeline.
  • to_transition — Uma função para converter dados de entrada brutos no formato padronizado EnvTransition.
  • to_output — Uma função para converter o EnvTransition final no formato de saída desejado.
  • before_step_hooks — Uma lista de funções a serem chamadas antes de cada etapa ser executada.
  • after_step_hooks — Uma lista de funções a serem chamadas após a execução de cada etapa.

Um pipeline sequencial para processamento de dados, integrado ao Hugging Face Hub.

Esta classe encadeia múltiplas instâncias de ProcessorStep para formar um fluxo de trabalho completo de processamento de dados. Ela é genérica, permitindo tipos de entrada e saída personalizados, que são tratados pelos conversores to_transition e to_output.

from_config

< >

( config: dict[str, Any]state_dict: dict[str, dict[str, torch.Tensor]] | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None )

Parâmetros

  • config — Um dicionário de configuração com a mesma estrutura do JSON do processador salvo.
  • state_dict — Estado opcional do pipeline em memória, agrupado por chave de estado sem sufixo.
  • overrides — Sobrescritas opcionais do construtor, indexadas pelo nome do registro ou pelo nome da classe.
  • to_transition — Conversor opcional dos dados de entrada para EnvTransition.
  • to_output — Conversor opcional de EnvTransition para dados de saída.

Construa um pipeline a partir de uma configuração em memória e tensores de estado opcionais.

from_pretrained

< >

( pretrained_model_name_or_path: str | Pathconfig_filename: strforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict[str, str] | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None**kwargs )

Parâmetros

  • pretrained_model_name_or_path — O identificador do repositório no Hugging Face Hub, um caminho para um diretório local ou um caminho para um arquivo de configuração único.
  • config_filename — O nome do arquivo de configuração JSON do pipeline. Sempre obrigatório para evitar ambiguidade quando existem múltiplas configurações (por exemplo, pré-processador vs. pós-processador).
  • force_download — Se deve forçar o (re)download dos arquivos.
  • resume_download — Mantido para compatibilidade com versões anteriores e ignorado. Os downloads retomam automaticamente.
  • proxies — Mantido para compatibilidade com versões anteriores e ignorado. Use HTTP_PROXY e HTTPS_PROXY em vez disso.
  • token — O token a ser usado como autorização HTTP bearer para repositórios privados do Hub.
  • cache_dir — O caminho para uma pasta de cache específica para armazenar os arquivos baixados.
  • local_files_only — Se True, evita o download de arquivos do Hub.
  • revision — A versão específica do modelo a ser usada (por exemplo, um nome de branch, nome de tag ou id de commit).
  • overrides — Um dicionário para sobrescrever a configuração de etapas específicas. As chaves devem corresponder ao nome da classe ou ao nome no registro da etapa.
  • to_transition — Uma função personalizada para converter os dados de entrada em EnvTransition.
  • to_output — Uma função personalizada para converter o EnvTransition final para o formato de saída.
  • **kwargs — Argumentos adicionais (não utilizados).

Exceções

FileNotFoundError ou ValueError ou ImportError ou KeyError ou ProcessorMigrationError

  • FileNotFoundError — Se o arquivo de configuração não puder ser encontrado.
  • ValueError — Se a configuração for ambígua ou a instanciação falhar.
  • ImportError — Se a classe de uma etapa não puder ser importada.
  • KeyError — Se uma chave de substituição não corresponder a nenhuma etapa do pipeline.
  • ProcessorMigrationError — Se o modelo exigir migração para o formato de processador.

Carrega um pipeline de um diretório local, de um arquivo único ou de um repositório do Hugging Face Hub.

Este método implementa um pipeline de carregamento simplificado com detecção inteligente de migração:

Estratégia de carregamento simplificada:

  1. Carregamento de configuração (_load_config):

    • Diretório: Carrega o config_filename especificado do diretório
    • Arquivo único: Carrega o arquivo diretamente (config_filename é ignorado)
    • Repositório do Hub: Baixe o config_filename especificado do Hub

  2. Validação de Configuração (_validate_loaded_config):

    • Validação de formato: Verifique se a configuração está em um formato de processador válido
    • Detecção de migração: oriente os usuários a migrar modelos antigos do LeRobot
    • Erros claros: Forneça mensagens de erro acionáveis

  3. Construção de etapas (_build_steps_with_overrides):

    • Resolução de classes: consulta ao registro ou importações dinâmicas
    • Sobrescrita de mesclagem: os parâmetros do usuário sobrescrevem a configuração salva
    • Carregamento de estado: Carregue arquivos .safetensors para etapas com estado

  4. Sobrescrita de Validação (_validate_overrides_used):

    • Garanta que todas as substituições do usuário foram aplicadas (detecte erros de digitação)
    • Forneça mensagens de erro úteis com as chaves disponíveis

Deteção de Migração:

  • Detecção inteligente: Analisa arquivos JSON para detectar modelos antigos do LeRobot
  • Alvo preciso: Evita falsos positivos em outros modelos do HuggingFace
  • Guias claros: Fornece o comando exato de migração para executar
  • Modo de erro: Sempre levanta ProcessorMigrationError para ação clara do usuário

Carregando exemplos:

# Directory loading
pipeline = DataProcessorPipeline.from_pretrained("/models/my_model", config_filename="processor.json")

# Single file loading
pipeline = DataProcessorPipeline.from_pretrained(
    "/models/my_model/processor.json", config_filename="processor.json"
)

# Hub loading
pipeline = DataProcessorPipeline.from_pretrained("user/repo", config_filename="processor.json")

# Multiple configs (preprocessor/postprocessor)
preprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_preprocessor.json"
)
postprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_postprocessor.json"
)

Sistema de Substituição:

  • Correspondência de chaves: Use nomes de registro ou nomes de classe como chaves de substituição
  • Mesclagem de configurações: as substituições do usuário têm precedência sobre a configuração salva
  • Validação: Verifique se todas as chaves de substituição correspondem a etapas reais (detectar erros de digitação)
  • Exemplo: overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

< >

( )

Retorna a configuração do pipeline serializável em JSON.

load_state_dict

< >

( state_dict: dict[str, dict[str, torch.Tensor]] )

Parâmetros

  • state_dict — Um dicionário que mapeia chaves de estado sem sufixo para dicionários de estado de etapa.

Exceções

KeyError

  • KeyError — Se o carregamento encontrar estado esperado ausente ou estado extra inesperado.

Carregue os tensores do estado do pipeline nas etapas existentes.

process_action

< >

( action: PolicyAction | RobotAction | EnvAction )

Parâmetros

  • action — Os dados da ação.

Processa apenas a parte de ação de uma transição por meio do pipeline.

process_complementary_data

< >

( complementary_data: dict[str, Any] )

Parâmetros

  • complementary_data — O dicionário de dados complementares.

Processa apenas a parte de dados complementares de uma transição através do pipeline.

process_done

< >

( done: bool | torch.Tensor )

Parâmetros

  • done — A flag done.

Processa apenas a flag done de uma transição por meio do pipeline.

process_info

< >

( info: dict[str, Any] )

Parâmetros

  • info — O dicionário de informações.

Processa apenas o dicionário de informações de uma transição por meio do pipeline.

process_observation

< >

( observation: RobotObservation )

Parâmetros

  • observation — O dicionário de observação.

Processa apenas a parte de observação de uma transição por meio do pipeline.

process_reward

< >

( reward: float | torch.Tensor )

Parâmetros

  • reward — O valor da recompensa.

Processa apenas a parte de recompensa de uma transição por meio do pipeline.

process_truncated

< >

( truncated: bool | torch.Tensor )

Parâmetros

  • truncated — A flag truncada.

Processa apenas a flag truncada de uma transição através do pipeline.

register_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Parâmetros

  • fn — Uma função chamável que aceita o índice da etapa e a transição atual.

Registra uma função para ser chamada após cada etapa.

register_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Parâmetros

  • fn — Uma função chamável que aceita o índice da etapa e a transição atual.

Registra uma função para ser chamada antes de cada etapa.

reset

< >

( )

Redefine o estado de todas as etapas com estado no pipeline.

save_pretrained

< >

( save_directory: str | Path | None = Nonerepo_id: str | None = Nonepush_to_hub: bool = Falsecard_kwargs: dict[str, Any] | None = Noneconfig_filename: str | None = None**push_to_hub_kwargs )

Parâmetros

  • save_directory — O diretório onde o pipeline será salvo. Se for None, salva em HF_LEROBOT_HOME/processors/{sanitized_pipeline_name}.
  • repo_id — ID do seu repositório no Hub. Usado apenas se push_to_hub=true.
  • push_to_hub — Se o seu objeto deve ser enviado para o Hugging Face Hub após ser salvo.
  • card_kwargs — Argumentos adicionais passados para o modelo de cartão para personalizar o cartão.
  • config_filename — O nome do arquivo de configuração JSON. Se for None, um nome é gerado a partir do atributo name do pipeline.
  • **push_to_hub_kwargs — Argumentos de palavra-chave adicionais passados ao método push_to_hub.

Salva a configuração e o estado do pipeline em um diretório.

Este método cria um arquivo de configuração JSON que define a estrutura do pipeline (nome e etapas). Para cada etapa com estado, ele também salva um arquivo .safetensors contendo seu dicionário de estado.

state_dict

< >

( )

Retorna os tensores de estado do pipeline agrupados por chave de estado.

step_through

< >

( data: TInput )

Parâmetros

  • data — Os dados de entrada.

Processa os dados passo a passo, gerando a transição em cada etapa.

Este é um método gerador útil para depuração e inspeção do estado intermediário dos dados à medida que passam pelo pipeline.

transform_features

< >

( initial_features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

Parâmetros

  • initial_features — Um dicionário descrevendo os recursos iniciais.

Aplica as transformações de recursos de todas as etapas sequencialmente.

Este método propaga um dicionário de descrição de recursos através do método transform_features de cada etapa, permitindo que o pipeline determine estaticamente a especificação dos recursos de saída sem processar nenhum dado real.

unregister_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Parâmetros

  • fn — O objeto de função exato que foi registrado anteriormente.

Exceções

ValueError

  • ValueError — Se o hook não for encontrado na lista.

Desregistra um hook 'after_step'.

unregister_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

Parâmetros

  • fn — O objeto de função exato que foi registrado anteriormente.

Exceções

ValueError

  • ValueError — Se o hook não for encontrado na lista.

Desregistra um hook 'before_step'.

PolicyProcessorPipeline

lerobot.processor.DataProcessorPipeline

( *args**kwargs )

Update on GitHub

←Políticas Ambientes→