# MuseGlimmerAssistant

[MuseGlimmerAssistant](https://research.meta.ai/blog/introducing-muse-glimmer-open-agentic-model) — это [DFlash](https://huggingface.co/papers/2602.06036)-драфтер для [MuseGlimmer](./muse_glimmer). Это не самостоятельная языковая модель. Она содержит 5 слоёв со скользящим окном и не имеет собственных эмбеддингов. Она заимствует входные и выходные эмбеддинги основной модели и читает скрытые состояния основной модели на `target_layer_ids` (по умолчанию слои 1, 13, 25, 37 и 49) в качестве контекста.

Вместо того чтобы генерировать по одному токену за раз, drafter снимает шум со всего блока из `block_size` замаскированных токенов за один прямой проход, подобно окну диффузии. Затем основная модель проверяет блок за один шаг. Meta сообщает об ускорении декодирования в 3,1 раза на RTX 5090 и в 1,5–1,8 раза на чипах Apple M-series.

Передайте drafter в [generate()](/docs/transformers/main/ru/main_classes/text_generation#transformers.GenerationMixin.generate) как `assistant_model` и установите `speculation_type="dflash"`. Drafter должен быть загружен с тем же dtype и на том же устройстве, что и основная модель.

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

## Примечания

- Драфтеру нужны скрытые состояния основной модели, поэтому `generate` принудительно устанавливает `output_hidden_states=True` для целевой модели, когда `speculation_type="dflash"`.
- Подробнее о возможностях и примерах использования см. в блоге [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/main/src/transformers/models/muse_glimmer_assistant/configuration_muse_glimmer_assistant.py#L27)

**Параметры:**

hidden_size (`int`, *optional*, по умолчанию `6656`) : Размерность скрытых представлений.

intermediate_size (`int`, *optional*, по умолчанию `19968`) : Размерность представлений MLP.

num_hidden_layers (`int`, *необязательный*, по умолчанию `5`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `32`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

num_key_value_heads (`int`, *optional*, по умолчанию `8`) : Это количество ключевых и value-голов, которое следует использовать для реализации Grouped Query Attention. Если `num_key_value_heads=num_attention_heads`, модель будет использовать Multi Head Attention (MHA), если `num_key_value_heads=1` — Multi Query Attention (MQA), в противном случае используется GQA. При конвертации multi-head checkpoint в GQA checkpoint каждая группа ключевых и value-голов должна быть построена путем усреднения (meanpooling) всех исходных голов в этой группе. Подробнее см. в [этой статье](https://huggingface.co/papers/2305.13245). Если значение не указано, по умолчанию используется `num_attention_heads`.

head_dim (`int`, *необязательный*, по умолчанию `128`) : Размер измерения головы внимания. Если None, по умолчанию будет hidden_size // num_attention_heads

rms_norm_eps (`float`, *необязательный*, по умолчанию `1e-05`) : Значение epsilon, используемое слоями нормализации rms.

rope_parameters (`dict`, *необязательный*) : Словарь, содержащий параметры конфигурации для вложений RoPE. Словарь должен содержать значение для `rope_theta` и, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длинными `max_position_embeddings`.

max_position_embeddings (`int`, *необязательный*, по умолчанию `131072`) : Максимальная длина последовательности, с которой может использоваться эта модель.

sliding_window (`int`, *optional*, по умолчанию `2048`) : Размер окна скользящего внимания. Если `None`, скользящее окно не применяется.

layer_types (`list[str]`, *необязательный*) : Список, который явно сопоставляет каждый индекс слоя с его типом. Если не указан, будет автоматически сгенерирован на основе значений конфигурации.

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0`) : Коэффициент dropout для вероятностей внимания.

hidden_act (`str`, *необязательный*, по умолчанию `silu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

bos_token_id (`int`, *необязательный*, по умолчанию `200000`) : Идентификатор токена, используемый для обозначения начала потока в словаре.

eos_token_id (`int`, *необязательный*, по умолчанию `200001`) : Идентификатор токена, используемый для обозначения конца потока в словаре.

pad_token_id (`int`, *необязательный*, по умолчанию `200018`) : Идентификатор токена, используемый для выравнивания в словаре.

block_size (`int`, *optional*) : Размер блока входных данных шума, которые будут очищены.

mask_token_id (`int`, *optional*) : Идентификаторы токенов маски, используемые в качестве зашумленного входа для модели.

target_layer_ids (`list[int]`, *необязательный*) : Нулевые идентификаторы слоёв, скрытые состояния которых конкатенируются в качестве контекста для модели.

Это класс конфигурации для хранения настроек модели MuseGlimmerAssistantModel. Он используется для создания модели Muse Glimmer Assistant в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [meta-models/Muse-Glimmer-30B-assistant](https://huggingface.co/meta-models/Muse-Glimmer-30B-assistant)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/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/main/src/transformers/models/muse_glimmer_assistant/modeling_muse_glimmer_assistant.py#L273)

**Параметры:**

config ([PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

## MuseGlimmerAssistantModel[[transformers.MuseGlimmerAssistantModel]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_glimmer_assistant/modeling_muse_glimmer_assistant.py#L359)

**Параметры:**

config ([MuseGlimmerAssistantConfig](/docs/transformers/main/ru/model_doc/muse_glimmer_assistant#transformers.MuseGlimmerAssistantConfig)) : класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Muse Glimmer Assistant в исходном виде, выводящая необработанные скрытые состояния без какого-либо специализированного слоя наверху.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/main/src/transformers/models/muse_glimmer_assistant/modeling_muse_glimmer_assistant.py#L373)

**Параметры:**

noise_embeds (`torch.Tensor` формы `[batch_size, config.block_size, dim]`) : Встроенные представления последнего сгенерированного якорного токена и маскированных токенов, подлежащих денойзингу.

context_hidden_states (`torch.Tensor` формы `[batch_size, number_of_previous_accepted_tokens, dim * len(config.target_layer_ids)]`) : Скрытые состояния контекста из выбранных идентификаторов слоёв целевой модели, объединённые по последнему измерению.

attention_mask (`torch.Tensor` формы `[batch_size, number_of_previous_accepted_tokens + config.block_size]`) : Аналогично обычному attention_mask, но обратите внимание, что его длина составляет `number_of_previous_accepted_tokens + config.block_size`, поскольку Attention сначала конкатенирует `context_hidden_states` и скрытые состояния, полученные из `noise_embeds`, из-за чего состояния k/v не имеют той же длины, что и q_states, даже до вызова `cache.update()`. Таким образом, размерность kv_seq_len маски внимания должна охватывать дополнительные позиции.

position_ids (`torch.Tensor` формы `[batch_size, number_of_previous_accepted_tokens + config.block_size]`) : Аналогично обычным position_ids, но обратите внимание, что его длина составляет `number_of_previous_accepted_tokens + config.block_size`, поскольку Attention сначала конкатенирует `context_hidden_states` и скрытые состояния, полученные из `noise_embeds`, из-за чего состояния k/v не имеют той же длины, что и q_states, даже до вызова `cache.update()`. Таким образом, `position_ids` и производные от них `position_embeddings` должны охватывать все дополнительные позиции.

past_key_values (`~cache_utils.DFlashCache`, *optional*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входных данных допускается только экземпляр [Cache](/docs/transformers/main/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/main/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)`, а не все `input_ids` с формой `(batch_size, sequence_length)`.

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

**Возвращает:** [BaseModelOutputWithPast](/docs/transformers/main/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) или `tuple(torch.Tensor)`

[BaseModelOutputWithPast](/docs/transformers/main/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([MuseGlimmerAssistantConfig](/docs/transformers/main/ru/model_doc/muse_glimmer_assistant#transformers.MuseGlimmerAssistantConfig)) и входных данных.

Метод forward модели [MuseGlimmerAssistantModel](/docs/transformers/main/ru/model_doc/muse_glimmer_assistant#transformers.MuseGlimmerAssistantModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.

  Если используется `past_key_values`, выводится только последнее скрытое состояние последовательностей формы `(batch_size, 1, hidden_size)`.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/main/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и, при необходимости, если `config.is_encoder_decoder=True`, в блоках кросс-внимания), которые можно использовать (см. входной параметр `past_key_values`) для ускорения последовательного декодирования.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.