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 trên 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 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:

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

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.

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

lớp transformers.RopeParameters

< source >

( )

Tham số

rope_theta (float, tùy chọn, mặc định là RotaryEmbeddingConfigMixin.default_theta) — Chu kỳ cơ bản của các embedding RoPE. Tùy 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 RoPE gốc.
partial_rotary_factor (float, tùy chọn) — Tỷ lệ phần trăm của embedding đầu query và key mà RoPE sẽ được áp dụng.
factor (float, tùy chọn) — Đượ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. Trong phần lớn 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, tùy chọn) — Dùng với ‘yarn’, ‘longrope’ và ‘llama3’. Giá trị max position embeddings gốc được sử dụng trong quá trình pretraining.
attention_factor (float, tùy chọn) — Đượ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, tùy chọn) — 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, tùy chọn) — 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], tùy chọn) — Chỉ được sử dụng với ‘longrope’. Hệ số tỷ lệ được á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], tùy chọn) — 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, tùy 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, tùy 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, tùy 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, tùy 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_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 dựa trên factor mà thôi.
truncate (bool, tùy 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], tùy chọn) — Dùng với Multimodal RoPE (MRoPE). Kích thước của các dải tần số 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).

lớp .dict

( )

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

Update on GitHub