# Music Flamingo

## Aperçu

Music Flamingo est un grand modèle audio-langage entièrement ouvert, conçu pour une compréhension et un raisonnement robustes sur la musique. Il s'appuie sur l'architecture [Audio Flamingo 3](./audioflamingo3) en intégrant des **Rotary Time Embeddings (RoTE)**, qui injectent des informations de position temporelle afin de permettre au modèle de traiter des séquences audio allant jusqu'à 20 minutes (1200 secondes).

Le point de contrôle du modèle est disponible à l'adresse : [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

Points forts :

- Encodeur audio unifié pour la parole, les sons et la musique.
- **Embeddings temporels rotatifs (RoTE)** pour un modélisation temporelle améliorée, permettant de prendre en charge **jusqu'à 20 minutes d'audio**.
- **Prise en charge étendue des longs audios via fenêtrage et alignement post-pooling (jusqu'à 20 minutes maximum).** Le modèle traite l'audio par fenêtres de 30 secondes avec une limite stricte de 40 fenêtres (20 minutes au total). Tout audio d'une durée supérieure à 20 minutes sera tronqué.
- Tokens de délimitation de son spéciaux (`<|sound_bos|>` et `<|sound_eos|>`) pour une modélisation améliorée des séquences audio.
- Fusion déterministe qui préserve la longueur de la séquence en remplaçant les jetons de placeholder audio par des embeddings audio.

Ce modèle a été contribué par [Lasha Koroshinadze](https://huggingface.co/lashahub) et [Eric Bezzam](https://huggingface.co/bezzam).

### Article

[Music Flamingo : Élargir la compréhension musicale dans les modèles de langage audio](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 et University of Maryland Projet : https://research.nvidia.com/labs/adlr/MF/

## Utilisation

### Mode Instruct Audio

Le modèle prend en charge les instructions audio-texte, y compris les interactions multi-tours, le tout traité par lots.

➡️ audio + instruction text

```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-tours :

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

➡️ inférence par lots !

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

➡️ Entraînement :

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

## Fonctionnement du modèle

### Architecture

* **Encodeur audio** Extracteur de caractéristiques et encodeur de type Whisper → moyenne sur l'axe temporel (pas 2) → LayerNorm. Produit des états cachés par image à la fréquence post-pooling.

* **Embeddings temporels rotatifs (RoTE)** appliqués à la sortie de l'encodeur pour injecter des informations de position temporelle, permettant au modèle de traiter des séquences audio allant jusqu'à 20 minutes (1200 secondes). RoTE utilise des embeddings rotatifs axiaux 2D pour les dimensions de lot et de temps, avec une modulation des angles basée sur le temps.

* **MusicFlamingoMultiModalProjector** Un petit MLP qui mappe les caractéristiques du codeur vers la taille cachée du modèle de langage.

* **MusicFlamingoForConditionalGeneration** Un modèle de langage causal qui accepte des embeddings de texte dans lesquels chaque emplacement de jeton de remplacement audio est remplacé, sur place, par un embedding de trame audio. Utilise des jetons de frontière spéciaux (`<|sound_bos|>` et `<|sound_eos|>`) pour marquer les séquences audio. La fusion n’entraîne aucun changement de longueur de séquence.

### Alignement au niveau du processeur

1. Chaque forme d’onde brute est découpée en fenêtres de longueur fixe en fonction de `chunk_length` (secondes) et de `sampling_rate` (Hz) de l’extracteur de caractéristiques.
2. Pour chaque fenêtre, le processeur calcule le nombre de trames post-pooling `post_pool_len` que le encodeur produira (correspondant à l'agenda conv/pool).
3. Le processeur étend le jeton de placeholder audio par le nombre total de trames post-pooling sur toutes les fenêtres.
4. Le modèle remplace ensuite ces positions de jetons par les embeddings audio projetés correspondants.

## Audio long et fenêtrage

**Important : la durée maximale de l'audio est de 20 minutes.** Tout audio plus long sera tronqué.

* La configuration par défaut traite des fenêtres de 30 secondes en mono à 16 kHz.
* **Le processeur impose une limite stricte de 40 fenêtres par échantillon, ce qui correspond à un maximum de 20 minutes d'audio (40 fenêtres × 30 secondes).**
* Les embeddings de temps rotatifs (RoTE) fournissent des informations de position pour des séquences allant jusqu'à 20 minutes (1200 secondes).
* Pour chaque fenêtre :

  * `mel_len` est la longueur mel rembourrée.
  * Une pile de convolutions réduit le temps, car `conv_output_len = (mel_len - 1) // 2 + 1`.
  * Images par fenêtre après pooling : `post_pool_len = (conv_output_len - 2) // 2 + 1`.
  * Un jeton de réserve audio est développé en la somme de `post_pool_len` sur toutes les fenêtres.

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

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

**Paramètres :**

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone audio.

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone de texte.

audio_token_id (`int`, *facultatif*, valeur par défaut `151669`) : L'index du jeton audio utilisé comme espace réservé pour l'audio en entrée.

projector_hidden_act (`str`, *facultatif*, par défaut `gelu`) : Fonction d'activation utilisée par le projecteur multimodal.

projector_bias (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut utiliser un biais dans le projecteur multimodal.

audio_bos_token_id (`int`, *facultatif*, valeur par défaut 151670) : L'index du jeton de début d'audio utilisé pour marquer le début des segments audio.

audio_eos_token_id (`int`, *facultatif*, valeur par défaut 151671) : L'index du jeton de fin d'audio utilisé pour marquer la fin des segments audio.

audio_frame_step (`float`, *facultatif*, valeur par défaut 0.01) : Durée en secondes d'une trame mel d'entrée (entraîné avec hop_length 160 et sampling_rate 16000).

rope_parameters (`dict`, *facultatif*) : Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pour `rope_theta` et, le cas échéant, les paramètres utilisés pour le mise à l'échelle si vous souhaitez utiliser RoPE avec des `max_position_embeddings` plus longs.

Ceci est la classe de configuration destinée à stocker la configuration d'un MusicFlamingoModel. Elle est utilisée pour instancier un modèle Musicflamingo en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

feature_extractor (`feature_extractor_class`) : l'extracteur de caractéristiques est une entrée obligatoire.

tokenizer (`tokenizer_class`) : Le tokenizer est une entrée obligatoire.

chat_template (`str`) : Un modèle Jinja pour convertir des listes de messages d'une conversation en une chaîne tokenisable.

audio_token (`Optional[str]`, *facultatif*, valeur par défaut `"<sound>"`) : Jeton spécial utilisé pour représenter les entrées audio dans le modèle de discussion.

audio_bos_token (`Optional[str]`, *facultatif*, valeur par défaut `"<|sound_bos|>"`) : Jeton spécial utilisé pour représenter le début de l'audio.

audio_eos_token (`Optional[str]`, *facultatif*, valeur par défaut `"<|sound_eos|>"`) : Jeton spécial utilisé pour représenter la fin de l'audio.

max_audio_len (`int`, *facultatif*, valeur par défaut : 1200) : Longueur maximale des séquences audio, en secondes. Tout audio plus long sera tronqué.

Construit un MusicFlamingoProcessor qui encapsule un extracteur de caractéristiques et un tokenizer en un seul processeur.

[MusicFlamingoProcessor](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) offre toutes les fonctionnalités de `feature_extractor_class` et de `tokenizer_class`. Consultez `~feature_extractor_class` et `~tokenizer_class` pour plus d’informations.

## MusicFlamingoModel[[transformers.MusicFlamingoModel]]

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

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

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

**Paramètres :**

config ([MusicFlamingoConfig](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle MusicFlamingo (encodeur Whisper affiné, projecteur multimodal, modèle de langage Qwen2), sans tête de modélisation du langage.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

input_features (`torch.Tensor` de forme `(batch_size, sequence_length, feature_dim)`, *facultatif*) : Les tenseurs correspondant aux caractéristiques audio d’entrée. Les caractéristiques audio peuvent être obtenues à l’aide de `feature_extractor_class`. Voir `feature_extractor_class.__call__` pour plus de détails ([MusicFlamingoProcessor](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) utilise `feature_extractor_class` pour le traitement des audios).

input_features_mask (`torch.Tensor` de forme `(batch_size, feature_sequence_length)`) : Masque pour éviter d'appliquer l'attention aux indices de remplissage.

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des positions des jetons de chaque séquence d'entrée dans les embeddings de position. Sélectionnés dans l'intervalle `[0, config.n_positions - 1]`.  [Que sont les identifiants de position ?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`.  Seule une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut.  Le modèle renverra le même format de cache que celui fourni en entrée.  Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`).

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

Un `MusicFlamingoModelOutputWithPast` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([MusicFlamingoConfig](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) et les entrées.

La méthode forward du [MusicFlamingoModel](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoModel) surcharge la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **audio_hidden_states** (`torch.Tensor`, *facultatif*) -- États cachés audio projetés.

## MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

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

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

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

**Paramètres :**

config ([MusicFlamingoConfig](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle MusicFlamingo, qui se compose d'un encodeur Whisper fine-tuné, d'un embedding temporel rotatif, d'un projecteur multi-modal et d'un modèle de langage Qwen2.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

input_features (`torch.Tensor` de forme `(batch_size, sequence_length, feature_dim)`, *facultatif*) : Les tenseurs correspondant aux caractéristiques audio d’entrée. Les caractéristiques audio peuvent être obtenues à l’aide de `feature_extractor_class`. Voir `feature_extractor_class.__call__` pour plus de détails ([MusicFlamingoProcessor](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) utilise `feature_extractor_class` pour le traitement des audios).

input_features_mask (`torch.Tensor` de forme `(batch_size, feature_sequence_length)`) : Masque pour éviter d'appliquer l'attention aux indices de remplissage.

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des positions des jetons de chaque séquence d'entrée dans les embeddings de position. Sélectionnés dans l'intervalle `[0, config.n_positions - 1]`.  [Que sont les identifiants de position ?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`.  Seule une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut.  Le modèle renverra le même format de cache que celui fourni en entrée.  Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

labels (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Étiquettes pour le calcul de la perte de modélisation de langage masqué.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *facultatif*, valeur par défaut `0`) : Si c'est un `int`, calcule les logits pour les `logits_to_keep` derniers jetons. Si c'est `0`, calcule les logits pour tous les `input_ids` (cas particulier). Seuls les logits du dernier jeton sont nécessaires pour la génération, et les calculer uniquement pour ce jeton peut faire économiser de la mémoire, ce qui devient assez significatif pour les séquences longues ou les tailles de vocabulaire importantes. Si c'est un `torch.Tensor`, il doit être 1D et correspondre aux indices à conserver dans la dimension de la longueur de la séquence. C'est utile lors de l'utilisation du format de tenseurs empilés (une seule dimension pour le lot et la longueur de la séquence).

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

Un `MusicFlamingoCausalLMOutputWithPast` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([MusicFlamingoConfig](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) et les entrées.

La méthode forward de [MusicFlamingoForConditionalGeneration](/docs/transformers/main/fr/model_doc/musicflamingo#transformers.MusicFlamingoForConditionalGeneration) surcharge la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de modélisation du langage (pour la prédiction du jeton suivant).
- **logits** (`torch.Tensor` de forme `(batch_size, sequence_length, config.vocab_size)`) -- Scores de prédiction de la tête de modélisation du langage.
- **past_key_values** (`Cache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache).
- **hidden_states** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
- **attentions** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pondérations des attentions après le softmax d'attention, utilisées pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **audio_hidden_states** (`torch.Tensor`, *facultatif*) -- États cachés de l'encodeur audio après projection.

Exemple :

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