# Music Flamingo

## Обзор

Music Flamingo — это полностью открытая крупная аудиоязыковая модель, предназначенная для надёжного понимания и рассуждений о музыке. Она основана на архитектуре [Audio Flamingo 3](./audioflamingo3) и включает **Rotary Time Embeddings (RoTE)**, которые добавляют информацию о временном положении, позволяя модели обрабатывать аудиопоследовательности длительностью до 20 минут (1200 секунд).

Чекпоинт модели доступен по адресу: [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

Ключевые моменты:

- Единый аудио-энкодер для речи, звуков и музыки.
- **Вращательные временные эмбеддинги (RoTE)** для улучшенного моделирования временных зависимостей, что позволяет обрабатывать **аудио длительностью до 20 минут**.
- **Расширенная поддержка длинных аудио за счёт оконной обработки и выравнивания после пулинга (максимум 20 минут).** Модель обрабатывает аудио в окнах по 30 секунд с жёстким ограничением в 40 окон (20 минут суммарно). Аудио длительностью более 20 минут будет обрезано.
- Специальные токены границ звука (`<|sound_bos|>` и `<|sound_eos|>`) для улучшения моделирования аудиопоследовательностей.
- Детерминированное слияние, сохраняющее длину последовательности путём замены плейсхолдер-токенов аудио на аудио-эмбеддинги.

Эта модель была предоставлена [Lasha Koroshinadze](https://huggingface.co/lashahub) и [Eric Bezzam](https://huggingface.co/bezzam).

### Статья

[Music Flamingo: масштабирование понимания музыки в аудиоязыковых моделях](https://huggingface.co/papers/2511.10289) S. Ghosh, A. Goel, L. Koroshinadze, S. Lee, Z. Kong, J. F. Santos, R. Duraiswami, D. Manocha, W. Ping, M. Shoeybi, B. Catanzaro NVIDIA и Университет Мэриленда Проект: https://research.nvidia.com/labs/adlr/MF/

## Использование

### Режим Audio Instruct

Модель поддерживает аудио-текстовые инструкции, включая многоходовые взаимодействия, все они обрабатываются пачками.

➡️ аудио + текстовая инструкция

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this track in full detail - tell me the genre, tempo, and key, then dive into the instruments, production style, and overall mood it creates."},
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3"},
        ],
    }
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
```

➡️ многоходовой:

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Write a rich caption that blends the technical details (genre, BPM, key, chords, mix) with how the song feels emotionally and dynamically as it unfolds.",
            },
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3"},
        ],
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "This energetic Eurodance anthem at 150 BPM in E major combines bright synth arpeggios with a punchy four-on-the-floor beat..."}],
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What instruments stand out the most?"},
        ],
    },
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
```

➡️ пакетный вывод!

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversations = [
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this track in full detail - tell me the genre, tempo, and key, then dive into the instruments, production style, and overall mood it creates."},
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3",
                },
            ],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Generate a structured lyric sheet from the input music.",
                },
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_2.mp3"},
            ],
        }
    ],
]

