LeRobot documentation

Processeurs

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

Processeurs

Les processeurs constituent la couche de transformation des données située entre un robot, un jeu de données et une politique. Un pipeline est une chaîne d'étapes ProcessorStep ; chaque étape déclare comment elle transforme à la fois les données et le contrat de fonctionnalités.

Consultez Introduction aux processeurs robotiques pour les concepts, Implémenter votre propre processeur pour écrire une étape, et Déboguer votre pipeline de processeur lorsqu'un pipeline se comporte de manière inattendue.

ProcessorStep

classe lerobot.processor.ProcessorStep

( )

Classe de base abstraite pour une étape unique dans un pipeline de traitement de données.

Chaque étape doit implémenter la méthode __call__ pour effectuer sa transformation sur une transition de données et la méthode transform_features pour décrire comment elle modifie la forme ou le type des fonctionnalités de données.

Les sous-classes peuvent éventuellement être étatiques en implémentant state_dict et load_state_dict.

get_config

( )

Retourne la configuration de l'étape pour la sérialisation.

load_state_dict

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

Paramètres

state — Un dictionnaire de tenseurs d'état.

Charge l'état de l'étape à partir d'un dictionnaire d'état.

réinitialiser

( )

Réinitialise l'état interne de l'étape du processeur, le cas échéant.

save_artifacts

( save_directory: Path )

Enregistrer les actifs non tenseurs et mapper les arguments du constructeur vers des chemins relatifs.

state_dict

( )

Retourne l'état de l'étape (par exemple, les paramètres appris, les moyennes mobiles).

transform_features

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

Paramètres

features — Un dictionnaire décrivant les caractéristiques d'entrée pour les observations, les actions, etc.

Définit la manière dont cette étape modifie la description des fonctionnalités du pipeline.

Cette méthode est utilisée pour suivre les modifications des formes de données, des dtypes ou des modalités au fur et à mesure que les données traversent le pipeline, sans avoir besoin de traiter les données réelles.

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

Paramètres

steps — Une séquence d'objets ProcessorStep qui composent le pipeline.
name — Un nom descriptif pour le pipeline.
to_transition — Une fonction pour convertir les données d’entrée brutes dans le format standardisé EnvTransition.
to_output — Une fonction pour convertir le EnvTransition final dans le format de sortie souhaité.
before_step_hooks — Une liste de fonctions à appeler avant l'exécution de chaque étape.
after_step_hooks — Une liste de fonctions à appeler après l'exécution de chaque étape.

Un pipeline séquentiel pour le traitement des données, intégré au Hugging Face Hub.

Cette classe enchaîne plusieurs instances de ProcessorStep pour former un flux de traitement de données complet. Elle est générique, permettant des types d’entrée et de sortie personnalisés, qui sont gérés par les convertisseurs to_transition et 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 )

Paramètres

config — Un dictionnaire de configuration ayant la même structure que le JSON du processeur enregistré.
state_dict — État de pipeline en mémoire optionnel, regroupé par clé d'état sans suffixe.
overrides — Remplacements de constructeur facultatifs, indexés par nom d’enregistrement ou nom de classe.
to_transition — Convertisseur facultatif des données d’entrée vers EnvTransition.
to_output — Convertisseur facultatif de EnvTransition vers les données de sortie.

Construire un pipeline à partir d'une configuration en mémoire et de tenseurs d'état facultatifs.

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 )

Paramètres

