# Katman başına yapılandırmalar

Bazı checkpoint'ler heterojendir (katmanlar arasında homojen değildir). Bir katmanda daha küçük bir MLP, başka bir katmanda daha az key-value head veya seçili katmanlarda farklı bir yerleşim, tek bir global config'in yığını doğru bir şekilde tanımlamadığı anlamına gelir.

Bir yapılandırma oluştururken veya incelerken ve model kodu bu farkları kullanacaksa, bu farkları kaydetmek için [PreTrainedConfig](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig) üzerinde `per_layer_config` kullanın. Her giriş, yalnızca küresel yapılandırmadan farklı olanları saklar; geri kalanı devralınır.

> [!NOTE]
> Heterojen yapılandırmalar güçlü bir özelliktir. Heterojen bir yerleşim yaygın veya öne çıkan bir mimari haline gelirse, `per_layer_config`’e güvenmek yerine bunu mimari uygulamasında açıkça modellemeye çalışacağız. Açık bir mimari mevcut olduğunda onu tercih edin.

Aşağıdaki modeller heterojen kontrol noktalarıdır. Katmanlar yığın boyunca homojen değildir. Standart bir mimarideki `per_layer_config` yerine, `block_configs` ve kendi `model_type`'lerine sahip özel bir mimari kullanırlar.

