# MuseGlimmerAssistant

[MuseGlimmerAssistant](https://research.meta.ai/blog/introducing-muse-glimmer-open-agentic-model)는 [MuseGlimmer](./muse_glimmer)의 [DFlash](https://huggingface.co/papers/2602.06036) 드래프터입니다. 독립적인 언어 모델이 아닙니다. 5개의 슬라이딩 윈도우 레이어를 가지며 자체 임베딩이 없습니다. 메인 모델의 입력 및 출력 임베딩을 빌려 사용하고, `target_layer_ids`(기본값은 1, 13, 25, 37, 49 레이어)의 메인 모델 히든 상태를 컨텍스트로 읽습니다.

토큰을 하나씩 생성하는 대신, drafter는 `block_size`개의 마스킹된 토큰으로 구성된 블록 전체를 diffusion window처럼 단일 forward pass에서 denoise합니다. 이후 main model이 해당 블록을 한 단계에서 검증합니다. Meta는 RTX 5090에서 3.1배, Apple M-series 칩에서 1.5~1.8배 빠른 decoding을 보고했습니다.

drafter를 [generate()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin.generate)에 `assistant_model`로 전달하고 `speculation_type="dflash"`를 설정합니다. drafter는 메인 모델과 동일한 dtype과 동일한 device에 로드되어야 합니다.

```python
from transformers import AutoProcessor, MuseGlimmerAssistantModel, MuseGlimmerForConditionalGeneration

processor = AutoProcessor.from_pretrained("meta-models/Muse-Glimmer-30B")
model = MuseGlimmerForConditionalGeneration.from_pretrained(
    "meta-models/Muse-Glimmer-30B",
    device_map="auto",
)
drafter = MuseGlimmerAssistantModel.from_pretrained(
    "meta-models/Muse-Glimmer-30B-assistant",
    device_map="auto",
)

messages = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Write a bash one-liner that counts lines of Python in a repo."}],
    },
]
inputs = processor.apply_chat_template(
    messages,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(
    **inputs,
    assistant_model=drafter,
    speculation_type="dflash",
    max_new_tokens=256,
)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
print(response)
```

## The input is a single word "Notes".

참고

- drafter는 메인 모델의 hidden states가 필요하므로, `speculation_type="dflash"`인 경우 `generate`는 대상 모델에 대해 `output_hidden_states=True`를 강제합니다.
- 자세한 내용과 사용 예시는 [Meta는 Muse Glimmer로 돌아왔다: 로컬, 에이전틱, 멀티모달, 오픈 소스!](https://huggingface.co/blog/muse-glimmer) 블로그 포스트를 참고하세요.

## MuseGlimmerAssistantConfig[[transformers.MuseGlimmerAssistantConfig]]

#### transformers.MuseGlimmerAssistantConfig[[transformers.MuseGlimmerAssistantConfig]]

```python
transformers.MuseGlimmerAssistantConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 6656, intermediate_size: int = 19968, num_hidden_layers: int = 5, num_attention_heads: int = 32, num_key_value_heads: int = 8, head_dim: int = 128, rms_norm_eps: float = 1e-05, rope_parameters: dict | None = None, max_position_embeddings: int = 131072, sliding_window: int = 2048, layer_types: list[str] | None = None, attention_dropout: float | int = 0, hidden_act: str = 'silu', bos_token_id: int | None = 200000, eos_token_id: int | None = 200001, pad_token_id: int | None = 200018, block_size: int = 16, mask_token_id: int = 201818, target_layer_ids: list[int] | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/muse_glimmer_assistant/configuration_muse_glimmer_assistant.py#L27)

**매개변수:**

hidden_size (`int`, *선택 사항*, 기본값 `6656`) : 숨겨진 표현의 차원.

intermediate_size (`int`, *선택 사항*, 기본값 `19968`) : MLP 표현의 차원.

num_hidden_layers (`int`, *선택 사항*, 기본값 `5`) : Transformer 디코더의 숨겨진 레이어 수.

num_attention_heads (`int`, *선택 사항*, 기본값 `32`) : Transformer decoder의 각 attention layer에 사용할 attention head 수입니다.

num_key_value_heads (`int`, *선택 사항*, 기본값 `8`) : Grouped Query Attention 구현에 사용할 key_value 헤드 수입니다. `num_key_value_heads=num_attention_heads`인 경우 모델은 Multi Head Attention(MHA)을, `num_key_value_heads=1`인 경우 Multi Query Attention(MQA)을, 그 외에는 GQA를 사용합니다. 멀티 헤드 체크포인트를 GQA 체크포인트로 변환할 때, 각 그룹의 key 및 value 헤드는 해당 그룹 내 모든 원래 헤드를 meanpooling하여 구성해야 합니다. 자세한 내용은 [이 논문](https://huggingface.co/papers/2305.13245)을 참고하세요. 지정되지 않으면 `num_attention_heads`가 기본값으로 사용됩니다.

head_dim (`int`, *선택 사항*, 기본값 `128`) : attention head 차원입니다. None인 경우 hidden_size // num_attention_heads 값이 기본값으로 사용됩니다.

rms_norm_eps (`float`, *선택 사항*, 기본값 `1e-05`) : rms normalization 레이어에서 사용되는 epsilon 값입니다.

rope_parameters (`dict`, *선택*) : RoPE 임베딩의 구성 매개변수를 포함하는 사전입니다. 사전에는 `rope_theta` 값이 포함되어야 하며, 더 긴 `max_position_embeddings`로 RoPE를 사용하려는 경우 스케일링에 사용되는 매개변수를 선택적으로 포함할 수 있습니다.

max_position_embeddings (`int`, *선택 사항*, 기본값 `131072`) : 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다.

sliding_window (`int`, *선택 사항*, 기본값 `2048`) : 슬라이딩 윈도우 어텐션의 윈도우 크기입니다. `None`인 경우 슬라이딩 윈도우가 적용되지 않습니다.

layer_types (`list[str]`, *선택 사항*) : 각 레이어 인덱스를 해당 레이어 유형에 명시적으로 매핑하는 리스트입니다. 제공되지 않으면 config 값에 기반하여 자동으로 생성됩니다.

attention_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0`) : attention 확률에 적용할 dropout 비율입니다.

hidden_act (`str`, *선택 사항*, 기본값 `silu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다.

bos_token_id (`int`, *선택 사항*, 기본값 `200000`) : 어휘에서 스트림 시작에 사용되는 토큰 ID입니다.

eos_token_id (`int`, *선택 사항*, 기본값 `200001`) : 어휘에서 스트림 종료에 사용되는 토큰 ID입니다.

pad_token_id (`int`, *선택 사항*, 기본값 `200018`) : 어휘에서 패딩에 사용되는 토큰 ID입니다.

block_size (`int`, *선택 사항*) : 노이즈 제거 대상 노이즈 입력의 블록 크기입니다.

mask_token_id (`int`, *선택 사항*) : 모델의 노이즈 입력으로 사용되는 마스크 토큰 ID입니다.

target_layer_ids (`list[int]`, *선택 사항*) : 모델의 컨텍스트로 연결되는 숨겨진 상태(hidden states)를 가지는 0부터 시작하는 레이어 ID입니다.

이것은 MuseGlimmerAssistantModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Muse Glimmer Assistant 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [meta-models/Muse-Glimmer-30B-assistant](https://huggingface.co/meta-models/Muse-Glimmer-30B-assistant)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:

```python
>>> from transformers import MuseGlimmerAssistantConfig, MuseGlimmerAssistantModel

>>> # Initializing a Muse Glimmer Assistant config similar to `meta-models/Muse-Glimmer-30B-assistant`.
>>> configuration = MuseGlimmerAssistantConfig(text_config)

>>> # Initializing a model from the `meta-models/Muse-Glimmer-30B-assistant` configuration.
>>> model = MuseGlimmerAssistantModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## MuseGlimmerAssistantPreTrainedModel[[transformers.MuseGlimmerAssistantPreTrainedModel]]

#### transformers.MuseGlimmerAssistantPreTrainedModel[[transformers.MuseGlimmerAssistantPreTrainedModel]]

```python
transformers.MuseGlimmerAssistantPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/muse_glimmer_assistant/modeling_muse_glimmer_assistant.py#L273)

**매개변수:**

config ([PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

## MuseGlimmerAssistantModel[[transformers.MuseGlimmerAssistantModel]]

#### transformers.MuseGlimmerAssistantModel[[transformers.MuseGlimmerAssistantModel]]

```python
transformers.MuseGlimmerAssistantModel(config: MuseGlimmerAssistantConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/muse_glimmer_assistant/modeling_muse_glimmer_assistant.py#L359)

**매개변수:**

config ([MuseGlimmerAssistantConfig](/docs/transformers/v5.23.0/ko/model_doc/muse_glimmer_assistant#transformers.MuseGlimmerAssistantConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 Muse Glimmer Assistant Model의 기본 형태입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.MuseGlimmerAssistantModel.forward]]

```python
forward(noise_embeds: Tensor, context_hidden_states: Tensor, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.DFlashCache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/muse_glimmer_assistant/modeling_muse_glimmer_assistant.py#L373)

**매개변수:**

noise_embeds (`torch.Tensor`, shape `[batch_size, config.block_size, dim]`) : 마지막에 생성된 앵커 토큰과 노이즈 제거 대상 마스크 토큰의 입력 임베딩.

context_hidden_states (`torch.Tensor`, shape `[batch_size, number_of_previous_accepted_tokens, dim * len(config.target_layer_ids)]`) : 타깃 모델의 선택된 레이어 ID에서 가져온 컨텍스트 히든 스테이트를 마지막 차원 방향으로 연결한 값.

attention_mask (`torch.Tensor`, shape `[batch_size, number_of_previous_accepted_tokens + config.block_size]`) : 일반적인 attention_mask와 유사하지만, Attention이 `context_hidden_states`와 `noise_embeds`에서 파생된 hidden states를 먼저 연결하기 때문에 `cache.update()` 호출 이전에도 k/v states의 길이가 q_states와 같지 않으므로, 길이가 `number_of_previous_accepted_tokens + config.block_size`임을 유의하세요. 따라서 attention mask의 kv_seq_len 차원은 추가적인 위치를 포함하도록 확장되어야 합니다.

position_ids (`torch.Tensor`, shape `[batch_size, number_of_previous_accepted_tokens + config.block_size]`) : 일반적인 position_ids와 유사하지만, `cache.update()` 호출 이전에도 k/v 상태의 길이가 q_states와 같지 않으므로, Attention이 먼저 `context_hidden_states`와 `noise_embeds`에서 파생된 hidden states를 연결하기 때문에 길이가 `number_of_previous_accepted_tokens + config.block_size`임을 유의하세요. 따라서 `position_ids`와 여기서 파생되는 `position_embeddings`는 모든 추가 위치를 포괄해야 합니다.

past_key_values (`~cache_utils.DFlashCache`, *선택*) : 순차 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 이는 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 이전 디코딩 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 캐시 형식과 동일한 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

**반환값:** [BaseModelOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `tuple(torch.Tensor)`

구성([MuseGlimmerAssistantConfig](/docs/transformers/v5.23.0/ko/model_doc/muse_glimmer_assistant#transformers.MuseGlimmerAssistantConfig))과 입력에 따라 다양한 요소를 포함하는 [BaseModelOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[MuseGlimmerAssistantModel](/docs/transformers/v5.23.0/ko/model_doc/muse_glimmer_assistant#transformers.MuseGlimmerAssistantModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 형태는 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

