# Modüler dönüştürücülerle bir model ekleyin

Modular transformers, [tek model, tek dosya](https://huggingface.co/blog/transformers-design-philosophy) politikasının aksine, içe aktarma ve kalıtım imkânı sağlayarak bir model eklemek için gereken kodu azaltır. Model bileşenlerini dosyalar arasında tekrarlamak yerine, model klasörünüze bir *modüler* dosya ekleyin ve mevcut sınıflardan kalıtım alın.

Dönüştürücü, modüler dosyadan bağımsız dosyalar üretir. Kullanıcılar, zaten bildikleri tek dosyalı arayüzün aynısını alır.

> [!NOTE]
> Modüler transformers, [eski modelleme kodunu](./add_new_model) değiştirmek için tasarlanmamıştır. Modeliniz mevcut bir modele dayanmıyorsa, `modeling.py` dosyasını manuel olarak ekleyin. Benzer bir dosyadan temiz bir şekilde devralınamayan yapılandırma, belirteçleştirme veya işleme dosyaları için de aynı kural geçerlidir.
>
> Tek bir doğru sıra da yoktur. Bazı katkıda bulunanlar önce modüler dosyayı yazar ve ondan üretir. Diğerleri elle yazılmış bir `modeling.py` ile başlar ve onu daha sonra bir modüler dosyaya dönüştürür. Her iki yaklaşım da işe yarar.

## Modüler bir dosya uygulama

Önce Transformers'ta sizin modelinize benzer bir model bulun. İyi başlangıç noktaları [Mistral](./model_doc/mistral), [Qwen2](./model_doc/qwen2), [Cohere](./model_doc/cohere) ve [Cohere2](./model_doc/cohere2) ile [Llama](./model_doc/llama)'dır. Aşağıdaki tablo, ortak bileşenleri devralabileceğiniz modellere eşler.

| Bileşen | Model |
|---|---|
| Uzmanlar karışımı | Mixtral veya Qwen2-MoE |
| Aralı (ve/veya kısmi) döner gömme | GLM, Phi |
| Durum uzayı modelleri | Jamba, Bamba, Zamba, Mamba2 |
| Yinelenen gizli durumlar | Gemma2 |
| Katman başına kayan pencere dikkati/tam dikkat deseni | Gemma2, Cohere2 |
| QKV kırpma | Olmo |
| QK normalizasyonu | Olmo2, Cohere |
| Birleştirilmiş QKV (önerilmez) | Phi3 |

> [!TIP]
> Mevcut ve devralınabilecek uygulamaları bulmak için [modular-detector-v2](https://huggingface.co/spaces/Molbap/modular-detector-v2) aracını kullanın. Bir kod parçasını yapıştırın; araç, Transformers içindeki en benzer yöntemleri döndürür, böylece kod yazmaya başlamadan önce en uygun üst sınıfı belirleyebilirsiniz.

Mevcut bir modeli yalnızca yeni modeliniz için kalıtımın çalışmasını sağlamak amacıyla değiştirmeyin. Bir üst sınıfı yeniden adlandırmak veya alt sınıf oluşturmak çok zahmetliyse, ilgili kodu doğrudan kopyalayın.

`src/transformers/models/<name>/modular_<name>.py` dosyasını oluşturun; burada `<name>`, snake_case model dizin adıyla eşleşir. Bu bölümde, [Olmo](./model_doc/olmo) modelinden [Olmo2](./model_doc/olmo2) modelini modüler yaklaşımla nasıl uygulayacağınızı adım adım ele alıyoruz (orijinal [modular_olmo2.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modular_olmo2.py) dosyasına bakın).

### Yapılandırma

[Olmo2Config](/docs/transformers/v5.23.0/tr/model_doc/olmo2#transformers.Olmo2Config), [OlmoConfig](/docs/transformers/v5.23.0/tr/model_doc/olmo#transformers.OlmoConfig)'den iki noktada farklılık gösterir.

1. Yeni bir argüman var: `rms_norm_eps`.
2. `clip_qkv` argümanı artık kullanılmıyor.

Yeni argümanları, varsayılan bir değere sahip sınıf düzeyi tip açıklamaları olarak tanımlayın. Kaldırılan argümanlar için, üretilen dosyada devralınan özniteliği bastırmak üzere `AttributeError()` atayın (bkz. [Öznitelikleri kaldırma](#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` standart argüman belgelerini otomatik olarak oluşturur ([@auto_docstring](./auto_docstring) kılavuzuna bakın). `@strict`, anında oluşturulma sırasında bilinmeyen kwargs'ları reddeder ve yazım hatalarını ile eski argümanları erken yakalar. Decorator'lar üst sınıftan devralınmadığı için her config sınıfına her ikisini de ekleyin. Üst config zaten bunlara sahip olsa bile bunları açıkça bildirin.

Türetilmiş bir özniteliği ayarlamak veya geriye dönük uyumluluk mantığını işlemek için `__init__` yerine `__post_init__` kullanın. Örneğin, Cohere2, başlatma sırasında `head_dim` değerini hesaplar ve `layer_types` değerini türetir.

```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)
```

Tensor veya pipeline paralellik desteği olan modeller için, `base_model_tp_plan` ve `base_model_pp_plan` öğelerini config üzerinde sınıf düzeyinde sözlükler olarak tanımlayın. Her iki sözlük de modelin cihazlar arasında nasıl paylaştırılacağını (shard) belirler. Örnekler için [Olmo2](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modular_olmo2.py) veya [Cohere2](https://github.com/huggingface/transformers/blob/main/src/transformers/models/cohere2/modular_cohere2.py) gibi mevcut config'lere bakın.

```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

Değişiklik yapmadan bir üst sınıfı kopyalamak için `pass` ile kalıtım alın. Linter, üst sınıfın içeriğini kopyalar ve yeni modele uyması için tüm referansları yeniden adlandırır.

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

class Olmo2RotaryEmbedding(OlmoRotaryEmbedding):
    pass
```

Belirli bir davranışı değiştirmek için yalnızca farklı olan kısımları devralıp geçersiz kılın. `Olmo2RMSNorm`, `LlamaRMSNorm`'den tek bir satırda farklılık gösterir. Çarpma işlemi, girdi veri türüne geri dönüştürülmeden *önce* yapılır, sonra değil.

```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)
```

### Dikkat

Olmo2'nin dikkati, Olmo'nunkinden `RMSNorm`'un sorgulara ve anahtarlara uygulanması ve qkv kırpmanın kaldırılması dışında aynıdır. `super().__init__(...)` ana gövdeyi kopyalar ve iki yeni norm satırını ekler. `forward`, sorguların ve anahtarların projeksiyondan önce normlardan geçmesi nedeniyle tamamen yeniden tanımlanmıştır. Linter, `apply_rotary_pos_emb`, `eager_attention_forward` ve bağımlılıkları dahil olmak üzere, içe aktarılan tüm işlevleri de üretilen dosyaya çeker.

```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

`super().__init__(...)` çağrısından sonra, norm özniteliklerini `Olmo2RMSNorm` örnekleriyle yeniden yazın ve `self.self_attn` özniteliğini yeni `Olmo2Attention` sınıfına atayın. `del self.input_layernorm` ifadesi, Olmo2'nin normu dikkatin (attention) *sonrasına* uygulaması nedeniyle üst sınıfın `input_layernorm` atamasını kaldırır. `del` ifadesinin neyi sildiği ve neyi silmediğine ilişkin ayrıntılar için [Öznitelikleri kaldırma](#removing-attributes) bölümüne bakın.

`forward`, dikkat sonrası norm yerleşimini yansıtacak şekilde yeniden yazılır. Bir `forward` yeniden yazımı yalnızca bir öznitelik yeniden adlandırıldığında gerekir, yalnızca türü değiştiğinde değil.

```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

Burada yalnızca `self.norm`'ün tipi değişir. `forward` metodu ebeveynininkiyle aynıdır, bu nedenle linter onu otomatik olarak devralır.

```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)]
+         )
```

### Model başlığı

Mantık, [OlmoForCausalLM](/docs/transformers/v5.23.0/tr/model_doc/olmo#transformers.OlmoForCausalLM) ile aynıdır, bu nedenle değişiklik yapılmasına gerek yoktur.

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

class Olmo2ForCausalLM(OlmoForCausalLM):
    pass
```

### Diğer sınıflar

Linter tarafından oluşturulan [modeling_olmo2.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modeling_olmo2.py), `modular_olmo2.py` içinde açıkça tanımlanmamış sınıfları da (`Olmo2MLP`, `Olmo2RotaryEmbedding`, `Olmo2PreTrainedModel`) içerir.

Linter, bir sınıfın bağımlı olduğu herhangi bir sınıfı, onu açıkça yeniden tanımlamadığınız sürece dahil eder. `apply_rotary_pos_emb` gibi içe aktarılan işlevler de aynı kurala tabidir.

Örneğin, `OlmoDecoderLayer` içinde `self.mlp = OlmoMLP(config)` bulunur. `Olmo2MLP` modüler dosyada hiç tanımlanmadığı için linter bunu otomatik olarak oluşturur; bu, `pass` kullanmakla eşdeğerdir.

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

class Olmo2MLP(OlmoMLP):
    pass
```

`Olmo2MLP`'nin farklı bir modelden devralmasını istiyorsanız, bunu açıkça belirtin.

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

class Olmo2MLP(MistralMLP):
    pass
```

### Dosyayı tamamlama

Her modüler dosya, modül düzeyinde bir `logger` ve bir `__all__` listesi bildirmelidir.

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

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

`__all__`, dosyadaki her halka açık sınıfı listelemelidir. Dönüştürücü ve aşağı akış içe aktarmaları buna bağlıdır. `__all__` içinde yer almayan bir sınıf doğru şekilde dışa aktarılmaz.

## Modelleme dosyalarını oluşturun

`modular_model_converter.py` betiği, modüler dosyanızdan bağımsız `modeling.py`, `configuration.py` ve diğer dosyaları oluşturur. Miras alınan her sınıf için, üst sınıfın gövdesini alt sınıfa kopyalar, yeni modele uygun olacak şekilde tüm referansları yeniden adlandırır ve bu üst sınıfların bağımlı olduğu yardımcı işlevleri veya sınıfları dahil eder.

Çıktı dosyaları, modeller arası içe aktarma ve diğer model dizinlerinden miras alma içermez. Linter, miras almayı tek seviyeye indirger. `Olmo2Attention`, `OlmoAttention`'den miras alıyorsa, oluşturulan `Olmo2Attention` tamamen kendi içinde kapalıdır. Ancak `OlmoAttention` kendisi başka bir şeyden miras alıyorsa, linter o büyükanneyi (grandparent) satır içine (inline) yerleştirmez.

Modüler bir dosyadan dosyaları oluşturmak için aşağıdaki komutu çalıştırın.

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

Oluşturulan dosyaları doğrudan düzenlemeyin; bir sonraki çalıştırmada yapılan tüm değişiklikler üzerine yazılır.

## Modüler dosyalar için kalıplar

Aşağıdaki bölümler, modüler bir dosya ile çalışırken öznitelikleri kaldırma veya süslenmiş (decorated) metotları geçersiz kılma gibi yaygın kullanım kalıplarını belgelemektedir.

### Öznitelikleri kaldırma

Miras alınan bir özniteliğin kaldırılması, bir yapılandırma sınıfı mı yoksa `nn.Module` alt sınıfı mı üzerinde çalıştığınıza bağlıdır.

Bir yapılandırma sınıfı için, sınıf düzeyinde özniteliğe `AttributeError()` atayın.

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

Linter, üretilen yapılandırma dosyasından öznitelik bildirimini tamamen kaldırır. Yapılandırma sınıfları `__init__` içermeyen bir dataclass tarzı düzen kullandığından, sınıf düzeyinde `AttributeError()` atamak doğru yaklaşımdır.

`nn.Module` alt sınıfı için, `super().__init__(...)` sonrasında `del self.attribute` kullanın.

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

`del self.attribute`, kopyalanan üst sınıf gövdesinden yalnızca `self.attribute = ...` atama satırını kaldırır. `self.attribute`'ye atıfta bulunan diğer satırları kaldırmaz. Üst sınıfın `forward` veya diğer yöntemleri de bu özeğe atıfta bulunuyorsa, bu yöntemleri de geçersiz kılın.

```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.
```

### `super()` ile çalışma

`super().__init__(config)`, dönüştürücüye ebeveyn gövdesinin çocuğa kopyalanması gerektiğini söyler. Bu davranışı geçersiz kılmak için iki desen kullanabilirsiniz.

- Üretilen çıktının modüler üst sınıf yerine büyük üst sınıfı (`nn.Module.__init__`) çağırmaya ihtiyacı olduğunda, belirli bir üst sınıfı doğrudan çağırın.
- Bir üst sınıf metodunun tam imzasını devralırken özel bir dokümantasyon dizgesi eklemek veya bir dekoratörü değiştirmek için `**super_kwargs` kullanın.

#### Büyük bir üst sınıfı doğrudan çağırın

`super()` çağrısı gerektiğinde, hedefin modüler üst sınıf değil de üretilen sınıfın üst sınıfı olduğunu açıkça belirtin. Aşağıdaki örnek `nn.Module.__init__(self)` fonksiyonunu doğrudan çağırır. `DummyModule` zaten bir `nn.Module` olduğundan, dönüştürücü bunu üretilen `MyNewDummyModule` içinde `super().__init__()` olarak yazar.

```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

`**super_kwargs`, bir üst sınıf metodunun tam imzasını devralırken özel bir dokümantasyon dizgesi eklemek veya bir dekoratörü değiştirmek için kullanılır. Eşlenmiş imzada, linter'a üretilen çıktıdaki tüm üst sınıf argümanlarını genişletmesini söyler.

En yaygın kullanım, tam imzayı yeniden yazmadan, `labels` argümanını belgelemek gibi modele özgü bir docstring eklemektir.

```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)
```

Oluşturulan `GemmaForCausalLM.forward`, manuel kopyalama gerektirmeden tam `LlamaForCausalLM` imzasına sahiptir.

`**super_kwargs`, niş durumlar için bir kısayoldur. Davranışı değiştiriyorsanız bunun yerine tam imzayı yazın.

### Kullanılmayan yöntemleri silme

`raise AttributeError("")` ifadesiyle üst yazarak bir üst sınıf metodunu kaldırın. Linter, bu metodu üretilen dosyadan kaldırır.

```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")
```

### Süslenmiş yöntemlerin geçersiz kılınması

Dekorlanmış bir üst sınıf metodunu geçersiz kıldığınızda, üst sınıfın dekoratörü otomatik olarak devralınır. Kendi dekoratörünüzü eklerseniz, üst sınıfın dekoratörünün yerini alır.

Kütüphanenin genelinde iki dekoratör yer alır: biri [modelin ara çıktılarını yakalamak](./model_output_tracing), diğeri [docstring'leri otomatik olarak oluşturmak](./auto_docstring) içindir.

Aşağıdaki örnekte, bir alt sınıf, kendi dekoratörünü eklemeyerek dekore edilmiş bir üst sınıf metodunu geçersiz kılar. Üst sınıfın dekoratörü devralınır.

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

Yeni bir dekoratör eklerseniz, dekoratörünüz üst sınıfınkini değiştirir.

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

### Özel adlandırma

Linter, bir sınıftan devralırken her şeyi otomatik olarak yeniden adlandırır. Aynı dosyadaki tüm sınıflarda aynı sınıf adı önekini kullanın.

Aşağıdaki örnekteki gibi önekleri karıştırmaktan kaçının. `MyModelIncredibleMLP` adlandırma kurallarını ihlal eder ve linter, üst düzey bağımlılıkları yeniden adlandırırken `MyModelIncredible` mi yoksa `MyModel` mi kullanılacağını bilemez.

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

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

[örtük bağımlılıklar](#other-classes) olmadığından, tek bir sınıfı yerel olarak yeniden adlandırabilirsiniz. Bu sınıfın diğer tüm geçişlerini yeni ad kalıbıyla açıkça yeniden tanımlayın. Aksi takdirde, linter `MyModelIncredibleMLP` yanında istenmeyen bir `MyModelMLP` sınıfı ekler.

Linter, belirsiz bir önek algıladığında bir uyarı oluşturur.

```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).
```

Belirsiz önekler, sınıf adlarında `Text` gibi bir modallık belirleyici içeren çok modallı modellerde en sık görülür. Bir bağımlılığa belirli bir önek vermek için, onu `pass` ile açıkça yeniden adlandırın.

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

### Yapılandırma docstring'leri

Linter henüz kısmi docstring mirasını desteklemiyor. Yapılandırma öznitelikleri eklerken veya kaldırırken, tam docstring'i doğrudan modüler dosyada sınıf tanımının altına ekleyin.

## Checkpoint dönüştürme

Modelleme dosyalarınızı oluşturduktan sonra, gerçek ağırlıkların doğru yüklendiğini doğrulayın. Yukarı akış kontrol noktası biçimini Transformers ile uyumlu bir biçime dönüştüren bir dönüştürme betiği yazın ve ardından Hub'a kaydedin.

### Dönüştürme betiği yazın

`src/transformers/models/<model>/` dizinine bir `convert_<model>_to_hf.py` dosyası ekleyin. Betik, üst akış ağırlıklarını yükler, modülünüzün parametre adlarıyla eşleşmesi için anahtarları yeniden adlandırır ve yeniden şekillendirir, ardından sonucu [save_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel.save_pretrained) ile kaydeder.

> [!TIP]
> Kopyalanıp uyarlanacak mevcut bir betik arayın. `src/transformers/models/` altındaki modeller, başlangıç noktası olarak kullanabileceğiniz bir `convert_*_to_hf.py` içerir.

Betik çalıştırıldıktan sonra, kaydedilen checkpoint'i [from_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel.from_pretrained) ile yükleyin ve beklenen her ağırlığın doğru şekilde yüklendiğini doğrulayın. Kullanılmayan checkpoint anahtarları, eşleşmeyen adları gösterir; bu nedenle sorunları erken yakalamak için bunları yazdırın.

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

Anahtarlar üzerinde iterasyon yaparken şekil ve ad eşleşmelerini kontrol edin. Şekil uyuşmazlıkları genellikle yapılandırmanızdaki bir parametrenin yanlış olduğunu, mimarinin orijinalinden farklı olduğunu veya bir ağırlığın transpoze edilmesi gerektiğini gösterir.

```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}"
    )
```

Tüm ağırlıkların sorunsuz bir şekilde yüklenene kadar modüler dosyanız, oluşturulan modelleme dosyası ve dönüştürme betiği arasında tekrarlayarak tüm sorunları giderin.

Kontrol noktası sorunsuz bir şekilde yüklendikten sonra, [push_to_hub()](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) kullanarak Hub'a gönderin. Daha fazla ayrıntı için [model paylaşımı](./model_sharing) kılavuzuna başvurun.

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

### Çalışma zamanı dönüştürme eşlemesi

Yayınlanan ağırlıklar modülünüzün parametre yerleşimiyle eşleşmiyorsa `src/transformers/conversion_mapping.py` dosyasına çalışma zamanı eşlemesi ekleyin. Yaygın durumlar arasında ayrı olarak saklanan füzyonlu ağırlıklar ve yığılması gereken MoE uzman tensörleri bulunur. Bu eşleme, [from_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel.from_pretrained) işlevinin Hub kontrol noktasını ayrı bir dışa aktarma adımı olmadan yüklemesini sağlar.

`WeightRenaming` ve [WeightConverter](/docs/transformers/v5.23.0/tr/internal/modeling_utils#transformers.WeightConverter) kurallarını nasıl yazacağınız ve bunları `model_type` için nasıl kaydedeceğiniz hakkında [dinamik ağırlık yükleme](./weightconverter) kılavuzuna başvurun.

## Sonraki adımlar

- [Model yapı kuralları](./modeling_rules), tüm `modeling_*.py`, `modular_*.py` ve `configuration_*.py` dosyalarında uygulanan statik kurallardır. Bir PR açmadan önce bunları kontrol etmek için `make typing` komutunu çalıştırın.
- [Görüntü işleme bileşenleri ekleme](./add_vision_processing_components), çok modlu bir model için görüntü işleyici, video işleyici ve işleyici eklemeyi adım adım anlatır.
- [Docstring'lerin otomatik oluşturulması](./auto_docstring), paylaşılan model API'leri için argüman belgelerini elle yazmak zorunda kalmamanız için `@auto_docstring`'in nasıl kullanılacağını gösterir.
- [Model testleri yazma](./testing), yeni modeliniz için entegrasyon testleri yazmayı ve bunları yerel olarak çalıştırmayı açıklar.
- [Pull request kontrolleri](./pr_checks), birleştirmeden önce PR'ınızın geçmesi gereken CI kontrollerini ve bunların yerel olarak nasıl yeniden oluşturulup düzeltileceğini açıklar.

