Hugging Face's logo

Transformers documentation

Утилиты для вращательных эмбеддингов

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Утилиты для вращательных эмбеддингов

Эта страница объясняет, как вычисляется и применяется Rotary Embedding в Transformers, а также какие типы RoPE поддерживаются.

Обзор

Rotary Position Embeddings — это техника, используемая для внедрения позиционной информации в механизмы внимания без опоры на явные позиционные кодировки.
Вместо добавления векторов позиций к эмбеддингам токенов RoPE поворачивает векторы запросов и ключей в комплексной плоскости в соответствии с их позициями, что обеспечивает относительное позиционное восприятие и лучшую экстраполяцию на невидимые длины последовательностей.

Библиотека Transformers предоставляет гибкую и расширяемую реализацию различных типов RoPE, определенных в ~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS, включая как вариант по умолчанию, так и масштабированные варианты:

Тип RopeОписание
"default"Стандартное вращательное встраивание, как в LLaMA.
"linear"RoPE с линейным масштабированием, позволяющий использовать более длинные контекстные окна.
"dynamic"Масштабирование с учётом NTK, вычисляемое путём перемасштабирования базовой частоты (θ) для более длинного контекста.
"yarn"Вариант масштабирования YaRN, обеспечивающий более плавную экстраполяцию и стабильность.
"longrope"Масштабирование LongRoPE, как в серии моделей Phi-2.
"llama3"Масштабирование RoPE, как в Llama3.1.

Конфигурация в Model Configs

Чтобы включить и настроить ротационные эмбеддинги, добавьте поле rope_parameters в файл конфигурации вашей модели (config.json). Это поле управляет поведением RoPE в слоях модели. Обратите внимание, что каждый вариант RoPE определяет собственный набор ожидаемых ключей, а отсутствие ключей приведёт к ошибке. Ниже приведён пример создания конфигурации llama с параметрами RoPE по умолчанию:

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
}

Конфигурация RoPE по типу слоя

Некоторые модели, такие как Gemma-3, используют различные типы слоёв с разными механизмами внимания, например, «полное внимание» в одних блоках и «скользящее окно внимания» в других. Transformers поддерживает указание отдельных параметров RoPE для каждого типа слоя в таких моделях. В этом случае rope_parameters должен быть вложенным словарём, где ключи верхнего уровня соответствуют config.layer_types, а значения — параметрами RoPE для каждого типа. При инициализации модели каждый слой декодера автоматически находит соответствующую конфигурацию RoPE на основе объявленного типа слоя.

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 — это тип вращения, применяемый в мультимодальных моделях и определяемый параметром mrope_section. Это не отдельная запись в таблице rope_type. При этом с ним по-прежнему можно применять масштабирование rope (linear, dynamic).

