# Memperluas exporter

`torch.export` menelusuri model menjadi sebuah graf, tahap-tahap selanjutnya mentransformasi graf tersebut, dan tahap terakhir menurunkan atau menghasilkan graf untuk runtime target. Sebagian besar model melewati proses ini tanpa perubahan. Ketika ada pola PyTorch yang tidak dapat ditangani oleh backend, exporter menerapkan workaround kecil pada tahap tersebut, alih-alih mengedit model.

Tambahkan solusi sementara dengan menulis satu fungsi dan mendaftarkannya dengan dekorator. Setiap solusi sementara harus ditempatkan pada tahap terendah yang dapat mengekspresikannya dengan jelas.

## Perbaikan dan perbaikan

Solusi sementara berupa patch atau fix. Keduanya berbeda dalam hal apakah dapat dibatalkan atau tidak.

|              | Patch                                                                          | Perbaiki                                                                                   |
| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Fungsinya | Mengganti atribut (op `torch`, internal ExecuTorch, atau metode model) selama proses ekspor | Menulis ulang graf atau program yang ditelusuri                                                  |
| Dibatalkan     | Ya, versi asli dipulihkan setelahnya                                        | Tidak, itu memperbaiki artefak sebelum tahap berikutnya dijalankan                                |
| Daftar dengan | `@register_patch(backend, *paths)`                                            | `@register_fx_node_fix(backend)` atau `@register_fx_program_fix(backend)`               |

Keduanya berada di sebuah registry di [exporters/utils.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py), dan exporter menginstal semua yang terdaftar untuk backend-nya pada tahap yang tepat.

Gunakan patch ketika masalahnya adalah bug lowering pada satu backend: terjemahan ONNX yang hilang, keanehan validasi ORT, atau dekomposisi FX yang menghasilkan op mati. Workaround tetap berada di exporter, dan kode modeling tetap bersih.

Ketika blok pola diekspor di beberapa backend, seperti loop yang bergantung pada data, cache berstatus di luar `Cache`, atau perhatian split-loop yang ditulis manual, perbaiki modelnya. Memperbaikinya sekali di dalam model akan membantu semua exporter.

## Tambahkan patch

Misalkan sebuah metode model melakukan sesuatu yang tidak dapat ditelusuri oleh `torch.export`. `NllbMoeTop2Router._cast_classifier` dari NLLB-MoE mengubah bobot klasifikator ke dtype lain, yang tidak dapat ditelusuri. Ganti dengan no-op selama proses export berlangsung.

Tulis sebuah factory yang menerima metode asli dan mengembalikan penggantinya, lalu daftarkan factory tersebut terhadap jalur bertitik (dotted path) metode tersebut:

```python
from transformers.exporters.utils import register_patch

@register_patch("dynamo", "transformers.models.nllb_moe.modeling_nllb_moe.NllbMoeTop2Router._cast_classifier")
def _patch_classifier_cast(_original):
    # Replace the untraceable dtype cast with a no-op during export.
    return lambda self, *args, **kwargs: None
```

Exporter mengganti metode sebelum pelacakan dan memulihkannya setelahnya, sehingga patch hanya memengaruhi ekspor. Beberapa variasinya:

- Lewati jalur tambahan untuk berbagi satu pabrik di antara beberapa titik pemanggilan, misalnya `@register_patch("dynamo", path_a, path_b)`.
- Patch sebuah op `torch` dengan menunjuk path ke op tersebut, misalnya `@register_patch("onnx", "torch.where")`. Factory menerima op asli sebagai argumennya, sehingga penggantian dapat memanggilnya.
- Tulis fix, bukan patch, ketika Anda perlu menulis ulang graph setelah tracing. Mekanismenya sama, yaitu fungsi yang didekorasi di registry yang sesuai.

## Referensi tahap

Sumber setiap exporter menandai tahapannya sebagai blok komentar `# ── Stage N: … ──`, sehingga file dan referensi ini selaras. Lihat di sana untuk operasi dan kelas persis yang ditangani oleh setiap tahap.

