# Cấu hình theo từng lớp

Một số checkpoint là không đồng nhất (không đồng nhất theo lớp). Việc một lớp có MLP nhỏ hơn, một lớp khác có ít đầu key-value hơn, hoặc một bố cục khác trên các lớp được chọn có nghĩa là một cấu hình toàn cục duy nhất không mô tả chính xác toàn bộ stack.

Sử dụng `per_layer_config` trên [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để ghi lại các khác biệt đó khi bạn tạo hoặc kiểm tra một config, và khi mã mô hình sẽ sử dụng chúng. Mỗi mục chỉ lưu trữ những gì khác biệt so với cấu hình toàn cục, phần còn lại sẽ kế thừa.

> [!NOTE]
> Cấu hình dị thể là một tính năng mạnh mẽ. Nếu bố cục dị thể trở thành một kiến trúc phổ biến hoặc nổi bật, chúng tôi sẽ cố gắng mô hình hóa nó một cách tường minh trong việc triển khai kiến trúc thay vì dựa vào `per_layer_config`. Ưu tiên sử dụng kiến trúc tường minh khi có sẵn.

Các mô hình bên dưới là các checkpoint không đồng nhất. Các lớp không đồng nhất xuyên suốt toàn bộ stack. Chúng sử dụng kiến trúc chuyên dụng với `block_configs` và `model_type` riêng, thay vì `per_layer_config` trên một kiến trúc chuẩn.

| Mô hình | Được dẫn xuất từ |
|---|---|
| [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) |

## Định nghĩa các ghi đè theo từng lớp

Truyền `per_layer_config` vào [LlamaConfig](/docs/transformers/v5.23.0/vi/model_doc/llama2#transformers.LlamaConfig) dưới dạng ánh xạ từ chỉ số lớp đến các ghi đè thuộc tính. Chỉ số lớp bắt đầu từ 0. Chỉ cần chỉ định các thuộc tính khác với cấu hình toàn cục.

`per_layer_config` ghi nhận và giải quyết các giá trị cấu hình. Bản thân nó không thay đổi các module mà mô hình tạo ra hay cách các module đó chạy. Việc áp dụng một lệnh ghi đè kích thước hoặc một `skip` đòi hỏi mã mô hình phải đọc cấu hình từng lớp đã được giải quyết khi xây dựng hoặc chạy mỗi lớp. `LlamaModel` hiện tại xây dựng mọi `LlamaDecoderLayer` với cấu hình toàn cục, do đó các mục `skip` bên dưới vẫn là các giá trị cấu hình chứ không phải việc loại bỏ các module sau `from_pretrained`.

Ví dụ sau ghi đè cho bốn lớp: lớp 5 sử dụng MLP nhỏ hơn, lớp 11 sử dụng ít đầu key-value hơn, và các lớp 23 và 27 ghi lại các giá trị `skip` cho các kiến trúc hỗ trợ chúng.

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

Các submodule mà một kiến trúc có thể bỏ qua (ví dụ, `"mlp"` và `"attention"`) được định nghĩa theo từng kiến trúc. `skip` nhận một danh sách, do đó một lớp có thể ghi đè nhiều hơn một submodule.

Truy cập `config.per_layer_config[layer_idx]` sẽ trả về cấu hình lớp đã được giải quyết. Cấu hình đã giải quyết này kết hợp cấu hình toàn cục với các ghi đè cho lớp đó.

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

Các cấu hình sử dụng `per_layer_config` hỗ trợ cùng một vòng lặp [save_pretrained()](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig.save_pretrained) và [from_pretrained()](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig.from_pretrained) như các cấu hình khác.

Mỗi kiến trúc xác định trong mã nguồn của nó các thuộc tính mà nó sử dụng ở cấp độ lớp. `per_layer_config` cung cấp cơ chế để ghi lại những khác biệt ở cấp độ lớp đó và đối chiếu chúng với cấu hình toàn cục.

## Truy cập thuộc tính toàn cục

Thuộc tính có ghi đè theo từng lớp không có một giá trị duy nhất cho toàn bộ mô hình. `num_key_value_heads` có thể là `8` ở hầu hết các lớp và `4` ở một số lớp được chọn. Việc đọc `config.num_key_value_heads` bên ngoài ngữ cảnh của một lớp là mơ hồ.

Theo mặc định, thao tác truy cập đó sẽ gây ra `AmbiguousGlobalPerLayerAttributeError` và hướng bạn đến `config.per_layer_config[layer_idx]`. Thuộc tính này vẫn tồn tại trên cấu hình toàn cục, vì vậy đây không phải là `AttributeError`. Việc đọc giá trị toàn cục đó mà không có chỉ số lớp vẫn là sai. Mã nguồn xây dựng bộ nhớ đệm key-value từ `num_key_value_heads` toàn cục sẽ xác định sai kích thước cho các lớp không đúng.

Chỉ đặt `allow_global_per_layer_attribute_access=True` khi bạn thực sự cần cơ chế dự phòng toàn cục và có thể xử lý các cấu hình không đồng nhất. Khi đó, việc truy cập toàn cục sẽ được cho phép. Một cảnh báo sẽ được phát ra một lần.

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

## Chuẩn hóa

`per_layer_config` được serialize thưa theo mặc định, và các lớp không có ghi đè sẽ bị bỏ qua. Các thuộc tính được ghi đè trùng với giá trị toàn cục cũng bị bỏ qua.

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

Đặt `serialize_explicit_per_layer_config=True` để bao gồm mọi lớp cho các thuộc tính được đại diện trong `per_layer_config`. Điều này giúp việc kiểm tra bố cục lớp dễ dàng hơn khi một số giá trị vẫn khớp với cấu hình toàn cục.

```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},
# }
```

Sử dụng chuỗi hóa thưa (sparse serialization) cho các cấu hình gọn gàng, và chuỗi hóa tường minh (explicit serialization) khi bạn cần bố cục chi tiết theo từng lớp để tăng tính dễ đọc hoặc hỗ trợ công cụ.