inputs = processor.apply_chat_template(
    conversations,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
```

➡️ Обучение:

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")
model.train()

conversation = [
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Break the track down like a critic - list its tempo, key, and chordal motion, then explain the textures, dynamics, and emotional impact of the performance."},
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3"},
            ],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "This Eurodance track operates at 150 BPM in E major, with harmonic movement centering on the I-vi-IV-V family. The production features layered synth arpeggios, a four-on-the-floor kick pattern, and a mezzo-soprano lead vocal with bright timbre. Dynamically, the track builds through verses into an anthemic chorus with full synth orchestration and backing vocals, creating an uplifting, euphoric atmosphere characteristic of late 2000s dance-pop."}],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe this song from both a technical and artistic lens: mention tempo, harmony, and instrumentation, but also mood, lyrical themes, and structure.",
                },
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_2.mp3"},
            ],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "This electronic pop track combines upbeat production with playful lyrical themes centered around late-night pizza cravings. The structure follows a verse-chorus format with recurring melodic motifs and rhythmic patterns that emphasize the celebratory, lighthearted mood of the piece."}],
        }

    ]
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    processor_kwargs={"output_labels": True},
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

loss = model(**inputs).loss
loss.backward()
```

## Как работает модель

### Архитектура

* **Аудио-энкодер** Извлекатель признаков и энкодер в стиле Whisper → усреднение по времени (шаг 2) → LayerNorm. Формирует скрытые состояния для каждого кадра на частоте после пулинга.

* **Rotary Time Embeddings (RoTE)** применяются к выходу кодировщика для внедрения информации о временном положении, что позволяет модели обрабатывать аудиопоследовательности длительностью до 20 минут (1200 секунд). RoTE использует 2D-осевые ротационные эмбеддинги для размерностей батча и времени с модуляцией углов на основе времени.

* **MusicFlamingoMultiModalProjector** Небольшая MLP, отображающая признаки энкодера в размер скрытого слоя языковой модели.

* **MusicFlamingoForConditionalGeneration** — каузальная языковая модель, принимающая текстовые эмбеддинги, в которых каждый слот-заполнитель аудио заменяется на месте эмбеддингом кадра аудио. Для разметки аудиопоследовательностей используются специальные граничные токены (`<|sound_bos|>` и `<|sound_eos|>`). Фьюжн не приводит к изменению длины последовательности.

### Выравнивание на уровне процессора

1. Каждая исходная волновая форма разбивается на окна фиксированной длины на основе параметров `chunk_length` (в секундах) и `sampling_rate` (Гц) экстрактора признаков.
2. Для каждого окна процессор вычисляет количество кадров после пулинга `post_pool_len`, которые будет выдать энкодер (в соответствии с расписанием свёрток/пулинга).
3. Процессор расширяет аудио-заполнитель на общее количество кадров после пулинга по всем окнам.
4. Затем модель заменяет позиции этих токенов на соответствующие проекции аудио-эмбеддингов.

## Длинные аудио и оконная обработка

**Важно: максимальная длительность аудио — 20 минут.** Более длинные аудио будут обрезаны.

* По умолчанию обработка выполняется для 30-секундных окон с частотой дискретизации 16 кГц в моно-канале.
* **Процессор устанавливает жёсткий лимит в 40 окон на образец, что соответствует максимум 20 минутам аудио (40 окон × 30 секунд).**
* Вращательные временные эмбеддинги (RoTE) предоставляют информацию о позиции для последовательностей длительностью до 20 минут (1200 секунд).
* Для каждого окна:

  * `mel_len` — это дополненная длина мел-спектрограммы.
  * Стек свёрток сокращает время, так как `conv_output_len = (mel_len - 1) // 2 + 1`.
  * Кадров после пулинга на окно: `post_pool_len = (conv_output_len - 2) // 2 + 1`.
  * Токен-заполнитель для аудио раскрывается в сумму `post_pool_len` по всем окнам.

## MusicFlamingoConfig[[transformers.MusicFlamingoConfig]]

#### transformers.MusicFlamingoConfig[[transformers.MusicFlamingoConfig]]

```python
transformers.MusicFlamingoConfig(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, audio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_token_id: int = 151669, projector_hidden_act: str = 'gelu', projector_bias: bool = True, audio_bos_token_id: int = 151670, audio_eos_token_id: int = 151671, audio_frame_step: float = 0.01, rope_parameters: dict | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicflamingo/configuration_musicflamingo.py#L31)

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

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь аудио-бэкбона.

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь текстового бэкбона.

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

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

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

audio_bos_token_id (`int`, *optional*, по умолчанию 151670) : Индекс токена начала аудио, используемый для обозначения начала аудиосегментов.

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

audio_frame_step (`float`, *optional*, по умолчанию 0.01) : Длительность одного входного мел-кадра в секундах (обучен с hop_length 160 при sampling_rate 16000).

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

Это класс конфигурации для хранения настроек модели MusicFlamingoModel. Он используется для создания модели Musicflamingo в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

```python
>>> from transformers import MusicFlamingoForConditionalGeneration, MusicFlamingoConfig, AudioFlamingo3EncoderConfig, Qwen2Config

>>> # Initializing an MusicFlamingoEncoder config
>>> audio_config = AudioFlamingo3EncoderConfig()

>>> # Initializing a Qwen2 config
>>> text_config = Qwen2Config()

>>> # Initializing an MusicFlamingo configuration
>>> configuration = MusicFlamingoConfig(audio_config, text_config)

>>> # Initializing a model from the musicflamingo style configuration
>>> model = MusicFlamingoForConditionalGeneration(configuration)

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

## MusicFlamingoProcessor[[transformers.MusicFlamingoProcessor]]

#### transformers.MusicFlamingoProcessor[[transformers.MusicFlamingoProcessor]]

```python
transformers.MusicFlamingoProcessor(feature_extractor, tokenizer, chat_template = None, audio_token = '<sound>', audio_bos_token = '<|sound_bos|>', audio_eos_token = '<|sound_eos|>', max_audio_len = 1200)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicflamingo/processing_musicflamingo.py#L42)

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

feature_extractor (`feature_extractor_class`) : Извлечение признаков является обязательным входом.

tokenizer (`tokenizer_class`) : Токенизатор является обязательным входным параметром.

chat_template (`str`) : Шаблон Jinja для преобразования списков сообщений в чате в строку, готовую к токенизации.

audio_token (`Optional[str]`, *необязательный*, по умолчанию `"<sound>"`) : Специальный токен, используемый для представления аудиовходов в шаблоне чата.

audio_bos_token (`Optional[str]`, *необязательный*, по умолчанию `"<|sound_bos|>"`) : Специальный токен, используемый для обозначения начала аудио.

audio_eos_token (`Optional[str]`, *необязательный*, по умолчанию `"<|sound_eos|>"`) : Специальный токен, используемый для обозначения конца аудиоданных.

max_audio_len (`int`, *optional*, по умолчанию 1200) : Максимальная длина аудиопоследовательностей в секундах. Аудио, превышающее эту длину, будет обрезано.

Создаёт MusicFlamingoProcessor, который объединяет feature extractor и tokenizer в единый processor.

[MusicFlamingoProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) предоставляет все возможности `feature_extractor_class` и `tokenizer_class`. Подробнее см. в `~feature_extractor_class` и `~tokenizer_class`.

## MusicFlamingoModel[[transformers.MusicFlamingoModel]]

#### transformers.MusicFlamingoModel[[transformers.MusicFlamingoModel]]

```python
transformers.MusicFlamingoModel(config: MusicFlamingoConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L204)

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

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

Модель MusicFlamingo (дообученный энкодер Whisper, мультимодальный проектор, языковая модель Qwen2), без головы для моделирования языка.

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

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

#### forward[[transformers.MusicFlamingoModel.forward]]

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L277)

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