| Model | Türetilen |
|---|---|
| [nvidia/Llama-3_3-Nemotron-Super-49B-v1_5](https://huggingface.co/nvidia/Llama-3_3-Nemotron-Super-49B-v1_5) | [meta-llama/Llama-3.3-70B-Instruct](https://huggingface.co/meta-llama/Llama-3.3-70B-Instruct) |
| [nvidia/Llama-3_1-Nemotron-Ultra-253B-v1](https://huggingface.co/nvidia/Llama-3_1-Nemotron-Ultra-253B-v1) | [meta-llama/Llama-3.1-405B-Instruct](https://huggingface.co/meta-llama/Llama-3.1-405B-Instruct) |
| [nvidia/gpt-oss-puzzle-88B](https://huggingface.co/nvidia/gpt-oss-puzzle-88B) | [openai/gpt-oss-120b](https://huggingface.co/openai/gpt-oss-120b) |
| [nvidia/NVIDIA-Nemotron-Labs-3-Puzzle-75B-A9B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-Labs-3-Puzzle-75B-A9B-BF16) | [nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16) |

## Katman başına geçersiz kılma tanımlayın

`per_layer_config` değerini, katman indekslerinden öznitelik geçersiz kılma değerlerine giden bir eşleme olarak [LlamaConfig](/docs/transformers/v5.23.0/tr/model_doc/llama2#transformers.LlamaConfig) sınıfına iletin. Katman indeksleri sıfır tabanlıdır. Sadece küresel yapılandırmadan farklı olan özniteliklerin belirtilmesi gerekir.

`per_layer_config`, yapılandırma değerlerini kaydeder ve çözümler. Kendi başına, bir modelin oluşturduğu modülleri veya bu modüllerin çalışma biçimini değiştirmez. Bir boyut geçersiz kılma (size override) veya `skip` uygulaması, her katmanı oluştururken veya çalıştırırken çözümlenmiş katman bazlı yapılandırmayı okuyan model kodu gerektirir. Mevcut `LlamaModel`, her `LlamaDecoderLayer` örneğini küresel yapılandırmayla oluşturduğundan, aşağıdaki `skip` girdileri, `from_pretrained` sonrasında modülleri kaldırmak yerine yalnızca yapılandırma değerleri olarak kalır.

Aşağıdaki örnek, dört katman için geçersiz kılma kayıtları oluşturur: 5. katman daha küçük bir MLP kullanır, 11. katman daha az anahtar-değer başlığı kullanır ve 23 ile 27. katmanlar, bunları destekleyen mimariler için `skip` değerleri kaydeder.

```py
from transformers import LlamaConfig

config = LlamaConfig(
    hidden_size=4096,
    intermediate_size=14336,
    num_hidden_layers=32,
    num_attention_heads=32,
    num_key_value_heads=8,
    per_layer_config={
        # Use a smaller MLP in one layer.
        5: {"intermediate_size": 8192},

        # Use fewer key-value heads in another layer.
        11: {"num_key_value_heads": 4},

        # Record a request to skip the MLP in architectures that support it.
        23: {"skip": ["mlp"]},

        # Record a request to skip attention in architectures that support it.
        27: {"skip": ["attention"]},
    },
)
```

Bir mimarinin atlayabileceği alt modüller (örneğin, `"mlp"` ve `"attention"`) mimari bazında tanımlanır. `skip` bir liste kabul eder, bu nedenle bir katman birden fazla alt modül geçersiz kılma işlemini kaydedebilir.

`config.per_layer_config[layer_idx]` adresine erişildiğinde çözümlenmiş bir katman yapılandırması döner. Çözümlenmiş yapılandırma, küresel yapılandırmayı o katman için tanımlanan geçersiz kılma ayarlarıyla birleştirir.

```py
# Layer 0 does not define overrides, so it inherits the global values.
config.per_layer_config[0].intermediate_size
# 14336

config.per_layer_config[0].num_key_value_heads
# 8

# Layer 5 overrides the MLP intermediate size.
config.per_layer_config[5].intermediate_size
# 8192

# Layer 11 overrides the number of key-value heads.
config.per_layer_config[11].num_key_value_heads
# 4

# Layer 23 records an MLP skip.
config.per_layer_config[23].skip
# ["mlp"]

# Layer 27 records an attention skip.
config.per_layer_config[27].skip
# ["attention"]
```

`per_layer_config` kullanan yapılandırmalar, diğer yapılandırmalarla aynı [save_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig.save_pretrained) ve [from_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig.from_pretrained) gidiş-dönüşünü destekler.

Her mimari, kodunda katman düzeyinde hangi öznitelikleri tükettiğini tanımlar. `per_layer_config`, bu katman düzeyindeki farklılıkları kaydetmek ve bunları küresel yapılandırma ile çözmek için mekanizmayı sağlar.

## Küresel öznitelik erişimi

Katman bazlı geçersiz kılmalara sahip bir öznitelik, model genelinde tek bir değere sahip değildir. `num_key_value_heads` çoğu katmanda `8`, seçili katmanlarda ise `4` olabilir. `config.num_key_value_heads` ifadesinin bir katman bağlamı dışında okunması belirsizdir.

Varsayılan olarak bu erişim `AmbiguousGlobalPerLayerAttributeError` hatasını oluşturur ve sizi `config.per_layer_config[layer_idx]` adresine yönlendirir. Öznitelik küresel yapılandırmada hâlâ mevcut olduğundan bu bir `AttributeError` değildir. Katman indeksi olmadan bu küresel değeri okumak yine de yanlıştır. Küresel bir `num_key_value_heads` değerinden anahtar-değer önbelleği oluşturan kod, yanlış katmanları hatalı boyutlandırır.

`allow_global_per_layer_attribute_access=True` değerini yalnızca global yedeklemeyi bilinçli olarak gerektirdiğiniz ve heterojen yapılandırmaları yönetebildiğiniz durumlarda ayarlayın. Bu durumda global erişime izin verilir. Bir kez uyarı yayımlanır.

```py
config = LlamaConfig(
    hidden_size=4096,
    intermediate_size=14336,
    num_hidden_layers=32,
    num_attention_heads=32,
    num_key_value_heads=8,
    allow_global_per_layer_attribute_access=True,
    per_layer_config={
        11: {"num_key_value_heads": 4},
    },
)

config.num_key_value_heads
# 8
# Emits a one-time warning because num_key_value_heads has a per-layer override.
```

## Seri hale getirme

`per_layer_config` varsayılan olarak seyrek olarak serialize edilir ve override içermeyen katmanlar atlanır. Küresel değerle eşleşen override edilmiş öznitelikler de atlanır.

```py
from transformers import LlamaConfig

config = LlamaConfig(
    hidden_size=4096,
    intermediate_size=14336,
    num_hidden_layers=4,
    num_attention_heads=32,
    num_key_value_heads=8,
    per_layer_config={
        0: {"num_key_value_heads": 8},
        2: {"num_key_value_heads": 4},
    },
)

config.to_dict()["per_layer_config"]
# {"2": {"num_key_value_heads": 4}}
```

`serialize_explicit_per_layer_config=True` değerini ayarlayarak, `per_layer_config` içinde temsil edilen öznitelikler için her bir katmanı dahil edebilirsiniz. Bu, bazı değerler hâlâ genel yapılandırmayla eşleştiğinde katman yerleşiminin incelenmesini kolaylaştırır.

```py
explicit_config = LlamaConfig(
    hidden_size=4096,
    intermediate_size=14336,
    num_hidden_layers=4,
    num_attention_heads=32,
    num_key_value_heads=8,
    serialize_explicit_per_layer_config=True,
    per_layer_config={
        0: {"num_key_value_heads": 8},
        2: {"num_key_value_heads": 4},
    },
)

serialized_per_layer_config = explicit_config.to_dict()["per_layer_config"]

serialized_per_layer_config
# {
#     "0": {"num_key_value_heads": 8},
#     "1": {"num_key_value_heads": 8},
#     "2": {"num_key_value_heads": 4},
#     "3": {"num_key_value_heads": 8},
# }
```

Kompakt yapılandırmalar için sparse serialization kullanın; okunabilirlik veya araçlar için tam katman başına yerleşime ihtiyacınız olduğunda ise explicit serialization kullanın.