pretrained_model_name_or_path — L'identifiant du dépôt sur le Hugging Face Hub, un chemin vers un répertoire local ou un chemin vers un fichier de configuration unique.
config_filename — Le nom du fichier de configuration JSON du pipeline. Toujours requis pour éviter toute ambiguïté lorsque plusieurs configurations existent (par exemple, préprocesseur et postprocesseur).
force_download — Indique s'il faut forcer le (re)téléchargement des fichiers.
resume_download — Conservé pour la compatibilité ascendante et ignoré. Les téléchargements reprennent automatiquement.
proxies — Conservé pour la compatibilité ascendante et ignoré. Utilisez HTTP_PROXY et HTTPS_PROXY à la place.
token — Jeton à utiliser comme autorisation bearer HTTP pour les dépôts privés du Hub.
cache_dir — Le chemin vers un dossier de cache spécifique pour stocker les fichiers téléchargés.
local_files_only — Si True, évite le téléchargement de fichiers depuis le Hub.
revision — La version spécifique du modèle à utiliser (par exemple, un nom de branche, un nom de tag ou un identifiant de commit).
overrides — Un dictionnaire pour remplacer la configuration d’étapes spécifiques. Les clés doivent correspondre au nom de classe ou au nom d’enregistrement de l’étape.
to_transition — Une fonction personnalisée pour convertir les données d’entrée en EnvTransition.
to_output — Une fonction personnalisée pour convertir le EnvTransition final vers le format de sortie.
**kwargs — Arguments supplémentaires (non utilisés).

Lève

FileNotFoundError ou ValueError ou ImportError ou KeyError ou ProcessorMigrationError

FileNotFoundError — Si le fichier de configuration ne peut pas être trouvé.
ValueError — Si la configuration est ambiguë ou si l'instantiation échoue.
ImportError — Si la classe d’une étape ne peut pas être importée.
KeyError — Si une clé de substitution ne correspond à aucune étape du pipeline.
ProcessorMigrationError — Si le modèle nécessite une migration vers le format processeur.

Charge un pipeline à partir d'un répertoire local, d'un fichier unique ou d'un dépôt du Hugging Face Hub.

Cette méthode implémente un pipeline de chargement simplifié avec une détection intelligente de la migration :

Stratégie de chargement simplifiée :

Chargement de la configuration (_load_config) :
- Directory : Charge le fichier de configuration config_filename depuis le répertoire
- Fichier unique : charge le fichier directement (config_filename ignoré)
- Dépôt Hub : Téléchargez le config_filename spécifié depuis le Hub
Validation de la configuration (_validate_loaded_config) :
- Validation du format : Assurez-vous que la configuration est au format de processeur valide
- Détection de migration : Guidez les utilisateurs pour migrer les anciens modèles LeRobot
- Erreurs claires : fournir des messages d'erreur actionnables
Construction des étapes (_build_steps_with_overrides) :
- Résolution des classes : recherche dans le registre ou importations dynamiques
- Fusion par écrasement : les paramètres de l'utilisateur écrasent la configuration enregistrée
- Chargement de l'état : Chargez les fichiers .safetensors pour les étapes avec état
Validation des substitutions (_validate_overrides_used) :
- Vérifier que toutes les substitutions de l'utilisateur ont été appliquées (détecter les fautes de frappe)
- Fournir des messages d'erreur utiles avec les clés disponibles

Détection de migration :

Détection intelligente : Analyse les fichiers JSON pour détecter les anciens modèles LeRobot
Ciblage précis : Évite les faux positifs sur d'autres modèles HuggingFace
Guides clairs : Fournit la commande de migration exacte à exécuter
Mode d’erreur : lève toujours ProcessorMigrationError pour une action utilisateur claire

Chargement des exemples :

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

Système de substitution :

Correspondance des clés : utilisez les noms du registre ou les noms de classes comme clés de substitution
Fusion des configurations : les remplacements de l'utilisateur ont la priorité sur la configuration enregistrée
Validation : Vérifiez que toutes les clés de substitution correspondent aux étapes réelles (détecter les fautes de frappe)
Exemple : overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

( )

Retourne la configuration du pipeline sérialisable en JSON.

load_state_dict

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

Paramètres

state_dict — Un dictionnaire associant des clés d'état sans suffixe à des dictionnaires d'état par étape.

Lève

KeyError

KeyError — Si le chargement détecte un état attendu manquant ou un état supplémentaire inattendu.

Charger les tenseurs d'état du pipeline dans les étapes existantes.

process_action

( action: PolicyAction | RobotAction | EnvAction )

Paramètres

action — Les données d'action.

