# Rotary 임베딩 유틸리티

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

## 개요

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

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

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

## Model Configs에서 설정

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

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

## 레이어 유형별 RoPE 구성

Gemma-3와 같은 일부 모델은 서로 다른 어텐션 메커니즘을 가진 다양한 레이어 유형을 사용합니다. 즉, 일부 블록에서는 "full attention", 다른 블록에서는 "sliding-window attention"을 사용합니다. Transformers는 이러한 모델에 대해 레이어 유형별로 서로 다른 RoPE 매개변수를 지정할 수 있도록 지원합니다. 이 경우 `rope_parameters`는 중첩된 사전(nested dictionary)이어야 하며, 최상위 키는 `config.layer_types`에 대응하고 값은 유형별 RoPE 매개변수입니다. 모델 초기화 시 각 디코더 레이어는 선언된 레이어 유형을 기반으로 일치하는 RoPE 구성을 자동으로 조회합니다.

```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는 멀티모달 모델에서 적용되는 회전 유형으로, `mrope_section`으로 정의됩니다. `rope_type` 테이블의 별도 항목이 아닙니다. MRoPE와 함께 rope scaling(`linear`, `dynamic`)을 적용할 수 있습니다.

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

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_rope_utils.py#L678)

**매개변수:**

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'와 함께 사용됩니다. 사전 학습 시 사용된 원래 최대 위치 임베딩입니다.

attention_factor (`float`, *선택 사항*) : 'yarn' 및 'longrope'와 함께 사용됩니다. attention 계산에 적용할 scaling factor입니다. 지정되지 않으면, `factor` 필드를 사용하여 구현에서 권장하는 값을 추론하여 기본값으로 사용합니다.

beta_fast (`float`, *선택 사항*) : 'yarn'에서만 사용됩니다. 선형 램프 함수에서 외삽(extrapolation)에만 적용되는 경계 값을 설정하는 매개변수입니다. 지정하지 않으면 기본값은 32입니다.

beta_slow (`float`, *선택*) : 'yarn'에서만 사용됩니다. 선형 램프 함수에서 보간(interpolation)에만 적용되는 경계 값을 설정하는 매개변수입니다. 지정하지 않으면 기본값은 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`와 같습니다)에 대한 연속 주파수 밴드의 크기를 지정합니다.

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

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