# Audio Flamingo 3

## 概要

Audio Flamingo 3 (AF3) は、音声、環境音、音楽に対する堅牢な理解と推論のために設計された、完全にオープンな大規模オーディオ言語モデルです。AF3 は Whisper 風のオーディオエンコーダーと因果言語モデルを組み合わせ、インプレース置換によるオーディオとテキストの融合を実行します。プロセッサはプーリング後のオーディオフレームを専用のプレースホルダトークンにアラインし、モデルはフォワードパス中にこれらのトークンスロットを射影されたオーディオ埋め込みで置き換えます。

モデルのチェックポイントは、[nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf) で利用できます。

ハイライト:

- 音声、サウンド、音楽にまたがる統合オーディオエンコーダー。
- **ウィンドウ処理とプーリング後のアラインメントによる長時間音声のサポート（最大10分）。** モデルは30秒のウィンドウで音声を処理し、ウィンドウ数は最大20個（合計10分）に制限されています。10分を超える音声は切り捨てられます。
- 音声プレースホルダトークンを音声埋め込みで置き換えることでシーケンス長を維持する、決定論的な融合。

このモデルは、[Lasha Koroshinadze](https://huggingface.co/lashahub)氏と[Eric Bezzam](https://huggingface.co/bezzam)氏によって提供されました。

### 論文

[Audio Flamingo 3](https://huggingface.co/papers/2507.08128): 完全オープンな大規模オーディオ言語モデルによるオーディオインテリジェンスの推進 A. Goel, S. Ghosh, J. Kim, S. Kumar, Z. Kong, S. Lee, C.-H. H. Yang, R. Duraiswami, D. Manocha, R. Valle, B. Catanzaro NVIDIA and University of Maryland Project: https://research.nvidia.com/labs/adlr/AF3/

## 使用方法

### Audio Instruct モード

モデルは、マルチターン対話を含む音声テキスト指示をサポートし、すべてバッチ処理で処理されます。

➡️ 音声 + テキスト指示

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe the input speech."},
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/WhDJDIviAOg_120_10.mp3"},
        ],
    }
]

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

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

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

➡️ マルチターン:

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Instruction: How does the tone of female speech change throughout the audio? Choose the correct option among the options below: (A) Sad to happy (B) Happy to sad (C) Neutral to happy (D) Happy to neutral.",
            },
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/000000786159.31.wav"},
        ],
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "(A) Sad to happy"}],
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Why do you think so?"},
        ],
    },
]

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

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

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

➡️ テキストのみ:

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the capital of France?"},
        ],
    }
]

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

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

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

➡️ オーディオのみ:

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/WhDJDIviAOg_120_10.mp3"},
        ],
    }
]

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

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

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

➡️ バッチ推論!

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

conversations = [
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Transcribe the input speech."},
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/t_837b89f2-26aa-4ee2-bdf6-f73f0dd59b26.wav",
                },
            ],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This track feels really peaceful and introspective. What elements make it feel so calming and meditative?",
                },
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/FPSbCAANfbJLVSwD.mp3"},
            ],
        }
    ],
]

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

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

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

➡️ 学習:

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

conversation = [
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Transcribe the input speech."},
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/WhDJDIviAOg_120_10.mp3"},
            ],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "The transcription of the audio is 'summer follows spring the days grow longer and the nights are warm'."}],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This track feels really peaceful and introspective. What elements make it feel so calming and meditative?",
                },
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/FPSbCAANfbJLVSwD.mp3"},
            ],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "The transcription of the audio is 'some transcription of the audio'."}],
        }

    ]
]

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

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

➡️ 文字起こしのショートカット

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

inputs = processor.apply_transcription_request(audio="https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/t_837b89f2-26aa-4ee2-bdf6-f73f0dd59b26.wav").to(model.device, dtype=model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True, strip_prefix=True)

