# Pemetaan fusi (fitur eksperimental)

Pemetaan fusion menyediakan cara opt-in untuk mengganti submodul model saat pemuatan sambil mempertahankan format checkpoint asli.

Dibangun di atas:

- [Monkey patching](./monkey_patching) untuk mengganti kelas modul sebelum instansiasi model.
- [Pemuatan bobot dinamis](./weightconverter) untuk memetakan bobot antara tata letak runtime asli dan yang digabungkan.

> [!WARNING]
> Pemetaan fusi adalah fitur pemuatan eksperimental. Fitur ini mengubah struktur modul runtime dan dapat memengaruhi perilaku model. Gunakan hanya jika Anda secara eksplisit menginginkan tata letak runtime yang terfusi.

## Mulai cepat

Fusion is enabled through [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) with `fusion_config`:

```python
from transformers import AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen2-VL-2B-Instruct",
    fusion_config={"patch_embeddings": True},
)
```

Secara default, tidak ada fusi yang diterapkan. Jika `fusion_config` disimpan dalam konfigurasi model, `from_pretrained()` akan memakainya secara otomatis.

## Cara kerjanya

Pendaftaran fusi terjadi sebelum model diinstansiasi:

1. [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) menggunakan argumen `fusion_config` yang eksplisit atau kembali ke `config.fusion_config`.
2. Registry fusi memvalidasi nama-nama fusi yang diminta.
3. Setiap fusion yang diaktifkan melakukan meta-inisialisasi pada kelas model target, secara opsional memfilter modul kandidat berdasarkan nama, dan menggunakan `is_fusable(...)` untuk menemukan kelas modul yang kompatibel.
4. Kelas pengganti yang digabungkan didaftarkan melalui [register_patch_mapping()](/docs/transformers/v5.23.0/id/monkey_patching#transformers.monkey_patching.register_patch_mapping).
5. Aturan `~WeightTransform` yang cocok dihasilkan dari config sehingga pemuatan checkpoint dapat memetakan bobot ke tata letak runtime yang telah digabungkan.
6. Secara default, [save_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.save_pretrained) menggunakan jalur konversi terbalik untuk memulihkan tata letak checkpoint asli. Lewati `save_original_format=False` untuk mempertahankan tata letak runtime yang telah dikonversi.

Hal ini memungkinkan sebuah fusion menggunakan struktur modul runtime yang berbeda sambil tetap memuat dari format checkpoint asli, dan secara default menyimpan kembali ke format tersebut.

Catatan: Dengan mekanisme monkey-patching saat ini, pendaftaran fusion berada di level kelas: satu kelas modul yang kompatibel dipetakan ke satu kelas pengganti yang ter-fuse.

## Keluarga fusi saat ini

Saat ini, `fusion_config` mendukung satu keluarga fusi:

- `patch_embeddings` Aktifkan dengan:

  ```python
  fusion_config = {"patch_embeddings": True}
  ```

  Efek: Mengganti proyeksi patch embedding `nn.Conv3d` yang kompatibel dengan proyeksi `nn.Linear` yang diratakan dan ekuivalen pada saat runtime.

## Memperluas pemetaan fusi

Untuk menambahkan keluarga fusi baru:

1. Tambahkan predikat `is_fusable`. Predikat ini menentukan apakah modul yang ditemukan kompatibel dengan fusi.
2. Secara opsional, tambahkan `target_modules_patterns`. Hal ini membuat langkah penemuan menjadi lebih eksplisit dengan memfilter nama modul kandidat terlebih dahulu sebelum `is_fusable(...)`.
3. Tambahkan factory `make_fused_class`. Ini mengembalikan kelas pengganti runtime untuk kelas modul yang kompatibel.
4. Tambahkan pabrik `make_transforms` jika layout yang digabungkan memerlukan konversi checkpoint. Fungsi ini mengembalikan aturan `~WeightTransform` yang memetakan bobot antara layout asli dan layout yang digabungkan untuk konfigurasi tertentu.
5. Daftarkan `ModuleFusionSpec` baru di [`fusion_mapping.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

Setelah terdaftar, fusion baru menjadi tersedia melalui `fusion_config`.

## API Internal[[transformers.fusion_mapping.ModuleFusionSpec]]

#### transformers.fusion_mapping.ModuleFusionSpec[[transformers.fusion_mapping.ModuleFusionSpec]]

```python
transformers.fusion_mapping.ModuleFusionSpec()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L47)

Resep dasar untuk keluarga fusion.

Spesifikasi fusion menentukan modul mana yang memenuhi syarat untuk fusion, cara membangun kelas pengganti runtime, dan transformasi bobot apa yang diperlukan untuk memetakan checkpoint antara tata letak asli dan yang sudah difusi.

#### get_empty_log[[transformers.fusion_mapping.ModuleFusionSpec.get_empty_log]]

```python
get_empty_log(model_name: str)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L57)

Kembalikan pesan log yang dikeluarkan ketika tidak ada modul yang kompatibel ditemukan.

#### is_fusable[[transformers.fusion_mapping.ModuleFusionSpec.is_fusable]]

```python
is_fusable(module: Module)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L61)

Kembalikan apakah `module` kompatibel dengan keluarga fusi ini.

#### make_fused_class[[transformers.fusion_mapping.ModuleFusionSpec.make_fused_class]]

```python
make_fused_class(original_cls: type[torch.nn.Module])
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L65)

Bangun kelas pengganti runtime untuk kelas modul yang kompatibel.

#### make_transforms[[transformers.fusion_mapping.ModuleFusionSpec.make_transforms]]

```python
make_transforms(config: PretrainedConfig)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L69)

Bangun transformasi bobot yang diperlukan untuk memuat dan menyimpan tata letak runtime yang telah digabungkan.

#### transformers.fusion_mapping.PatchEmbeddingsFusionSpec[[transformers.fusion_mapping.PatchEmbeddingsFusionSpec]]

```python
transformers.fusion_mapping.PatchEmbeddingsFusionSpec()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L97)

Fuse patch embeddings Conv3d yang kompatibel menjadi proyeksi Linear yang diratakan.

#### transformers.fusion_mapping._register_module_fusion[[transformers.fusion_mapping._register_module_fusion]]

```python
transformers.fusion_mapping._register_module_fusion(config: PretrainedConfig, fusion_name: str, spec: ModuleFusionSpec)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L193)

Daftarkan satu keluarga fusi untuk `cls`.

Fungsi ini memperbarui dua registri global yang digunakan oleh fused loading:
- registry monkey-patching, sehingga kelas modul yang kompatibel diganti sebelum inisialisasi
- pemetaan konversi checkpoint, sehingga modul runtime yang ter-fusi masih dimuat dari tata letak checkpoint asli

Catatan:
- transform checkpoint yang saling bertentangan gagal dengan cepat

#### transformers.fusion_mapping.register_fusion_patches[[transformers.fusion_mapping.register_fusion_patches]]

```python
transformers.fusion_mapping.register_fusion_patches(config, fusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L269)

Daftarkan fusi runtime yang diminta untuk `cls`.

Fungsi ini:
- memvalidasi `fusion_config` terhadap `_FUSION_REGISTRY`
- menyelesaikan keluarga fusi yang diaktifkan sesuai urutan pengguna
- mendaftarkan monkey patches dan transformasi checkpoint sebelum instansiasi model

