# Ekspor kuantisasi

Setiap konfigurasi [export](./exporters) dapat menerima `quantizer`, yang melakukan kuantisasi model selama proses export. Kuantizer-kuantizer ini berada di `transformers.exporters.quantizers`, dan masing-masing dijalankan pada titik tetap dari export: pada grafik FX `torch.export`, sebelum konversi apa pun, atau pada model yang dikonversi oleh backend.

| Quantizer | Mengkuantisasi | Dynamo | ONNX | ExecuTorch | OpenVINO |
| --- | --- | --- | --- | --- | --- |
| [PT2EQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.PT2EQuantizer) | graf FX, dengan kuantisasi PyTorch 2 Export (PT2E) | 🟢 | 🟢 | 🟢 | 🟢 |
| [NNCFTorchFXQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.NNCFTorchFXQuantizer) | graf FX, dengan [NNCF](https://github.com/openvinotoolkit/nncf) | 🟢 | 🟢 | 🟢 (hanya-berat) | 🟢 |
| [OnnxRuntimeQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.OnnxRuntimeQuantizer) | model ONNX, dengan `onnxruntime.quantization` | 🔴 | 🟢 | 🔴 | 🔴 |
| [NNCFOnnxQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.NNCFOnnxQuantizer) | model ONNX, dengan [NNCF](https://github.com/openvinotoolkit/nncf) | 🔴 | 🟢 | 🔴 | 🔴 |
| [NNCFOpenVINOQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.NNCFOpenVINOQuantizer) | model OpenVINO, dengan [NNCF](https://github.com/openvinotoolkit/nncf) | 🔴 | 🔴 | 🔴 | 🟢 |

Ekspor memeriksa kuantizer terhadap backend dan paket yang terpasang sebelum pelacakan, sehingga ketidakcocokan akan gagal lebih awal. Sama seperti exporter, setiap kuantizer mencantumkan versi paket yang telah diuji, dan memberikan peringatan jika versi Anda berbeda.

Contoh di bawah ini mengkuantisasi klasifikator sentimen ke int8 dengan ONNX Runtime, lalu menjalankannya.

```python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from transformers.exporters import OnnxConfig, OnnxExporter, OnnxRuntimeQuantizer

model_id = "distilbert/distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForSequenceClassification.from_pretrained(model_id)

texts = [
    "A wonderful, heartfelt film.",
    "The plot was dull and the acting worse.",
    "I would watch it again tomorrow.",
    "Two hours I will never get back.",
]
calibration_dataset = [tokenizer(text, return_tensors="pt") for text in texts]
inputs = tokenizer("An absolute delight from start to finish.", return_tensors="pt")

config = OnnxConfig(dynamic=True, quantizer=OnnxRuntimeQuantizer(calibration_dataset=calibration_dataset))
exported = OnnxExporter().export(model, inputs, config)

logits = exported(**inputs).logits
print(model.config.id2label[int(logits.argmax())])  # POSITIVE
```

## PT2E

[PT2EQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.PT2EQuantizer) membungkus kuantizer PT2E, baik dari torchao maupun dari runtime target, dan menjalankannya pada grafik FX (`prepare_pt2e` → kalibrasi → `convert_pt2e`), sehingga kompatibel dengan semua backend. Setiap kuantizer PT2E menyuntikkan operasi quantize/dequantize-nya sendiri, jadi pilihlah yang didukung oleh runtime Anda:

| Di mana Anda akan menjalankan | Kuantizer PT2E | Impor dari |
| --- | --- | --- |
| PyTorch inductor, ONNX Runtime (QDQ), OpenVINO | `X86InductorQuantizer` | `torchao.quantization.pt2e.quantizer.x86_inductor_quantizer` |
| Backend XNNPACK ExecuTorch | `XNNPACKQuantizer` | `executorch.backends.xnnpack.quantizer.xnnpack_quantizer` |

Untuk ExecuTorch, bungkus `XNNPACKQuantizer` milik ExecuTorch itu sendiri:

```python
from executorch.backends.xnnpack.quantizer.xnnpack_quantizer import (
    XNNPACKQuantizer,
    get_symmetric_quantization_config,
)
from transformers.exporters import ExecutorchConfig, PT2EQuantizer

xnnpack = XNNPACKQuantizer().set_global(get_symmetric_quantization_config())
config = ExecutorchConfig(backend="xnnpack", quantizer=PT2EQuantizer(xnnpack, calibration_dataset=calibration_dataset))
```

Kuantisasi model generatif melalui `~HfExporter.export_for_generation`. Di sini, `calibration_dataset` berisi kwargs generate, seperti `inputs`, dan setiap komponen melakukan kalibrasi pada input yang ditangkap untuknya. Model teks saja memiliki komponen `prefill` dan `decode`; model multimodal memecah prefill-nya lebih lanjut, menjadi encoder modalitasnya (seperti `image_encoder`), projectornya, `language_model`-nya, dan `lm_head`-nya (lihat [Cara kerja `export_for_generation`](./exporters#how-exportforgeneration-works)).

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

model_id = "meta-llama/Llama-3.2-1B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

prompts = ["The capital of France is", "Photosynthesis turns sunlight into", "The first moon landing was in"]
calibration_dataset = [tokenizer(prompt, return_tensors="pt") for prompt in prompts]
inputs = tokenizer("Once upon a time", return_tensors="pt")

x86 = X86InductorQuantizer().set_global(get_default_x86_inductor_quantization_config())
config = DynamoConfig(dynamic=True, quantizer=PT2EQuantizer(x86, calibration_dataset=calibration_dataset))
exported = DynamoExporter().export_for_generation(model, inputs, config)  # "prefill" and "decode" components
```

Pada OpenVINO, bobot PT2E tetap dalam presisi penuh di belakang pasangan quantize/dequantize, yang kemudian dikonversi oleh OpenVINO menjadi `FakeQuantize` dan dikompres menjadi int8 oleh OpenVINO itu sendiri.

## ONNX Runtime

[OnnxRuntimeQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.OnnxRuntimeQuantizer) menjalankan `quantize_static` secara default (aktivasi dan bobot int8 QDQ, dikalibrasi pada `calibration_dataset`), seperti pada contoh di atas, dengan argumen dari [OnnxRuntimeStaticConfig](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.OnnxRuntimeStaticConfig). Dengan [OnnxRuntimeDynamicConfig](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.OnnxRuntimeDynamicConfig), ia menjalankan `quantize_dynamic` (bobot int8, aktivasi dikuantisasi saat runtime, tanpa kalibrasi).

```python
from transformers.exporters import OnnxRuntimeDynamicConfig, OnnxRuntimeStaticConfig

config = OnnxConfig(
    quantizer=OnnxRuntimeQuantizer(OnnxRuntimeStaticConfig(per_channel=True), calibration_dataset=calibration_dataset)
)
config = OnnxConfig(quantizer=OnnxRuntimeQuantizer(OnnxRuntimeDynamicConfig()))
```

## NNCF

Ketiga kuantizer NNCF dalam tabel di atas menjalankan `nncf.quantize` secara default (aktivasi dan bobot int8, dikalibrasi pada `calibration_dataset`, dengan `model_type=nncf.ModelType.TRANSFORMER` kecuali Anda meneruskan nilai lain), dengan argumen dari [NNCFQuantizationConfig](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.NNCFQuantizationConfig). Dengan [NNCFWeightCompressionConfig](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.NNCFWeightCompressionConfig), mereka menjalankan `nncf.compress_weights` (hanya bobot int8 atau int4, dengan AWQ dan estimasi skala untuk int4, serta koreksi GPTQ dan LoRA pada OpenVINO). ExecuTorch hanya menurunkan hasil hanya-bobot dari [NNCFTorchFXQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.NNCFTorchFXQuantizer).

```python
import nncf
from transformers.exporters import (
    DynamoConfig,
    NNCFOnnxQuantizer,
    NNCFOpenVINOQuantizer,
    NNCFTorchFXQuantizer,
    NNCFWeightCompressionConfig,
    OnnxConfig,
    OpenVINOConfig,
    OpenVINOExporter,
)

int4 = NNCFWeightCompressionConfig(mode=nncf.CompressWeightsMode.INT4_SYM, group_size=128)

# OpenVINO: int8 activations and weights, or weight-only int4
openvino_int8 = OpenVINOConfig(quantizer=NNCFOpenVINOQuantizer(calibration_dataset=calibration_dataset))
openvino_int4 = OpenVINOConfig(quantizer=NNCFOpenVINOQuantizer(int4))
# ONNX: weight-only int4, as ONNX Runtime's `MatMulNBits`
onnx_int4 = OnnxConfig(quantizer=NNCFOnnxQuantizer(int4))
# Dynamo: int8 on the FX graph
dynamo_int8 = DynamoConfig(quantizer=NNCFTorchFXQuantizer(calibration_dataset=calibration_dataset))

exported = OpenVINOExporter().export(model, inputs, openvino_int4)
```

Aktivasi Int8 menjalankan matmul int8, yang mengalami saturasi pada CPU tanpa VNNI (Intel hanya AVX2 dan AMD Zen 2 atau lebih lama), sehingga akurasi yang lebih rendah dapat diharapkan di sana. Kompresi hanya-berat (weight-only) mempertahankan matmul dalam titik apung (floating point).

## Kalibrasi

`calibration_dataset` dari sebuah quantizer adalah iterable dari input model, seperti daftar output tokenizer atau `DataLoader` yang batch-nya dicollate menjadi input model. Ini adalah atribut biasa, sehingga Anda juga dapat menyetelnya setelah membuat quantizer (`quantizer.calibration_dataset = samples`). Jika diabaikan, quantizer yang membutuhkan data akan melakukan kalibrasi pada input sampel dari export itu sendiri, disertai peringatan, karena satu sampel dapat membiaskan rentang yang diamati. Quantizer yang tidak membutuhkan data (kuantisasi ONNX Runtime dinamis, kompresi bobot int8) tidak pernah membacanya.

## Resep yang berbeda untuk setiap komponen

Lewatkan dict `{component: config}` ke `~HfExporter.export_for_generation` untuk mengkuantisasi setiap komponen dengan ketentuan masing-masing. Untuk model di atas, gunakan static int8 pada `prefill` dan dynamic int8 yang lebih ringan pada `decode`:

```python
dynamic_x86 = X86InductorQuantizer().set_global(get_default_x86_inductor_quantization_config(is_dynamic=True))

config = {
    "prefill": DynamoConfig(dynamic=True, quantizer=PT2EQuantizer(x86)),
    "decode": DynamoConfig(dynamic=True, quantizer=PT2EQuantizer(dynamic_x86)),
}
exported = DynamoExporter().export_for_generation(model, inputs, config)
```

Dict tersebut harus menamai setiap komponen yang dihasilkan oleh [decompose_for_generation()](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.utils.decompose_for_generation) (model multimodal menambahkan encoder-nya, dan dapat memisahkan `language_model` serta `lm_head`). Komponen yang konfigurasinya tidak mengatur quantizer tetap berada dalam presisi penuh. Dalam dict ini, `calibration_dataset` dari quantizer berisi kwargs forward komponen, bukan kwargs generate.

## Tambahkan kuantizer

Quantizer berada di `transformers.exporters.quantizers`, satu kelas per toolchain dan representasi. Subclass [ExportQuantizer](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.ExportQuantizer) dan deklarasikan:

- `quantizes_fx_graph`: `True` untuk grafik FX `torch.export`, sebelum konversi apa pun (sehingga setiap backend mengambil hasilnya), atau `False` (default) untuk model yang dikonversi oleh backend (`onnx_ir.Model`, `openvino.Model`).
- `supported_formats`: format ekspor yang dikuantisasi. Ekspor menolak format lain sebelum pelacakan.
- `required_packages`, dan secara opsional `min_versions` dan `tested_versions`: apa yang diimpor. Ekspor memeriksa apakah paket-paket tersebut terinstal sebelum pelacakan, memicu error jika versi di bawah minimum, dan memberikan peringatan jika versi berbeda dari versi yang diuji.

Lalu implementasikan `quantize(model, sample_inputs, export_format)`. `model` adalah grafik FX atau model backend, dan `sample_inputs` adalah input dari export itu sendiri. Lakukan kalibrasi pada [CalibrationSet](/docs/transformers/main/id/main_classes/exporters#transformers.exporters.quantizers.CalibrationSet): komponen ini membaca `calibration_dataset` dari quantizer (atau `sample_inputs` jika tidak ada) dan memetakan setiap sampel ke input model dengan feed: `traced_inputs` dari `transformers.exporters.quantizers.utils` untuk grafik FX, serta `onnx_feed` atau `openvino_feed` dari `transformers.exporters.utils` untuk ONNX atau OpenVINO.

```python
from transformers.exporters import ExportFormat
from transformers.exporters.quantizers import CalibrationSet, ExportQuantizer
from transformers.exporters.utils import onnx_feed

class MyOnnxQuantizer(ExportQuantizer):
    supported_formats = (ExportFormat.ONNX,)
    required_packages = ("my_toolkit",)
    tested_versions = {"my_toolkit": "1.0.0"}

    def quantize(self, model, sample_inputs, export_format):
        import my_toolkit

        names = [graph_input.name for graph_input in model.graph.inputs]
        calibration = CalibrationSet(self.calibration_dataset, sample_inputs, lambda sample: onnx_feed(names, sample))
        return my_toolkit.quantize(model, calibration_feeds=list(calibration))
```

