# 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 `ProcessorStep`s; cada etapa declara como transforma tanto os dados quanto o contrato de recursos.

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

## ProcessorStep[[lerobot.processor.ProcessorStep]]

#### lerobot.processor.ProcessorStep[[lerobot.processor.ProcessorStep]]

```python
lerobot.processor.ProcessorStep()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L150)

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[[lerobot.processor.ProcessorStep.get_config]]

```python
get_config()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L193)

**Retorna:**

Um dicionário serializável em JSON de parâmetros de configuração.

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

#### load_state_dict[[lerobot.processor.ProcessorStep.load_state_dict]]

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

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L209)

**Parâmetros:**

state : Um dicionário de tensores de estado.

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

#### reset[[lerobot.processor.ProcessorStep.reset]]

```python
reset()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L221)

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

#### save_artifacts[[lerobot.processor.ProcessorStep.save_artifacts]]

```python
save_artifacts(save_directory: Path)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L217)

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

#### state_dict[[lerobot.processor.ProcessorStep.state_dict]]

```python
state_dict()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L201)

**Retorna:**

Um dicionário que mapeia nomes de estado para tensores.

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

#### transform_features[[lerobot.processor.ProcessorStep.transform_features]]

```python
transform_features(features: dict[PipelineFeatureType, dict[str, PolicyFeature]])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L225)

**Parâmetros:**

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

**Retorna:**

Um dicionário descrevendo os recursos de saída após a transformação desta etapa.

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[[lerobot.processor.DataProcessorPipeline]]

#### lerobot.processor.DataProcessorPipeline[[lerobot.processor.DataProcessorPipeline]]

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

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L273)

**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[[lerobot.processor.DataProcessorPipeline.from_config]]

```python
from_config(config: dict[str, Any], state_dict: dict[str, dict[str, torch.Tensor]] | None = None, overrides: dict[str, Any] | None = None, to_transition: Callable[[TInput], EnvTransition] | None = None, to_output: Callable[[EnvTransition], TOutput] | None = None)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L792)

**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 de construtor indexadas por nome de registro ou nome de classe.

to_transition : Conversor opcional de dados de entrada para `EnvTransition`.

to_output : Conversor opcional de `EnvTransition` para dados de saída.

**Retorna:**

Um pipeline de processador construído a partir da configuração e do estado opcional.

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

#### from_pretrained[[lerobot.processor.DataProcessorPipeline.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | Path, config_filename: str, force_download: bool = False, resume_download: bool | None = None, proxies: dict[str, str] | None = None, token: str | bool | None = None, cache_dir: str | Path | None = None, local_files_only: bool = False, revision: str | None = None, overrides: dict[str, Any] | None = None, to_transition: Callable[[TInput], EnvTransition] | None = None, to_output: Callable[[EnvTransition], TOutput] | None = None, **kwargs)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L647)

**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 único arquivo de configuração.

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 de bearer HTTP 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 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).

**Retorna:**

Uma instância de `DataProcessorPipeline` carregada com a configuração e o estado especificados.

**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**:
```python
# 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[[lerobot.processor.DataProcessorPipeline.get_config]]

```python
get_config()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L451)

**Retorna:**

Um dicionário com o mesmo conteúdo que `save_pretrained()` grava como JSON.

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

#### load_state_dict[[lerobot.processor.DataProcessorPipeline.load_state_dict]]

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

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L515)

**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[[lerobot.processor.DataProcessorPipeline.process_action]]

```python
process_action(action: PolicyAction | RobotAction | EnvAction)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1786)

**Parâmetros:**

action : Os dados da ação.

**Retorna:**

A ação processada.

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

#### process_complementary_data[[lerobot.processor.DataProcessorPipeline.process_complementary_data]]