### DynamoExporter

Ekspor dasar menjalankan satu tahap patch dan empat helper, secara berurutan, di dalam `DynamoExporter.export_program` (lihat [exporter_dynamo.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_dynamo.py)).

1. Patch tanda tangan forward: memberikan `model.forward` tanda tangan argumen datar agar `torch.export` tidak membundel input menjadi satu tuple `**kwargs`. Ini bersifat internal dan bukan titik ekstensi.
2. Patch model: ganti metode model yang tidak dapat dilacak dengan padanan yang aman untuk ekspor selama pelacakan. Perluas dengan `@register_patch("dynamo", ...)`.
3. Pendaftaran Pytree: daftarkan setiap `Cache` dan `ModelOutput` agar `torch.export` dapat meratakan dan membangun ulang objek tersebut (biasanya terjadi secara otomatis). Tambahkan cabang ke `_flatten_to_context` / `_unflatten_from_context` untuk tipe yang tidak dapat dijangkau oleh penelusuran atribut.
4. Bentuk dinamis: tetapkan `Dim.AUTO` ke setiap tensor dan cache daun ketika `dynamic=True`. Timpa dengan `DynamoConfig.dynamic_shapes`.
5. Bersihkan state: reset atribut tensor yang diset oleh model di dalam `forward` yang ditinggalkan `torch.export` sebagai tensor palsu. Perluas dengan menambahkan nama atribut ke `_STATEFUL_CACHE_ATTRS`.

### OnnxExporter

`OnnxExporter` menambahkan lima tahap di sekitar `torch.onnx.export` (lihat [exporter_onnx.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_onnx.py)). Cari daftar lengkap patch di file tersebut:

```bash
grep -nE "^def (_patch_|_fix_|_aten_)" src/transformers/exporters/exporter_onnx.py
```

1. Patch Torch: ganti ops `torch` yang tidak dapat diterjemahkan apa adanya oleh exporter ONNX. Perluas dengan `@register_patch("onnx", ...)`.
2. Perbaikan ONNX: jalankan ulang perbaikan node setelah `run_decompositions` agar node shape-guard yang baru diperkenalkan diperbaiki sebelum lowering. Menggunakan registry `@register_patch("onnx", ...)` yang sama.
3. Perbaikan node FX: menulis ulang ulang node graph yang tidak dapat diturunkan oleh exporter ONNX, seperti operasi alias, view in-place, dan assert yang tidak terpakai. Perluas dengan `@register_fx_node_fix("onnx")`.
4. Terjemahan ONNX: sediakan lowering kustom untuk op aten di mana default tidak ada atau memiliki bug (misalnya `aten.index_put` atau `aten._grouped_mm`). Tambahkan fungsi `_aten_*` ke `_ONNX_TRANSLATION_TABLE`.
5. Perbaikan ONNX IR: tulis ulang program ONNX yang sudah selesai untuk menghindari bug ONNX Runtime (misalnya dengan memaksa `TopK(sorted=True)`). Tambahkan fungsi `_fix_ir_*` ke `_IR_FIXES`.

### ExecutorchExporter

`ExecutorchExporter` menambahkan lima tahap di sekitar `to_edge_transform_and_lower` dan `to_executorch`, dimulai dengan persiapan backend (lihat [exporter_executorch.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_executorch.py)).

