# Audio Flamingo 3

## 概述

Audio Flamingo 3 (AF3) 是一个完全开放的大型音频-语言模型，旨在对语音、环境声音和音乐进行稳健的理解与推理。AF3 将 Whisper 风格的音频编码器与因果语言模型相结合，并执行原位替换的音频-文本融合：处理器将池化后的音频帧与专用占位符 token 对齐，模型在前向传播过程中用投影后的音频嵌入替换这些 token 槽位。

模型检查点可在以下位置获取：[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 和马里兰大学 项目：https://research.nvidia.com/labs/adlr/AF3/

## 用法

### 音频指令模式

该模型支持音频-文本指令，包括多轮交互，且均以批量方式处理。

➡️ 音频 + 文本指令

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

➡️ 训练：

将目标转录文本通过 `transcription` 传递给 `apply_transcription_request`。它们会被写入助手轮次，并返回 `labels` 用于计算损失。

```python
from datasets import Audio, load_dataset
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

model_id = "nvidia/audio-flamingo-3-hf"
NUM_SAMPLES = 2

processor = AutoProcessor.from_pretrained(model_id)
model = AudioFlamingo3ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
model.train()

ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))
speech_samples = [el["array"] for el in ds["audio"][:NUM_SAMPLES]]
text_samples = ds["text"][:NUM_SAMPLES]

inputs = processor.apply_transcription_request(speech_samples, transcription=text_samples)
inputs.to(model.device, dtype=model.dtype)

loss = model(**inputs).loss
print("Loss:", loss.item())
loss.backward()
```

对于其他任务，请将目标放在助手轮次中，并传入 `processor_kwargs={"output_labels": True}`。

```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": "How does the tone of female speech change throughout the audio?"},
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/000000786159.31.wav"},
        ],
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "It goes from sad to happy."}],
    },
]

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
print("Loss:", loss.item())
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 风格的特征提取器 + 编码器 → 沿时间维度进行平均池化（步长为 2）→ LayerNorm。输出池化后速率下的逐帧隐藏状态。

* **AudioFlamingo3MultiModalProjector** 一个小型 MLP，用于将编码器特征映射到语言模型的隐藏维度。

* **AudioFlamingo3ForConditionalGeneration** 一种因果语言模型，它接受文本嵌入，其中每个音频占位符 token 槽位会被就地替换为音频帧嵌入。融合过程不会引入序列长度的变化。

### 处理器级对齐

1. 每个原始波形会根据特征提取器的 `chunk_length`（秒）和 `sampling_rate`（Hz）被分割为固定长度的窗口。
2. 对于每个窗口，处理器会计算编码器将输出的池化后帧数 `post_pool_len`（与卷积/池化计划相匹配）。
3. 处理器会根据所有窗口中池化后帧的总数来扩展音频占位符标记。
4. 模型随后会用对应的投影音频嵌入替换这些 token 位置。

## 使用模式

### 转录快捷方式

对于自动语音识别，您可以跳过每次编写默认指令，直接调用 `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 秒的窗口。
* **处理器对每个样本强制执行 20 个窗口的硬性限制，因此最多可处理 10 分钟的音频（20 个窗口 × 30 秒）。**
* 对于每个窗口：

  * `mel_len` 是填充后的 mel 长度。
  * 卷积堆栈会缩短时间，因为 `conv_output_len = (mel_len - 1) // 2 + 1`。
  * 每个窗口的池化后帧数：`post_pool_len = (conv_output_len - 2) // 2 + 1`。
  * 音频占位符 token 会被扩展为所有窗口中 `post_pool_len` 的总和。

## 填充、注意力机制与缓存

* **左侧填充与右侧填充** 对于批次中提示长度不一的生成任务，通常更推荐左侧填充。对于训练任务，右侧填充更为常见；AF3 的融合机制本身与填充方式无关，因为它是在原位置进行替换的。
* **注意力掩码** 处理器会返回 `attention_mask`（文本）和 `input_features_mask`（音频）。模型会在编码器的池化前轴上构建一个内部的 4 维掩码，其中填充位置的值设为负无穷。
* **缓存** 在生成过程中，`input_features` 和 `input_features_mask` 仅在第一步时传入。后续步骤会使用语言模型中缓存的键/值。

## 故障排除

* 在批量处理时出现空输出或截断的输出 对于批量生成，请使用左侧填充，并且仅解码提示长度之后的新 token，如快速入门中所示。

## 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]`，*可选*)：音频骨干网络的配置对象或字典。

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：文本骨干网络的配置对象或字典。

audio_token_id (`int`，*可选*，默认为 `151669`)：用作输入音频占位符的音频 token 索引。

projector_hidden_act (`str`，*可选*，默认为 `gelu`)：多模态投影器所使用的激活函数。

projector_bias (`bool`，*可选*，默认为 `True`)：是否在多模态投影器中使用偏置。

这是用于存储 AudioFlamingo3Model 配置的类。它根据指定的参数实例化 Audioflamingo3 模型，并定义模型架构。使用默认值实例化配置，将得到与 [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/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`)：每个输入帧使用的 mel 特征数量。应与 `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`)：注意力概率的 dropout 比率。

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 滤波器组特征的最大序列长度。

这是用于存储 AudioFlamingo3Model 配置的类。它根据指定的参数实例化 Audioflamingo3 模型，并定义模型架构。使用默认值实例化配置，将得到与 [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/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`，*可选*，默认值为 600)：音频序列的最大长度（以秒为单位）。超过此时长的音频将被截断。

构造一个 AudioFlamingo3Processor，它将特征提取器和分词器封装为单个处理器。

[AudioFlamingo3Processor](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) 提供了 [WhisperFeatureExtractor](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor) 和 [Qwen2Tokenizer](/docs/transformers/main/zh/model_doc/qwen2#transformers.Qwen2Tokenizer) 的所有功能。有关更多信息，请参阅 [~WhisperFeatureExtractor](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor) 和 [~Qwen2Tokenizer](/docs/transformers/main/zh/model_doc/qwen2#transformers.Qwen2Tokenizer)。

#### __调用__[[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/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回：** [BatchFeature](/docs/transformers/main/zh/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/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3EncoderConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。如需加载模型权重，请参阅 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法。

AudioFlamingo3 的音频模型，顶部未添加任何分类头或投影层。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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.Tensor`，形状为 `(batch_size, feature_size, sequence_length)`)：从原始音频中提取的 Log-Mel 特征。请使用处理器/特征提取器从波形输入中计算并填充这些特征。

input_features_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充特征索引执行注意力机制的掩码。掩码值选自 `[0, 1]`： - 对于**未掩码**的 token，值为 1； - 对于**已掩码**的 token，值为 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/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Config))：模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

AudioFlamingo3 模型（经过微调的 Whisper 编码器、多模态投影器、Qwen2 语言模型），不包含语言建模头。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L510)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [WhisperFeatureExtractor](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [WhisperFeatureExtractor.__call__()](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__)（[AudioFlamingo3Processor](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) 使用 [WhisperFeatureExtractor](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor) 处理音频）。

input_features_mask (`torch.Tensor`，形状为 `(batch_size, feature_sequence_length)`)：用于避免对填充特征索引执行注意力机制的掩码。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** `AudioFlamingo3ModelOutputWithPast` 或 `tuple(torch.Tensor)`

`AudioFlamingo3ModelOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[AudioFlamingo3Config](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)）和输入。

[AudioFlamingo3Model](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Model) 的 forward 方法会重写 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **audio_hidden_states** (`torch.Tensor`，*可选*) -- 投影后的音频隐藏状态。

## 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/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Config))：模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

AudioFlamingo3 模型由一个经过微调的 Whisper 编码器、一个多模态投影器以及一个 Qwen2 语言模型组成。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L578)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [WhisperFeatureExtractor](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [WhisperFeatureExtractor.__call__()](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__)（[AudioFlamingo3Processor](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) 使用 [WhisperFeatureExtractor](/docs/transformers/main/zh/model_doc/whisper#transformers.WhisperFeatureExtractor) 处理音频）。

input_features_mask (`torch.Tensor`，形状为 `(batch_size, feature_sequence_length)`)：用于避免对填充特征索引执行注意力机制的掩码。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算掩码语言建模损失的标签。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回：** `AudioFlamingo3CausalLMOutputWithPast` 或 `tuple(torch.Tensor)`

`AudioFlamingo3CausalLMOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[AudioFlamingo3Config](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)）和输入。

[AudioFlamingo3ForConditionalGeneration](/docs/transformers/main/zh/model_doc/audioflamingo3#transformers.AudioFlamingo3ForConditionalGeneration) 的 forward 方法会重写 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例。
- **hidden_states** (`tuple[torch.Tensor]`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple[torch.Tensor]`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **audio_hidden_states** (`torch.Tensor`，*可选*) -- 音频编码器投影后的隐藏状态。

示例：

```python
>>> from transformers import 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)