Hugging Face's logo

LeRobot documentation

プロセッサ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

プロセッサ

プロセッサは、ロボット、データセット、ポリシーの間のデータ変換レイヤーです。パイプラインはProcessorStepの連鎖であり、各ステップはデータとフィーチャー契約の両方をどのように変換するかを宣言します。

概念についてはRobot Processors の紹介を、ステップの作成については独自のプロセッサの実装を、パイプラインが正常に動作しない場合はプロセッサパイプラインのデバッグを参照してください。

ProcessorStep

クラス lerobot.processor.ProcessorStep

< >

( )

データ処理パイプラインの単一ステップのための抽象基底クラス。

各ステップは、データ遷移に対して変換を実行するための__call__メソッドと、データ特徴の形状や型をどのように変更するかを記述するためのtransform_featuresメソッドを実装する必要があります。

サブクラスは、state_dictとload_state_dictを実装することで、任意にステートフルにすることができます。

get_config

< >

( )

シリアライズ用のステップ設定を返します。

load_state_dict

< >

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

パラメータ

  • state — 状態テンソルの辞書。

ステート辞書からステップの状態を読み込みます。

リセット

< >

( )

プロセッサステップの内部状態（存在する場合）をリセットします。

save_artifacts

< >

( save_directory: Path )

非テンソルアセットを保存し、コンストラクタの引数を相対パスにマッピングします。

state_dict

< >

( )

ステップの状態（学習済みパラメータ、実行平均など）を返します。

transform_features

< >

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

パラメータ

  • features — 観測や行動などの入力特徴を記述する辞書

このステップがパイプラインの機能の説明をどのように変更するかを定義します。

このメソッドは、パイプラインを通過するデータの流れを追跡するために使用されます。実際のデータを処理することなく、データの形状、dtype、またはモダリティの変化を追跡できます。

DataProcessorPipeline

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

パラメータ

  • steps — パイプラインを構成するProcessorStepオブジェクトのシーケンス。
  • name — パイプラインの説明用の名前。
  • to_transition — 生の入力データを標準化されたEnvTransition形式に変換する関数です。
  • to_output — 最終的なEnvTransitionを所望の出力形式に変換する関数。
  • before_step_hooks — 各ステップの実行前に呼び出される関数のリスト。
  • after_step_hooks — 各ステップの実行後に呼び出される関数のリストです。

Hugging Face Hub と統合された、データを処理するためのシーケンシャルなパイプライン。

このクラスは、複数のProcessorStepインスタンスを連結して、完全なデータ処理ワークフローを構築します。汎用的であり、to_transitionおよび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 )

パラメータ

  • config — 保存されたプロセッサの JSON と同じ構造を持つ設定辞書。
  • state_dict — サフィックスなしのステートキーでグループ化された、任意のインメモリのパイプラインステート。
  • overrides — レジストリ名またはクラス名をキーとする、任意のコンストラクタのオーバーライド。
  • to_transition — 入力データをEnvTransitionに変換する任意のコンバーター。
  • to_output — EnvTransitionから出力データへの変換器（オプション）。

インメモリ設定と任意の状態テンソルからパイプラインを構築します。

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 )

パラメータ

  • pretrained_model_name_or_path — Hugging Face Hub 上のリポジトリの識別子、ローカルディレクトリへのパス、または単一の設定ファイルへのパス。
  • config_filename — パイプラインの JSON 設定ファイルの名前。複数の設定（例：preprocessor と postprocessor）が存在する場合に曖昧さを防ぐため、常に指定が必要です。
  • force_download — ファイルの（再）ダウンロードを強制するかどうか。
  • resume_download — 後方互換性のために保持されていますが、無視されます。ダウンロードは自動的に再開されます。
  • proxies — 後方互換性のために保持されていますが、無視されます。代わりに HTTP_PROXY と HTTPS_PROXY を使用してください。
  • token — プライベートな Hub リポジトリの HTTP ベアラ認証に使用するトークン。
  • cache_dir — ダウンロードしたファイルを保存するための特定のキャッシュフォルダへのパス。
  • local_files_only — True の場合、Hub からファイルをダウンロードしないようにします。
  • revision — 使用する特定のモデルのバージョン（ブランチ名、タグ名、コミット ID など）。
  • overrides — 特定のステップの設定を上書きするための辞書。キーは、ステップのクラス名またはレジストリ名と一致させる必要があります。
  • to_transition — 入力データをEnvTransitionに変換するためのカスタム関数。
  • to_output — 最終的なEnvTransitionを出力形式に変換するためのカスタム関数。
  • **kwargs — 追加の引数（未使用）。