print(decoded_outputs)
```

モデルは、`The spoken content of the audio is "<text>".` のようなアシスタントのフレーミングで接頭された文字起こしを出力するように学習されています。上記のように `strip_prefix=True` を使用すると、固定のアシスタント文と周囲の引用符が除去され、文字起こしのみが残ります。

## モデルの動作

### アーキテクチャ

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

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

* **AudioFlamingo3ForConditionalGeneration** は、各オーディオプレースホルダトークンスロットが、その場でオーディオフレーム埋め込みによって置き換えられたテキスト埋め込みを受け入れる因果言語モデルです。融合によってシーケンス長の变化は生じません。

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

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

## 使用パターン

### 文字起こしのショートカット

自動音声認識では、毎回デフォルトの指示を書く必要はなく、`apply_transcription_request()`を呼び出すことができます。

```python
inputs = processor.apply_transcription_request(audio=audio_array)
```

音声プレースホルダーの処理を維持したまま指示をカスタマイズするには、`prompt="Transcribe the input speech."`（バッチ音声の場合はプロンプトのリスト）を渡します。

`audio` は、メモリ内配列、ローカルファイルパス、または URL を受け取ります。プロセッサのキーワード引数（`text_kwargs`、`audio_kwargs` など）はすべて転送されるため、`processor(...)` を呼び出す場合と同様に、パディングやテンソル形式を調整できます。

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

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

* デフォルトのセットアップでは、16 kHzのモノラルで30秒のウィンドウを処理します。
* **プロセッサは1サンプルあたり20ウィンドウという上限を強制するため、音声の最大長は10分（20ウィンドウ × 30秒）となります。**
* 各ウィンドウについて:

  * `mel_len`は、パディング後のメル長です。
  * Convスタックにより、`conv_output_len = (mel_len - 1) // 2 + 1` となるため、時間が短縮されます。
  * ウィンドウあたりのプーリング後フレーム数: `post_pool_len = (conv_output_len - 2) // 2 + 1`。
  * 音声プレースホルダトークンは、すべてのウィンドウの`post_pool_len`の合計に展開されます。

## パディング、アテンション、およびキャッシュ

* **左パディングと右パディング** バッチ内でプロンプトの長さが混在する生成タスクでは、通常、左パディングが望ましいとされています。一方、学習では右パディングが一般的です。AF3のフュージョン機構自体はパディングに依存しないため、インプレースで置換を行います。
* **アテンションマスク** プロセッサーは `attention_mask`（テキスト）と `input_features_mask`（オーディオ）を返します。モデルは、エンコーダーのプールの前の軸で、パッド位置を負の無限大とする内部の4次元マスクを構築します。
* **キャッシュ** 生成中、`input_features` と `input_features_mask` は最初のステップでのみ渡されます。以降のステップでは、言語モデルからキャッシュされたキー/バリューが使用されます。

## トラブルシューティング

* バッチ処理時に出力が空になる、または途中で切れてしまう場合 プロンプト長より後の新しいトークンのみをデコードするように、クイックスタートに示されているように、バッチ生成には左パディングを使用してください。

## AudioFlamingo3Config[[transformers.AudioFlamingo3Config]]

#### transformers.AudioFlamingo3Config[[transformers.AudioFlamingo3Config]]

```python
transformers.AudioFlamingo3Config(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)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/configuration_audioflamingo3.py#L73)

**パラメータ:**

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`) : マルチモーダルプロジェクターでバイアスを使用するかどうか。

これは、[nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf) と同様の設定をデフォルト値で生成する、AudioFlamingo3Model の設定を保存するための設定クラスです。指定された引数に基づいて Audioflamingo3 モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import AudioFlamingo3ForConditionalGeneration, AudioFlamingo3Config, AudioFlamingo3EncoderConfig, Qwen2Config

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

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

>>> # Initializing an AudioFlamingo3 configuration
>>> configuration = AudioFlamingo3Config(audio_config, text_config)

>>> # Initializing a model from the audioflamingo3 style configuration
>>> model = AudioFlamingo3ForConditionalGeneration(configuration)

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

## AudioFlamingo3EncoderConfig[[transformers.AudioFlamingo3EncoderConfig]]

#### transformers.AudioFlamingo3EncoderConfig[[transformers.AudioFlamingo3EncoderConfig]]

```python
transformers.AudioFlamingo3EncoderConfig(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, num_mel_bins: int = 128, num_hidden_layers: int = 32, num_attention_heads: int = 20, intermediate_size: int = 5120, layerdrop: float | int = 0.0, activation_function: str = 'gelu', hidden_size: int = 1280, dropout: float | int = 0.0, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, initializer_range: float = 0.02, scale_embedding: bool = False, max_source_positions: int = 1500)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/configuration_audioflamingo3.py#L26)

**パラメータ:**

num_mel_bins (`int`、*任意*、デフォルトは`128`) : 入力フレームごとに使用されるメル特徴の数を指定します。`AutoFeatureExtractor`クラスで使用される値と一致させる必要があります。

num_hidden_layers (`int`、*任意*、デフォルトは`32`) : Transformerデコーダーの隠れ層の数。

num_attention_heads (`int`、*任意*、デフォルトは`20`) : Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。

intermediate_size (`int`、*任意*、デフォルトは `5120`) : MLP 表現の次元数。

layerdrop (`Union[float, int]`、*任意*、デフォルトは `0.0`) : LayerDrop の確率です。詳細については、[LayerDrop の論文](see https://huggingface.co/papers/1909.11556)を参照してください。

activation_function (`str`、*任意*、デフォルトは`gelu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

