Rotary 임베딩 유틸리티

이 페이지에서는 Transformers에서 Rotary Embedding이 어떻게 계산되고 적용되는지, 그리고 어떤 유형의 RoPE가 지원되는지 설명합니다.

개요

Rotary Position Embeddings는 명시적인 위치 인코딩에 의존하지 않고 attention 메커니즘에 위치 정보를 주입하는 데 사용되는 기법입니다.
토큰 임베딩에 위치 벡터를 추가하는 대신, RoPE는 위치를 기준으로 query와 key 벡터를 복소 평면에서 회전시켜 상대적 위치 인식과未见된 시퀀스 길이에 대한 더 나은 외삽을 가능하게 합니다.

Transformers 라이브러리는 ~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS에 정의된 다양한 RoPE 유형을 유연하고 확장 가능하게 구현하며, 기본 변형과 스케일링 변형을 모두 포함합니다:

Rope 유형	설명
`"default"`	LLaMA와 동일한 표준 회전 임베딩
`"linear"`	더 긴 컨텍스트 윈도우를 허용하는 선형 스케일 RoPE
`"dynamic"`	더 긴 컨텍스트를 위해 주파수 기반(`θ`)을 다시 스케일링하여 계산하는 NTK-aware scaling
`"yarn"`	더 매끄러운 외삽과 안정성을 제공하는 YaRN 스케일링 변형입니다.
`"longrope"`	Phi-2 모델 시리즈와 동일한 LongRoPE 스케일링.
`"llama3"`	Llama3.1과 동일한 RoPE 스케일링.

Model Configs에서 설정

회전 임베딩을 활성화하고 사용자 정의하려면 모델의 구성 파일(config.json)에 rope_parameters 필드를 추가하세요. 이 필드는 모델 레이어 전반의 RoPE 동작을 제어합니다. 각 RoPE 변형은 자체적으로 기대하는 키 집합을 정의하며, 누락된 키가 있으면 오류가 발생합니다. 아래 예제는 기본 RoPE 매개변수를 가진 llama 구성을 생성합니다:

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와 같은 일부 모델은 서로 다른 어텐션 메커니즘을 가진 다양한 레이어 유형을 사용합니다. 즉, 일부 블록에서는 “full attention”, 다른 블록에서는 “sliding-window attention”을 사용합니다. Transformers는 이러한 모델에 대해 레이어 유형별로 서로 다른 RoPE 매개변수를 지정하는 것을 지원합니다. 이 경우 rope_parameters는 중첩된 사전(nested dictionary)이어야 하며, 최상위 키는 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 테이블의 별도 항목이 아닙니다. MRoPE와 함께 rope scaling(linear, dynamic)을 적용할 수 있습니다.

