# Canary

## Обзор

Модель Canary-1B-v2 была предложена в статье [Canary-1B-v2 & Parakeet-TDT-0.6B-v3: Efficient and High-Performance Models for Multilingual ASR and AST](https://huggingface.co/papers/2509.14128) авторами Monica Sekoyan, Nithin Rao Koluguri, Nune Tadevosyan, Piotr Zelasko, Travis Bartley, Nikolay Karpov, Jagadeesh Balam и Boris Ginsburg.

Аннотация из статьи следующая:

*В данном отчёте представлен Canary-1B-v2 — быстрая и надёжная многоязычная модель для автоматического распознавания речи (ASR) и перевода речи в текст (AST). Модель построена на основе кодировщика FastConformer и декодера Transformer и поддерживает 25 европейских языков. Обучение проводилось на 1,7 млн часов данных, включая Granary и NeMo ASR Set 3.0, при этом для снижения галлюцинаций в задачах ASR и AST в набор данных добавлялись неговорящие аудиозаписи. Мы описываем двухэтапный процесс предварительного обучения и дообучения с динамическим балансированием данных, а также эксперименты с кодировщиком nGPT. Результаты показывают, что nGPT хорошо масштабируется при работе с большими объёмами данных, тогда как FastConformer демонстрирует превосходные результаты после дообучения. Для получения временных меток Canary-1B-v2 использует NeMo Forced Aligner (NFA) с вспомогательной моделью CTC, что обеспечивает надёжные временные метки на уровне сегментов для ASR и AST. По результатам оценки Canary-1B-v2 превосходит Whisper-large-v3 в английском ASR, работая в 10 раз быстрее, и обеспечивает конкурентоспособные результаты в многоязычных задачах ASR и AST по сравнению с более крупными моделями, такими как Seamless-M4T-v2-large, и системами на основе LLM. Также мы выпускаем Parakeet-TDT-0.6B-v3, преемника версии v2, который обеспечивает многоязычный ASR для тех же 25 языков при объёме параметров всего 600 млн.*

Canary переиспользует энкодер [Fast Conformer](https://huggingface.co/papers/2305.05084) из [Parakeet](./parakeet) (загружаемый через [ParakeetEncoder](/docs/transformers/v5.23.0/ru/model_doc/parakeet#transformers.ParakeetEncoder) / [ParakeetEncoderConfig](/docs/transformers/v5.23.0/ru/model_doc/parakeet#transformers.ParakeetEncoderConfig)) и комбинирует его с декодером Transformer, который использует фиксированные синусоидальные позиционные эмбеддинги, кросс-внимание к выходам энкодера и связанные входные/выходные эмбеддинги. Задача выбирается через префикс-промпт декодера, формируемый [CanaryProcessor](/docs/transformers/v5.23.0/ru/model_doc/canary#transformers.CanaryProcessor) в виде `<|startofcontext|> <|startoftranscript|> <|emo:undefined|> <source_lang> <target_lang> <pnc|nopnc> <|noitn|> <|notimestamp|> <|nodiarize|>`, где `source_lang == target_lang` выбирает транскрипцию, а в противном случае — перевод.

Оригинальная реализация доступна в [NVIDIA NeMo](https://github.com/NVIDIA/NeMo). Чекпоинт модели можно найти по адресу [nvidia/canary-1b-v2](https://huggingface.co/nvidia/canary-1b-v2).

Эта модель была предоставлена [Harshal Janjani](https://huggingface.co/harshaljanjani).

> [!NOTE]
> Сегментные временные метки для Canary-1B-v2 генерируются внешним NeMo Forced Aligner (NFA) с использованием вспомогательной CTC-модели, а не декодером, поэтому они не входят в вывод `generate`.

## Использование

### Расшифровка

Самый простой способ расшифровать аудио — использовать `apply_transcription_request`, который формирует промпт для мультитаскового декодера за вас (это удобный обёртка для `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])
```

### Перевод

Установите `target_language` в значение, отличное от `source_language`, для перевода речи в текст.

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

### Пакетный вывод

Передайте список аудио и, при необходимости, списки `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

Для авторегрессионной транскрипции `torch.compile` ускоряет посимвольные прямые проходы внутри `generate`, предоставляя объект `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])
```

### Обучение

Canary можно обучать с использованием потерь, вычисляемых моделью. Поместите целевую транскрипцию в реплику ассистента и передайте `output_labels=True`. Позиции, заполненные padding, маскируются автоматически.

```python
...

model.train()
transcription = "mister Quilter is the apostle of the middle classes, and we are glad to welcome his gospel."

conversation = [
    [
        {
            "role": "user",
            "content": [
                {"type": "audio", "audio": ds[0]["audio"]["array"]},
                {"type": "text", "source_language": "en", "target_language": "en", "punctuation": True},
            ],
        },
        {"role": "assistant", "content": transcription},
    ]
]

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

outputs = model(**inputs)
outputs.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)
```

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

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

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

encoder_config (`Union[dict, ParakeetEncoderConfig]`, *необязательный*) : Объект конфигурации или словарь конфигурации энкодера FastConformer ([ParakeetEncoderConfig](/docs/transformers/v5.23.0/ru/model_doc/parakeet#transformers.ParakeetEncoderConfig)).

decoder_config (`Union[dict, CanaryDecoderConfig]`, *необязательный*) : Объект конфигурации или словарь конфигурации декодера Transformer ([CanaryDecoderConfig](/docs/transformers/v5.23.0/ru/model_doc/canary#transformers.CanaryDecoderConfig)).

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

tie_word_embeddings (`bool`, *необязательный*, по умолчанию `True`) : Связывать ли веса эмбеддингов согласно отображению `tied_weights_keys` модели.

pad_token_id (`int`, *необязательный*, по умолчанию `2`) : Идентификатор токена, используемый для выравнивания в словаре.

bos_token_id (`int`, *необязательный*, по умолчанию `4`) : Идентификатор токена, используемый для обозначения начала потока в словаре.

eos_token_id (`int`, *необязательный*, по умолчанию `3`) : Идентификатор токена, используемый для обозначения конца потока в словаре.

decoder_start_token_id (`int`, *optional*, по умолчанию 7) : Идентификатор токена, с которого начинается декодирование (`<|startofcontext|>`, первый токен многостекового промпта).

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

vocab_size (`int`, *необязательный*, по умолчанию `16384`) : Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены в `input_ids`.

Это класс конфигурации для хранения настроек модели CanaryModel. Он используется для создания модели Canary в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [nvidia/canary-1b-v2](https://huggingface.co/nvidia/canary-1b-v2)

Объекты конфигурации наследуются от [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 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)
```

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

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

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

vocab_size (`int`, *необязательный*, по умолчанию `16384`) : Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены в `input_ids`.

hidden_size (`int`, *необязательный*, по умолчанию `1024`) : Размерность скрытых представлений.

intermediate_size (`int`, *необязательный*, по умолчанию `4096`) : Размерность представлений MLP.

num_hidden_layers (`int`, *необязательный*, по умолчанию `8`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `8`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

num_key_value_heads (`int`, *optional*, по умолчанию `8`) : Это количество ключевых и value-голов, которое следует использовать для реализации Grouped Query Attention. Если `num_key_value_heads=num_attention_heads`, модель будет использовать Multi Head Attention (MHA), если `num_key_value_heads=1` — Multi Query Attention (MQA), в противном случае используется GQA. При конвертации multi-head checkpoint в GQA checkpoint каждая группа ключевых и value-голов должна быть построена путем усреднения (meanpooling) всех исходных голов в этой группе. Подробнее см. в [этой статье](https://huggingface.co/papers/2305.13245). Если значение не указано, по умолчанию используется `num_attention_heads`.

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

max_position_embeddings (`int`, *необязательный*, по умолчанию `1024`) : Максимальная длина последовательности, с которой может использоваться данная модель.

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

pad_token_id (`int`, *необязательный*, по умолчанию `2`) : Идентификатор токена, используемый для выравнивания в словаре.

bos_token_id (`int`, *необязательный*, по умолчанию `4`) : Идентификатор токена, используемый для обозначения начала потока в словаре.

eos_token_id (`int`, *необязательный*, по умолчанию `3`) : Идентификатор токена, используемый для обозначения конца потока в словаре.

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

attention_dropout (`Union[int, float]`, *необязательный*, по умолчанию `0.0`) : Доля dropout для вероятностей внимания.

head_dim (`int`, *необязательный*, по умолчанию `128`) : Размер измерения головы внимания. Если None, по умолчанию будет hidden_size // num_attention_heads

Это класс конфигурации для хранения настроек модели CanaryModel. Он используется для создания модели Canary в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [nvidia/canary-1b-v2](https://huggingface.co/nvidia/canary-1b-v2)

Объекты конфигурации наследуются от [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 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)
```

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

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

feature_extractor (`ParakeetFeatureExtractor`) : Извлекатель признаков является обязательным входом.

tokenizer (`TokenizersBackend`) : Токенизатор является обязательным входным параметром.

chat_template (`str`) : Шаблон Jinja для преобразования списков сообщений в чате в строку, готовую к токенизации.

Создаёт CanaryProcessor, который объединяет feature extractor и tokenizer в единый processor.

[CanaryProcessor](/docs/transformers/v5.23.0/ru/model_doc/canary#transformers.CanaryProcessor) предоставляет все возможности [ParakeetFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/parakeet#transformers.ParakeetFeatureExtractor) и [TokenizersBackend](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.TokenizersBackend). Подробнее см. в [~ParakeetFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/parakeet#transformers.ParakeetFeatureExtractor) и [~TokenizersBackend](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.TokenizersBackend).

#### 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, tokenize: bool = True, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

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

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

audio (`AudioInput` или `list[AudioInput]`) : Аудио для расшифровки или перевода. Может быть строкой с URL, локальным путём, массивом numpy или списком этих значений.

source_language (`str` или `list[str]`, *необязательный*, по умолчанию `"en"`) : Язык входной речи. Принимает ISO-коды (например, `"en"`, `"de"`, `"fr"`) или полные названия (например, `"English"`, `"German"`, `"French"`).

target_language (`str` или `list[str]`, *необязательный*) : Язык выходного текста. Принимает ISO-коды или полные названия. По умолчанию — `source_language` (транскрипция); установите другой язык для перевода с аудио на текст.

punctuation (`bool`, *необязательный*, по умолчанию `True`) : Запрашивать ли пунктуацию и заглавные буквы в выводе.

tokenize (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли токенизировать промпты и обрабатывать аудио. Если `False`, аудио не загружается, а промпты возвращаются в виде строк с неразвёрнутыми плейсхолдерами для аудио. Передача их вместе с аудио в процессор, `processor(text=prompts, audio=audio)`, даёт те же результаты, что и `tokenize=True`.

- ****kwargs** : Дополнительные именованные аргументы, передаваемые в [apply_chat_template()](/docs/transformers/v5.23.0/ru/main_classes/processors#transformers.ProcessorMixin.apply_chat_template).

**Возвращает:** [BatchFeature](/docs/transformers/v5.23.0/ru/main_classes/feature_extractor#transformers.BatchFeature) или `list[str]`

Один промпт на один аудиофайл, если `tokenize=False`, иначе процессор выводит данные, готовые к передаче в [CanaryForConditionalGeneration.generate()](/docs/transformers/v5.23.0/ru/main_classes/text_generation#transformers.GenerationMixin.generate).

Подготовьте входные данные для транскрипции или перевода без ручного написания шаблона чата.

## CanaryModel[[transformers.CanaryModel]]

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

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

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

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

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

Модель Canary без дополнительных компонентов (кодировщик FastConformer + декодер Transformer), выводящая «сырые» скрытые состояния без какого-либо специализированного слоя на выходе.

Эта модель наследуется от [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.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'>)
```

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

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

input_features (`torch.Tensor` формы `(batch_size, audio_length)`) : Значения типа float для исходной звуковой волны. Исходную звуковую волну можно получить, загрузив аудиофайл `.flac` или `.wav` в массив типа `list[float]`, `numpy.ndarray` или `torch.Tensor`, *например*, с помощью библиотеки torchcodec (`pip install torchcodec`) или библиотеки soundfile (`pip install soundfile`). Для подготовки массива в `input_features` следует использовать [AutoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoFeatureExtractor) для выравнивания и преобразования в тензор типа `torch.Tensor`.

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

decoder_input_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью [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__). [Что такое входные ID декодера?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Маска для исключения внимания к определённым индексам токенов. По умолчанию используется каузальная маска, чтобы модель могла учитывать только предыдущие входные данные при прогнозировании будущих.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *необязательный*) : Кортеж состоит из (`last_hidden_state`, *необязательный*: `hidden_states`, *необязательный*: `attentions`) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

past_key_values (`~cache_utils.EncoderDecoderCache`, *optional*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `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)`.

decoder_inputs_embeds (`tuple[torch.Tensor]` формы `(batch_size, target_sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `decoder_input_ids` можно напрямую передать встроенное представление. Если используется `past_key_values`, по желанию на вход необходимо передавать только последние `decoder_inputs_embeds` (см. `past_key_values`). Это полезно, если требуется больший контроль над тем, как индексы `decoder_input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. Если `decoder_input_ids` и `decoder_inputs_embeds` не заданы, `decoder_inputs_embeds` принимает значение `inputs_embeds`.

decoder_position_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Используются для вычисления позиционных эмбеддингов до `config.decoder_config.max_position_embeddings`

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

**Возвращает:** [Seq2SeqModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) или `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя декодера модели.

  Если используется `past_key_values`, выводится только последнее скрытое состояние последовательностей формы `(batch_size, 1, hidden_size)`.
- **past_key_values** (`EncoderDecoderCache`, *необязательный*, возвращается при передаче `use_cache=True` или при `config.use_cache=True`) -- это экземпляр [EncoderDecoderCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.EncoderDecoderCache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также необязательные выходные значения начального эмбеддинга.
- **decoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния энкодера на выходе каждого слоя, а также необязательные выходные значения начального эмбеддинга.
- **encoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

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

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

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

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

Модель Canary с головой языкового моделирования. Может использоваться для многоязычного автоматического распознавания речи и перевода речи в текст.

Эта модель наследуется от [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.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'>)
```

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

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

input_features (`torch.Tensor` формы `(batch_size, audio_length)`) : Значения типа float для исходной звуковой волны. Исходную звуковую волну можно получить, загрузив аудиофайл `.flac` или `.wav` в массив типа `list[float]`, `numpy.ndarray` или `torch.Tensor`, *например*, с помощью библиотеки torchcodec (`pip install torchcodec`) или библиотеки soundfile (`pip install soundfile`). Для подготовки массива в `input_features` следует использовать [AutoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoFeatureExtractor) для выравнивания и преобразования в тензор типа `torch.Tensor`.

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

decoder_input_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью [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__). [Что такое входные ID декодера?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Маска для исключения внимания к определённым индексам токенов. По умолчанию используется каузальная маска, чтобы модель могла учитывать только предыдущие входные данные при прогнозировании будущих.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *необязательный*) : Кортеж состоит из (`last_hidden_state`, *необязательный*: `hidden_states`, *необязательный*: `attentions`) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

past_key_values (`~cache_utils.EncoderDecoderCache`, *optional*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `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)`.

decoder_inputs_embeds (`tuple[torch.Tensor]` формы `(batch_size, target_sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `decoder_input_ids` можно напрямую передать встроенное представление. Если используется `past_key_values`, по желанию на вход необходимо передавать только последние `decoder_inputs_embeds` (см. `past_key_values`). Это полезно, если требуется больший контроль над тем, как индексы `decoder_input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. Если `decoder_input_ids` и `decoder_inputs_embeds` не заданы, `decoder_inputs_embeds` принимает значение `inputs_embeds`.

decoder_position_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Используются для вычисления позиционных эмбеддингов до `config.decoder_config.max_position_embeddings`

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

labels (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Метки для вычисления потерь маскированного языкового моделирования. Индексы должны находиться в диапазоне `[0, ..., config.vocab_size]` или равняться -100 (см. docstring `input_ids`). Токены с индексами, установленными в `-100`, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне `[0, ..., config.vocab_size]`.

**Возвращает:** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели.
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **past_key_values** (`EncoderDecoderCache`, *необязательный*, возвращается при передаче `use_cache=True` или при `config.use_cache=True`) -- это экземпляр [EncoderDecoderCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.EncoderDecoderCache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
- **decoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **encoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

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