mrope_section задаёт размеры непрерывных частотных диапазонов для осей времени, высоты и ширины (сумма этих размеров равна head_dim // 2). Затем частоты повторяются так, чтобы эмбеддинг покрывал весь head_dim. Для мультимодальных входных данных (обычно визуальных) RoPE применяется за один шаг (matmul или побазовое умножение частот на позиции). mrope_section лишь переупорядочивает эти частоты вдоль (t, h, w), как в recomposition_frequencies для Qwen2-VL. Текст промпта и сгенерированные токены сохраняют обычный одномерный RoPE, используя одинаковые идентификаторы позиций на всех трёх сетках 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 использует mrope_section = [16, 24, 24] (16 временных, 24 по высоте, 24 по ширине, когда head_dim равно 128). Мультимодальные модели часто используют такую раскладку в текстовом бэкбоне (Qwen2-VL, GLM-4V). Некоторые VLM не используют MRoPE и остаются на обычном 2D текстовом RoPE. Проверьте mrope_section в текстовой конфигурации.

Axial RoPE

Отдельно отметим, что "axial" является зарегистрированным rope_type для моделей зрения, но он не указан в ROPE_INIT_FUNCTIONS. Настройка частот остаётся на стороне модели. Как правило, для позиций по высоте и ширине применяются одни и те же частоты (head_dim // 4 на каждую пространственную ось), при этом масштабирование не поддерживается. Среди примеров — модель зрения Qwen2-VL и другие стеки для зрения, такие как Pixtral.

Утилиты

класс transformers.RopeParameters

< >

( )

Параметры

  • rope_theta (float, необязательный, по умолчанию RotaryEmbeddingConfigMixin.default_theta) — Базовый период вложений RoPE. Необязательный параметр в сериализованных конфигурациях — если он опущен, используется default_theta модели (обычно 10000.0).
  • rope_type (str, необязательный, по умолчанию “default”) — Подвариант RoPE, который следует использовать. Может быть одним из [‘default’, ‘linear’, ‘dynamic’, ‘yarn’, ‘longrope’, ‘llama3’, ‘proportional’, ‘axial’], где ‘default’ — это исходная реализация RoPE.
  • partial_rotary_factor (float, необязательный) — Доля вложений заголовков запроса и ключа, к которой будет применён RoPE.
  • factor (float, необязательный) — Используется со всеми типами rope, кроме ‘default’. Коэффициент масштабирования, применяемый к эмбеддингам RoPE. В большинстве типов масштабирования значение factor, равное x, позволяет модели обрабатывать последовательности длины x * исходная максимальная длина, на которой обучалась модель.
  • original_max_position_embeddings (int, необязательный) — Используется с ‘yarn’, ‘longrope’ и ‘llama3’. Исходные максимальные позиционные эмбеддинги, применявшиеся во время предварительного обучения.
  • attention_factor (float, необязательный) — Используется с ‘yarn’ и ‘longrope’. Коэффициент масштабирования, применяемый при вычислении внимания. Если не указан, по умолчанию используется значение, рекомендуемое реализацией, на основе поля factor.
  • beta_fast (float, необязательный) — Используется только с ‘yarn’. Параметр для установки границы для экстраполяции (только) в линейной функции ramp. Если не указан, по умолчанию равен 32.
  • beta_slow (float, необязательный) — Используется только с ‘yarn’. Параметр для установки границы для интерполяции (только) в линейной функции нарастания. Если не указан, по умолчанию равен 1.
  • short_factor (list[float], необязательный) — Используется только с ‘longrope’. Коэффициент масштабирования, применяемый к коротким контекстам (< original_max_position_embeddings). Должен быть списком чисел той же длины, что и размер скрытого слоя, деленный на количество головок внимания, деленный на 2
  • long_factor (list[float], необязательный) — Используется только с ‘longrope’. Коэффициент масштабирования, применяемый к длинным контекстам (< original_max_position_embeddings). Должен быть списком чисел, длина которого равна размеру скрытого слоя, деленному на количество головок внимания, деленному на 2
  • low_freq_factor (float, необязательный) — Используется только с ‘llama3’. Коэффициент масштабирования, применяемый к низкочастотным компонентам RoPE
  • high_freq_factor (float, необязательный) — Используется только с ‘llama3’. Коэффициент масштабирования, применяемый к высокочастотным компонентам RoPE
  • mscale (float, необязательный) — Используется только с ‘yarn’. Если attention_factor равно None и указаны оба параметра mscale и mscale_all_dim, то mscale действует как скаляр, дополняющий log(factor) при вычислении числителя для определяемого значения attention_factor. Если не указан, attention_factor будет рассчитан на основе только factor.
  • mscale_all_dim (float, необязательный) — Используется только с ‘yarn’. Если attention_factor равно None и заданы оба параметра mscale и mscale_all_dim, то mscale_all_dim действует как скаляр, дополняющий log(factor) при вычислении знаменателя для выведенного значения attention_factor. Если не задан, attention_factor будет рассчитан на основе только factor.
  • truncate (bool, необязательный) — Используется только с ‘yarn’. Определяет, следует ли усекать диапазон коррекции с помощью math.floor и math.ceil. Если не указано, по умолчанию True.
  • mrope_section (list[int], необязательный) — Используется с мультимодальным RoPE (MRoPE). Размеры непрерывных частотных диапазонов для мультимодальных осей (обычно временной, высоты и ширины, сумма которых равна head_dim // 2).

класс .dict

( )

dict() -> новый пустой словарь dict(mapping) -> новый словарь, инициализированный парами (ключ, значение) объекта mapping dict(iterable) -> новый словарь, инициализированный так, как если бы выполнялся код: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> новый словарь, инициализированный парами name=value из списка аргументов с ключами. Например: dict(one=1, two=2)

Update on GitHub

←Утилиты для временных рядов Переменные окружения→