hidden_size (`int`、*任意*、デフォルトは`1280`) : 隠れ表現の次元数。

dropout (`Union[float, int]`、*任意*、デフォルトは`0.0`) : すべての dropout レイヤーの比率。

attention_dropout (`Union[float, int]`、*任意*、デフォルトは`0.0`) : 注意確率のドロップアウト率。

activation_dropout (`Union[float, int]`、*任意*、デフォルトは`0.0`) : 全結合層内の活性化に対する dropout 率。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

scale_embedding (`bool`、*任意*、デフォルトは`False`) : sqrt(d_model) で割って埋め込みをスケーリングするかどうか。

max_source_positions (`int`、*任意*、デフォルトは 1500) : このモデルが使用される可能性がある log-mel フィルターバンク特徴量の最大シーケンス長です。

これは、[nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf) と同様の設定をデフォルト値で生成する、AudioFlamingo3Model の設定を保存するための設定クラスです。指定された引数に基づいて Audioflamingo3 モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import AudioFlamingo3EncoderConfig, AudioFlamingo3Encoder

>>> # Initializing an AudioFlamingo3EncoderConfig
>>> configuration = AudioFlamingo3EncoderConfig()

>>> # Initializing an AudioFlamingo3Encoder (with random weights)
>>> model = AudioFlamingo3Encoder(configuration)

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

## AudioFlamingo3Processor[[transformers.AudioFlamingo3Processor]]

#### transformers.AudioFlamingo3Processor[[transformers.AudioFlamingo3Processor]]

```python
transformers.AudioFlamingo3Processor(feature_extractor, tokenizer, chat_template = None, audio_token = '<sound>', default_transcription_prompt = 'Transcribe the input speech.', max_audio_len = 600)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/processing_audioflamingo3.py#L53)

**パラメータ:**

feature_extractor (`WhisperFeatureExtractor`) : 特徴量抽出器は必須の入力です。

tokenizer (`Qwen2Tokenizer`) : トークナイザーは必須の入力です。

chat_template (`str`) : チャット内のメッセージのリストをトークン化可能な文字列に変換するための Jinja テンプレート。

audio_token (`Optional[str]`、*任意*、デフォルトは `"<sound>"`) : チャットテンプレート内で音声入力を表すために使用される特殊トークン。

default_transcription_prompt (`str`、*任意*、デフォルトは `"Transcribe the input speech."`) : 転写リクエストを適用する際に、転写タスクで使用するデフォルトのプロンプト。

max_audio_len (`int`、*optional*、デフォルトは 600) : 音声シーケンスの最大長（秒）。これを超える音声は切り捨てられます。

AudioFlamingo3Processor を構築します。このクラスは、フィーチャーエクストラクターとトークナイザーを単一のプロセッサーにラップします。

[AudioFlamingo3Processor](/docs/transformers/main/ja/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) は、[WhisperFeatureExtractor](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor) と [Qwen2Tokenizer](/docs/transformers/main/ja/model_doc/qwen2#transformers.Qwen2Tokenizer) のすべての機能を提供します。詳細については、[~WhisperFeatureExtractor](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor) および [~Qwen2Tokenizer](/docs/transformers/main/ja/model_doc/qwen2#transformers.Qwen2Tokenizer) を参照してください。

#### __call__[[transformers.AudioFlamingo3Processor.__call__]]

```python
__call__(text: str | list[str], audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, output_labels: bool | None = False, **kwargs: *<class 'transformers.models.audioflamingo3.processing_audioflamingo3.AudioFlamingo3ProcessorKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/processing_audioflamingo3.py#L79)

**パラメータ:**

text (`Union[str, list[str]]`) : エンコード対象のシーケンス、またはシーケンスのバッチです。各シーケンスは文字列、または文字列のリスト（プレトークナイズ済み文字列）であることができます。プレトークナイズ済み入力を渡す場合は、バッチ入力との曖昧さを避けるために`is_split_into_words=True`を設定してください。

audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`, *任意*) : 準備対象のオーディオまたはオーディオのバッチです。各オーディオは NumPy 配列または PyTorch テンソルであることができます。NumPy 配列/PyTorch テンソルの場合、各オーディオの形状は (C, T) である必要があります。ここで C はチャネル数、T はオーディオのサンプル長を表します。

output_labels (`bool`、*任意*、デフォルト: False) : 学習用のラベルを返すかどうか。

return_tensors (`str` または [TensorType](/docs/transformers/main/ja/internal/file_utils#transformers.TensorType)、*optional*) : 設定されている場合、特定のフレームワークのテンソルを返します。受け入れ可能な値は以下の通りです:  - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: NumPy の `np.ndarray` オブジェクトを返します。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ja/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 各モダリティ（テキスト、画像、動画、音声）の追加処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDict クラスを参照してください。

**戻り値:** [BatchFeature](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.BatchFeature)

トークン化されたテキスト(`input_ids`、`attention_mask`)と音声特徴(`input_features`、`input_features_mask`)を含む辞書。

## AudioFlamingo3Encoder[[transformers.AudioFlamingo3Encoder]]

#### transformers.AudioFlamingo3Encoder[[transformers.AudioFlamingo3Encoder]]

```python
transformers.AudioFlamingo3Encoder(config: AudioFlamingo3EncoderConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L303)

**パラメータ:**

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

AudioFlamingo3の音声モデルで、上部にヘッドや投影が一切付いていないものです。

このモデルは [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.AudioFlamingo3Encoder.forward]]

