# Tambahkan model dengan modular transformers

Modular transformers mengurangi kode yang diperlukan untuk menambahkan model dengan memungkinkan impor dan pewarisan, berbanding terbalik dengan kebijakan [satu model, satu file](https://huggingface.co/blog/transformers-design-philosophy). Alih-alih mengulang komponen model di berbagai file, tambahkan file *modular* ke folder model Anda dan warisi dari kelas yang sudah ada.

Konverter menghasilkan file mandiri dari file modular. Pengguna mendapatkan antarmuka file tunggal yang sama yang sudah mereka kenal.

> [!NOTE]
> Modular transformers tidak dimaksudkan untuk menggantikan [kode pemodelan lama](./add_new_model). Jika model Anda tidak didasarkan pada model yang sudah ada, tambahkan file `modeling.py` secara manual. Hal yang sama berlaku untuk file konfigurasi, tokenisasi, atau pemrosesan yang tidak dapat mewarisi dengan bersih dari file serupa.
>
> Tidak ada urutan yang benar secara tunggal. Beberapa kontributor menulis file modular terlebih dahulu dan menghasilkan kode darinya. Yang lain memulai dengan `modeling.py` yang ditulis manual dan kemudian merefaktornya menjadi file modular. Kedua pendekatan tersebut berhasil.

## Menerapkan file modular

Mulai dengan mencari model di Transformers yang mirip dengan model Anda. Titik awal yang baik adalah [Mistral](./model_doc/mistral), [Qwen2](./model_doc/qwen2), [Cohere](./model_doc/cohere) dan [Cohere2](./model_doc/cohere2), serta [Llama](./model_doc/llama). Tabel di bawah ini memetakan komponen umum ke model yang dapat Anda warisi.

| Komponen | Model |
|---|---|
| Campuran pakar | Mixtral atau Qwen2-MoE |
| Rotary embedding yang diselang-seling (dan/atau parsial) | GLM, Phi |
| Model ruang keadaan | Jamba, Bamba, Zamba, Mamba2 |
| State tersembunyi berulang | Gemma2 |
| Pola perhatian jendela geser/perhatian penuh per lapisan | Gemma2, Cohere2 |
| Pemotongan QKV | Olmo |
| Normalisasi QK | Olmo2, Cohere |
| QKV Terpadu (tidak disarankan) | Phi3 |

> [!TIP]
> Gunakan alat [modular-detector-v2](https://huggingface.co/spaces/Molbap/modular-detector-v2) untuk menemukan implementasi yang sudah ada agar dapat diwarisi. Tempelkan potongan kode, dan alat ini akan mengembalikan metode yang paling mirip yang sudah ada di Transformers, sehingga Anda dapat mengidentifikasi kelas induk terbaik sebelum mulai menulis.

Jangan memodifikasi model yang sudah ada hanya agar pewarisan dapat berfungsi untuk model baru Anda. Jika mengganti nama atau membuat subkelas dari kelas induk terasa terlalu rumit, salin kode yang relevan secara langsung sebagai gantinya.

Buat `src/transformers/models/<name>/modular_<name>.py`, di mana `<name>` sesuai dengan nama direktori model dalam format snake_case. Bagian ini memandu Anda dalam mengimplementasikan [Olmo2](./model_doc/olmo2) dari [Olmo](./model_doc/olmo) dengan pendekatan modular (lihat file [modular_olmo2.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modular_olmo2.py) asli).

### Konfigurasi

Ada dua poin di mana [Olmo2Config](/docs/transformers/v5.23.0/id/model_doc/olmo2#transformers.Olmo2Config) berbeda dari [OlmoConfig](/docs/transformers/v5.23.0/id/model_doc/olmo#transformers.OlmoConfig).

1. Ada argumen baru, `rms_norm_eps`.
2. Argumen `clip_qkv` tidak lagi digunakan.

Deklarasikan argumen baru sebagai anotasi tipe level kelas dengan nilai default. Untuk argumen yang dihapus, tetapkan `AttributeError()` untuk menekan atribut yang diwarisi di file yang dihasilkan (lihat [Menghapus atribut](#removing-attributes)).

```diff
- @auto_docstring(checkpoint="allenai/OLMo-7B-hf")
+ @auto_docstring(checkpoint="allenai/Olmo2-7B-1124-hf")
+ @strict
- class OlmoConfig(PreTrainedConfig):
+ class Olmo2Config(OlmoConfig):
      ...
-     model_type = "olmo"
+     model_type = "olmo2"
      ...
+     rms_norm_eps: float = 1e-5
-     clip_qkv: float | None = None
+     clip_qkv = AttributeError()
```

`@auto_docstring` menghasilkan dokumentasi argumen standar secara otomatis (lihat panduan [@auto_docstring](./auto_docstring)). `@strict` menolak kwargs yang tidak dikenal saat instansiasi, sehingga menangkap kesalahan ketik dan argumen yang sudah usang lebih awal. Tambahkan keduanya ke setiap kelas config karena dekorator tidak diwarisi dari kelas induk. Deklarasikan secara eksplisit meskipun config induk sudah memilikinya.

Untuk mengatur atribut turunan atau menangani logika kompatibilitas mundur, gunakan `__post_init__` alih-alih `__init__`. Sebagai contoh, Cohere2 menghitung `head_dim` dan menurunkan `layer_types` pada saat inisialisasi.

```py
def __post_init__(self, **kwargs):
    if self.num_key_value_heads is None:
        self.num_key_value_heads = self.num_attention_heads
    self.head_dim = self.hidden_size // self.num_attention_heads
    super().__post_init__(**kwargs)
```

Untuk model yang mendukung paralelisme tensor atau pipeline, definisikan `base_model_tp_plan` dan `base_model_pp_plan` sebagai kamus tingkat kelas pada config. Kedua kamus ini mendefinisikan cara memecah model ke berbagai perangkat. Lihat config yang sudah ada seperti [Olmo2](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modular_olmo2.py) atau [Cohere2](https://github.com/huggingface/transformers/blob/main/src/transformers/models/cohere2/modular_cohere2.py) untuk contoh.

```py
class MyNewModelConfig(PreTrainedConfig):
    model_type = "my_new_model"

    # Tensor parallelism: maps layer name patterns to sharding strategies.
    # Use "colwise" / "rowwise" for standard sharding, or the "gather_output" /
    # "split_input" variants when an extra op (e.g. a QK norm) prevents fusing.
    base_model_tp_plan = {
        "layers.*.self_attn.q_proj": "colwise",
        "layers.*.self_attn.k_proj": "colwise",
        "layers.*.self_attn.v_proj": "colwise",
        "layers.*.self_attn.o_proj": "rowwise",
        "layers.*.mlp.gate_proj": "colwise",
        "layers.*.mlp.up_proj": "colwise",
        "layers.*.mlp.down_proj": "rowwise",
    }

    # Pipeline parallelism: maps submodule names to their (input, output) tensor names.
    base_model_pp_plan = {
        "embed_tokens": (["input_ids"], ["inputs_embeds"]),
        "layers": (["hidden_states", "attention_mask"], ["hidden_states"]),
        "norm": (["hidden_states"], ["hidden_states"]),
    }
```

### Norm

Untuk menyalin kelas induk tanpa perubahan, warisi dengan `pass`. Linter akan menyalin konten induk dan mengganti nama semua referensi agar sesuai dengan model baru.

```py
from ..olmo.modeling_olmo import OlmoRotaryEmbedding

class Olmo2RotaryEmbedding(OlmoRotaryEmbedding):
    pass
```

Untuk mengubah perilaku tertentu, warisi dan timpa hanya bagian yang berbeda. `Olmo2RMSNorm` berbeda dari `LlamaRMSNorm` pada satu baris. Perkalian terjadi *sebelum* pengembalian ke dtype input, bukan setelahnya.

```diff
  from ..llama.modeling_llama import LlamaRMSNorm

  class Olmo2RMSNorm(LlamaRMSNorm):
      def forward(self, hidden_states):
          input_dtype = hidden_states.dtype
          hidden_states = hidden_states.to(torch.float32)
          variance = hidden_states.pow(2).mean(-1, keepdim=True)
          hidden_states = hidden_states * torch.rsqrt(variance + self.variance_epsilon)
-         return self.weight * hidden_states.to(input_dtype)
+         return (self.weight * hidden_states).to(input_dtype)
```

### Perhatian

Atensi Olmo2 identik dengan Olmo kecuali ia menerapkan `RMSNorm` pada query dan key, serta menghapus pemotongan qkv. `super().__init__(...)` menyalin tubuh induk dan menambahkan dua baris norm baru. `forward` didefinisikan ulang sepenuhnya karena query dan key kini melewati norm sebelum proyeksi. Linter juga menarik semua fungsi yang diimpor ke dalam file yang dihasilkan, termasuk `apply_rotary_pos_emb`, `eager_attention_forward`, dan dependensinya.

```diff
  class Olmo2Attention(OlmoAttention):
      def __init__(self, config: Olmo2Config, layer_idx: int | None = None):
          super().__init__(config, layer_idx=layer_idx)
+         self.q_norm = Olmo2RMSNorm(config.num_attention_heads * self.head_dim, config.rms_norm_eps)
+         self.k_norm = Olmo2RMSNorm(config.num_key_value_heads * self.head_dim, config.rms_norm_eps)

      def forward(self, ...):
          ...
-         query_states = self.q_proj(hidden_states)
-         key_states = self.k_proj(hidden_states)
+         query_states = self.q_norm(self.q_proj(hidden_states))
+         key_states = self.k_norm(self.k_proj(hidden_states))
          value_states = self.v_proj(hidden_states)

-         if self.config.clip_qkv is not None:
-             query_states.clamp_(min=-self.config.clip_qkv, max=self.config.clip_qkv)
-             key_states.clamp_(min=-self.config.clip_qkv, max=self.config.clip_qkv)
-             value_states.clamp_(min=-self.config.clip_qkv, max=self.config.clip_qkv)
-
          ...
```

### DecoderLayer

Setelah `super().__init__(...)`, timpa atribut norm dengan instance `Olmo2RMSNorm` dan tetapkan ulang `self.self_attn` ke kelas `Olmo2Attention` yang baru. Perintah `del self.input_layernorm` menghapus penugasan `input_layernorm` dari kelas induk karena Olmo2 menerapkan norm *setelah* attention, bukan sebelumnya. Lihat [Menghapus atribut](#removing-attributes) untuk detail tentang apa yang dilakukan dan tidak dilakukan oleh `del`.

`forward` ditulis ulang untuk mencerminkan penempatan norm pasca-attention. Penulisan ulang `forward` hanya diperlukan ketika sebuah atribut diganti namanya, bukan ketika hanya tipenya yang berubah.

```diff
  class Olmo2DecoderLayer(OlmoDecoderLayer):
      def __init__(self, config: Olmo2Config, layer_idx: int):
          super().__init__(config, layer_idx=layer_idx)
-         self.self_attn = OlmoAttention(config=config, layer_idx=layer_idx)
-         self.input_layernorm = OlmoLayerNorm(config.hidden_size)
-         self.post_attention_layernorm = OlmoLayerNorm(config.hidden_size)
+         self.self_attn = Olmo2Attention(config=config, layer_idx=layer_idx)
+         del self.input_layernorm
+         self.post_attention_layernorm = Olmo2RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+         self.post_feedforward_layernorm = Olmo2RMSNorm(config.hidden_size, eps=config.rms_norm_eps)

      def forward(self, ...):
          residual = hidden_states
-         hidden_states = self.input_layernorm(hidden_states)
          # Self Attention
          hidden_states, _ = self.self_attn(...)
-         hidden_states = residual + hidden_states
+         hidden_states = self.post_attention_layernorm(hidden_states)
+         hidden_states = residual + hidden_states

          # Fully Connected
          residual = hidden_states
-         hidden_states = self.post_attention_layernorm(hidden_states)
          hidden_states = self.mlp(hidden_states)
-         hidden_states = residual + hidden_states
+         hidden_states = self.post_feedforward_layernorm(hidden_states)
+         hidden_states = residual + hidden_states
          return hidden_states
```

### Model

Hanya tipe dari `self.norm` yang berubah di sini. Metode `forward` identik dengan milik induk, sehingga linter akan membawanya secara otomatis.

```diff
  class Olmo2Model(OlmoModel):
      def __init__(self, config: Olmo2Config):
          super().__init__(config)
-         self.layers = nn.ModuleList(
-             [OlmoDecoderLayer(config, layer_idx) for layer_idx in range(config.num_hidden_layers)]
-         )
-         self.norm = OlmoLayerNorm(config.hidden_size)
+         self.norm = Olmo2RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+         self.layers = nn.ModuleList(
+             [Olmo2DecoderLayer(config, layer_idx) for layer_idx in range(config.num_hidden_layers)]
+         )
```

### Kepala model

Logikanya identik dengan [OlmoForCausalLM](/docs/transformers/v5.23.0/id/model_doc/olmo#transformers.OlmoForCausalLM), sehingga tidak diperlukan perubahan.

```py
from ..olmo.modeling_olmo import OlmoForCausalLM

class Olmo2ForCausalLM(OlmoForCausalLM):
    pass
```

### Kelas lainnya

[modeling_olmo2.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modeling_olmo2.py) yang dihasilkan oleh linter juga berisi kelas (`Olmo2MLP`, `Olmo2RotaryEmbedding`, `Olmo2PreTrainedModel`) yang tidak didefinisikan secara eksplisit di `modular_olmo2.py`.

Linter menarik kelas mana pun yang bergantung pada kelas yang diwarisi, kecuali Anda mendefinisikannya ulang secara eksplisit. Fungsi yang diimpor seperti `apply_rotary_pos_emb` mengikuti aturan yang sama.

Sebagai contoh, `OlmoDecoderLayer` memiliki `self.mlp = OlmoMLP(config)`. `Olmo2MLP` tidak pernah didefinisikan dalam file modular, sehingga linter membuatnya secara otomatis, setara dengan menggunakan `pass`.

```py
from ..olmo.modeling_olmo import OlmoMLP

class Olmo2MLP(OlmoMLP):
    pass
```

Jika Anda ingin `Olmo2MLP` mewarisi dari model lain, nyatakan secara eksplisit.

```py
# switch to Mistral definition
from ..mistral.modeling_mistral import MistralMLP

class Olmo2MLP(MistralMLP):
    pass
```

### Menyelesaikan file

Setiap file modular harus mendeklarasikan `logger` dan daftar `__all__` pada level modul.

```py
logger = logging.get_logger(__name__)

__all__ = [
    "Olmo2Config",
    "Olmo2ForCausalLM",
    "Olmo2Model",
    "Olmo2PreTrainedModel",
]
```

`__all__` harus mencantumkan setiap kelas publik dalam file tersebut. Konverter dan impor hilir bergantung padanya. Kelas yang tidak ada di `__all__` tidak akan diekspor dengan benar.

## Generate file pemodelan

Skrip `modular_model_converter.py` menghasilkan file `modeling.py`, `configuration.py`, dan file lainnya secara mandiri dari file modular Anda. Untuk setiap class yang diwarisi, skrip ini menyalin isi parent ke child, mengubah nama semua referensi agar sesuai dengan model baru, serta menarik fungsi atau class helper yang dibutuhkan oleh parent tersebut.

File output tidak mengandung impor lintas-model dan tidak ada pewarisan dari direktori model lain. Linter meratakan pewarisan ke satu tingkat. Jika `Olmo2Attention` mewarisi dari `OlmoAttention`, maka `Olmo2Attention` yang dihasilkan sepenuhnya mandiri. Namun, jika `OlmoAttention` sendiri mewarisi dari sesuatu yang lain, linter tidak akan meng-inline kakek dari kelas tersebut.

Jalankan perintah di bawah untuk menghasilkan file dari file modular.

```bash
python utils/modular_model_converter.py your_model
```

Jangan pernah mengedit file yang dihasilkan secara langsung karena semua perubahan akan ditimpa pada eksekusi berikutnya.

## Pola untuk file modular

Bagian-bagian di bawah ini mendokumentasikan pola penggunaan umum, seperti menghapus atribut atau menimpa metode yang didekorasi, saat bekerja dengan file modular.

### Menghapus atribut

Menghapus atribut yang diwariskan bergantung pada apakah Anda bekerja dengan kelas config atau subclass `nn.Module`.

Untuk kelas konfigurasi, tetapkan `AttributeError()` ke atribut pada level kelas.

```py
class MyNewConfig(ParentConfig):
    removed_attr = AttributeError()
```

Linter menghapus deklarasi atribut secara keseluruhan dari file config yang dihasilkan. Kelas config menggunakan tata letak bergaya dataclass tanpa `__init__`, sehingga penugasan `AttributeError()` pada level kelas adalah pendekatan yang benar.

Untuk subclass `nn.Module`, gunakan `del self.attribute` setelah `super().__init__(...)`.

```py
class MyNewModel(ParentModel):
    def __init__(self, config: MyNewConfig):
        super().__init__(config)
        del self.attribute
```

`del self.attribute` hanya menghapus baris penugasan `self.attribute = ...` dari tubuh induk yang disalin. Hal ini tidak menghapus baris lain yang merujuk ke `self.attribute`. Jika metode `forward` atau metode lain pada induk juga merujuk ke atribut tersebut, override metode-metode itu juga.

```py
class DummyModel(nn.Module):
    def __init__(self, config: DummyConfig):
        super().__init__()
        self.attribute = config.attribute
        if self.attribute:
            # do more stuff with `self.attribute` here
            ...

class MyNewDummyModel(DummyModel):
    def __init__(self, config: MyNewDummyConfig):
        super().__init__(config)
        del self.attribute
        # 'self.attribute = config.attribute' is removed, but the 'if self.attribute:' block remains.
        # Override forward() or any other method that references self.attribute.
```

### Bekerja dengan `super()`

`super().__init__(config)` memberi tahu konverter untuk menyalin isi kelas induk ke kelas turunan. Ada dua pola yang memungkinkan Anda menimpa perilaku ini.

- Panggil kelas induk tertentu secara langsung ketika Anda membutuhkan output yang dihasilkan untuk memanggil kelas kakek (`nn.Module.__init__`) alih-alih kelas induk modular.
- Gunakan `**super_kwargs` untuk mewarisi tanda tangan penuh metode induk sambil menambahkan docstring kustom atau mengganti dekorator.

#### Panggil kelas kakek-nenek secara langsung

Jelaskan secara eksplisit kelas mana yang Anda panggil ketika Anda membutuhkan `super()` untuk menargetkan kelas induk yang dihasilkan, bukan kelas induk modular. Contoh di bawah ini memanggil `nn.Module.__init__(self)` secara langsung. `DummyModule` itu sendiri adalah `nn.Module`, sehingga konverter menuliskannya sebagai `super().__init__()` di `MyNewDummyModule` yang dihasilkan.

```py
class MyNewDummyModule(DummyModule):                   |     class MyNewDummyModule(nn.Module):
                                                       |
  def __init__(self):                                  |       def __init__(self):
    nn.Module.__init__(self)                           |         super().__init__()
    self.foo = config.foo                              |         self.foo = config.foo
    ...                                                |         ...
```

#### super_kwargs

Gunakan `**super_kwargs` untuk mewarisi tanda tangan penuh metode induk sambil menambahkan docstring kustom atau mengganti dekorator. Dalam tanda tangan yang ditimpa, hal ini memberi tahu linter untuk memperluas semua argumen induk dalam output yang dihasilkan.

Penggunaan yang paling umum adalah menambahkan docstring yang spesifik untuk model, seperti mendokumentasikan argumen `labels`, tanpa menulis ulang seluruh signature.

```py
# modular_gemma.py
class GemmaForCausalLM(LlamaForCausalLM):
    def forward(**super_kwargs):
        r"""
        Example:

        ```python
        >>> from transformers import AutoTokenizer, GemmaForCausalLM
        >>> model = GemmaForCausalLM.from_pretrained("google/gemma-7b")
        ...
        ```"""
        return super().forward(**super_kwargs)
```

`GemmaForCausalLM.forward` yang dihasilkan memiliki tanda tangan `LlamaForCausalLM` lengkap tanpa perlu menyalin secara manual.

`**super_kwargs` adalah jalan pintas untuk kasus-kasus khusus. Jika Anda mengubah perilaku, tulislah tanda tangan lengkapnya sebagai gantinya.

### Menghapus metode yang tidak digunakan

Hapus metode induk dengan menimpanya menggunakan pernyataan `raise AttributeError("")`. Linter akan menghapus metode tersebut dari file yang dihasilkan.

```py
class GemmaTokenizer(LlamaTokenizer):
    ...

    def get_spm_processor(self):
        raise AttributeError("Not needed for Gemma")

    def unk_token_length(self):
        raise AttributeError("Not needed for Gemma")
```

### Menimpa metode yang dihias

Saat Anda menimpa metode induk yang sudah didekorasi, dekorator dari induk tersebut akan terbawa secara otomatis. Jika Anda menambahkan dekorator Anda sendiri, dekorator tersebut akan menggantikan dekorator induk.

Dua dekorator muncul di seluruh pustaka, satu untuk [mengambil output antara model](./model_output_tracing) dan satu lagi untuk [menghasilkan docstring secara otomatis](./auto_docstring).

Pada contoh di bawah, sebuah subclass menimpa metode parent yang sudah didekorasi tanpa menambahkan dekoratornya sendiri. Dekorator dari parent tersebut tetap berlaku.

```py
class NewModel(DummyModel):       |   class NewModel(nn.Module):
  ...                             |     ...
                                  |
  def forward(...):               |     @decorator(...)
    ...                           |     def forward(...):
                                  |       ...
```

Jika Anda menambahkan dekorator baru, dekorator Anda akan menggantikan dekorator induknya.

```py
class NewModel(DummyModel):       |   class NewModel(nn.Module):
  ...                             |     ...
                                  |
  @my_new_decorator(...)          |     @my_new_decorator(...)
  def forward(...):               |     def forward(...):
    ...                           |       ...
```

### Penamaan khusus

Linter secara otomatis mengganti nama semua elemen saat mewarisi dari sebuah kelas. Gunakan prefiks nama kelas yang sama di semua kelas dalam file yang sama.

Hindari mencampuradukkan awalan seperti pada contoh di bawah. `MyModelIncredibleMLP` melanggar konvensi penamaan, dan linter tidak akan tahu apakah harus menggunakan `MyModelIncredible` atau `MyModel` saat mengganti nama dependensi tingkat lebih tinggi.

```py
class MyModelIncredibleMLP(LlamaMLP):
    ...

class MyModelDecoderLayer(LlamaDecoderLayer):
    ...
```

Tanpa [dependensi implisit](#other-classes), Anda dapat mengganti nama satu kelas secara lokal. Definisikan ulang secara eksplisit setiap penyebutan lain dari kelas tersebut dengan pola nama baru. Jika tidak, linter akan menambahkan kelas `MyModelMLP` yang tidak diinginkan di samping `MyModelIncredibleMLP`.

Linter mengeluarkan peringatan ketika mendeteksi awalan yang ambigu.

```text
We detected multiple prefix names when inheriting from transformers.models.llama.modeling_llama: ('Emu3Text', 'Emu3'). We will only use the most used 'Emu3' prefix when grabbing args and dependencies. Make sure to subclass the intermediate classes with the prefix you want (if different from 'Emu3') or use a single prefix in all the modular (best).
```

Prefiks ambigu paling umum terjadi pada model multimodal di mana nama kelas mencakup kualifikasi modalitas seperti `Text`. Untuk memberikan prefiks tertentu pada sebuah dependensi, ubah namanya secara eksplisit dengan `pass`.

```py
class Emu3TextMLP(LlamaMLP):
    pass
```

### Docstring konfigurasi

Linter belum mendukung pewarisan docstring parsial. Saat menambahkan atau menghapus atribut konfigurasi, tambahkan docstring lengkap secara langsung di file modular di bawah definisi kelas.

## Konversi checkpoint

Setelah Anda menghasilkan file pemodelan, pastikan bobot asli dimuat dengan benar. Tulis skrip konversi untuk menerjemahkan format checkpoint hulu menjadi format yang kompatibel dengan Transformers, lalu simpan ke Hub.

### Tulis skrip konversi

Tambahkan file `convert_<model>_to_hf.py` ke `src/transformers/models/<model>/`. Skrip ini memuat bobot upstream, mengubah nama dan bentuk kunci agar sesuai dengan nama parameter modul Anda, lalu menyimpan hasilnya dengan [save_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.save_pretrained).

> [!TIP]
> Cari skrip yang sudah ada untuk disalin dan diadaptasi. Model di bawah `src/transformers/models/` menyertakan `convert_*_to_hf.py` yang dapat Anda gunakan sebagai titik awal.

Setelah menjalankan skrip, muat checkpoint yang disimpan dengan [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) dan pastikan setiap bobot yang diharapkan dimuat dengan benar. Kunci checkpoint yang tidak digunakan menunjukkan nama yang tidak cocok, jadi cetak kunci tersebut untuk mendeteksi masalah sejak dini.

```py
model = YourModelForTask.from_pretrained("path/to/output/")
```

Periksa kecocokan bentuk dan nama saat mengiterasi kunci. Ketidakcocokan bentuk biasanya berarti ada parameter di konfigurasi Anda yang salah, arsitektur berbeda dari aslinya, atau bobot perlu ditransposisikan.

```py
for key, tensor in original_state_dict.items():
    hf_tensor = hf_model.state_dict().get(mapped_key)
    assert hf_tensor.shape == tensor.shape, (
        f"Shape mismatch for {key}: expected {tensor.shape}, got {hf_tensor.shape}"
    )
```

Perbaiki semua masalah dengan mengulang proses antara file modular Anda, file modeling yang dihasilkan, dan skrip konversi hingga semua bobot dimuat dengan bersih.

Setelah checkpoint dimuat dengan baik, unggah ke Hub menggunakan [push_to_hub()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub). Lihat panduan [model sharing](./model_sharing) untuk detail lebih lanjut.

```py
model.push_to_hub("username/your-model-name")
```

### Pemetaan konversi runtime

Tambahkan pemetaan runtime ke `src/transformers/conversion_mapping.py` ketika bobot yang dipublikasikan tidak sesuai dengan tata letak parameter modul Anda. Kasus umum meliputi bobot terpadu yang disimpan secara terpisah dan tensor pakar MoE yang perlu ditumpuk. Pemetaan ini memungkinkan [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) memuat checkpoint Hub tanpa langkah ekspor terpisah.

Lihat panduan [dynamic weight loading](./weightconverter) untuk cara menulis aturan `WeightRenaming` dan [WeightConverter](/docs/transformers/v5.23.0/id/internal/modeling_utils#transformers.WeightConverter) serta mendaftarkannya untuk `model_type` Anda.

## Langkah selanjutnya

- [Aturan struktur model](./modeling_rules) adalah aturan statis yang diterapkan pada semua file `modeling_*.py`, `modular_*.py`, dan `configuration_*.py`. Jalankan `make typing` untuk memeriksanya sebelum membuka PR.
- [Menambahkan komponen pemrosesan visual](./add_vision_processing_components) membahas cara menambahkan image processor, video processor, dan processor untuk model multimodal.
- [Menghasilkan docstring secara otomatis](./auto_docstring) menunjukkan cara menggunakan `@auto_docstring` sehingga Anda tidak perlu menulis dokumentasi argumen secara manual untuk API model bersama.
- [Menulis pengujian model](./testing) membahas cara menulis pengujian integrasi untuk model baru Anda dan menjalankannya secara lokal.
- [Periksa pull request](./pr_checks) menjelaskan pemeriksaan CI yang harus dilewati PR Anda sebelum dapat digabungkan, serta cara mereproduksi dan memperbaikinya secara lokal.

