# 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) で利用できます。

ハイライト:

- 音声、サウンド、音楽にまたがる統合オーディオエンコーダー。
- 時間モデリングを強化するための**Rotary Time Embeddings (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 and University of Maryland Project: 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()
```

## モデルの動作

### アーキテクチャ

* **Audio Encoder** Whisper 風の feature extractor + encoder → 時間方向での平均プーリング（stride 2）→ LayerNorm。プーリング後のレートでフレームごとの hidden states を生成します。

* **Rotary Time Embeddings (RoTE)**はエンコーダーの出力に適用され、時間的位置情報を注入することで、モデルが最大20分（1200秒）の音声シーケンスを処理できるようにします。RoTEは、バッチ次元と時間次元に対して2D軸方向のロータリー埋め込みを使用し、時間ベースの角度変調を行います。

* **MusicFlamingoMultiModalProjector** エンコーダーの特徴量を言語モデルの隠れ層サイズにマッピングする小さなMLPです。

* **MusicFlamingoForConditionalGeneration** は、各オーディオプレースホルダトークンスロットが、その場でオーディオフレーム埋め込みによって置き換えられるテキスト埋め込みを受け入れる因果言語モデルです。オーディオシーケンスをマークするために、特別な境界トークン（`<|sound_bos|>` および `<|sound_eos|>`）を使用します。フュージョンによってシーケンス長の変化は生じません。

### プロセッサレベルの整合性

1. 各生波形は、フィーチャーエクストラクターの`chunk_length`(秒)と`sampling_rate`(Hz)に基づいて、固定長のウィンドウに分割されます。
2. 各ウィンドウについて、プロセッサはエンコーダーが出力するプールの後のフレーム数`post_pool_len`を計算します（conv/poolのスケジュールに一致させます）。
3. プロセッサは、すべてのウィンドウにわたるプールの後のフレームの総数に応じて、音声プレースホルダートークンを展開します。
4. その後、モデルはこれらのトークン位置を、対応する投影されたオーディオ埋め込みで置き換えます。

## 長い音声とウィンドウ処理

**重要: 音声の最大長は20分です。** これを超える音声は切り捨てられます。

* デフォルトのセットアップでは、16 kHzのモノラルで30秒のウィンドウを処理します。
* **プロセッサは1サンプルあたり40ウィンドウという上限を強制するため、音声の最大長は20分（40ウィンドウ × 30秒）となります。**
* Rotary Time Embeddings (RoTE) は、最大 20 分（1200 秒）までのシーケンスに対して位置情報を提供します。
* 各ウィンドウについて:

  * `mel_len`は、パディング後のメル長です。
  * Convスタックにより、`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/main/src/transformers/models/musicflamingo/configuration_musicflamingo.py#L31)

**パラメータ:**

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : 音声バックボーンの config オブジェクトまたは辞書。

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : テキストバックボーンの config オブジェクトまたは辞書。

audio_token_id (`int`、*任意*、デフォルトは`151669`) : 入力音声のプレースホルダーとして使用されるオーディオトークンのインデックスです。

projector_hidden_act (`str`、*任意*、デフォルトは `gelu`) : マルチモーダルプロジェクターで使用する活性化関数。

projector_bias (`bool`、*任意*、デフォルトは`True`) : マルチモーダルプロジェクターでバイアスを使用するかどうか。

audio_bos_token_id (`int`, *optional*, デフォルトは 151670) : 音声スパンの開始をマークするために使用される beginning-of-audio トークンのインデックス。

audio_eos_token_id (`int`, *optional*, デフォルトは 151671) : 音声スパンの終わりを示すために使用される end-of-audio トークンのインデックス。

audio_frame_step (`float`、*optional*、デフォルト値は 0.01) : 1 つの入力 mel フレームの長さ（秒）です（hop_length 160、sampling_rate 16000 で学習されています）。

rope_parameters (`dict`, *任意*) : RoPE 埋め込みの設定パラメータを含む辞書です。この辞書には `rope_theta` の値が含まれており、より長い `max_position_embeddings` で RoPE を使用する場合にスケーリングに使用されるパラメータが任意で含まれます。

これはMusicFlamingoModelの設定を保存するための設定クラスです。指定された引数に基づいてMusicflamingoモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)と類似した設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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/main/src/transformers/models/musicflamingo/processing_musicflamingo.py#L58)

**パラメータ:**

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 を構築します。このプロセッサーは、フィーチャーエクストラクターとトークナイザーを単一のプロセッサーにラップします。

