LeRobot documentation

Procesadores

LeRobot

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Procesadores

Los procesadores son la capa de transformación de datos entre un robot, un conjunto de datos y una política. Un pipeline es una cadena de ProcessorSteps; cada paso declara cómo transforma tanto los datos como el contrato de características.

Consulte Introducción a los procesadores de robots para los conceptos, Implemente su propio procesador para escribir un paso y Depure su pipeline de procesadores cuando un pipeline se comporte de manera inesperada.

ProcessorStep

clase lerobot.processor.ProcessorStep

< source >

( )

Clase base abstracta para un paso individual en un pipeline de procesamiento de datos.

Cada paso debe implementar el método __call__ para realizar su transformación en una transición de datos y el método transform_features para describir cómo modifica la forma o el tipo de las características de los datos.

Las subclases pueden ser opcionalmente con estado implementando state_dict y load_state_dict.

get_config

< source >

( )

Devuelve la configuración del paso para la serialización.

load_state_dict

< source >

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

Parámetros

state — Un diccionario de tensores de estado.

Carga el estado del paso desde un diccionario de estado.

restablecer

< source >

( )

Restablece el estado interno del paso del procesador, si lo hay.

save_artifacts

< source >

( save_directory: Path )

Guarde los activos no tensoriales y mapee los argumentos del constructor a rutas relativas.

state_dict

< source >

( )

Devuelve el estado del paso (p. ej., parámetros aprendidos, medias en ejecución).

transform_features

< source >

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

Parámetros

features — Un diccionario que describe las características de entrada para observaciones, acciones, etc.

Define cómo este paso modifica la descripción de las características del pipeline.

Este método se utiliza para rastrear los cambios en las formas de los datos, los dtypes o las modalidades a medida que los datos fluyen a través de la pipeline, sin necesidad de procesar datos reales.

DataProcessorPipeline

clase lerobot.processor.DataProcessorPipeline

< source >

