# Music Flamingo

## Visão geral

Music Flamingo é um grande modelo de áudio–linguagem totalmente aberto, projetado para compreensão e raciocínio robustos sobre música. Ele se baseia na arquitetura do [Audio Flamingo 3](./audioflamingo3), incluindo **Rotary Time Embeddings (RoTE)**, que injeta informações de posição temporal para permitir que o modelo processe sequências de áudio de até 20 minutos (1200 segundos).

O checkpoint do modelo está disponível em: [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

Destaques:

- Codificador de áudio unificado para fala, som e música.
- **Embeddings de tempo rotativos (RoTE)** para modelagem temporal aprimorada, permitindo suporte a **até 20 minutos de áudio**.
- **Suporte estendido a áudio longo por meio de janelamento e alinhamento pós-pooling (máximo de 20 minutos).** O modelo processa o áudio em janelas de 30 segundos, com um limite rígido de 40 janelas (20 minutos no total). Áudios com mais de 20 minutos serão truncados.
- Tokens de fronteira de som especiais (`<|sound_bos|>` e `<|sound_eos|>`) para melhorar o modelamento de sequências de áudio.
- Fusão determinística que preserva o comprimento da sequência, substituindo tokens de placeholder de áudio por embeddings de áudio.

Este modelo foi contribuído por [Lasha Koroshinadze](https://huggingface.co/lashahub) e [Eric Bezzam](https://huggingface.co/bezzam).

### Artigo

[Music Flamingo: Escalando a compreensão de música em modelos de linguagem de áudio](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 e University of Maryland Projeto: https://research.nvidia.com/labs/adlr/MF/

## Uso

### Modo de Instrução de Áudio

O modelo suporta instruções de áudio e texto, incluindo interações de múltiplas rodadas, todas processadas em lotes.

➡️ áudio + instrução de texto

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

➡️ multi-turn:

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

➡️ inferência em lote!

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

➡️ Treinamento:

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

## Como o modelo funciona

### Arquitetura

* **Codificador de áudio** Extrator de recursos + codificador no estilo Whisper → pooling médio ao longo do tempo (passo 2) → LayerNorm. Gera estados ocultos por quadro na taxa pós-pooling.

* **Embeddings de tempo rotativos (RoTE)** aplicados à saída do codificador para injetar informações de posição temporal, permitindo que o modelo processe sequências de áudio de até 20 minutos (1200 segundos). O RoTE usa embeddings rotativos axiais 2D para as dimensões de lote e tempo, com modulação de ângulos baseada no tempo.

* **MusicFlamingoMultiModalProjector** Um pequeno MLP que mapeia os recursos do codificador para o tamanho oculto do modelo de linguagem.

* **MusicFlamingoForConditionalGeneration** Um modelo de linguagem causal que aceita embeddings de texto, nos quais cada slot de token placeholder de áudio é substituído, no local, por um embedding de frame de áudio. Utiliza tokens de fronteira especiais (`<|sound_bos|>` e `<|sound_eos|>`) para marcar sequências de áudio. A fusão não introduz nenhuma alteração no comprimento da sequência.

### Alinhamento no nível do processador

1. Cada forma de onda bruta é dividida em janelas de comprimento fixo com base no `chunk_length` (segundos) e na `sampling_rate` (Hz) do extrator de recursos.
2. Para cada janela, o processador calcula o número de quadros pós-pool `post_pool_len` que o codificador produzirá (correspondendo ao agendamento de conv/pool).
3. O processador expande o token de espaço reservado de áudio pelo número total de quadros pós-pooling em todas as janelas.
4. O modelo substitui, em seguida, essas posições de tokens pelos embeddings de áudio projetados correspondentes.

## Áudio longo e janelamento

**Importante: o comprimento máximo do áudio é de 20 minutos.** Áudios mais longos que isso serão truncados.

* A configuração padrão processa janelas de 30 segundos em 16 kHz mono.
* **O processador impõe um limite rígido de 40 janelas por amostra, resultando em um máximo de 20 minutos de áudio (40 janelas × 30 segundos).**
* Os Rotary Time Embeddings (RoTE) fornecem informações de posição para sequências de até 20 minutos (1200 segundos).
* Para cada janela:

  * `mel_len` é o comprimento mel preenchido.
  * Um stack de conv reduz o tempo, pois `conv_output_len = (mel_len - 1) // 2 + 1`.
  * Quadros por janela após o pooling: `post_pool_len = (conv_output_len - 2) // 2 + 1`.
  * Um token placeholder de áudio é expandido para a soma de `post_pool_len` em todas as janelas.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicflamingo/configuration_musicflamingo.py#L31)

**Parâmetros:**

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de áudio.

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de texto.

audio_token_id (`int`, *opcional*, padrão `151669`) : O índice do token de áudio usado como marcador para o áudio de entrada.

projector_hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação usada pelo projetor multimodal.

projector_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés no projetor multimodal.

audio_bos_token_id (`int`, *opcional*, padrão 151670) : O índice do token de início de áudio usado para marcar o início de trechos de áudio.

audio_eos_token_id (`int`, *opcional*, padrão 151671) : O índice do token de fim de áudio usado para marcar o fim dos intervalos de áudio.

audio_frame_step (`float`, *opcional*, padrão 0.01) : Duração em segundos de um quadro mel de entrada (treinado com hop_length 160 em sampling_rate 16000).

rope_parameters (`dict`, *opcional*) : Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para `rope_theta` e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com `max_position_embeddings` maiores.

Esta é a classe de configuração para armazenar a configuração de um MusicFlamingoModel. Ela é usada para instanciar um modelo Musicflamingo de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicflamingo/processing_musicflamingo.py#L58)

**Parâmetros:**

feature_extractor (`feature_extractor_class`) : O extrator de recursos é uma entrada obrigatória.

tokenizer (`tokenizer_class`) : O tokenizer é uma entrada obrigatória.

chat_template (`str`) : Um modelo Jinja para converter listas de mensagens em um chat em uma string tokenizável.

audio_token (`Optional[str]`, *opcional*, padrão `"<sound>"`) : Token especial usado para representar entradas de áudio no modelo de chat.

audio_bos_token (`Optional[str]`, *opcional*, padrão `"<|sound_bos|>"`) : Token especial usado para representar o início do áudio.

audio_eos_token (`Optional[str]`, *opcional*, padrão `"<|sound_eos|>"`) : Token especial usado para representar o fim do áudio.

max_audio_len (`int`, *opcional*, padrão 1200) : Comprimento máximo das sequências de áudio em segundos. Áudios mais longos que isso serão truncados.

Constrói um MusicFlamingoProcessor que encapsula um extrator de recursos e um tokenizador em um único processador.

[MusicFlamingoProcessor](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) oferece todas as funcionalidades de `feature_extractor_class` e `tokenizer_class`. Consulte `~feature_extractor_class` e `~tokenizer_class` para mais informações.

## MusicFlamingoModel[[transformers.MusicFlamingoModel]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L204)

**Parâmetros:**

config ([MusicFlamingoConfig](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo MusicFlamingo (codificador Whisper ajustado finamente, projetor multimodal, modelo de linguagem Qwen2), sem uma cabeça de modelagem de linguagem.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L277)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

input_features (`torch.Tensor` de forma `(batch_size, sequence_length, feature_dim)`, *opcional*) : Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando `feature_extractor_class`. Consulte `feature_extractor_class.__call__` para mais detalhes ([MusicFlamingoProcessor](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) usa `feature_extractor_class` para processar áudios).

input_features_mask (`torch.Tensor` de forma `(batch_size, feature_sequence_length)`) : Máscara para evitar a execução de atenção nos índices de preenchimento (padding) dos recursos.

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

**Retorna:** `MusicFlamingoModelOutputWithPast` ou `tuple(torch.Tensor)`

Um `MusicFlamingoModelOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([MusicFlamingoConfig](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) e das entradas.

O método forward do [MusicFlamingoModel](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoModel) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **audio_hidden_states** (`torch.Tensor`, *opcional*) -- Estados ocultos de áudio projetados.

## MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L402)

**Parâmetros:**

config ([MusicFlamingoConfig](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo MusicFlamingo, que consiste em um codificador Whisper ajustado finamente, incorporação de tempo rotativa, um projetor multimodal e um modelo de linguagem Qwen2.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L414)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

input_features (`torch.Tensor` de forma `(batch_size, sequence_length, feature_dim)`, *opcional*) : Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando `feature_extractor_class`. Consulte `feature_extractor_class.__call__` para mais detalhes ([MusicFlamingoProcessor](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) usa `feature_extractor_class` para processar áudios).

input_features_mask (`torch.Tensor` de forma `(batch_size, feature_sequence_length)`) : Máscara para evitar a execução de atenção nos índices de preenchimento (padding) dos recursos.

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, padrão `0`) : Se for um `int`, calcula os logits para os últimos `logits_to_keep` tokens. Se for `0`, calcula os logits para todos os `input_ids` (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um `torch.Tensor`, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

**Retorna:** `MusicFlamingoCausalLMOutputWithPast` ou `tuple(torch.Tensor)`

Um `MusicFlamingoCausalLMOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([MusicFlamingoConfig](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) e das entradas.

O método forward de [MusicFlamingoForConditionalGeneration](/docs/transformers/main/pt/model_doc/musicflamingo#transformers.MusicFlamingoForConditionalGeneration) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token).
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem.
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- É uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache).
- **hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **audio_hidden_states** (`torch.Tensor`, *opcional*) -- Estados ocultos do codificador de áudio após a projeção.

Exemplo:

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