[MusicFlamingoProcessor](/docs/transformers/main/ja/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/main/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L204)

**パラメータ:**

config ([MusicFlamingoConfig](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを参照してください。

MusicFlamingoモデル（ファインチューニング済みのWhisperエンコーダー、マルチモーダルプロジェクター、Qwen2言語モデル）で、言語モデリングヘッドは含まれません。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.FloatTensor] = 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.FloatTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

input_features (`torch.FloatTensor`、shape `(batch_size, sequence_length, feature_dim)`、*optional*) : 入力音声特徴に対応するテンソルです。音声特徴は`feature_extractor_class`を使用して取得できます。詳細は`feature_extractor_class.__call__`を参照してください（[MusicFlamingoProcessor](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoProcessor)は音声の処理に`feature_extractor_class`を使用します）。

input_features_mask (`torch.Tensor`、形状 `(batch_size, feature_sequence_length)`) : パディングのフィーチャーインデックスに対するアテンションの計算を回避するためのマスク。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

position_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックスです。`[0, config.n_positions - 1]` の範囲から選択されます。 [位置 ID とは何か？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

inputs_embeds (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

**戻り値:** `MusicFlamingoModelOutputWithPast` または `tuple(torch.FloatTensor)`

`MusicFlamingoModelOutputWithPast`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[MusicFlamingoConfig](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoConfig)）や入力に応じて、さまざまな要素で構成されます。

[MusicFlamingoModel](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **audio_hidden_states** (`torch.FloatTensor`、*任意*) -- 投影されたオーディオの隠れ状態。

## MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

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

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

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

**パラメータ:**

config ([MusicFlamingoConfig](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを参照してください。

MusicFlamingoモデルは、ファインチューニングされたWhisperエンコーダー、回転位置埋め込み、マルチモーダルプロジェクター、およびQwen2言語モデルで構成されています。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.FloatTensor] = 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.FloatTensor] = 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/main/src/transformers/models/musicflamingo/modeling_musicflamingo.py#L414)

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

input_features (`torch.FloatTensor`、shape `(batch_size, sequence_length, feature_dim)`、*optional*) : 入力音声特徴に対応するテンソルです。音声特徴は`feature_extractor_class`を使用して取得できます。詳細は`feature_extractor_class.__call__`を参照してください（[MusicFlamingoProcessor](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoProcessor)は音声の処理に`feature_extractor_class`を使用します）。

input_features_mask (`torch.Tensor`、形状 `(batch_size, feature_sequence_length)`) : パディングのフィーチャーインデックスに対するアテンションの計算を回避するためのマスク。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

position_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックスです。`[0, config.n_positions - 1]` の範囲から選択されます。 [位置 ID とは何か？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

inputs_embeds (`torch.FloatTensor`、shape `(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_to_keep` トークンについて logits を計算します。`0` の場合、すべての `input_ids` について logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。`torch.Tensor` の場合、シーケンス長次元で保持するインデックスに対応する 1 次元である必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめる形式）を使用する場合に有用です。

**戻り値:** `MusicFlamingoCausalLMOutputWithPast` または `tuple(torch.FloatTensor)`

`MusicFlamingoCausalLMOutputWithPast`、または `torch.FloatTensor` のタプル（`return_dict=False` が渡された場合、または `config.return_dict=False` の場合）。構成要素は、設定（[MusicFlamingoConfig](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoConfig)）と入力に応じて異なります。

[MusicFlamingoForConditionalGeneration](/docs/transformers/main/ja/model_doc/musicflamingo#transformers.MusicFlamingoForConditionalGeneration)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **loss** (`torch.FloatTensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 言語モデリングの損失(次のトークンの予測用)。
- **logits** (`torch.FloatTensor`、形状 `(batch_size, sequence_length, config.vocab_size)`) -- 言語モデリングヘッドの予測スコア。
- **past_key_values** (`Cache`、*任意*、`use_cache=True` が渡された場合または `config.use_cache=True` の場合に返されます) -- [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) のインスタンスです。
- **hidden_states** (`tuple[torch.FloatTensor]`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.FloatTensor` のタプル（モデルに埋め込み層がある場合はその出力用 + 各層の出力用）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple[torch.FloatTensor]`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **audio_hidden_states** (`torch.FloatTensor`、*任意*) -- 投影後のオーディオエンコーダーの隠れ状態。

例:

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