( 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 — Una secuencia de objetos ProcessorStep que componen el pipeline.
name — Un nombre descriptivo para el pipeline.
to_transition — Una función para convertir los datos de entrada crudos al formato estandarizado EnvTransition.
to_output — Una función para convertir el EnvTransition final al formato de salida deseado.
before_step_hooks — Una lista de funciones que se llamarán antes de que se ejecute cada paso.
after_step_hooks — Una lista de funciones que se llamarán después de que se ejecute cada paso.

Un pipeline secuencial para el procesamiento de datos, integrado con el Hugging Face Hub.

Esta clase encadena múltiples instancias de ProcessorStep para formar un flujo de trabajo completo de procesamiento de datos. Es genérica, lo que permite tipos de entrada y salida personalizados, que son manejados por los convertidores to_transition y to_output.

from_config

< source >

( 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 — Un diccionario de configuración con la misma estructura que el JSON del procesador guardado.
state_dict — Estado de la pipeline en memoria opcional, agrupado por clave de estado sin sufijo.
overrides — Sobrescripciones opcionales del constructor, indexadas por nombre de registro o nombre de clase.
to_transition — Convertidor opcional de los datos de entrada a EnvTransition.
to_output — Convertidor opcional de EnvTransition a datos de salida.

Construir un pipeline a partir de una configuración en memoria y tensores de estado opcionales.

from_pretrained

< source >

Parámetros

pretrained_model_name_or_path — El identificador del repositorio en Hugging Face Hub, una ruta a un directorio local o una ruta a un archivo de configuración individual.
config_filename — El nombre del archivo de configuración JSON del pipeline. Siempre es obligatorio para evitar ambigüedad cuando existen varias configuraciones (p. ej., preprocesador vs. posprocesador).
force_download — Si se debe forzar la (re)descarga de los archivos.
resume_download — Se mantiene por compatibilidad con versiones anteriores y se ignora. Las descargas se reanudan automáticamente.
proxies — Se conserva por compatibilidad con versiones anteriores y se ignora. Utilice HTTP_PROXY y HTTPS_PROXY en su lugar.
token — El token que se usará como autorización HTTP bearer para los repositorios privados del Hub.
cache_dir — La ruta a una carpeta de caché específica para almacenar los archivos descargados.
local_files_only — Si es True, evita descargar archivos del Hub.
revision — La versión específica del modelo que se va a usar (p. ej., un nombre de rama, un nombre de etiqueta o un id de commit).
overrides — Un diccionario para sobrescribir la configuración de pasos específicos. Las claves deben coincidir con el nombre de la clase o el nombre del registro del paso.
to_transition — Una función personalizada para convertir los datos de entrada en EnvTransition.
to_output — Una función personalizada para convertir el EnvTransition final al formato de salida.
**kwargs — Argumentos adicionales (no se usan).

Lanza

FileNotFoundError o ValueError o ImportError o KeyError o ProcessorMigrationError

FileNotFoundError — Si no se puede encontrar el archivo de configuración.
ValueError — Si la configuración es ambigua o la instanciación falla.
ImportError — Si la clase de un paso no se puede importar.
KeyError — Si una clave de reemplazo no coincide con ningún paso del pipeline.
ProcessorMigrationError — Si el modelo requiere migración al formato de procesador.

Carga un pipeline desde un directorio local, un archivo individual o un repositorio de Hugging Face Hub.

Este método implementa un pipeline de carga simplificado con detección inteligente de migración:

Estrategia de carga simplificada:

Carga de configuración (_load_config):
- Directorio: Carga el config_filename especificado desde el directorio
- Archivo único: Carga el archivo directamente (config_filename se ignora)
- Repositorio de Hub: Descarga el config_filename especificado desde Hub
Validación de la configuración (_validate_loaded_config):
- Validación del formato: Asegúrese de que la configuración sea un formato de procesador válido
- Detección de migración: Guía a los usuarios para migrar modelos antiguos de LeRobot
- Errores claros: Proporciona mensajes de error accionables
Construcción de pasos (_build_steps_with_overrides):
- Resolución de clases: búsqueda en el registro o importaciones dinámicas
- Fusión de sobrescritura: los parámetros del usuario sobrescriben la configuración guardada
- Carga de estado: Carga archivos .safetensors para pasos con estado
Sobrescritura de validación (_validate_overrides_used):
- Asegúrese de que se aplicaron todas las anulaciones del usuario (detectar errores tipográficos)
- Proporcionar mensajes de error útiles con las claves disponibles

Detección de migración:

Detección inteligente: Analiza los archivos JSON para detectar modelos antiguos de LeRobot
Detección precisa: Evita falsos positivos en otros modelos de HuggingFace
Guía clara: Proporciona el comando exacto de migración para ejecutar
Modo de error: Siempre lanza ProcessorMigrationError para una acción clara del usuario

Cargar ejemplos:

# 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 anulación:

Correspondencia de claves: Use nombres de registro o nombres de clase como claves de anulación
Fusión de configuraciones: Las configuraciones del usuario tienen prioridad sobre la configuración guardada
Validación: Asegúrate de que todas las claves de anulación coincidan con los pasos reales (detecta errores tipográficos)
Ejemplo: overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

< source >

( )

Devuelve la configuración de la pipeline serializable en JSON.

load_state_dict

< source >

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

Parámetros

state_dict — Un diccionario que mapea claves de estado sin sufijo a diccionarios de estado de paso.

Lanza

KeyError

KeyError — Si al cargar se encuentra un estado esperado ausente o un estado adicional inesperado.

Cargue los tensores del estado de la pipeline en los pasos existentes.

process_action

< source >

( action: PolicyAction | RobotAction | EnvAction )

Parámetros

action — Los datos de la acción.

Procesa solo la parte de la acción de una transición a través del pipeline.

process_complementary_data

< source >

( complementary_data: dict[str, Any] )

Parámetros

complementary_data — El diccionario de datos complementarios.

Procesa solo la parte de datos complementarios de una transición a través del pipeline.

process_done

< source >

( done: bool | torch.Tensor )

Parámetros

done — El indicador done.

Procesa únicamente la bandera done de una transición a través de la pipeline.

process_info

< source >

( info: dict[str, Any] )

Parámetros

info — El diccionario de información.

Procesa solo el diccionario de información de una transición a través de la tubería.

process_observation

< source >

( observation: RobotObservation )

Parámetros

observation — El diccionario de observación.

Procesa solo la parte de observación de una transición a través del pipeline.

process_reward

< source >

( reward: float | torch.Tensor )

Parámetros

reward — El valor de la recompensa.

Procesa solo la parte de recompensa de una transición a través del pipeline.

process_truncated

< source >

( truncated: bool | torch.Tensor )

Parámetros

truncated — El indicador truncado.

Procesa únicamente la bandera truncada de una transición a través de la tubería.

register_after_step_hook

< source >

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

Parámetros

fn — Un objeto invocable que acepta el índice de paso y la transición actual.

Registra una función para ser llamada después de cada paso.

register_before_step_hook

< source >

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

Parámetros

fn — Un objeto invocable que acepta el índice de paso y la transición actual.

Registra una función para ser llamada antes de cada paso.

restablecer

< source >

( )

Restablece el estado de todos los pasos con estado en la tubería.

save_pretrained

< source >

Parámetros

save_directory — El directorio donde se guardará el pipeline. Si es None, se guarda en HF_LEROBOT_HOME/processors/{sanitized_pipeline_name}.
repo_id — ID de tu repositorio en el Hub. Se usa solo si push_to_hub=true.
push_to_hub — Si se debe o no subir su objeto al Hugging Face Hub después de guardarlo.
card_kwargs — Argumentos adicionales que se pasan a la plantilla de la tarjeta para personalizarla.
config_filename — El nombre del archivo de configuración JSON. Si es None, se genera un nombre a partir del atributo name del pipeline.
**push_to_hub_kwargs — Argumentos de palabra clave adicionales que se pasan al método push_to_hub.

Guarda la configuración y el estado de la pipeline en un directorio.

Este método crea un archivo de configuración JSON que define la estructura de la pipeline (nombre y pasos). Para cada paso con estado, también guarda un archivo .safetensors que contiene su diccionario de estado.

state_dict

< source >

( )

Devuelve los tensores del estado de la pipeline agrupados por clave de estado.

step_through

< source >

( data: TInput )

Parámetros

data — Los datos de entrada.

Procesa los datos paso a paso, generando la transición en cada etapa.

Este es un método generador útil para depurar e inspeccionar el estado intermedio de los datos a medida que pasan por el pipeline.

transform_features

< source >

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

Parámetros

initial_features — Un diccionario que describe las características iniciales.

Aplica las transformaciones de características de todos los pasos de forma secuencial.

Este método propaga un diccionario de descripción de características a través del método transform_features de cada paso, lo que permite a la pipeline determinar estáticamente la especificación de las características de salida sin procesar ningún dato real.