1. Persiapan backend: pindahkan model ke perangkat dan dtype target, lalu pilih partisionernya (`prepare_for_xnnpack`, `prepare_for_cuda`). Tambahkan backend dengan mendaftarkan `prepare_for_<name>` di `_BACKEND_PREPARE`.
2. Torch patches: mengganti ops `torch` yang tidak dapat diterima oleh backend ExecuTorch, seperti `split_copy`, `chunk`, dan `topk(k>dim)`. Perluas dengan `@register_patch("executorch", ...)`.
3. Patch ExecuTorch: mengganti bagian internal ExecuTorch yang menyebabkan crash pada graf bentuk dinamis yang valid. Menggunakan registry `@register_patch("executorch", ...)` yang sama.
4. Perbaikan program FX: perbaiki program yang diekspor ketika perbaikan memerlukan konteks program secara keseluruhan, seperti memperlebar batasan rentang atau mengisi metadata placeholder yang hilang. Perluas dengan `@register_fx_program_fix("executorch")`.
5. Perbaikan node FX: menulis ulang node individual, seperti memetakan Python sym ops ke `executorch_prim.*` atau menulis ulang `pow` sebagai rantai `mul`. Perluas dengan `@register_fx_node_fix("executorch")`.

## Tambahkan backend

Backend adalah subclass dari `HfExporter`, ditambah sebuah config. `export_program` menelusuri satu graf dan mengembalikan program backend beserta metadata yang dicatat selama penelusuran, `save_program` menulis satu program ke disk, dan `load_program` membacanya kembali. `~HfExporter.export` dan `~HfExporter.export_for_generation` membangun `ExportedModel` di atasnya. Dengan membuat subclass dari `DynamoExporter`, penelusuran dan metadata-nya dapat digunakan kembali, sehingga backend hanya perlu mengonversi `ExportedProgram`:

```python
from dataclasses import dataclass

from transformers.exporters import DynamoConfig, DynamoExporter, register_backend

@dataclass
class MyConfig(DynamoConfig):
    export_format: str = "my_format"

class MyExporter(DynamoExporter):
    export_format = "my_format"
    config_class = MyConfig
    program_suffix = ".bin"

    def export_program(self, model, sample_inputs, config):
        exported_program, metadata = super().export_program(model, sample_inputs, config)
        return convert(exported_program), metadata

    @classmethod
    def save_program(cls, program, path):
        program.save(path)

    @classmethod
    def load_program(cls, path):
        return load(path)

register_backend(MyExporter)
```

Untuk memanggil ekspor-nya, daftarkan `ModelRunner` dengannya: `register_backend(MyExporter, MyRunner)`.

Kelas auto kemudian meneruskan `"my_format"` kepada mereka, dan `ExportedModel.from_pretrained` memuat ekspor tersimpannya:

```python
from transformers.exporters import AutoExportConfig, AutoHfExporter, ExportedModel

config = AutoExportConfig.from_dict({"export_format": "my_format", "dynamic": True})
exported = AutoHfExporter.from_config(config).export(model, inputs, config)
exported.save_pretrained("my-model-my_format")  # model.bin, export.json, config.json
exported.push_to_hub("my-org/my-model-my_format")

loaded = ExportedModel.from_pretrained("my-org/my-model-my_format")
```

## Solusi sementara yang diketahui di hulu

Beberapa kelas model mengalami bug yang terkonfirmasi pada optimizer graf `onnxscript` (constant folding yang crash pada `SplitToSequence`, inisialisasi FPN yang hilang). [ONNX_DISABLE_OPTIMIZE](https://github.com/huggingface/transformers/blob/main/tests/exporters/test_export.py) menonaktifkan optimasi `onnxscript` untuk model-model tersebut. Setiap entri mencatat isu upstream di samping nama model. Daftar ini diperkirakan akan menyusut seiring dengan diperbaikinya bug di upstream, sehingga entri baru harus merujuk pada bug upstream yang spesifik, bukan sekadar menonaktifkan optimasi secara sewenang-wenang.

[EXPORT_SKIPS](https://github.com/huggingface/transformers/blob/main/tests/exporters/test_export.py) mengecualikan sejumlah kelas model dari proses ekspor secara keseluruhan ketika model tersebut secara fundamental tidak dapat diekspor apa adanya (alur kontrol yang bergantung pada data yang tidak dapat divektorisasi, atau modul yang diperlakukan sebagai argumen forward). Setiap entri menyertakan alasan yang menyebutkan perubahan sisi model yang diperlukan. Daftar ini juga diharapkan akan menyusut, bukan bertambah.

