# Công cụ nhúng xoay

Trang này giải thích cách tính toán và áp dụng Rotary Embedding trong Transformers cũng như các loại RoPE được hỗ trợ.

## Tổng quan

Rotary Position Embeddings là một kỹ thuật được sử dụng để đưa thông tin vị trí vào các cơ chế chú ý mà không cần dựa vào các mã hóa vị trí tường minh. Thay vì cộng các vector vị trí vào các mã hóa token, RoPE xoay các vector truy vấn và khóa trong mặt phẳng phức theo vị trí của chúng, cho phép nhận thức vị trí tương đối và ngoại suy tốt hơn đến các độ dài chuỗi chưa từng thấy.

Thư viện Transformers cung cấp một triển khai linh hoạt và có thể mở rộng cho các loại RoPE khác nhau được định nghĩa trong ``~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS``, bao gồm cả các biến thể mặc định và đã được scale:

| Loại Rope | Mô tả |
|------------|-------------|
| `"default"` | Nhúng xoay chuẩn như trong LLaMA. |
| `"linear"` | RoPE có tỷ lệ tuyến tính, cho phép các cửa sổ ngữ cảnh dài hơn. |
| `"dynamic"` | Thang đo nhận thức NTK được tính bằng cách điều chỉnh lại cơ sở tần số (`θ`) cho ngữ cảnh dài hơn. |
| `"yarn"` | Biến thể mở rộng YaRN cung cấp ngoại suy mượt mà hơn và ổn định hơn. |
| `"longrope"` | [LongRoPE](https://github.com/microsoft/LongRoPE) scaling như trong các model của series Phi-2. |
| `"llama3"` | RoPE scaling như trong Llama3.1. |

## Cấu hình trong Model Configs

Để bật và tùy chỉnh rotary embeddings, hãy thêm trường `rope_parameters` vào tệp cấu hình của mô hình (`config.json`). Trường này kiểm soát hành vi của RoPE trên các lớp của mô hình. Lưu ý rằng mỗi biến thể RoPE định nghĩa một bộ khóa mong đợi riêng và các khóa bị thiếu sẽ gây ra lỗi. Xem ví dụ bên dưới tạo một llama config với các tham số RoPE mặc định:

```python
from transformers import LlamaConfig

config = LlamaConfig()
config.rope_parameters = {
    "rope_type": "default", # type of RoPE to use
    # rope_theta is optional — omitting it uses the model’s default_theta (typically 10000.0)
}

# If we want to apply a scaled RoPE type, we need to pass extra parameters
config.rope_parameters = {
    "rope_type": "linear",
    "rope_theta": 10000.0,  # can be omitted to fall back to default_theta
    "factor": 8.0  # scale factor for context extension
}
```

## Cấu hình RoPE theo loại lớp

Một số mô hình như Gemma-3 sử dụng các loại lớp khác nhau với các cơ chế chú ý khác nhau, ví dụ như "full attention" trong một số khối và "sliding-window attention" trong các khối khác. Transformers hỗ trợ việc chỉ định các tham số RoPE riêng biệt cho từng loại lớp đối với những mô hình này. Trong trường hợp này, `rope_parameters` nên là một từ điển lồng nhau, trong đó các khóa cấp trên cùng tương ứng với `config.layer_types` và các giá trị là tham số RoPE cho từng loại. Trong quá trình khởi tạo mô hình, mỗi lớp giải mã sẽ tự động tra cứu cấu hình RoPE phù hợp dựa trên loại lớp đã khai báo của nó.

```python
from transformers import Gemma3Config

config = Gemma3Config()
config.rope_parameters = {
    "full_attention": {
        "rope_type": "dynamic",
        "rope_theta": 1000000.0,
        "factor": 8.0,
        "original_max_position_embeddings": 8096,
    },
    "sliding_attention": {
        "rope_type": "default",
        "rope_theta": 10000.0,
    }
}
```

## MRoPE

MRoPE là một dạng phép quay được áp dụng trong các mô hình đa phương thức và được định nghĩa bởi `mrope_section`. Nó không phải là một mục riêng trong bảng `rope_type`. Bạn vẫn có thể áp dụng rope scaling (`linear`, `dynamic`) với nó.

`mrope_section` quy định kích thước của các dải tần số liên tục cho các trục thời gian, chiều cao và chiều rộng (tổng các kích thước này bằng `head_dim // 2`). Sau đó, các tần số được lặp lại để embedding bao phủ toàn bộ `head_dim`. Đối với đầu vào đa phương tiện (thường là thị giác), RoPE được áp dụng một lần duy nhất (nhân ma trận hoặc nhân từng phần tử giữa tần số và vị trí). `mrope_section` chỉ sắp xếp lại các tần số đó dọc theo `(t, h, w)` trước tiên, giống như `recomposition_frequencies` của Qwen2-VL. Văn bản trong prompt và các token được tạo ra vẫn giữ RoPE 1D thông thường bằng cách sử dụng các id vị trí giống nhau trên cả ba lưới THW.

```python
from transformers import Qwen2VLConfig

config = Qwen2VLConfig()
config.text_config.rope_parameters = {
    "rope_type": "default",
    "rope_theta": 1000000.0,
    "mrope_section": [16, 24, 24],  # temporal, height, width frequency band sizes
}
```

Qwen2-VL sử dụng `mrope_section = [16, 24, 24]` (16 thời gian, 24 chiều cao, 24 chiều rộng khi `head_dim` là 128). Các mô hình đa phương thức thường sử dụng bố cục này trong phần nền tảng văn bản (Qwen2-VL, GLM-4V). Một số VLM không sử dụng MRoPE mà vẫn dùng RoPE văn bản 2D thông thường. Kiểm tra `mrope_section` trong cấu hình văn bản.

## RoPE trục

Riêng biệt, `"axial"` là một `rope_type` đã đăng ký cho các mô hình thị giác, nhưng không được liệt kê trong `ROPE_INIT_FUNCTIONS`. Việc thiết lập tần số vẫn do mô hình đảm nhận. Nó thường áp dụng cùng một tần số (`head_dim // 4` cho mỗi trục không gian) cho các vị trí chiều cao và chiều rộng, và không cho phép mở rộng thêm. Các ví dụ bao gồm mô hình thị giác Qwen2-VL và các bộ xử lý thị giác khác như Pixtral.

## Công cụ tiện ích[[transformers.RopeParameters]]

#### transformers.RopeParameters[[transformers.RopeParameters]]

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_rope_utils.py#L678)

**Tham số:**

rope_theta (`float`, *tuỳ chọn*, mặc định là `RotaryEmbeddingConfigMixin.default_theta`) : Chu kỳ cơ bản của các nhúng RoPE. Tuỳ chọn trong các cấu hình đã được serialize — nếu bị bỏ qua, `default_theta` của mô hình (thường là 10000.0) sẽ được sử dụng.

rope_type (`str`, *tuỳ chọn*, mặc định là "default") : Biến thể con của RoPE cần sử dụng. Có thể là một trong ['default', 'linear', 'dynamic', 'yarn', 'longrope', 'llama3', 'proportional', 'axial'], trong đó 'default' là cài đặt gốc của RoPE.

partial_rotary_factor (`float`, *tuỳ chọn*) : Tỷ lệ phần trăm của embedding đầu query và key mà RoPE sẽ được áp dụng.

factor (`float`, *optional*) : Được sử dụng với tất cả các loại rope ngoại trừ 'default'. Hệ số tỷ lệ để áp dụng cho các embedding RoPE. Với hầu hết các loại tỷ lệ, một `factor` là x sẽ cho phép mô hình xử lý các chuỗi có độ dài x * độ dài tối đa ban đầu khi huấn luyện trước.

original_max_position_embeddings (`int`, *tuỳ chọn*) : Dùng với 'yarn', 'longrope' và 'llama3'. Số lượng max position embeddings gốc được sử dụng trong quá trình pretraining.

attention_factor (`float`, *optional*) : Được sử dụng với 'yarn' và 'longrope'. Hệ số tỷ lệ được áp dụng cho phép tính attention. Nếu không được chỉ định, giá trị mặc định sẽ là giá trị được khuyến nghị bởi cài đặt, sử dụng trường `factor` để suy ra giá trị đề xuất.

beta_fast (`float`, *optional*) : Chỉ được sử dụng với 'yarn'. Tham số để đặt ranh giới cho ngoại suy (chỉ) trong hàm ramp tuyến tính. Nếu không được chỉ định, giá trị mặc định là 32.

beta_slow (`float`, *optional*) : Chỉ được sử dụng với 'yarn'. Tham số để đặt ranh giới cho phép nội suy (chỉ) trong hàm ramp tuyến tính. Nếu không được chỉ định, giá trị mặc định là 1.

short_factor (`list[float]`, *optional*) : Chỉ được sử dụng với 'longrope'. Hệ số tỷ lệ cần áp dụng cho các ngữ cảnh ngắn (< `original_max_position_embeddings`). Phải là một danh sách các số có cùng độ dài bằng kích thước ẩn chia cho số đầu chú ý chia cho 2

long_factor (`list[float]`, *optional*) : Chỉ được sử dụng với 'longrope'. Hệ số tỷ lệ cần áp dụng cho các ngữ cảnh dài (< `original_max_position_embeddings`). Phải là một danh sách các số có cùng độ dài bằng kích thước ẩn chia cho số đầu chú ý chia cho 2

low_freq_factor (`float`, *tuỳ chọn*) : Chỉ được sử dụng với 'llama3'. Hệ số tỷ lệ được áp dụng cho các thành phần tần số thấp của RoPE

high_freq_factor (`float`, *tuỳ chọn*) : Chỉ được sử dụng với 'llama3'. Hệ số tỷ lệ được áp dụng cho các thành phần tần số cao của RoPE

mscale (`float`, *tuỳ chọn*) : Chỉ được sử dụng với 'yarn'. Nếu `attention_factor` là `None` và cả `mscale` lẫn `mscale_all_dim` đều được cung cấp, `mscale` đóng vai trò là một hệ số vô hướng bổ trợ cho `log(factor)` khi tính tử số cho giá trị suy ra của `attention_factor`. Nếu không được cung cấp, `attention_factor` sẽ được tính toán dựa trên `factor` duy nhất.

mscale_all_dim (`float`, *optional*) : Chỉ được sử dụng với 'yarn'. Nếu `attention_factor` là `None` và cả `mscale` lẫn `mscale_all_dim` đều được cung cấp, `mscale_all_dim` đóng vai trò là một hệ số vô hướng bổ trợ cho `log(factor)` khi tính mẫu số cho giá trị suy ra của `attention_factor`. Nếu không được cung cấp, `attention_factor` sẽ được tính toán dựa trên `factor` duy nhất.

truncate (`bool`, *tuỳ chọn*) : Chỉ được sử dụng với 'yarn'. Xác định có cắt ngắn phạm vi hiệu chỉnh bằng `math.floor` và `math.ceil` hay không. Nếu không được chỉ định, mặc định là `True`.

mrope_section (`list[int]`, *tuỳ chọn*) : Được sử dụng với Multimodal RoPE (MRoPE). Kích thước của các dải tần liên tục cho các trục đa phương thức (thường là thời gian, chiều cao và chiều rộng, với tổng bằng `head_dim // 2`).

#### dict[[transformers.RopeParameters.__call__]]

dict() -> từ điển mới rỗng dict(mapping) -> từ điển mới được khởi tạo từ các cặp (key, value) của đối tượng mapping dict(iterable) -> từ điển mới được khởi tạo như thể thông qua: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> từ điển mới được khởi tạo với các cặp name=value trong danh sách đối số keyword. Ví dụ: dict(one=1, two=2)