# Audio Flamingo 3

## Visão geral

Audio Flamingo 3 (AF3) é um grande modelo de áudio e linguagem totalmente aberto, projetado para compreensão e raciocínio robustos sobre fala, sons ambientais e música. O AF3 combina um codificador de áudio no estilo Whisper com um modelo de linguagem causal e realiza fusão de áudio e texto por substituição no local: o processador alinha os quadros de áudio pós-pool a um token placeholder dedicado e o modelo substitui esses slots de token por embeddings de áudio projetados durante a passagem de frente.

O checkpoint do modelo está disponível em: [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf)

Destaques:

- Codificador de áudio unificado para fala, som e música.
- **Suporte a áudio longo por meio de janelamento e alinhamento pós-pooling (máximo de 10 minutos).** O modelo processa o áudio em janelas de 30 segundos, com um limite rígido de 20 janelas (10 minutos no total). Áudios com mais de 10 minutos serão truncados.
- Fusão determinística que preserva o comprimento da sequência, substituindo tokens de placeholder de áudio por embeddings de áudio.

Este modelo foi contribuído por [Lasha Koroshinadze](https://huggingface.co/lashahub) e [Eric Bezzam](https://huggingface.co/bezzam).

### Artigo

[Audio Flamingo 3](https://huggingface.co/papers/2507.08128): Avançando a inteligência de áudio com grandes modelos de linguagem de áudio totalmente abertos 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 e University of Maryland Projeto: https://research.nvidia.com/labs/adlr/AF3/

## Uso

### Modo de Instrução de Áudio

O modelo suporta instruções de áudio e texto, incluindo interações de múltiplas rodadas, todas processadas em lotes.

➡️ áudio + instrução de texto

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

➡️ multi-turn:

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

➡️ apenas texto:

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

➡️ somente áudio:

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

➡️ inferência em lote!

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

➡️ Treinamento:

Passe os transcritos-alvo para `apply_transcription_request` com `transcription`. Eles são escritos como a vez do assistente, e `labels` são retornados para calcular a perda.

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

Para outras tarefas, coloque o alvo no turno do assistente e passe `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()
```

➡️ atalho de transcrição

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

O modelo é treinado para emitir transcrições prefixadas com a estrutura do assistente, como `The spoken content of the audio is "<text>".`. Use `strip_prefix=True` (como mostrado acima) para remover a frase fixa do assistente e as aspas circundantes, de modo que apenas a transcrição permaneça.

## Como o modelo funciona

### Arquitetura

* **AudioFlamingo3Encoder** extrator de recursos + codificador no estilo Whisper → pooling médio ao longo do tempo (passo 2) → LayerNorm. Gera estados ocultos por quadro na taxa pós-pooling.

* **AudioFlamingo3MultiModalProjector** Um pequeno MLP que mapeia os recursos do codificador para o tamanho oculto do modelo de linguagem.

* **AudioFlamingo3ForConditionalGeneration** Um modelo de linguagem causal que aceita embeddings de texto, nos quais cada slot de token placeholder de áudio é substituído, no local, por um embedding de frame de áudio. A fusão não introduz nenhuma alteração no comprimento da sequência.

### Alinhamento no nível do processador

1. Cada forma de onda bruta é dividida em janelas de comprimento fixo com base no `chunk_length` (segundos) e na `sampling_rate` (Hz) do extrator de recursos.
2. Para cada janela, o processador calcula o número de quadros pós-pool `post_pool_len` que o codificador produzirá (correspondendo ao agendamento de conv/pool).
3. O processador expande o token de espaço reservado de áudio pelo número total de quadros pós-pooling em todas as janelas.
4. O modelo substitui, em seguida, essas posições de tokens pelos embeddings de áudio projetados correspondentes.

## Padrões de uso

### Atalho de transcrição

Para reconhecimento automático de fala, você pode pular a escrita da instrução padrão a cada vez e chamar `apply_transcription_request()`:

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

Passe `prompt="Transcribe the input speech."` (ou uma lista de prompts para áudio em lote) para personalizar a instrução, mantendo o tratamento do placeholder de áudio.

`audio` aceita arrays em memória, caminhos de arquivos locais ou URLs. Todos os kwargs do processador (`text_kwargs`, `audio_kwargs`, etc.) são encaminhados, permitindo ajustar o padding ou os formatos de tensor da mesma forma que ao chamar `processor(...)`.

## Áudio longo e janelamento

**Importante: o comprimento máximo do áudio é de 10 minutos.** Áudios mais longos que isso serão truncados.

* A configuração padrão processa janelas de 30 segundos em 16 kHz mono.
* **O processador impõe um limite rígido de 20 janelas por amostra, resultando em um máximo de 10 minutos de áudio (20 janelas × 30 segundos).**
* Para cada janela:

  * `mel_len` é o comprimento mel preenchido.
  * Um stack de conv reduz o tempo, pois `conv_output_len = (mel_len - 1) // 2 + 1`.
  * Quadros por janela após o pooling: `post_pool_len = (conv_output_len - 2) // 2 + 1`.
  * Um token placeholder de áudio é expandido para a soma de `post_pool_len` em todas as janelas.

## Preenchimento, atenção e cache

* **Padding à esquerda vs padding à direita** Para geração com prompts de comprimentos mistos em um lote, o padding à esquerda é geralmente preferível. Para treinamento, o padding à direita é comum; o mecanismo de fusão do AF3 em si é agnóstico em relação ao padding, pois substitui no local.
* **Máscaras de atenção** O processador retorna `attention_mask` (texto) e `input_features_mask` (áudio). O modelo constrói uma máscara interna 4-D no eixo pré-pooling do codificador, com negativo infinito nas posições de preenchimento.
* **Cache** Durante a geração, `input_features` e `input_features_mask` são passados apenas na primeira etapa. As etapas subsequentes usam as chaves/valores em cache do modelo de linguagem.

## Solução de problemas

* Saídas vazias ou truncadas ao usar lotes (batching) Use padding à esquerda para a geração em lote e decodifique apenas os novos tokens após o comprimento do prompt, conforme mostrado no guia rápido.

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

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

**Parâmetros:**

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de áudio.

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de texto.

audio_token_id (`int`, *opcional*, padrão `151669`) : O índice do token de áudio usado como marcador para o áudio de entrada.

projector_hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação usada pelo projetor multimodal.

projector_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés no projetor multimodal.

Esta é a classe de configuração para armazenar a configuração de um AudioFlamingo3Model. Ela é usada para instanciar um modelo Audioflamingo3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

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

**Parâmetros:**

num_mel_bins (`int`, *opcional*, padrão `128`) : Número de recursos mel usados por quadro de entrada. Deve corresponder ao valor usado na classe `AutoFeatureExtractor`.

num_hidden_layers (`int`, *opcional*, padrão `32`) : Número de camadas ocultas no decodificador do Transformer.

num_attention_heads (`int`, *opcional*, padrão `20`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

intermediate_size (`int`, *opcional*, padrão `5120`) : Dimensão das representações do MLP.

layerdrop (`Union[float, int]`, *opcional*, padrão `0.0`) : A probabilidade de LayerDrop. Consulte o [artigo do LayerDrop](see https://huggingface.co/papers/1909.11556) para mais detalhes.

activation_function (`str`, *opcional*, padrão `gelu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

hidden_size (`int`, *opcional*, padrão `1280`) : Dimensão das representações ocultas.

dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A proporção para todas as camadas de dropout.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção.

activation_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as ativações dentro da camada totalmente conectada.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

scale_embedding (`bool`, *opcional*, padrão `False`) : Se as embeddings devem ser escalonadas dividindo por sqrt(d_model).

max_source_positions (`int`, *opcional*, padrão 1500) : O comprimento máximo da sequência de recursos de filtro-banco log-mel com os quais este modelo pode ser utilizado.

Esta é a classe de configuração para armazenar a configuração de um AudioFlamingo3Model. Ela é usada para instanciar um modelo Audioflamingo3 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [nvidia/audio-flamingo-3-hf](https://huggingface.co/nvidia/audio-flamingo-3-hf)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

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

**Parâmetros:**

feature_extractor (`WhisperFeatureExtractor`) : O extrator de recursos é uma entrada obrigatória.

tokenizer (`Qwen2Tokenizer`) : O tokenizer é uma entrada obrigatória.

chat_template (`str`) : Um modelo Jinja para converter listas de mensagens em um chat em uma string tokenizável.

audio_token (`Optional[str]`, *opcional*, padrão `"<sound>"`) : Token especial usado para representar entradas de áudio no modelo de chat.

default_transcription_prompt (`str`, *opcional*, padrão `"Transcribe the input speech."`) : Prompt padrão a ser usado para tarefas de transcrição ao aplicar solicitações de transcrição.

max_audio_len (`int`, *opcional*, padrão 600) : Comprimento máximo das sequências de áudio em segundos. Áudios mais longos que isso serão truncados.

Constrói um AudioFlamingo3Processor que encapsula um extrator de recursos e um tokenizer em um único processador.

[AudioFlamingo3Processor](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) oferece todas as funcionalidades de [WhisperFeatureExtractor](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor) e [Qwen2Tokenizer](/docs/transformers/main/pt/model_doc/qwen2#transformers.Qwen2Tokenizer). Consulte [~WhisperFeatureExtractor](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor) e [~Qwen2Tokenizer](/docs/transformers/main/pt/model_doc/qwen2#transformers.Qwen2Tokenizer) para mais informações.

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

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

**Parâmetros:**

text (`Union[str, list[str]]`) : A sequência ou lote de sequências a serem codificadas. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se você passar uma entrada pretokenizada, defina `is_split_into_words=True` para evitar ambiguidade com entradas em lote.

audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`, *opcional*) : O áudio ou lote de áudios a ser preparado. Cada áudio pode ser um array NumPy ou um tensor PyTorch. No caso de um array NumPy/tensor PyTorch, cada áudio deve ter a forma (C, T), onde C é o número de canais e T é o comprimento de amostras do áudio.

output_labels (`bool`, *opcional*, padrão=False) : Se deve retornar rótulos para o treinamento.

return_tensors (`str` ou [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *opcional*) : Se definido, retornará tensores de um framework específico. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessingKwargs), *opcional*) : Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

**Retorna:** [BatchFeature](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.BatchFeature)

Um dicionário com texto tokenizado (`input_ids`, `attention_mask`) e recursos de áudio (`input_features`, `input_features_mask`).

## AudioFlamingo3Encoder[[transformers.AudioFlamingo3Encoder]]

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

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

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

**Parâmetros:**

config ([AudioFlamingo3EncoderConfig](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3EncoderConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo de áudio do AudioFlamingo3 sem nenhum head ou projeção no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

input_features (`torch.Tensor` de forma `(batch_size, feature_size, sequence_length)`) : Recursos Log-Mel extraídos do áudio bruto. Use o processador/extrator de recursos para calcular e preencher esses recursos a partir da entrada de forma de onda.

input_features_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de preenchimento. Valores da máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.

## AudioFlamingo3Model[[transformers.AudioFlamingo3Model]]

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

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

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

**Parâmetros:**

config ([AudioFlamingo3Config](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo AudioFlamingo3 (codificador Whisper ajustado, projetor multimodal, modelo de linguagem Qwen2), sem uma cabeça de modelagem de linguagem.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

input_features (`torch.Tensor` de forma `(batch_size, sequence_length, feature_dim)`, *opcional*) : Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando [WhisperFeatureExtractor](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor). Veja [WhisperFeatureExtractor.__call__()](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__) para detalhes ([AudioFlamingo3Processor](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) usa [WhisperFeatureExtractor](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor) para processar áudios).

input_features_mask (`torch.Tensor` de forma `(batch_size, feature_sequence_length)`) : Máscara para evitar a execução de atenção nos índices de preenchimento (padding) dos recursos.

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

**Retorna:** `AudioFlamingo3ModelOutputWithPast` ou `tuple(torch.Tensor)`

Um `AudioFlamingo3ModelOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([AudioFlamingo3Config](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) e das entradas.

O método forward do [AudioFlamingo3Model](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Model) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **audio_hidden_states** (`torch.Tensor`, *opcional*) -- Estados ocultos de áudio projetados.

## AudioFlamingo3ForConditionalGeneration[[transformers.AudioFlamingo3ForConditionalGeneration]]

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

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

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

**Parâmetros:**

config ([AudioFlamingo3Config](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo AudioFlamingo3, que consiste em um codificador Whisper ajustado finamente, um projetor multimodal e um modelo de linguagem Qwen2.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

input_features (`torch.Tensor` de forma `(batch_size, sequence_length, feature_dim)`, *opcional*) : Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando [WhisperFeatureExtractor](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor). Veja [WhisperFeatureExtractor.__call__()](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor.__call__) para detalhes ([AudioFlamingo3Processor](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Processor) usa [WhisperFeatureExtractor](/docs/transformers/main/pt/model_doc/whisper#transformers.WhisperFeatureExtractor) para processar áudios).

input_features_mask (`torch.Tensor` de forma `(batch_size, feature_sequence_length)`) : Máscara para evitar a execução de atenção nos índices de preenchimento (padding) dos recursos.

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, padrão `0`) : Se for um `int`, calcula os logits para os últimos `logits_to_keep` tokens. Se for `0`, calcula os logits para todos os `input_ids` (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um `torch.Tensor`, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

**Retorna:** `AudioFlamingo3CausalLMOutputWithPast` ou `tuple(torch.Tensor)`

Um `AudioFlamingo3CausalLMOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([AudioFlamingo3Config](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3Config)) e das entradas.

O método forward de [AudioFlamingo3ForConditionalGeneration](/docs/transformers/main/pt/model_doc/audioflamingo3#transformers.AudioFlamingo3ForConditionalGeneration) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token).
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem.
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- É uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache).
- **hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **audio_hidden_states** (`torch.Tensor`, *opcional*) -- Estados ocultos do codificador de áudio após a projeção.

Exemplo:

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

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