# エクスポート

`HfExporter` をサブクラス化することで、Transformers に新しいエクスポートバックエンドを追加できます。

[Exporters](../exporters)ガイドで、組み込みエクスポート機能の使用方法を学びましょう。

## AutoHfExporter[[transformers.exporters.AutoHfExporter]]

#### transformers.exporters.AutoHfExporter[[transformers.exporters.AutoHfExporter]]

```python
transformers.exporters.AutoHfExporter()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L93)

`ExportConfig`に基づいて、適切な`HfExporter`に自動的にインスタンス化を行うAuto-HFエクスポートクラスです。

#### from_pretrained[[transformers.exporters.AutoHfExporter.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L113)

エクスポート設定を同梱した事前学習済みモデル/チェックポイントから、エクスポートアインスタンスを読み込みます。

**未実装** — 第一級「エクスポートレシピ」ワークフロー用のプレースホルダー。

アイデア: モデルのオーナーは、Hub 上の重みファイルとともに `export_config.json`（または `config.json` 内の `export_config` フィールド）を公開します。このファイルには、オーナーがそのアーキテクチャに対してすでに検証済みの設定が記録されます。具体的には、ターゲット形式（`dynamo` / `onnx` / `executorch`）、正確な動的形状の仕様（例: `text_ids` は 4096 まで動的、画像タイルは 448 に固定、エッジデプロイメント向けに `batch=1`）、`strict` フラグ、ONNX opset、prefill と decode のレイアウト、ExecuTorch のバックエンド選択、そして現在 README やプライベートなノートブックに属人的な知識として存在するその他のあらゆる設定項目です。

その後、コンシューマーは1回の呼び出しで、オーナーが検証済みのエクスポートを取得します。

```python
exporter = AutoHfExporter.from_pretrained("org/model-name")
program = exporter.export(model, inputs)
```

        [*register_export_input_preparer*] レジストリと組み合わせます。オーナーが `export_config.json` 経由で形状仕様を供給し、transformers がそのアーキテクチャ向けのデータ依存の事前計算（`cu_seqlens`、ビジョンの位置 ID、ウィンドウインデックスなど）を供給します。これにより、新モデルのエクスポートにおける 2 つの困難な部分、すなわち正しい形状契約の把握と正しい入力の準備がカバーされるため、下流のユーザーはどちらかをゼロから再導出する必要がなく（誤った実装で本番環境で壊れることもありません）。

#### supports_export_format[[transformers.exporters.AutoHfExporter.supports_export_format]]

```python
supports_export_format(export_config_dict: dict)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L145)

`export_format` が、登録済みの config クラスと登録済みの exporter クラスの両方を持つ形式を記述している場合は True を返します。形式が完全に欠落している、不明である、または片方のみ登録されている場合は、対応可能なメッセージで警告を発します。

## AutoExportConfig[[transformers.exporters.AutoExportConfig]]

#### transformers.exporters.AutoExportConfig[[transformers.exporters.AutoExportConfig]]

```python
transformers.exporters.AutoExportConfig()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/auto.py#L65)

辞書に保存されたエクスポート設定に基づいて、正しいエクスポート設定へ自動的にディスパッチする処理を担当するAuto-HFエクスポート設定クラスです。

## HfExporter[[transformers.exporters.HfExporter]]

#### transformers.exporters.HfExporter[[transformers.exporters.HfExporter]]

```python
transformers.exporters.HfExporter()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L41)

すべての Transformers エクスポート用の抽象基底クラス。

`~HfExporter.export` をサブクラス化して実装し、新しいエクスポートバックエンドを追加します。

#### export[[transformers.exporters.HfExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, torch.Tensor | Cache], config: ExportConfigMixin)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L61)

**パラメータ:**

model ([PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel)) : エクスポートするモデル。

sample_inputs (`dict[str, torch.Tensor | Cache]`) : **Forward** kwargs — `model(**sample_inputs)` に渡す引数です。これらはトレース中のサンプル入力として直接使用されます。自己回帰的なデコードステップのエクスポートを行う場合、`past_key_values` や `cache_position` などを含める必要があります。生成スタイルの入力しかない場合は、代わりに `~HfExporter.export_for_generation` を使用してください。これにより `model.generate` が実行され、各ステージがエクスポートされます。

config (`ExportConfigMixin`) : バックエンド固有の設定。

**戻り値:**

バックエンド固有のエクスポート成果物。

モデルをエクスポートし、バックエンド固有のプログラムオブジェクトを返します。

#### export_for_generation[[transformers.exporters.HfExporter.export_for_generation]]