Traite uniquement la partie action d'une transition à travers le pipeline.

process_complementary_data

( complementary_data: dict[str, Any] )

Paramètres

complementary_data — Le dictionnaire de données complémentaires.

Traite uniquement la partie de données complémentaires d'une transition à travers le pipeline.

process_done

( done: bool | torch.Tensor )

Paramètres

done — Le drapeau done.

Traite uniquement le drapeau « done » d'une transition à travers le pipeline.

process_info

( info: dict[str, Any] )

Paramètres

info — Le dictionnaire d'informations.

Traite uniquement le dictionnaire d'informations d'une transition à travers le pipeline.

process_observation

( observation: RobotObservation )

Paramètres

observation — Le dictionnaire d'observation.

Traite uniquement la partie observation d'une transition à travers le pipeline.

process_reward

( reward: float | torch.Tensor )

Paramètres

reward — La valeur de la récompense.

Traite uniquement la partie récompense d'une transition à travers le pipeline.

process_truncated

( truncated: bool | torch.Tensor )

Paramètres

truncated — Le drapeau tronqué.

Traite uniquement le drapeau tronqué d'une transition à travers le pipeline.

register_after_step_hook

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

Paramètres

fn — Un appelable qui accepte l'indice de la étape et la transition actuelle.

Enregistre une fonction à appeler après chaque étape.

register_before_step_hook

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

Paramètres

fn — Un appelable qui accepte l'indice de la étape et la transition actuelle.

Enregistre une fonction à appeler avant chaque étape.

réinitialiser

( )

Réinitialise l'état de toutes les étapes avec état du 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 )

Paramètres

save_directory — Le répertoire où le pipeline sera enregistré. Si None, enregistre dans HF_LEROBOT_HOME/processors/{sanitized_pipeline_name}.
repo_id — ID de votre dépôt sur le Hub. Utilisé uniquement si push_to_hub=true.
push_to_hub — Indique s'il faut ou non pousser votre objet vers le Hugging Face Hub après l'avoir enregistré.
card_kwargs — Arguments supplémentaires transmis au modèle de carte pour personnaliser la carte.
config_filename — Le nom du fichier de configuration JSON. Si None, un nom est généré à partir de l’attribut name du pipeline.
**push_to_hub_kwargs — Arguments supplémentaires passés à la méthode push_to_hub.

Enregistre la configuration et l’état du pipeline dans un répertoire.

Cette méthode crée un fichier de configuration JSON qui définit la structure du pipeline (nom et étapes). Pour chaque étape avec état, elle enregistre également un fichier .safetensors contenant son dictionnaire d'état.

state_dict

( )

Retourne les tenseurs d'état du pipeline groupés par clé d'état.

step_through

( data: TInput )

Paramètres

data — Les données d'entrée.

Traite les données étape par étape, en produisant la transition à chaque étape.

Il s’agit d’une méthode générateur, utile pour le débogage et l’inspection de l’état intermédiaire des données lorsqu’elles traversent le pipeline.

transform_features

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

Paramètres

initial_features — Un dictionnaire décrivant les fonctionnalités initiales.

Applique les transformations de fonctionnalités de toutes les étapes de manière séquentielle.

Cette méthode propage un dictionnaire de description des fonctionnalités à travers la méthode transform_features de chaque étape, permettant au pipeline de déterminer statiquement la spécification des fonctionnalités de sortie sans traiter de données réelles.

unregister_after_step_hook

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

Paramètres

fn — L'objet fonction exact qui a été enregistré précédemment.

Lève

ValueError

ValueError — Si l'accroche n'est pas trouvée dans la liste.

Désenregistre un hook « after_step ».

unregister_before_step_hook

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

Paramètres

fn — L'objet fonction exact qui a été enregistré précédemment.

Lève

ValueError

ValueError — Si l'accroche n'est pas trouvée dans la liste.

Désenregistre un hook « before_step ».

PolicyProcessorPipeline

lerobot.processor.DataProcessorPipeline

( *args**kwargs )

Update on GitHub

←Politiques Environnements→