# プロセッサ

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

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

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

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

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

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

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

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

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

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

```python
get_config()
```

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

**戻り値:**

JSON シリアライズ可能な設定パラメータの辞書。

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

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

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

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

**パラメータ:**

state : 状態テンソルの辞書。

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

#### リセット[[lerobot.processor.ProcessorStep.reset]]

```python
reset()
```

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

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

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

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

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

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

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

```python
state_dict()
```

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

**戻り値:**

状態名をテンソルにマッピングする辞書。

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

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

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

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

**パラメータ:**

features : 観測やアクションなどの入力特徴を説明する辞書

**戻り値:**

このステップの変換後の出力特徴を説明する辞書。

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

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

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

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

**パラメータ:**

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

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

**パラメータ:**

config : 保存されたプロセッサのJSONと同じ構造を持つ設定辞書。

state_dict : サフィックスなしのステートキーでグループ化された、任意のインメモリパイプラインステート。

overrides : レジストリ名またはクラス名をキーとする、任意のコンストラクタのオーバーライド。

to_transition : 入力データを`EnvTransition`に変換する任意のコンバーター。

to_output : `EnvTransition`から出力データへの変換器（オプション）。

**戻り値:**

設定と任意のステートから構築されたプロセッサのパイプライン。

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

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

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

**パラメータ:**

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** : 追加の引数（未使用）。

**戻り値:**

指定された設定と状態で読み込まれた`DataProcessorPipeline`のインスタンス。

**例外:** ``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 を発生させます

**サンプルの読み込み**：
```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"
)
```

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

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

```python
get_config()
```

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

**戻り値:**

`save_pretrained()`がJSONとして書き込むのと同じ内容を持つ辞書。

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

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

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

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

**パラメータ:**

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

**例外:** ``KeyError``

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

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

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

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

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

**パラメータ:**

action : アクションデータ。

**戻り値:**

処理されたアクション。

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

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

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

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

**パラメータ:**

complementary_data : 補完的なデータ辞書。

**戻り値:**

処理済みの補完データ辞書。

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

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

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

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

**パラメータ:**

done : doneフラグ。

**戻り値:**

処理済みのフラグ。

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

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

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

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

**パラメータ:**

info : info辞書。

**戻り値:**

処理済みの情報辞書。

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

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

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

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

**パラメータ:**

observation : 観測辞書。

**戻り値:**

処理済みの観測辞書。

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

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

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

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

**パラメータ:**

reward : 報酬値。

**戻り値:**

処理された報酬。

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

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

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

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

**パラメータ:**

truncated : 切り詰めフラグ。

**戻り値:**

処理された切り詰めフラグ。

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

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

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

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

**パラメータ:**

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

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

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

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

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

**パラメータ:**

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

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

#### リセット[[lerobot.processor.DataProcessorPipeline.reset]]

```python
reset()
```

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

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

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

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

**パラメータ:**

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

```python
state_dict()
```

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

**戻り値:**

サフィックスなしのステートキーを、クローンされたステップステートの辞書にマッピングする辞書。

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

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

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

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

**パラメータ:**

data : 入力データ。

**戻り値:**

初期状態から始まり、各処理ステップの後に得られる`EnvTransition`オブジェクト。

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

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

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

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

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

**パラメータ:**

initial_features : 初期特徴を説明する辞書。

**戻り値:**

すべての変換が適用された後の最終的な特徴量の説明。

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

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

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

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

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

**パラメータ:**

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

**例外:** ``ValueError``

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

「after_step」フックの登録を解除します。

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

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

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

**パラメータ:**

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

**例外:** ``ValueError``

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

「before_step」フックの登録を解除します。

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

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

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