```python
forward(input_features: Tensor, input_features_mask: typing.Optional[torch.Tensor] = None, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L350)

**パラメータ:**

input_features (`torch.FloatTensor`、shape `(batch_size, feature_size, sequence_length)`) : 生オーディオから抽出されたLog-Mel特徴量。プロセッサ/特徴量抽出器を使用して、波形入力からこれらの特徴量を計算し、パディングしてください。

input_features_mask (`torch.FloatTensor`、形状 `(batch_size, sequence_length)`、*任意*) : パディングのインデックスに対するアテンションの計算を回避するためのマスク。マスクの値は `[0, 1]` から選択します:  - **マスクされない**トークンは 1、**マスクされる**トークンは 0。

## AudioFlamingo3Model[[transformers.AudioFlamingo3Model]]

#### transformers.AudioFlamingo3Model[[transformers.AudioFlamingo3Model]]

```python
transformers.AudioFlamingo3Model(config: AudioFlamingo3Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L444)

**パラメータ:**

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

AudioFlamingo3モデル（ファインチューニング済みの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.AudioFlamingo3Model.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/audioflamingo3/modeling_audioflamingo3.py#L510)

**パラメータ:**

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)`、*任意*) : 入力音声特徴に対応するテンソルです。音声特徴は [WhisperFeatureExtractor](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor) を使用して取得できます。詳細は [WhisperFeatureExtractor.__call__()](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__) を参照してください（[AudioFlamingo3Processor](/docs/transformers/main/ja/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) は音声の処理に [WhisperFeatureExtractor](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor) を使用します）。

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`を参照）。

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

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

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

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

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

## AudioFlamingo3ForConditionalGeneration[[transformers.AudioFlamingo3ForConditionalGeneration]]

#### transformers.AudioFlamingo3ForConditionalGeneration[[transformers.AudioFlamingo3ForConditionalGeneration]]

```python
transformers.AudioFlamingo3ForConditionalGeneration(config: AudioFlamingo3Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L566)

**パラメータ:**

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

AudioFlamingo3モデルは、ファインチューニングされた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.AudioFlamingo3ForConditionalGeneration.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/audioflamingo3/modeling_audioflamingo3.py#L578)

**パラメータ:**

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)`、*任意*) : 入力音声特徴に対応するテンソルです。音声特徴は [WhisperFeatureExtractor](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor) を使用して取得できます。詳細は [WhisperFeatureExtractor.__call__()](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__) を参照してください（[AudioFlamingo3Processor](/docs/transformers/main/ja/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) は音声の処理に [WhisperFeatureExtractor](/docs/transformers/main/ja/model_doc/whisper#transformers.WhisperFeatureExtractor) を使用します）。

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 次元である必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめる形式）を使用する場合に有用です。

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

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

[AudioFlamingo3ForConditionalGeneration](/docs/transformers/main/ja/model_doc/audioflamingo3#transformers.AudioFlamingo3ForConditionalGeneration) の 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 AudioFlamingo3ForConditionalGeneration, AutoProcessor

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

#### get_audio_features[[transformers.AudioFlamingo3ForConditionalGeneration.get_audio_features]]

```python
get_audio_features(input_features, input_features_mask, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L575)