例外

FileNotFoundError または ValueError または ImportError または KeyError または ProcessorMigrationError

  • FileNotFoundError — 設定ファイルが見つからない場合。
  • ValueError — 設定が曖昧な場合、またはインスタンス化に失敗した場合。
  • ImportError — ステップのクラスをインポートできない場合。
  • KeyError — パイプラインのどのステップにも一致しないオーバーライドキーが指定された場合。
  • ProcessorMigrationError — モデルがプロセッサ形式への移行を必要とする場合。

ローカルディレクトリ、単一のファイル、または Hugging Face Hub リポジトリからパイプラインを読み込みます。

このメソッドは、インテリジェントなマイグレーション検出を備えた簡略化された読み込みパイプラインを実装します:

簡略化された読み込み戦略:

  1. 設定の読み込み (_load_config):

    • ディレクトリ: ディレクトリから指定されたconfig_filenameを読み込みます
    • 単一ファイル: ファイルを直接読み込む（config_filenameは無視されます）
    • Hubリポジトリ: Hubから指定されたconfig_filenameをダウンロード

  2. 設定の検証 (_validate_loaded_config):

    • 形式の検証: configが有効なプロセッサ形式であることを確認します
    • 移行の検出: ユーザーが古いLeRobotモデルに移行するよう案内します
    • エラーの明確化: 実行可能なエラーメッセージを提供する

  3. ステップの構築 (_build_steps_with_overrides):

    • クラスの解決: レジストリ検索または動的インポート
    • マージのオーバーライド: ユーザーのパラメータが保存された設定をオーバーライドします
    • ステートの読み込み: ステートフルなステップ用の.safetensorsファイルを読み込みます

  4. オーバーライドの検証 (_validate_overrides_used):

    • すべてのユーザーの上書きが適用されたことを確認します（タイプミスを検出します）
    • 利用可能なキーを含む役立つエラーメッセージを提供します

マイグレーションの検出:

  • スマート検出: JSONファイルを解析して、古いLeRobotモデルを検出します
  • 正確なターゲティング: 他の HuggingFace モデルでの誤検出を回避します
  • 明確なガイダンス: 実行すべき正確なマイグレーションコマンドを提供します
  • エラーモード: ユーザーが明確なアクションを取れるように、常に ProcessorMigrationError を発生させます

サンプルの読み込み：

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

オーバーライドシステム:

  • キーの一致: レジストリ名またはクラス名をオーバーライドのキーとして使用します
  • 設定のマージ: ユーザーのオーバーライドが保存された設定よりも優先されます
  • 検証: すべてのオーバーライドキーが実際のステップと一致することを確認します（タイプミスの検出）
  • 例: overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

< >

( )

JSON シリアライズ可能なパイプライン設定を返します。

load_state_dict

< >

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

パラメータ

  • state_dict — サフィックスなしのステートキーをステップステートの辞書にマッピングする辞書。

例外

KeyError

  • KeyError — 読み込み時に、期待される状態が見つからないか、予期しない余分な状態が見つかった場合。

パイプラインのステートテンソルを既存のステップに読み込みます。

process_action

< >

( action: PolicyAction | RobotAction | EnvAction )

パラメータ

  • action — アクションデータ。