```python
process_complementary_data(complementary_data: dict[str, Any])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1853)

**Parâmetros:**

complementary_data : O dicionário de dados complementar.

**Retorna:**

O dicionário de dados complementares processados.

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

#### process_done[[lerobot.processor.DataProcessorPipeline.process_done]]

```python
process_done(done: bool | torch.Tensor)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1814)

**Parâmetros:**

done : A flag done.

**Retorna:**

A flag de processamento concluído.

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

#### process_info[[lerobot.processor.DataProcessorPipeline.process_info]]

```python
process_info(info: dict[str, Any])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1840)

**Parâmetros:**

info : O dicionário de informações.

**Retorna:**

O dicionário de informações processadas.

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

#### process_observation[[lerobot.processor.DataProcessorPipeline.process_observation]]

```python
process_observation(observation: RobotObservation)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1773)

**Parâmetros:**

observation : O dicionário de observação.

**Retorna:**

O dicionário de observações processado.

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

#### process_reward[[lerobot.processor.DataProcessorPipeline.process_reward]]

```python
process_reward(reward: float | torch.Tensor)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1801)

**Parâmetros:**

reward : O valor da recompensa.

**Retorna:**

A recompensa processada.

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

#### process_truncated[[lerobot.processor.DataProcessorPipeline.process_truncated]]

```python
process_truncated(truncated: bool | torch.Tensor)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1827)

**Parâmetros:**

truncated : A flag truncada.

**Retorna:**

A bandeira truncada processada.

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

#### register_after_step_hook[[lerobot.processor.DataProcessorPipeline.register_after_step_hook]]

```python
register_after_step_hook(fn: Callable[[int, EnvTransition], None])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1697)

**Parâmetros:**

fn : Um objeto 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[[lerobot.processor.DataProcessorPipeline.register_before_step_hook]]

```python
register_before_step_hook(fn: Callable[[int, EnvTransition], None])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1673)

**Parâmetros:**

fn : Um objeto 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[[lerobot.processor.DataProcessorPipeline.reset]]

```python
reset()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1721)

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

#### save_pretrained[[lerobot.processor.DataProcessorPipeline.save_pretrained]]

```python
save_pretrained(save_directory: str | Path | None = None, repo_id: str | None = None, push_to_hub: bool = False, card_kwargs: dict[str, Any] | None = None, config_filename: str | None = None, **push_to_hub_kwargs)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L595)

**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 você deseja ou não enviar seu objeto para o Hugging Face Hub após salvá-lo.

card_kwargs : Argumentos adicionais passados para o modelo do cartão para personalizá-lo.

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[[lerobot.processor.DataProcessorPipeline.state_dict]]

```python
state_dict()
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L488)

**Retorna:**

Um dicionário que mapeia chaves de estado sem sufixo para dicionários de estado de etapa clonados.

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

#### step_through[[lerobot.processor.DataProcessorPipeline.step_through]]

```python
step_through(data: TInput)
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L343)

**Parâmetros:**

data : Os dados de entrada.

**Retorna:**

O objeto `EnvTransition`, começando pelo estado inicial e, em seguida, após cada etapa de processamento.

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[[lerobot.processor.DataProcessorPipeline.transform_features]]

```python
transform_features(initial_features: dict[PipelineFeatureType, dict[str, PolicyFeature]])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1750)

**Parâmetros:**

initial_features : Um dicionário descrevendo os recursos iniciais.

**Retorna:**

A descrição final do recurso após todas as transformações.

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[[lerobot.processor.DataProcessorPipeline.unregister_after_step_hook]]

```python
unregister_after_step_hook(fn: Callable[[int, EnvTransition], None])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1705)

**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[[lerobot.processor.DataProcessorPipeline.unregister_before_step_hook]]

```python
unregister_before_step_hook(fn: Callable[[int, EnvTransition], None])
```

[Fonte](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1681)

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

#### lerobot.processor.DataProcessorPipeline[[lerobot.processor.DataProcessorPipeline]]

```python
lerobot.processor.DataProcessorPipeline(*args, **kwargs)
```