mrope_section은 시간, 높이, 너비 축에 대해 연속적인 주파수 대역의 크기를 지정합니다(이 크기의 합은 head_dim // 2입니다). 이후 주파수가 반복되어 임베딩이 전체 head_dim를 포괄하도록 합니다. 멀티모달 입력(보통 비전)의 경우, RoPE는 주파수와 위치의 matmul 또는 요소별 곱셈을 통해 한 번에 적용됩니다. mrope_section는 Qwen2-VL의 recomposition_frequencies와 마찬가지로 먼저 (t, h, w)를 따라 해당 주파수의 순서만 재배열합니다. 프롬프트 텍스트와 생성된 토큰은 세 THW 그리드 모두에서 동일한 위치 id를 사용하여 일반적인 1D RoPE를 유지합니다.

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]를 사용합니다(head_dim이 128인 경우 시간 16, 높이 24, 너비 24). 멀티모달 모델은 텍스트 백본(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

< source >

( )

매개변수

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가 적용될 query 및 key head 임베딩의 비율입니다.
factor (float, 선택 사항) — ‘default’를 제외한 모든 rope 유형과 함께 사용됩니다. RoPE 임베딩에 적용할 스케일링 계수입니다. 대부분의 스케일링 유형에서 factor가 x이면 모델이 x * 원래 최대 사전 학습 길이의 시퀀스를 처리할 수 있도록 합니다.
original_max_position_embeddings (int, 선택 사항) — ‘yarn’, ‘longrope’, ‘llama3’와 함께 사용됩니다. 사전 학습(pretraining) 시 사용된 원래의 최대 위치 임베딩(max position embeddings)입니다.
attention_factor (float, 선택 사항) — ‘yarn’ 및 ‘longrope’와 함께 사용됩니다. attention 계산에 적용할 스케일링 팩터입니다. 지정되지 않으면, 구현에서 권장하는 값이 기본값으로 사용되며, factor 필드를 사용하여 권장 값을 추론합니다.
beta_fast (float, 선택 사항) — ‘yarn’에서만 사용됩니다. 선형 램프 함수에서 외삽(extrapolation)에만 적용되는 경계 값을 설정하는 매개변수입니다. 지정하지 않으면 기본값은 32입니다.
beta_slow (float, 선택 사항) — ‘yarn’에서만 사용됩니다. 선형 램프 함수에서 보간(만)의 경계를 설정하는 매개변수입니다. 지정되지 않으면 기본값은 1입니다.
short_factor (list[float], 선택 사항) — ‘longrope’와 함께 사용할 때만 적용됩니다. 짧은 컨텍스트(< original_max_position_embeddings)에 적용할 스케일링 팩터입니다. hidden size를 attention head 수로 나눈 값의 절반과 동일한 길이를 가진 숫자 리스트여야 합니다.
long_factor (list[float], 선택 사항) — ‘longrope’와 함께 사용할 때만 적용됩니다. 긴 컨텍스트(< original_max_position_embeddings)에 적용할 스케일링 팩터입니다. hidden size를 attention head 수로 나눈 값의 절반과 동일한 길이를 가진 숫자 리스트여야 합니다.
low_freq_factor (float, 선택 사항) — ‘llama3’에서만 사용됩니다. RoPE의 저주파 성분에 적용되는 스케일링 계수
high_freq_factor (float, 선택 사항) — ‘llama3’에서만 사용됩니다. RoPE의 고주파 성분에 적용되는 스케일링 계수
mscale (float, 선택 사항) — ‘yarn’과 함께 사용할 때만 적용됩니다. attention_factor가 None이고 mscale과 mscale_all_dim이 모두 제공된 경우, mscale은 attention_factor의 추론된 값을 계산할 때 분자의 log(factor)를 보강하는 스칼라로 작용합니다. 제공되지 않으면 attention_factor는 factor에만 기반하여 계산됩니다.
mscale_all_dim (float, 선택 사항) — ‘yarn’과 함께 사용할 때만 적용됩니다. attention_factor가 None이고 mscale과 mscale_all_dim이 모두 제공된 경우, mscale_all_dim은 attention_factor의 추론된 값을 계산하기 위한 분모를 계산할 때 log(factor)를 증분하는 스칼라로 작용합니다. 제공되지 않으면 attention_factor는 factor에만 기반하여 계산됩니다.
truncate (bool, 선택 사항) — ‘yarn’과 함께만 사용됩니다. math.floor와 math.ceil를 사용하여 보정 범위를 잘라낼지 여부입니다. 지정하지 않으면 기본값은 True입니다.
mrope_section (list[int], 선택 사항) — Multimodal RoPE(MRoPE)와 함께 사용됩니다. 멀티모달 축(일반적으로 시간, 높이, 너비이며, 그 합은 head_dim // 2와 같습니다)에 대한 연속 주파수 밴드의 크기입니다.

class .dict

( )

dict() -> 새로운 빈 사전 dict(mapping) -> 매핑 객체의 (키, 값) 쌍으로 초기화된 새로운 사전 dict(iterable) -> 다음과 같이 초기화된 것처럼 초기화된 새로운 사전: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> 키워드 인자 목록의 이름=값 쌍으로 초기화된 새로운 사전. 예를 들어: dict(one=1, two=2)

Update on GitHub