パイプラインを介して、トランジションのアクション部分のみを処理します。

process_complementary_data

< >

( complementary_data: dict[str, Any] )

パラメータ

  • complementary_data — 補完データ辞書。

パイプラインを介した遷移の補完データ部分のみを処理します。

process_done

< >

( done: bool | torch.Tensor )

パラメータ

  • done — doneフラグ。

パイプラインを介して、トランジションの完了フラグのみを処理します。

process_info

< >

( info: dict[str, Any] )

パラメータ

  • info — info辞書。

パイプラインを介して、トランジションのinfo辞書のみを処理します。

process_observation

< >

( observation: RobotObservation )

パラメータ

  • observation — 観測辞書。

パイプラインを介して、トランジションの観測部分のみを処理します。

process_reward

< >

( reward: float | torch.Tensor )

パラメータ

  • reward — 報酬の値。

パイプラインを介して、トランジションの報酬部分のみを処理します。

process_truncated

< >

( truncated: bool | torch.Tensor )

パラメータ

  • truncated — 切り詰めフラグ。

パイプラインを介して遷移のtruncatedフラグのみを処理します。

register_after_step_hook

< >

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

パラメータ

  • fn — ステップインデックスと現在の遷移を受け取る呼び出し可能なオブジェクト。

各ステップの後に呼び出される関数を登録します。

register_before_step_hook

< >

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

パラメータ

  • fn — ステップインデックスと現在の遷移を受け取る呼び出し可能なオブジェクト。

各ステップの前に呼び出される関数を登録します。

リセット

< >

( )

パイプライン内のすべてのステートフルなステップの状態をリセットします。

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 )

パラメータ

  • save_directory — パイプラインを保存するディレクトリ。None の場合、HF_LEROBOT_HOME/processors/{sanitized_pipeline_name} に保存されます。
  • repo_id — Hub 上のリポジトリの ID。push_to_hub=true の場合のみ使用されます。
  • push_to_hub — オブジェクトを保存した後、Hugging Face Hub にプッシュするかどうか。
  • card_kwargs — カードのカスタマイズのためにカードテンプレートに渡す追加の引数。
  • config_filename — JSON設定ファイルの名前。Noneの場合、パイプラインのname属性から名前が生成されます。
  • **push_to_hub_kwargs — Additional key word arguments passed along to the push_to_hub method.

パイプラインの設定と状態をディレクトリに保存します。

このメソッドは、パイプラインの構造（名前とステップ）を定義する JSON 設定ファイルを作成します。ステートフルな各ステップについては、そのステートディクショナリを含む.safetensorsファイルも保存されます。

state_dict

< >

( )

ステートキーごとにグループ化されたパイプラインステートのテンソルを返します。

step_through

< >

( data: TInput )

パラメータ

  • data — 入力データ。

データを段階的に処理し、各段階での遷移を返します。

これは、パイプラインを通過するデータの中間状態をデバッグおよび検査するために役立つジェネレーターメソッドです。

transform_features

< >

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

パラメータ

  • initial_features — 初期特徴量を記述する辞書。

すべてのステップの機能変換を順番に適用します。

このメソッドは、各ステップのtransform_featuresメソッドを通じて特徴量説明辞書を伝播させることで、実際のデータを処理せずにパイプラインが出力特徴量の仕様を静的に決定できるようにします。

unregister_after_step_hook

< >

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

パラメータ

  • fn — 以前に登録された正確な関数オブジェクト。

例外

ValueError

  • ValueError — フックがリスト内に見つからない場合。

‘after_step’フックを登録解除します。

unregister_before_step_hook

< >

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

パラメータ

  • fn — 以前に登録された正確な関数オブジェクト。

例外

ValueError

  • ValueError — フックがリスト内に見つからない場合。

‘before_step’フックの登録を解除します。

PolicyProcessorPipeline

lerobot.processor.DataProcessorPipeline

( *args**kwargs )

Update on GitHub

←ポリシー 環境→