```python
export_for_generation(model: PreTrainedModel, sample_inputs: MutableMapping[str, torch.Tensor | Cache], config: ExportConfigMixin | dict[str, ExportConfigMixin], generation_config: GenerationConfig | None = None, multi_token_decode: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L93)

**パラメータ:**

model ([PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel)) : エクスポート対象の生成モデル。`model.generate(**sample_inputs)` をサポートしている必要があります。

sample_inputs (`dict[str, torch.Tensor | Cache]`) : **Generate** の引数 — `model.generate(**sample_inputs)` に渡すもの（通常は `input_ids` と `attention_mask`、マルチモーダルモデルの場合は `pixel_values` や `input_features` などのモーダリティ入力）。ステージごとの forward 引数は内部で取得されます。

config (`ExportConfigMixin` または `dict[str, ExportConfigMixin]`) : バックエンド固有の設定。すべてのコンポーネントに適用する場合は単一の設定を、コンポーネント名をキーとする `dict`（例: `"image_encoder"`、`"language_model"`、`"lm_head"`、`"decode"`）を渡すことでコンポーネントごとに上書きできます。dict にはすべてのコンポーネント名が含まれている必要があります。

generation_config ([GenerationConfig](/docs/transformers/main/ja/main_classes/text_generation#transformers.GenerationConfig)、*optional*) : `generate()` のキャプチャに転送されます（デフォルトではモデル自身のものを使用）。固定サイズの`StaticCache`に対してエクスポートするには、`cache_implementation="static"`を指定したものを渡してください。

multi_token_decode (`bool`、*任意*、デフォルトは `False`) : `decode` コンポーネントが複数のクエリトークンを一度に処理するかどうかを示します。動的なクエリ軸（キャッシュが空の場合は prefill、それ以外は past からの継続）と、従来の単一トークンステップ（[decompose_for_generation()](/docs/transformers/main/ja/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) を参照）のいずれかを指定します。動的な形状のエクスポート（`config.dynamic=True`）の場合にのみ、動的な状態を維持します。

**戻り値:** `dict[str, Any]`

`{component_name: backend_specific_artifact}` — [decompose_for_generation()](/docs/transformers/main/ja/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) と同じキーを持ちます。値は、具体的なバックエンド（`ExportedProgram`、`ONNXProgram`、`ExecutorchProgramManager`）に対して `~HfExporter.export` が返すものです。

生成モデルを分解し、各コンポーネントを独立してエクスポートします。

Thin wrapper around [decompose_for_generation()](/docs/transformers/main/ja/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) that calls `~HfExporter.export` on every returned `(submodel, forward_inputs)` pair. If you need the intermediate `(submodel, forward_inputs)` pairs (for verification, custom inputs, skipping a stage, …), call [decompose_for_generation()](/docs/transformers/main/ja/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) directly.

#### validate_environment[[transformers.exporters.HfExporter.validate_environment]]

```python
validate_environment(*args, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/base.py#L57)

`required_packages` がインストールされていることを確認し、`tested_versions` とのバージョンの乖離がある場合は警告を発します。

## DynamoExporter[[transformers.exporters.DynamoExporter]]

#### transformers.exporters.DynamoExporter[[transformers.exporters.DynamoExporter]]

```python
transformers.exporters.DynamoExporter()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_dynamo.py#L69)

`ExportedProgram` に変換する [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) のエクスポートツールです。

例:

```python
>>> from transformers.exporters.exporter_dynamo import DynamoExporter, DynamoConfig

>>> exporter = DynamoExporter()
>>> exported = exporter.export(model, inputs, config=DynamoConfig(dynamic=True))
>>> outputs = exported.module()(**inputs)
```

#### export[[transformers.exporters.DynamoExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, Any], config: DynamoConfig | dict[str, Any])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_dynamo.py#L87)

## OnnxExporter[[transformers.exporters.OnnxExporter]]

#### transformers.exporters.OnnxExporter[[transformers.exporters.OnnxExporter]]

```python
transformers.exporters.OnnxExporter()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_onnx.py#L108)

[PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel)をONNXの`ONNXProgram`に変換するエクスポートツールです。

例:

```python
>>> from transformers.exporters.exporter_onnx import OnnxExporter, OnnxConfig

>>> exporter = OnnxExporter()
>>> onnx_program = exporter.export(model, inputs, config=OnnxConfig(dynamic=True))
>>> outputs = onnx_program(**inputs)  # run in-memory
>>> exporter.export(model, inputs, config=OnnxConfig(output_path="model.onnx"))  # save to disk
```

#### export[[transformers.exporters.OnnxExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, Any], config: OnnxConfig | dict[str, Any])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_onnx.py#L126)

## ExecutorchExporter[[transformers.exporters.ExecutorchExporter]]

#### transformers.exporters.ExecutorchExporter[[transformers.exporters.ExecutorchExporter]]

```python
transformers.exporters.ExecutorchExporter()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_executorch.py#L109)

[PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を ExecuTorch の `ExecutorchProgramManager` に変換する Exporter です。

例:

```python
>>> from transformers.exporters.exporter_executorch import ExecutorchExporter, ExecutorchConfig

>>> exporter = ExecutorchExporter()
>>> et_program = exporter.export(model, inputs, config=ExecutorchConfig(backend="xnnpack"))
>>> et_program.write_to_file("model.pte")
```

#### export[[transformers.exporters.ExecutorchExporter.export]]

```python
export(model: PreTrainedModel, sample_inputs: MutableMapping[str, Any], config: ExecutorchConfig | dict[str, Any])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_executorch.py#L126)

モデルをExecuTorchにエクスポートし、バックエンドの準備とtorch opのパッチを適用します。

## DynamoConfig[[transformers.exporters.DynamoConfig]]

#### transformers.exporters.DynamoConfig[[transformers.exporters.DynamoConfig]]

```python
transformers.exporters.DynamoConfig(export_format: ExportFormat = <ExportFormat.DYNAMO: 'dynamo'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L83)

**パラメータ:**

dynamic (*bool*、*optional*、デフォルトは *False*) : 動的（シンボリック）な形状でエクスポートするかどうか。*True* かつ *dynamic_shapes* が設定されていない場合、すべてのテンソル次元が自動的に *Dim.AUTO* に設定されます。

strict (*bool*、*optional*、デフォルトは *False*) : *torch.export* で厳格モードを有効にするかどうか。完全なシンボリックトレースを実行し、より多くのエラーを検出できますが、速度が遅く、複雑なモデルでは失敗する可能性が高くなります。

dynamic_shapes (*dict[str, Any]*、*optional*) : *torch.export* に渡す、入力ごとの動的形状の明示的な指定です。*dynamic* より優先されます。

prefer_deferred_runtime_asserts_over_guards (*bool*、*optional*、デフォルトは *False*) : *True* の場合、データ依存の形状ガードは、トレース時にガードがシンボリック形状の全範囲にわたって成立しない場合にエクスポートを失敗させるのではなく、エクスポートされたグラフ内でランタイムアサートとして出力されます。細粒度の `Dim(min=, max=)` 境界を使用するほとんどの Transformer LLM では、これを *True* に設定する必要があります。`dynamic=True` / `Dim.AUTO` を使用する場合、`torch.export` がユーザーが指定した境界に対して検証するのではなく、形状の関係を推論するため、この設定は不要です。

quantizer ([*~exporters.quantizers.ExportQuantizer*]、*optional*) : エクスポート時に適用されるポストトレーニング量子化: すべてのバックエンドの FX グラフに対して [*~exporters.quantizers.PT2EQuantizer*] または [*~exporters.quantizers.NNCFTorchFXQuantizer*]、変換後の ONNX モデルに対して [*~exporters.quantizers.OnnxRuntimeQuantizer*]、変換後の OpenVINO / ONNX モデルに対して [*~exporters.quantizers.NNCFOpenVINOQuantizer*] / [*~exporters.quantizers.NNCFOnnxQuantizer*]。

*torch.export* 経由でモデルをエクスポートするための設定クラスです。

## OnnxConfig[[transformers.exporters.OnnxConfig]]

#### transformers.exporters.OnnxConfig[[transformers.exporters.OnnxConfig]]

```python
transformers.exporters.OnnxConfig(export_format: ExportFormat = <ExportFormat.ONNX: 'onnx'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None, output_path: str | PathLike | None = None, opset_version: int | None = None, external_data: bool = True, optimize: bool = True, export_params: bool = True, keep_initializers_as_inputs: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L125)

**パラメータ:**

output_path (`str` または `PathLike`、*省略可*) : `.onnx` ファイルの出力パス。`None`（デフォルト）の場合、エクスポートされたモデルは `ONNXProgram` としてメモリ内に保持され、ディスクに書き出されません。

opset_version (`int`, *任意*) : ターゲットとする ONNX opset のバージョンです。デフォルトでは、インストールされている `onnxscript` のバージョンがサポートする最新の opset が使用されます。

external_data (`bool`、*任意*、デフォルトは`True`) : 大きな重みテンソルを protobuf に埋め込む代わりに、別個の`.onnx_data` サイドカーファイルに保存します。重みが 2 GB の protobuf 制限を超えるモデルには必須です。

optimize (`bool`、*任意*、デフォルトは`True`) : エクスポートされたグラフに対して`onnxscript`の最適化パス（定数畳み込み、デッドコードエリミネーションなど）を実行します。アップストリームの`onnxscript`オプティマイザーのバグに遭遇するモデルでは無効にしてください。

export_params (`bool`、*任意*、デフォルトは`True`) : モデルの重みを ONNX グラフに埋め込みます。`False` に設定すると、重みを含まないグラフをエクスポートします（重みは実行時に供給する必要があります）。

keep_initializers_as_inputs (`bool`, *任意*, デフォルトは `False`) : 重みの初期化器を明示的なグラフ入力として公開します。一部の古い ONNX ランタイム (opset < 9) で必要です。

`torch.onnx.export` を介してモデルを ONNX にエクスポートするための設定クラスです。

`DynamoConfig`（`dynamic`、`strict`、`dynamic_shapes`、`prefer_deferred_runtime_asserts_over_guards`）のすべてのフィールドを継承します。

## ExecutorchConfig[[transformers.exporters.ExecutorchConfig]]

#### transformers.exporters.ExecutorchConfig[[transformers.exporters.ExecutorchConfig]]

```python
transformers.exporters.ExecutorchConfig(export_format: ExportFormat = <ExportFormat.EXECUTORCH: 'executorch'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None, backend: str = 'xnnpack', alloc_graph_input: bool = True, alloc_graph_output: bool = True, alloc_mutable_buffers: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L167)

**パラメータ:**

backend (`str`、*任意*、デフォルトは `"xnnpack"`) : 対象の ExecuTorch バックエンド。サポートされている値: - `"xnnpack"` — XNNPACK ライブラリによる CPU 推論（デフォルト。どこでも実行可能）。 - `"cuda"` — ExecuTorch CUDA バックエンドによる GPU 推論。 - `"mlx"` — Apple Silicon 上で ExecuTorch MLX バックエンドによる GPU 推論。

alloc_graph_input (`bool`、*任意*、デフォルトは `True`) : メモリ計画パスがグラフの入力に対してアレーナメモリを確保するかどうかを指定します。`False` の場合、ランタイムはコピーせずに呼び出し元が提供した入力バッファを直接使用します。そのため、インプレースの `USER_INPUT_MUTATION`（例：`StaticCache` への書き込み）は、アレーナのコピーではなく呼び出し元のテンソルに反映されます。

alloc_graph_output (`bool`、*任意*、デフォルトは `True`) : メモリ計画パスがグラフの出力用にアレーナメモリを確保するかどうか。`False` の場合、呼び出し側が実行時に出力バッファをバインドする必要があります（`Method::set_output_data_ptr`）。出力を、変更された入力と同じバッファにバインドすることで、コピーアウトの往復を回避できます。

alloc_mutable_buffers (`bool`、*任意*、デフォルトは `True`) : メモリ計画パスが、可変バッファ（モデル常駐状態）のためにアリーナメモリを確保するかどうかを指定します。`MemoryPlanningPass` に渡されます。

ExecuTorch形式へモデルをエクスポートするための設定クラスです。

`DynamoConfig`（`dynamic`、`strict`、`dynamic_shapes`、`prefer_deferred_runtime_asserts_over_guards`）のすべてのフィールドを継承します。

## OpenVINOConfig[[transformers.exporters.OpenVINOConfig]]

#### transformers.exporters.OpenVINOConfig[[transformers.exporters.OpenVINOConfig]]

```python
transformers.exporters.OpenVINOConfig(export_format: ExportFormat = <ExportFormat.OPENVINO: 'openvino'>, dynamic: bool = False, strict: bool = False, dynamic_shapes: dict[str, Any] | None = None, prefer_deferred_runtime_asserts_over_guards: bool = False, quantizer: ExportQuantizer | None = None, output_path: str | PathLike | None = None, compress_to_fp16: bool = True, stateful: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/configs.py#L204)

**パラメータ:**

output_path (*str* または *PathLike*、*省略可*) : *.xml* ファイルの出力パス（対応する *.bin* も同じ場所に書き込まれます）。*None*（デフォルト）の場合、変換されたモデルは `openvino.Model` としてメモリ内に保持されます。

compress_to_fp16 (*bool*、*optional*、デフォルトは *True*) : 保存時に浮動小数点の重みを FP16 に圧縮します。ほとんどのモデルでは精度への影響はほぼなく、ディスク上のサイズを半分にできます。`output_path` が設定されている場合のみ適用されます。

stateful (*bool*, *optional*, defaults to *True*) : Fold round-tripped state tensors (KV cache, SSM states, …) into internal OV variables (`ReadValue`/``Assign`). The runtime then carries state across `infer()` calls instead of marshalling cache tensors through inputs/outputs on every step, and a fused `beam_idx`` input reorders state in-graph for beam search. No-op for models without round-tripped state (encoders, prefill-only exports). Set it to *False* for targets that take no stateful model, such as the NPU plugin.

`openvino.convert_model` を介してモデルを OpenVINO IR にエクスポートするための設定クラスです。

[*DynamoConfig*] (*dynamic*、*strict*、*dynamic_shapes*、*prefer_deferred_runtime_asserts_over_guards*) のすべてのフィールドを継承します。

## 量子化[[transformers.exporters.ExportQuantizer]]

#### transformers.exporters.ExportQuantizer[[transformers.exporters.ExportQuantizer]]

```python
transformers.exporters.ExportQuantizer(calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L32)

**パラメータ:**

calibration_dataset (`Iterable[dict]`、*任意*) : 量子化器がキャリブレーションに使用する入力辞書です。リスト、またはバッチがモデルの入力にコラートされる`DataLoader`を指定します。`~HfExporter.export_for_generation`の場合、これらは generate の kwarg であり、コンポーネントごとにキャリブレーションセットとして取得されます。`None`の場合、データが必要な量子化器は、エクスポート自身のサンプル入力でキャリブレーションを行い、警告が表示されます。

エクスポート時に適用されるポストトレーニング量子化器の基底クラスです。

Quantizer は、エクスポート時にサポートするエクスポート形式と、必要なパッケージ（exporter と同様に、テスト済みのバージョンを含む）を宣言します。また、変換を行う前に `torch.export` FX グラフを量子化するか（その場合、すべてのバックエンドが結果を受け取ります）、それともバックエンドが変換したモデル（`onnx_ir.Model`、`openvino.Model`）を量子化するかを指定します。exporter は最初にエクスポートに対して検証を行い、その後、そのモデルとエクスポートのサンプル入力引数を引数として `~ExportQuantizer.quantize` を呼び出します。新しい量子化手法を追加するには、これをサブクラス化して `quantize` を実装します。`CalibrationSet` は、キャリブレーションサンプルをモデル自身の入力引数にマッピングします。

#### quantize[[transformers.exporters.ExportQuantizer.quantize]]

```python
quantize(model: Any, sample_inputs: dict[str, Any], export_format: ExportFormat)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L77)

`model`（`quantizes_fx_graph` が真の場合は FX グラフ、それ以外の場合はバックエンドモデル）を量子化し、`calibration_dataset` 上でキャリブレーションした結果を返します。`calibration_dataset` が存在しない場合は、エクスポートの `sample_inputs` 上でキャリブレーションします。

#### validate_environment[[transformers.exporters.ExportQuantizer.validate_environment]]

```python
validate_environment(export_format: ExportFormat)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L67)

このクオンタイザーが`export_format`のエクスポートで実行できない場合、または必要なパッケージが欠落しているかバージョンが古すぎる場合は例外を発生させ、テストされたバージョンと異なる場合は警告を表示します。

#### with_calibration[[transformers.exporters.ExportQuantizer.with_calibration]]

```python
with_calibration(calibration_dataset: Iterable[dict[str, Any]])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L61)

`calibration_dataset`でキャリブレーションを行う、このクオンタイザーのコピー。

#### transformers.exporters.quantizers.CalibrationSet[[transformers.exporters.quantizers.CalibrationSet]]

```python
transformers.exporters.quantizers.CalibrationSet(calibration_dataset: Iterable[dict[str, Any]] | None, sample_inputs: dict[str, Any], transform: Callable[[dict[str, Any]], Any])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/base.py#L83)

モデル入力としてのキャリブレーションサンプルの再イテラブルビュー。

サンプルは、量子化器の`calibration_dataset`、またはそれが存在しない場合はエクスポート自身の`sample_inputs`（読み込まれた時点で警告が表示されます）です。トークナイザーの`BatchEncoding`のような、任意のマッピングであっても構いません。`transform`は、各パスにおいて1サンプルずつ遅延評価で、各フォワード kwarg のサンプルを、量子化モデルが受け取る形式（トレースされた kwargs、ONNX のフィード、OpenVINO のポートフィード）に変換します。

#### transformers.exporters.PT2EQuantizer[[transformers.exporters.PT2EQuantizer]]

```python
transformers.exporters.PT2EQuantizer(quantizer: Any, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_pt2e.py#L34)

**パラメータ:**

quantizer (`torchao.quantization.pt2e.quantizer.Quantizer`) : グラフにアノテーションを付与する PT2E クアンタイザーです。その quantize/dequantize 演算子は、ターゲットバックエンドがサポートしているものでなければなりません: inductor には `X86InductorQuantizer`、ONNX (QDQ) または OpenVINO、ExecuTorch には `XNNPACKQuantizer`。

calibration_dataset (`Iterable[dict]`、*任意*) : 観測者がキャリブレーションに使用する入力辞書（`ExportQuantizer`を参照）で、1回ずつのフォワードパス分です。バッチでキャリブレーションを行う場合は、単一のサンプルのリストではなく、サンプルをバッチ化された入力辞書にまとめる`DataLoader`を渡してください。

[PyTorch 2 Export (PT2E) 量子化](https://docs.pytorch.org/ao/main/pt2e_quantization/index.html)で FX グラフを量子化します: `prepare_pt2e` がオブザーバーを挿入し、キャリブレーションセットがそれらを駆動し、`convert_pt2e` がそれらを量子化/量子化解除オペレーションに置き換えます。すべてのエクスポートバックエンドで動作します。

例:

```python
>>> from torchao.quantization.pt2e.quantizer.x86_inductor_quantizer import (
...     X86InductorQuantizer,
...     get_default_x86_inductor_quantization_config,
... )
>>> from transformers.exporters import DynamoConfig, PT2EQuantizer

>>> x86 = X86InductorQuantizer().set_global(get_default_x86_inductor_quantization_config())
>>> DynamoConfig(quantizer=PT2EQuantizer(x86, calibration_dataset=samples))
```

#### transformers.exporters.OnnxRuntimeQuantizer[[transformers.exporters.OnnxRuntimeQuantizer]]

```python
transformers.exporters.OnnxRuntimeQuantizer(config: OnnxRuntimeStaticConfig | OnnxRuntimeDynamicConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L78)

変換した ONNX モデルを、ONNX Runtime 独自のツール (`onnxruntime.quantization`) で量子化します。`OnnxRuntimeStaticConfig` (デフォルト) を使用した `quantize_static`、または `OnnxRuntimeDynamicConfig` を使用した `quantize_dynamic` を使用できます。

例:

```python
>>> from transformers.exporters import (
...     OnnxConfig,
...     OnnxRuntimeDynamicConfig,
...     OnnxRuntimeQuantizer,
...     OnnxRuntimeStaticConfig,
... )

>>> static = OnnxRuntimeStaticConfig(per_channel=True)
>>> OnnxConfig(quantizer=OnnxRuntimeQuantizer(static, calibration_dataset=samples))
>>> OnnxConfig(quantizer=OnnxRuntimeQuantizer(OnnxRuntimeDynamicConfig()))
```

#### transformers.exporters.OnnxRuntimeStaticConfig[[transformers.exporters.OnnxRuntimeStaticConfig]]

```python
transformers.exporters.OnnxRuntimeStaticConfig(quant_format: Any = None, op_types_to_quantize: list[str] | None = None, per_channel: bool | None = None, reduce_range: bool | None = None, activation_type: Any = None, weight_type: Any = None, nodes_to_quantize: list[str] | None = None, nodes_to_exclude: list[str] | None = None, calibrate_method: Any = None, calibration_providers: list[str] | None = None, extra_options: dict[str, Any] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L41)

`onnxruntime.quantization.quantize_static` の引数: int8 アクティベーションと重み(デフォルトでは QDQ)、クオンタイザーの `calibration_dataset` でキャリブレーション済みです。`None` に設定されたフィールドは、ONNX Runtime のデフォルトが維持されます。各引数については [`quantize_static`](https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html) を参照してください。

#### transformers.exporters.OnnxRuntimeDynamicConfig[[transformers.exporters.OnnxRuntimeDynamicConfig]]

```python
transformers.exporters.OnnxRuntimeDynamicConfig(op_types_to_quantize: list[str] | None = None, per_channel: bool | None = None, reduce_range: bool | None = None, weight_type: Any = None, nodes_to_quantize: list[str] | None = None, nodes_to_exclude: list[str] | None = None, extra_options: dict[str, Any] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_onnxruntime.py#L62)

`onnxruntime.quantization.quantize_dynamic` の引数: int8 重み、実行時に量子化される活性化値、キャリブレーションなし。`None` に設定されたフィールドは、ONNX Runtime のデフォルトが維持されます。各引数については [`quantize_dynamic`](https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html) を参照してください。

#### transformers.exporters.NNCFOpenVINOQuantizer[[transformers.exporters.NNCFOpenVINOQuantizer]]

```python
transformers.exporters.NNCFOpenVINOQuantizer(config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L143)

変換済みの OpenVINO モデルを [NNCF](https://github.com/openvinotoolkit/nncf) で量子化します: `nncf.quantize` に `NNCFQuantizationConfig` (デフォルト) を指定するか、`nncf.compress_weights` に `NNCFWeightCompressionConfig` を指定します。

例:

```python
>>> import nncf
>>> from transformers.exporters import NNCFOpenVINOQuantizer, NNCFWeightCompressionConfig, OpenVINOConfig

>>> OpenVINOConfig(quantizer=NNCFOpenVINOQuantizer(calibration_dataset=samples))
>>> OpenVINOConfig(
...     quantizer=NNCFOpenVINOQuantizer(NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM))
... )
```

#### transformers.exporters.NNCFOnnxQuantizer[[transformers.exporters.NNCFOnnxQuantizer]]

```python
transformers.exporters.NNCFOnnxQuantizer(config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L175)

変換済みの ONNX モデルを、[NNCF](https://github.com/openvinotoolkit/nncf) の ONNX バックエンドを通じて量子化します: `nncf.quantize` に `NNCFQuantizationConfig` (デフォルトの int8 QDQ) を指定するか、`nncf.compress_weights` に `NNCFWeightCompressionConfig` (ONNX Runtime の `MatMulNBits` による int4) を指定します。

例:

```python
>>> import nncf
>>> from transformers.exporters import NNCFOnnxQuantizer, NNCFWeightCompressionConfig, OnnxConfig

>>> OnnxConfig(quantizer=NNCFOnnxQuantizer(calibration_dataset=samples))
>>> OnnxConfig(quantizer=NNCFOnnxQuantizer(NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM)))
```

#### transformers.exporters.NNCFTorchFXQuantizer[[transformers.exporters.NNCFTorchFXQuantizer]]

```python
transformers.exporters.NNCFTorchFXQuantizer(config: NNCFQuantizationConfig | NNCFWeightCompressionConfig | None = None, calibration_dataset: Iterable[dict[str, Any]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L231)

`torch.export` FX グラフを、その TorchFX バックエンド経由で [NNCF](https://github.com/openvinotoolkit/nncf) により量子化します: `NNCFQuantizationConfig` (デフォルトの `quantize`/`dequantize` オペレーション) を使用した `nncf.quantize`、または `NNCFWeightCompressionConfig` を使用した `nncf.compress_weights` です。`PT2EQuantizer` と同様に、変換のいずれよりも前に実行されるため、すべてのバックエンドがその結果を受け取ります。ExecuTorch は、weight-only の結果のみをローワーします: XNNPACK は `quantize`/`dequantize` オペレーションを委譲せず、ExecuTorch にはそれらのカーネルが存在しないためです。

例:

```python
>>> from transformers.exporters import DynamoConfig, NNCFTorchFXQuantizer

>>> DynamoConfig(quantizer=NNCFTorchFXQuantizer(calibration_dataset=samples))
```

#### transformers.exporters.NNCFQuantizationConfig[[transformers.exporters.NNCFQuantizationConfig]]

```python
transformers.exporters.NNCFQuantizationConfig(mode: Any = None, preset: Any = None, target_device: Any = None, subset_size: int | None = None, fast_bias_correction: bool | None = None, model_type: Any = None, ignored_scope: Any = None, advanced_parameters: Any = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L58)

`nncf.quantize` の引数: int8 アクティベーションと重み。クオンタイザーの `calibration_dataset` でキャリブレーションされます。`None` のままのフィールドは NNCF のデフォルトが維持されますが、`model_type` はデフォルトが `nncf.ModelType.TRANSFORMER` です。各引数については [`nncf.quantize`](https://openvinotoolkit.github.io/nncf/autoapi/nncf/index.html#nncf.quantize) を参照してください。

#### transformers.exporters.NNCFWeightCompressionConfig[[transformers.exporters.NNCFWeightCompressionConfig]]

```python
transformers.exporters.NNCFWeightCompressionConfig(mode: Any = None, ratio: float | None = None, group_size: int | None = None, ignored_scope: Any = None, all_layers: bool | None = None, sensitivity_metric: Any = None, subset_size: int | None = None, awq: bool | None = None, scale_estimation: bool | None = None, gptq: bool | None = None, lora_correction: bool | None = None, backup_mode: Any = None, compression_format: Any = None, advanced_parameters: Any = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/quantizers/quantizer_nncf.py#L76)

`nncf.compress_weights` の引数: データ認識型手法 (AWQ、スケール推定、GPTQ) を用いた weight-only の int8 または int4 です。int4 モードではこれらの手法が使用されます。int8 モードはデータ不要ですが、その他のモードではクオンタイザーの `calibration_dataset` でキャリブレーションを行います。`gptq` と `lora_correction` は OpenVINO 専用です。`None` に設定されたフィールドは NNCF のデフォルト値を維持します。各引数については [`nncf.compress_weights`](https://openvinotoolkit.github.io/nncf/autoapi/nncf/index.html#nncf.compress_weights) を参照してください。

## ユーティリティ[[transformers.exporters.utils.get_leaf_tensors]]

`export_for_generation`を支える低レベルの関数群です。モデルの分解と各コンポーネントのエクスポートの間に介入する必要がある場合に便利です。

#### transformers.exporters.utils.get_leaf_tensors[[transformers.exporters.utils.get_leaf_tensors]]

```python
transformers.exporters.utils.get_leaf_tensors(obj: Any)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L340)

**パラメータ:**

obj (`Any`) : テンソル、dataclass、dict、list、tuple、またはそれらの任意のネスト。

**戻り値:** `dict[str, torch.Tensor]`

ドット区切りパス文字列からテンソルへのフラットなマッピング。

ネストされた構造から、再帰的にすべてのリーフテンソルを取得します。

#### transformers.exporters.utils.prepare_for_export[[transformers.exporters.utils.prepare_for_export]]

```python
transformers.exporters.utils.prepare_for_export(model: PreTrainedModel | torch.nn.Module, inputs: MutableMapping[str, Any])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L407)

エクスポート用にモデルと入力を設定します。`model` と `inputs` の両方をインプレースで変更し、`(model, inputs, output_flags)` を返します。`output_flags` には、`use_cache` や `return_dict` などの値が `inputs` からポップされて保持されます（トレース中に `patch_model_config` によって `model.config` に可逆的に適用されます）。

- ラベル入力(`labels`、`future_values`)を除去します。損失の計算はサポートされていません。
- `inputs` から出力フラグ（`use_cache`、`return_dict` など）を取り除き、トレースされた kwargs として表示されないようにします。これらの値は返され、トレースブロックによって `model.config` に適用されます。
- `@register_export_input_preparer` によって登録されたデータ依存の vision/audio kwargs を事前計算し、`inputs` に書き込みます。
- モデルの`dtype` / `device`に合わせて、入力テンソルをキャストします。

#### transformers.exporters.utils.decompose_prefill_decode[[transformers.exporters.utils.decompose_prefill_decode]]

```python
transformers.exporters.utils.decompose_prefill_decode(model: PreTrainedModel, inputs: dict[str, Any], generation_config: Any = None, multi_token_decode: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L811)

**戻り値:** `dict[str, tuple[torch.nn.Module, dict]]`

`{"prefill": (model, prefill_inputs), "decode": (model, decode_inputs)}`.

`model.generate()` を実行し、prefill と decode の入力を取得します。

完全な生成機構を再利用することで、すべてのアーキテクチャ（decoder-only、SSM、encoder-decoder、マルチモーダルなど）が、ループを再実装することなく正しい入力を受け取ります。

`generation_config` は `generate()` に転送されます（デフォルトではモデル自身の設定が使用されます）。そのため、キャプチャされる入力には、`generate()` が構築するであろうキャッシュが使用されます。`cache_implementation="static"` と `max_cache_len=N` を指定して渡すことで、デコード入力に**静的にサイズ指定された**キャッシュをキャプチャできます。これが static-cache エクスポートの基盤となります。`max_cache_len` はキャプチャとは独立してキャッシュのサイズを決定するため、エクスポートされたデコードは増加するキャッシュではなく、固定の `[..., N, ...]` キャッシュを使用します。

`multi_token_decode` が設定されている場合、`decode` コンポーネントは**マルチトークン**デコードとしてキャプチャされます。これは2つの連続するデコードステップをマージしたものです（`_merge_decode_calls` を参照）。これにより、クエリシーケンス軸がシンボリックな状態を維持されます（単一トークンのデコードでは、その軸が 1 に特殊化されてしまうためです）。その後、1 トークン（通常のデコード）と複数トークン（過去からの継続、またはキャッシュが空の場合の通常のプリフィル）の両方を処理します。それ以外の場合、`decode` は従来の単一トークンデコードです。

#### transformers.exporters.utils.decompose_multimodal[[transformers.exporters.utils.decompose_multimodal]]

```python
transformers.exporters.utils.decompose_multimodal(model: PreTrainedModel, inputs: dict[str, Any])
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L934)

**戻り値:** `dict[str, tuple[torch.nn.Module, dict]]`

検出された各サブモジュール（画像/音声エンコーダー、プロジェクター、言語モデル、lm_head）ごとに、`name: (module, inputs)` エントリが1つあります。

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

- ``ValueError`` -- モデル上で既知のマルチモーダルサブモジュールが見つからない場合。

単一の forward passで、各マルチモーダルサブモジュールへの入力をキャプチャします。

属性名（vision tower、projector、language model、lm_head など）に基づいて既知のマルチモーダルサブモジュールをすべて検出し、`model(**inputs)` の呼び出し1回中にそれらの forward kwargs を取得します。

各サブモジュールは、独立したエクスポートのために、`name: (module, inputs)` のエントリとして個別に返されます。トークンマージのステップ（マルチモーダルモデルにおける `masked_scatter` など）は、意図的にエクスポートされたグラフの外に置かれています。デコーダーを実行する前にエンコーダーの出力から `inputs_embeds` を組み立てることは、呼び出し側の責任です。

#### transformers.exporters.utils.decompose_for_generation[[transformers.exporters.utils.decompose_for_generation]]

```python
transformers.exporters.utils.decompose_for_generation(model: PreTrainedModel, inputs: dict[str, Any], generation_config: Any = None, multi_token_decode: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L978)

**パラメータ:**

model : 生成モデル。`model.generate(**inputs)` をサポートしている必要があります。

inputs : **Generate** kwargs — `model.generate(**inputs)` に渡す引数。

generation_config : キャプチャ中に `generate()` に転送される任意の `GenerationConfig`。静的にサイズ指定されたキャッシュに対してエクスポートするには、`cache_implementation="static"` と `max_cache_len=N` を指定して渡します（`decompose_prefill_decode` を参照）。

multi_token_decode : `True`の場合、`decode`コンポーネントをマルチトークンデコードとしてキャプチャします（動的クエリシーケンス軸：一度に複数のトークン — 過去からの継続、またはキャッシュが空の場合の通常のプリフィル）。シングルトークンデコードは動的に保つことができません（`decompose_prefill_decode`を参照）。

**戻り値:** `{component_name

(submodel, forward_inputs)}`. Keys are `"prefill"` / `"decode"` for plain generative models and `"<modality>_encoder"` / `"multi_modal_projector"` / `"language_model"` / `"lm_head"` / `"decode"` for multi-modal generative models.

生成モデルを、独立してエクスポート可能な`(model, forward_inputs)`のペアに分解します。

`decompose_prefill_decode` を実行し、実際の `model.generate(**inputs, max_new_tokens=2)` から prefill と decode の forward kwargs を取得します。prefill がマルチモーダルである場合(`is_multimodal` に従う)、`decompose_multimodal` を介して、サブモジュール(ビジョン/オーディオエンコーダー、プロジェクター、言語モデル、`lm_head`)ごとに1エントリずつ分割します。

#### transformers.exporters.utils.is_multimodal[[transformers.exporters.utils.is_multimodal]]

```python
transformers.exporters.utils.is_multimodal(model: PreTrainedModel | torch.nn.Module)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py#L925)

モデルがマルチモーダルであり、モーダルエンコーダーと言語モデルを備えている場合は`True`を返します。

`PreTrainedModel` ではないモデル（例：素の `nn.Module`）には、正規の `get_encoder`/`get_decoder` アクセサーが存在せず、マルチモーダルではないことは自明であるため、`False` にショートサーキットします。