# Canary

## Visão geral

Canary-1B-v2 foi proposto em [Canary-1B-v2 & Parakeet-TDT-0.6B-v3: Efficient and High-Performance Models for Multilingual ASR and AST](https://huggingface.co/papers/2509.14128) por Monica Sekoyan, Nithin Rao Koluguri, Nune Tadevosyan, Piotr Zelasko, Travis Bartley, Nikolay Karpov, Jagadeesh Balam e Boris Ginsburg.

O resumo do artigo é o seguinte:

*Este relatório apresenta o Canary-1B-v2, um modelo multilíngue rápido e robusto para Reconhecimento Automático de Fala (ASR) e Tradução de Fala para Texto (AST). Construído com um codificador FastConformer e um decodificador Transformer, ele suporta 25 idiomas europeus. O modelo foi treinado com 1,7 milhão de horas de amostras de dados no total, incluindo Granary e NeMo ASR Set 3.0, com áudio não-falado adicionado para reduzir alucinações em ASR e AST. Descrevemos seu processo de pré-treinamento e ajuste fino em duas etapas com balanceamento dinâmico de dados, bem como experimentos com um codificador nGPT. Os resultados mostram que o nGPT escala bem com dados massivos, enquanto o FastConformer se destaca após o ajuste fino. Para timestamps, o Canary-1B-v2 usa o NeMo Forced Aligner (NFA) com um modelo CTC auxiliar, fornecendo timestamps confiáveis em nível de segmento para ASR e AST. As avaliações mostram que o Canary-1B-v2 supera o Whisper-large-v3 em ASR em inglês, sendo 10× mais rápido, e oferece desempenho competitivo em ASR e AST multilíngues em comparação com modelos maiores, como o Seamless-M4T-v2-large e sistemas baseados em LLM. Também liberamos o Parakeet-TDT-0.6B-v3, sucessor do v2, que oferece ASR multilíngue nos mesmos 25 idiomas com apenas 600M de parâmetros.*

O Canary reutiliza o codificador [Fast Conformer](https://huggingface.co/papers/2305.05084) do [Parakeet](./parakeet) (carregado por meio de [ParakeetEncoder](/docs/transformers/main/pt/model_doc/parakeet#transformers.ParakeetEncoder) / [ParakeetEncoderConfig](/docs/transformers/main/pt/model_doc/parakeet#transformers.ParakeetEncoderConfig)) e o combina com um decodificador Transformer que utiliza embeddings posicionais sinusoidais fixos, atenção cruzada com as saídas do codificador e embeddings de entrada/saída compartilhados. A tarefa é selecionada por um prefixo de prompt do decodificador construído por [CanaryProcessor](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryProcessor) no formato `<|startofcontext|> <|startoftranscript|> <|emo:undefined|> <source_lang> <target_lang> <pnc|nopnc> <|noitn|> <|notimestamp|> <|nodiarize|>`, em que `source_lang == target_lang` seleciona a transcrição e, caso contrário, seleciona a tradução.

A implementação original pode ser encontrada em [NVIDIA NeMo](https://github.com/NVIDIA/NeMo). Um checkpoint do modelo está disponível em [nvidia/canary-1b-v2](https://huggingface.co/nvidia/canary-1b-v2).

Este modelo foi contribuído por [Harshal Janjani](https://huggingface.co/harshaljanjani).

> [!NOTE]
> Os timestamps de nível de segmento para o Canary-1B-v2 são gerados pelo NeMo Forced Aligner (NFA) externo, com um modelo CTC auxiliar, e não pelo decodificador, portanto, não fazem parte da saída de `generate`.

## Uso

### Transcrição

A forma mais simples de transcrever áudio é com `apply_transcription_request`, que monta o prompt do decodificador multitarefa para você (é um wrapper de conveniência para `apply_chat_template`).

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

processor = AutoProcessor.from_pretrained("nvidia/canary-1b-v2")
model = AutoModelForSpeechSeq2Seq.from_pretrained("nvidia/canary-1b-v2", device_map="auto")

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

inputs = processor.apply_transcription_request(audio=ds[0]["audio"]["array"], source_language="en").to(model.device)
generated_ids = model.generate(**inputs, max_new_tokens=128)
print(processor.decode(generated_ids, skip_special_tokens=True)[0])
```

### Tradução

Defina `target_language` para um idioma diferente de `source_language` para tradução de fala para texto.

```python
...

inputs = processor.apply_transcription_request(
    audio=ds[0]["audio"]["array"], source_language="en", target_language="de"
).to(model.device)
generated_ids = model.generate(**inputs, max_new_tokens=128)
print(processor.decode(generated_ids, skip_special_tokens=True)[0])
```

### Inferência em lote

Passe uma lista de áudios e, opcionalmente, uma lista de `source_language` / `target_language`.

```python
...

audios = [ds[0]["audio"]["array"], ds[1]["audio"]["array"]]
# single entries get broadcasted to list
inputs = processor.apply_transcription_request(
    audio=audios, source_language="en", target_language=["en", "de"]
).to(model.device)
generated_ids = model.generate(**inputs, max_new_tokens=128)
for text in processor.decode(generated_ids, skip_special_tokens=True):
    print(text)
```

### Torch compile

Para transcrição autoregressiva, `torch.compile` acelera as passadas de frente por token dentro de `generate` ao fornecer um objeto `CompileConfig`.

```python
...

from transformers import CompileConfig

inputs = processor.apply_transcription_request(audio=ds[0]["audio"]["array"], source_language="en").to(model.device)
compile_config = CompileConfig()

# Warmup
for _ in range(3):
    _ = model.generate(**inputs, max_new_tokens=128, cache_implementation="static", compile_config=compile_config)

# Apply model
generated_ids = model.generate(**inputs, max_new_tokens=128, cache_implementation="static", compile_config=compile_config)
print(processor.decode(generated_ids, skip_special_tokens=True)[0])
```

### Treinamento

Passe os transcritos-alvo para `apply_transcription_request` com `transcription`, e os `labels` retornados são usados para calcular a perda.

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

model_id = "nvidia/canary-1b-v2"
NUM_SAMPLES = 2

processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForSpeechSeq2Seq.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, source_language="en", transcription=text_samples)
inputs.to(model.device, dtype=model.dtype)

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

## CanaryConfig[[transformers.CanaryConfig]]

#### transformers.CanaryConfig[[transformers.CanaryConfig]]

```python
transformers.CanaryConfig(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, 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, is_encoder_decoder: bool = True, encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, use_cache: bool = True, tie_word_embeddings: bool = True, pad_token_id: int | None = 2, bos_token_id: int | None = 4, eos_token_id: int | None = 3, decoder_start_token_id: int | None = 7, initializer_range: float = 0.02, vocab_size: int = 16384)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/configuration_canary.py#L85)

**Parâmetros:**

is_encoder_decoder (`bool`, *opcional*, padrão `True`) : Indica se o modelo é usado como codificador/decodificador ou não.

encoder_config (`Union[dict, ParakeetEncoderConfig]`, *opcional*) : O objeto de configuração ou dicionário do encoder FastConformer ([ParakeetEncoderConfig](/docs/transformers/main/pt/model_doc/parakeet#transformers.ParakeetEncoderConfig)).

decoder_config (`Union[dict, CanaryDecoderConfig]`, *opcional*) : O objeto de configuração ou dicionário do decodificador Transformer ([CanaryDecoderConfig](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryDecoderConfig)).

use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador.

tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

pad_token_id (`int`, *opcional*, padrão `2`) : ID do token usado para preenchimento no vocabulário.

bos_token_id (`int`, *opcional*, padrão `4`) : ID do token usado para o início do fluxo no vocabulário.

eos_token_id (`int`, *opcional*, padrão `3`) : ID do token usado para o fim do fluxo no vocabulário.

decoder_start_token_id (`int`, *opcional*, padrão 7) : O id do token que inicia a decodificação (`<|startofcontext|>`, o primeiro token do prompt multitarefa).

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

vocab_size (`int`, *opcional*, padrão `16384`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

Esta é a classe de configuração para armazenar a configuração de um CanaryModel. Ela é usada para instanciar um modelo Canary 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/canary-1b-v2](https://huggingface.co/nvidia/canary-1b-v2)

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 CanaryForConditionalGeneration, CanaryConfig

>>> # Initializing a Canary configuration
>>> configuration = CanaryConfig()

>>> # Initializing a model from the configuration
>>> model = CanaryForConditionalGeneration(configuration)

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

## CanaryDecoderConfig[[transformers.CanaryDecoderConfig]]

#### transformers.CanaryDecoderConfig[[transformers.CanaryDecoderConfig]]

```python
transformers.CanaryDecoderConfig(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, 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, is_encoder_decoder: bool = True, vocab_size: int = 16384, hidden_size: int = 1024, intermediate_size: int = 4096, num_hidden_layers: int = 8, num_attention_heads: int = 8, num_key_value_heads: int = 8, hidden_act: str = 'relu', max_position_embeddings: int = 1024, initializer_range: float = 0.02, use_cache: bool = True, pad_token_id: int | None = 2, bos_token_id: int | None = 4, eos_token_id: int | None = 3, attention_bias: bool = True, attention_dropout: int | float | None = 0.0, head_dim: int = 128)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/configuration_canary.py#L30)

**Parâmetros:**

is_encoder_decoder (`bool`, *opcional*, padrão `True`) : Indica se o modelo é usado como codificador/decodificador ou não.

vocab_size (`int`, *opcional*, padrão `16384`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

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

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

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

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

num_key_value_heads (`int`, *opcional*, padrão `8`) : Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se `num_key_value_heads=num_attention_heads`, o modelo usará Multi Head Attention (MHA); se `num_key_value_heads=1`, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada cabeça de chave e valor do grupo deve ser construída pela média (meanpooling) de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte [este artigo](https://huggingface.co/papers/2305.13245). Se não for especificado, o valor padrão será `num_attention_heads`.

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

max_position_embeddings (`int`, *opcional*, padrão `1024`) : O comprimento máximo de sequência com o qual este modelo pode ser usado.

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

use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador.

pad_token_id (`int`, *opcional*, padrão `2`) : ID do token usado para preenchimento no vocabulário.

bos_token_id (`int`, *opcional*, padrão `4`) : ID do token usado para o início do fluxo no vocabulário.

eos_token_id (`int`, *opcional*, padrão `3`) : ID do token usado para o fim do fluxo no vocabulário.

attention_bias (`bool`, *opcional*, padrão `True`) : Se deve usar um viés nas camadas de projeção de query, key, value e output durante a autoatenção.

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

head_dim (`int`, *opcional*, padrão `128`) : A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads

Esta é a classe de configuração para armazenar a configuração de um CanaryModel. Ela é usada para instanciar um modelo Canary 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/canary-1b-v2](https://huggingface.co/nvidia/canary-1b-v2)

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.

```python
>>> from transformers import CanaryDecoderModel, CanaryDecoderConfig

>>> # Initializing a CanaryDecoder canary_decoder-7b style configuration
>>> configuration = CanaryDecoderConfig()

>>> # Initializing a model from the canary_decoder-7b style configuration
>>> model = CanaryDecoderModel(configuration)

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

## CanaryProcessor[[transformers.CanaryProcessor]]

#### transformers.CanaryProcessor[[transformers.CanaryProcessor]]

```python
transformers.CanaryProcessor(feature_extractor = None, tokenizer = None, chat_template = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/processing_canary.py#L77)

**Parâmetros:**

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

tokenizer (`TokenizersBackend`) : 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.

Constrói um CanaryProcessor que encapsula um extrator de recursos e um tokenizador em um único processador.

[CanaryProcessor](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryProcessor) oferece todas as funcionalidades de [ParakeetFeatureExtractor](/docs/transformers/main/pt/model_doc/parakeet#transformers.ParakeetFeatureExtractor) e [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend). Consulte [~ParakeetFeatureExtractor](/docs/transformers/main/pt/model_doc/parakeet#transformers.ParakeetFeatureExtractor) e [~TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend) para mais informações.

#### apply_transcription_request[[transformers.CanaryProcessor.apply_transcription_request]]

```python
apply_transcription_request(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], list[typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]]], source_language: str | list[str] = 'en', target_language: str | list[str] | None = None, punctuation: bool = True, transcription: str | list[str] | None = None, tokenize: bool = True, **kwargs: *<class 'transformers.models.canary.processing_canary.CanaryProcessorKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/processing_canary.py#L114)

**Parâmetros:**

audio (`AudioInput` ou `list[AudioInput]`) : Áudio para transcrever ou traduzir. Pode ser uma string de URL, um caminho local, um array numpy ou uma lista desses.

source_language (`str` ou `list[str]`, *opcional*, padrão `"en"`) : O idioma do áudio de entrada. Aceita códigos ISO (por exemplo, `"en"`, `"de"`, `"fr"`) ou nomes completos (por exemplo, `"English"`, `"German"`, `"French"`).

target_language (`str` ou `list[str]`, *opcional*) : O idioma do texto de saída. Aceita códigos ISO ou nomes completos. O padrão é `source_language` (transcrição); defina um idioma diferente para tradução de fala para texto.

punctuation (`bool`, *opcional*, padrão `True`) : Se deve solicitar pontuação e capitalização na saída.

transcription (`str` ou `list[str]`, *opcional*) : Transcrição(ões) de referência (ou traduções) para o treinamento, uma por áudio. Quando fornecidas, cada transcrição é escrita como o turno do assistente e `labels` são retornadas (veja `output_labels` em `__call__()`).

tokenize (`bool`, *opcional*, padrão `True`) : Se deve tokenizar os prompts e processar o áudio. Se `False`, o áudio não é carregado e os prompts são retornados como strings com placeholders de áudio não expandidos. Passá-los com o áudio para o processador, `processor(text=prompts, audio=audio)`, produz as mesmas saídas que `tokenize=True`.

- ****kwargs** : Argumentos de palavra-chave adicionais encaminhados para [apply_chat_template()](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessorMixin.apply_chat_template). Os kwargs do processador (por exemplo `text_kwargs`, `audio_kwargs`, ...) devem ser passados como `processor_kwargs={...}`.

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

Um prompt por áudio quando `tokenize=False`, caso contrário, as saídas do processador estão prontas para serem passadas a [CanaryForConditionalGeneration.generate()](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationMixin.generate) ou a [CanaryForConditionalGeneration.forward()](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryForConditionalGeneration.forward) para calcular a perda quando `transcription` é fornecida.

Prepare os inputs para transcrição ou tradução sem escrever manualmente o chat template, seja para inferência ou, quando `transcription` é fornecido, para treinamento.

## CanaryModel[[transformers.CanaryModel]]

#### transformers.CanaryModel[[transformers.CanaryModel]]

```python
transformers.CanaryModel(config: CanaryConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/modeling_canary.py#L455)

**Parâmetros:**

config ([CanaryConfig](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryConfig)) : 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 Canary puro (codificador FastConformer + decodificador Transformer) que gera estados ocultos brutos, sem nenhum cabeçalho específico 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.CanaryModel.forward]]

```python
forward(input_features: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.EncoderDecoderCache | None = None, decoder_inputs_embeds: tuple[torch.Tensor] | None = None, decoder_position_ids: tuple[torch.LongTensor] | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/modeling_canary.py#L483)

**Parâmetros:**

input_features (`torch.Tensor` de forma `(batch_size, audio_length)`) : Valores em ponto flutuante da forma de onda bruta da fala. A forma de onda bruta da fala pode ser obtida carregando um arquivo de áudio `.flac` ou `.wav` em um array do tipo `list[float]`, um `numpy.ndarray` ou um `torch.Tensor`, *por exemplo*, via a biblioteca torchcodec (`pip install torchcodec`) ou a biblioteca soundfile (`pip install soundfile`). Para preparar o array como `input_features`, o [AutoFeatureExtractor](/docs/transformers/main/pt/model_doc/auto#transformers.AutoFeatureExtractor) deve ser usado para padding e conversão em um tensor do tipo `torch.Tensor`.

attention_mask (`torch.LongTensor` 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)

decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. 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 do decodificador?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção em determinados índices de tokens. Por padrão, uma máscara causal será usada, para garantir que o modelo só possa olhar para entradas anteriores a fim de prever o futuro.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *opcional*) : A tupla consiste em (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de hidden-states na saída da última camada do encoder. Usado na cross-attention do decoder.

past_key_values (`~cache_utils.EncoderDecoderCache`, *opcional*) : Estados ocultos 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 cache de kv](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)`.

decoder_inputs_embeds (`tuple[torch.Tensor]` de forma `(batch_size, target_sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `decoder_input_ids`, você pode escolher passar diretamente uma representação embutida. Se `past_key_values` for usado, opcionalmente apenas o último `decoder_inputs_embeds` precisa ser fornecido (veja `past_key_values`). Isso é útil se você quiser ter mais controle sobre como converter os índices de `decoder_input_ids` em vetores associados do que a matriz de busca de incorporação interna do modelo. Se `decoder_input_ids` e `decoder_inputs_embeds` estiverem ambos não definidos, `decoder_inputs_embeds` assume o valor de `inputs_embeds`.

decoder_position_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Usado para calcular os embeddings de posição até `config.decoder_config.max_position_embeddings`

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:** [Seq2SeqModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) ou `tuple(torch.Tensor)`

Um [Seq2SeqModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`), contendo diversos elementos, dependendo da configuração ([CanaryConfig](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryConfig)) e das entradas.

O método forward do [CanaryModel](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryModel) 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.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do decoder do modelo.

  Se `past_key_values` for usado, apenas o último hidden-state das sequências, com forma `(batch_size, 1, hidden_size)`, é retornado.
- **past_key_values** (`EncoderDecoderCache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- É uma instância de [EncoderDecoderCache](/docs/transformers/main/pt/internal/generation_utils#transformers.EncoderDecoderCache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

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

  Pesos de atenção do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção da camada de atenção cruzada do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do encoder do modelo.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

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

  Pesos de atenção do codificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplo:

```python
>>> import torch
>>> from transformers import AutoFeatureExtractor, CanaryModel
>>> from datasets import load_dataset

>>> model = CanaryModel.from_pretrained("UsefulSensors/canary-tiny")
>>> feature_extractor = AutoFeatureExtractor.from_pretrained("UsefulSensors/canary-tiny")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = feature_extractor(ds[0]["audio"]["array"], return_tensors="pt")
>>> input_features = inputs.input_features
>>> decoder_input_ids = torch.tensor([[1, 1]]) * model.config.decoder_start_token_id
>>> last_hidden_state = model(input_features, decoder_input_ids=decoder_input_ids).last_hidden_state
>>> list(last_hidden_state.shape)
[1, 2, 288]
```

## CanaryForConditionalGeneration[[transformers.CanaryForConditionalGeneration]]

#### transformers.CanaryForConditionalGeneration[[transformers.CanaryForConditionalGeneration]]

```python
transformers.CanaryForConditionalGeneration(config: CanaryConfig)
```

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

**Parâmetros:**

config ([CanaryConfig](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryConfig)) : 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 Canary com uma cabeça de modelagem de linguagem. Pode ser usado para reconhecimento automático de fala multilíngue e tradução de fala para texto.

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.CanaryForConditionalGeneration.forward]]

```python
forward(input_features: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.EncoderDecoderCache | None = None, decoder_inputs_embeds: tuple[torch.Tensor] | None = None, decoder_position_ids: tuple[torch.LongTensor] | None = None, use_cache: bool | None = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/canary/modeling_canary.py#L598)

**Parâmetros:**

input_features (`torch.Tensor` de forma `(batch_size, audio_length)`) : Valores em ponto flutuante da forma de onda bruta da fala. A forma de onda bruta da fala pode ser obtida carregando um arquivo de áudio `.flac` ou `.wav` em um array do tipo `list[float]`, um `numpy.ndarray` ou um `torch.Tensor`, *por exemplo*, via a biblioteca torchcodec (`pip install torchcodec`) ou a biblioteca soundfile (`pip install soundfile`). Para preparar o array como `input_features`, o [AutoFeatureExtractor](/docs/transformers/main/pt/model_doc/auto#transformers.AutoFeatureExtractor) deve ser usado para padding e conversão em um tensor do tipo `torch.Tensor`.

attention_mask (`torch.LongTensor` 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)

decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. 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 do decodificador?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção em determinados índices de tokens. Por padrão, uma máscara causal será usada, para garantir que o modelo só possa olhar para entradas anteriores a fim de prever o futuro.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *opcional*) : A tupla consiste em (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de hidden-states na saída da última camada do encoder. Usado na cross-attention do decoder.

past_key_values (`~cache_utils.EncoderDecoderCache`, *opcional*) : Estados ocultos 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 cache de kv](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)`.

decoder_inputs_embeds (`tuple[torch.Tensor]` de forma `(batch_size, target_sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `decoder_input_ids`, você pode escolher passar diretamente uma representação de embedding. Se `past_key_values` for usado, opcionalmente apenas o último `decoder_inputs_embeds` precisa ser fornecido (veja `past_key_values`). Isso é útil se você quiser ter mais controle sobre como converter os índices de `decoder_input_ids` em vetores associados do que a matriz de busca de embedding interna do modelo. Se `decoder_input_ids` e `decoder_inputs_embeds` estiverem ambos não definidos, `decoder_inputs_embeds` assume o valor de `inputs_embeds`.

decoder_position_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Usado para calcular os embeddings de posição até `config.decoder_config.max_position_embeddings`

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

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`.

**Retorna:** [Seq2SeqLMOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) ou `tuple(torch.Tensor)`

Um [Seq2SeqLMOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`), composto por diversos elementos, dependendo da configuração ([CanaryConfig](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryConfig)) e das entradas.

O método forward de [CanaryForConditionalGeneration](/docs/transformers/main/pt/model_doc/canary#transformers.CanaryForConditionalGeneration) 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.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem.
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax).
- **past_key_values** (`EncoderDecoderCache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- É uma instância de [EncoderDecoderCache](/docs/transformers/main/pt/internal/generation_utils#transformers.EncoderDecoderCache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

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

  Pesos de atenção do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção da camada de atenção cruzada do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do encoder do modelo.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do codificador na saída de cada camada, além das saídas do embedding inicial.
- **encoder_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do codificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplo:

```python
>>> import torch
>>> from transformers import AutoProcessor, CanaryForConditionalGeneration
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("UsefulSensors/canary-tiny")
>>> model = CanaryForConditionalGeneration.from_pretrained("UsefulSensors/canary-tiny")

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")
>>> input_features = inputs.input_features

>>> generated_ids = model.generate(input_features, max_new_tokens=100)

>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> transcription
'Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.'
```