Memperluas exporter

torch.export menelusuri model menjadi sebuah graf, tahap-tahap selanjutnya mentransformasi graf tersebut, dan tahap akhir menurunkan atau mengeluarkannya 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.

Keduanya berada di registry di 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 ke beberapa backend, seperti loop yang bergantung pada data, cache stateful 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 ekspor berlangsung.

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

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

Eksporertukar metode sebelum pelacakan dan memulihkannya setelahnya, sehingga patch hanya memengaruhi ekspor. Beberapa variasi:

• 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 perbaikan (fix) alih-alih tambalan (patch) ketika Anda perlu menulis ulang graf setelah pelacakan (tracing). Mekanismenya sama, yaitu fungsi yang didekorasi di dalam 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 (lihat 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 membangunnya kembali (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 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). Cari daftar lengkap patch di file tersebut:

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 sehingga node shape-guard yang baru diperkenalkan diperbaiki sebelum lowering. Menggunakan registry @register_patch("onnx", ...) yang sama.
3. Perbaikan node FX: menulis ulang node graph yang tidak dapat diturunkan oleh exporter ONNX, seperti operasi alias, view in-place, dan assert mati. 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 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).

1. Persiapan backend: pindahkan model ke perangkat dan dtype target serta pilih partisionernya (prepare_for_xnnpack, prepare_for_cuda). Tambahkan backend dengan mendaftarkan prepare_for_<name> di _BACKEND_PREPARE.
2. Patch Torch: ganti 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 di mana perbaikan memerlukan konteks program 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 operasi sim Python ke executorch_prim.* atau menulis ulang pow sebagai rantai mul. Perluas dengan @register_fx_node_fix("executorch").

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 menonaktifkan optimasi onnxscript untuk model-model tersebut. Setiap entri mencatat masalah upstream di samping nama model. Daftar ini diharapkan menyusut seiring dengan perbaikan bug upstream, sehingga entri baru harus merujuk pada bug upstream yang spesifik, bukan sekadar menonaktifkan optimasi secara sewenang-wenang.

EXPORT_SKIPS, opsi untuk 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 membawa alasan yang menyebutkan perubahan sisi model yang diperlukan. Daftar ini juga diharapkan menyusut, bukan bertambah.