# 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 и Университет Мэриленда Проект: 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 → усреднение по времени (шаг 2) → LayerNorm. Формирует скрытые состояния для каждого кадра на частоте после пулинга.

* **AudioFlamingo3MultiModalProjector** Небольшой MLP, который отображает признаки энкодера в размер скрытого слоя языковой модели.

* **AudioFlamingo3ForConditionalGeneration** — каузальная языковая модель, принимающая текстовые эмбеддинги, в которых каждый слот плейсхолдер-токена аудио заменяется на месте эмбеддингом кадра аудио. Слияние не приводит к изменению длины последовательности.

### Выравнивание на уровне процессора

1. Каждая исходная волновая форма разбивается на окна фиксированной длины на основе параметров `chunk_length` (в секундах) и `sampling_rate` (Гц) экстрактора признаков.
2. Для каждого окна процессор вычисляет количество кадров после пулинга `post_pool_len`, которые будет выдать энкодер (в соответствии с расписанием свёрток/пулинга).
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` и т. д.) передаются дальше, поэтому вы можете настраивать padding и форматы тензоров так же, как при вызове `processor(...)`.

## Длинные аудио и оконная обработка

**Важно: максимальная длительность аудио составляет 10 минут.** Более длинные аудио будут обрезаны.

* По умолчанию обработка выполняется для 30-секундных окон с частотой дискретизации 16 кГц в моно-канале.
* **Процессор устанавливает жёсткий лимит в 20 окон на образец, что соответствует максимум 10 минутам аудио (20 окон × 30 секунд).**
* Для каждого окна:

  * `mel_len` — это дополненная длина мел-спектрограммы.
  * Стек свёрток сокращает время, так как `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` передаются только на первом шаге. Последующие шаги используют закэшированные ключи/значения из языковой модели.

## Устранение неполадок

* Пустые или обрезанные результаты при батчинге Используйте левое выравнивание (left padding) для генерации в батче и декодируйте только новые токены после длины промпта, как показано в быстром старте.

## 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/v5.23.0/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`) : Индекс аудио-токена, используемый как плейсхолдер для входного аудио.

projector_hidden_act (`str`, *необязательный*, по умолчанию `gelu`) : Функция активации, используемая мультимодальным проектором.

projector_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение (bias) в мультимодальном проекторе.

Это класс конфигурации для хранения настроек модели AudioFlamingo3Model. Он используется для создания модели Audioflamingo3 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/audioflamingo3/configuration_audioflamingo3.py#L26)

**Параметры:**

num_mel_bins (`int`, *optional*, по умолчанию `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`) : Коэффициент 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`, *optional*, по умолчанию 1500) : Максимальная длина последовательности признаков log-mel filter-bank, с которой может использоваться данная модель.

Это класс конфигурации для хранения настроек модели AudioFlamingo3Model. Он используется для создания модели Audioflamingo3 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/audioflamingo3/processing_audioflamingo3.py#L37)

**Параметры:**

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, который объединяет feature extractor и tokenizer в единый processor.

[AudioFlamingo3Processor](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) предоставляет все возможности [WhisperFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor) и [Qwen2Tokenizer](/docs/transformers/v5.23.0/ru/model_doc/qwen2#transformers.Qwen2Tokenizer). Подробнее см. в документации [~WhisperFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor) и [~Qwen2Tokenizer](/docs/transformers/v5.23.0/ru/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.processing_utils.ProcessingKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/audioflamingo3/processing_audioflamingo3.py#L71)

**Параметры:**

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_mm_token_type_ids (`bool`, *kwargs*) : Нужно ли возвращать идентификаторы типов мультимодальных токенов, указывающие на позиции мультимодальных плейсхолдер-токенов.

return_text_replacement_offsets (`bool`, *kwargs*) : Нужно ли возвращать смещения символов для каждого мультимодального плейсхолдера и его замены.

return_tensors (`str` или [TensorType](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/ru/main_classes/processors#transformers.ProcessingKwargs), *optional*) : Дополнительные параметры обработки для каждой модальности (текст, изображения, видео, аудио). Специфичные для модели параметры перечислены выше; полный список поддерживаемых аргументов см. в классе TypedDict.

**Возвращает:** [BatchFeature](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L303)

**Параметры:**

config ([AudioFlamingo3EncoderConfig](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3EncoderConfig)) : класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Аудиомодель из AudioFlamingo3 без какой-либо головы или проекции сверху.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/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]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.

## AudioFlamingo3Model[[transformers.AudioFlamingo3Model]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L448)

**Параметры:**

config ([AudioFlamingo3Config](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель AudioFlamingo3 (дообученный кодировщик Whisper, мультимодальный проектор, языковая модель Qwen2), без головы для моделирования языка.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L514)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

input_features (`torch.Tensor` формы `(batch_size, sequence_length, feature_dim)`, *необязательно*) : Тензоры, соответствующие входным аудиособытиям. Аудиособытия можно получить с помощью [WhisperFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor). Подробности см. в [WhisperFeatureExtractor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__) ([AudioFlamingo3Processor](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) использует [WhisperFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor) для обработки аудио).

input_features_mask (`torch.Tensor` формы `(batch_size, feature_sequence_length)`) : Маска для предотвращения применения внимания к индексам заполняющих признаков.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

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/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) и входных данных.

Метод forward модели [AudioFlamingo3Model](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Model) переопределяет специальный метод `__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/v5.23.0/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L570)

**Параметры:**

config ([AudioFlamingo3Config](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель AudioFlamingo3, состоящая из дообученного кодировщика Whisper, мультимодального проектора и языковой модели Qwen2.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L582)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

input_features (`torch.Tensor` формы `(batch_size, sequence_length, feature_dim)`, *необязательно*) : Тензоры, соответствующие входным аудиособытиям. Аудиособытия можно получить с помощью [WhisperFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor). Подробности см. в [WhisperFeatureExtractor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__) ([AudioFlamingo3Processor](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) использует [WhisperFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/whisper#transformers.WhisperFeatureExtractor) для обработки аудио).

input_features_mask (`torch.Tensor` формы `(batch_size, feature_sequence_length)`) : Маска для предотвращения применения внимания к индексам заполняющих признаков.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

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 для последних `logits_to_keep` токенов. Если передано `0`, logits вычисляются для всех `input_ids` (специальный случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа `torch.Tensor`, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (одно измерение для batch и длины последовательности).

**Возвращает:** `AudioFlamingo3CausalLMOutputWithPast` или `tuple(torch.Tensor)`

Объект `AudioFlamingo3CausalLMOutputWithPast` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([AudioFlamingo3Config](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) и входных данных.

Метод forward класса [AudioFlamingo3ForConditionalGeneration](/docs/transformers/v5.23.0/ru/model_doc/audioflamingo3#transformers.AudioFlamingo3ForConditionalGeneration) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/audioflamingo3/modeling_audioflamingo3.py#L579)