input_features (`torch.Tensor` формы `(batch_size, sequence_length, feature_dim)`, *необязательно*) : Тензоры, соответствующие входным аудиособытиям. Аудиособытия можно получить с помощью `feature_extractor_class`. Подробности см. в `feature_extractor_class.__call__` ([MusicFlamingoProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) использует `feature_extractor_class` для обработки аудио).

input_features_mask (`torch.Tensor` формы `(batch_size, feature_sequence_length)`) : Маска для предотвращения применения внимания к индексам заполняющих признаков.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

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

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

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

**Возвращает:** `MusicFlamingoModelOutputWithPast` или `tuple(torch.Tensor)`

Объект `MusicFlamingoModelOutputWithPast` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([MusicFlamingoConfig](/docs/transformers/v5.23.0/ru/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) и входных данных.

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

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

- **audio_hidden_states** (`torch.Tensor`, *необязательный*) -- Спроецированные скрытые состояния аудио.

## MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

#### transformers.MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

```python
transformers.MusicFlamingoForConditionalGeneration(config: MusicFlamingoConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L402)

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

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

Модель MusicFlamingo, состоящая из дообученного кодировщика Whisper, вращательного временного эмбеддинга, мультимодального проектора и языковой модели Qwen2.

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

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

#### forward[[transformers.MusicFlamingoForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L414)

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

input_features (`torch.Tensor` формы `(batch_size, sequence_length, feature_dim)`, *необязательно*) : Тензоры, соответствующие входным аудиособытиям. Аудиособытия можно получить с помощью `feature_extractor_class`. Подробности см. в `feature_extractor_class.__call__` ([MusicFlamingoProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) использует `feature_extractor_class` для обработки аудио).

input_features_mask (`torch.Tensor` формы `(batch_size, feature_sequence_length)`) : Маска для предотвращения применения внимания к индексам заполняющих признаков.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

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

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

labels (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Метки для вычисления потерь маскированного языкового моделирования.

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

logits_to_keep (`Union[int, torch.Tensor]`, *необязательный*, по умолчанию `0`) : Если передано значение типа `int`, вычисляются logits для последних `logits_to_keep` токенов. Если передано `0`, logits вычисляются для всех `input_ids` (специальный случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа `torch.Tensor`, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (одно измерение для batch и длины последовательности).

**Возвращает:** `MusicFlamingoCausalLMOutputWithPast` или `tuple(torch.Tensor)`

Объект `MusicFlamingoCausalLMOutputWithPast` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([MusicFlamingoConfig](/docs/transformers/v5.23.0/ru/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) и входных данных.

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache).
- **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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **audio_hidden_states** (`torch.Tensor`, *необязательный*) -- Скрытые состояния аудио-кодера после проекции.

Пример:

```python
>>> from transformers import MusicFlamingoForConditionalGeneration, AutoProcessor

>>> model_id = "nvidia/audio-flamingo-3-hf"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")
```

