Transformers documentation
金丝雀
该模型于 2025-09-17 在 HF papers 上发布，并于 2026-08-31 贡献至 Hugging Face Transformers。
金丝雀
概述
Canary-1B-v2 由 Monica Sekoyan、Nithin Rao Koluguri、Nune Tadevosyan、Piotr Zelasko、Travis Bartley、Nikolay Karpov、Jagadeesh Balam 和 Boris Ginsburg 在 Canary-1B-v2 & Parakeet-TDT-0.6B-v3: Efficient and High-Performance Models for Multilingual ASR and AST 中提出。
该论文的摘要如下：
本报告介绍了 Canary-1B-v2，这是一款用于自动语音识别（ASR）和语音转文本翻译（AST）的快速、鲁棒的多语言模型。该模型采用 FastConformer 编码器和 Transformer 解码器构建，支持 25 种欧洲语言。模型在总计 170 万小时的数据样本上进行训练，包括 Granary 和 NeMo ASR Set 3.0，并加入了非语音音频以减少 ASR 和 AST 中的幻觉现象。我们描述了其采用动态数据平衡的两阶段预训练和微调过程，以及使用 nGPT 编码器的实验。结果表明，nGPT 在海量数据下具有良好的扩展性，而 FastConformer 在微调后表现卓越。对于时间戳，Canary-1B-v2 使用 NeMo Forced Aligner (NFA) 配合辅助 CTC 模型，为 ASR 和 AST 提供可靠的片段级时间戳。评估显示，Canary-1B-v2 在英语 ASR 上优于 Whisper-large-v3，同时速度快 10 倍，并且在多语言 ASR 和 AST 性能上与 Seamless-M4T-v2-large 和基于 LLM 的系统等更大规模的模型相比具有竞争力。我们还发布了 Parakeet-TDT-0.6B-v3，它是 v2 的后续版本，仅使用 6 亿参数即可在相同的 25 种语言上提供多语言 ASR 能力。
Canary 复用了 Parakeet 中的 Fast Conformer 编码器（通过 ParakeetEncoder / ParakeetEncoderConfig 加载），并将其与一个 Transformer 解码器配对。该解码器使用固定的正弦位置嵌入、对编码器输出的交叉注意力，以及共享的输入/输出嵌入。任务通过 CanaryProcessor 构建的解码器提示前缀来选择，其形式为 <|startofcontext|> <|startoftranscript|> <|emo:undefined|> <source_lang> <target_lang> <pnc|nopnc> <|noitn|> <|notimestamp|> <|nodiarize|>，其中 source_lang == target_lang 表示选择转录任务，否则选择翻译任务。
原始实现可在 NVIDIA NeMo 中找到。模型检查点可在 nvidia/canary-1b-v2 获取。
该模型由 Harshal Janjani 贡献。
Canary-1B-v2 的片段级时间戳由外部 NeMo Forced Aligner (NFA) 配合辅助 CTC 模型生成，而非由解码器生成，因此它们不属于
generate的输出。
用法
转录
最简单的音频转录方式是使用 apply_transcription_request，它会自动为你构建多任务解码器提示（它是 apply_chat_template 的便捷封装）。
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 不同的语言，以实现语音到文本的翻译。
...
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 列表。
...
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 编译
对于自回归转录，torch.compile 通过提供一个 CompileConfig 对象来加速 generate 内部逐 token 的前向传播。
...
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])训练
将目标转录文本通过transcription传递给apply_transcription_request，返回的labels用于计算损失。
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
class transformers.CanaryConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Trueencoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonedecoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneuse_cache: bool = Truetie_word_embeddings: bool = Truepad_token_id: int | None = 2bos_token_id: int | None = 4eos_token_id: int | None = 3decoder_start_token_id: int | None = 7initializer_range: float = 0.02vocab_size: int = 16384 )
参数
- is_encoder_decoder (
bool，可选，默认为True) — 指示该模型是否用作编码器/解码器。 - encoder_config (
Union[dict, ParakeetEncoderConfig]，可选) — FastConformer 编码器的配置对象或字典（ParakeetEncoderConfig）。 - decoder_config (
Union[dict, CanaryDecoderConfig], 可选) — Transformer 解码器的配置对象或字典（CanaryDecoderConfig）。 - use_cache (
bool，可选，默认为True) — 模型是否应返回最后一次键/值注意力（并非所有模型都使用）。仅当config.is_decoder=True或模型为仅解码器生成式模型时相关。 - tie_word_embeddings (
bool，可选，默认为True) — 是否根据模型的tied_weights_keys映射来绑定权重嵌入。 - pad_token_id (
int，可选，默认为2) — 词表中用于填充的 token id。 - bos_token_id (
int，可选，默认为4) — 词汇表中用于表示流起始的 token id。 - eos_token_id (
int, 可选，默认为3) — 词汇表中用于表示流结束（end-of-stream）的 token id。 - decoder_start_token_id (
int，可选，默认值为 7) — 用于启动解码的 token id（<|startofcontext|>，即多任务提示的第一个 token）。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - vocab_size (
int，可选，默认为16384) — 模型的词汇表大小。定义了input_ids可以表示的不同 token 数量。
这是用于存储 CanaryModel 配置的类。它根据指定的参数实例化 Canary 模型，并定义模型架构。使用默认值实例化配置将生成与 nvidia/canary-1b-v2 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> 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.configCanaryDecoderConfig
class transformers.CanaryDecoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Truevocab_size: int = 16384hidden_size: int = 1024intermediate_size: int = 4096num_hidden_layers: int = 8num_attention_heads: int = 8num_key_value_heads: int = 8hidden_act: str = 'relu'max_position_embeddings: int = 1024initializer_range: float = 0.02use_cache: bool = Truepad_token_id: int | None = 2bos_token_id: int | None = 4eos_token_id: int | None = 3attention_bias: bool = Trueattention_dropout: int | float | None = 0.0head_dim: int = 128 )
参数
- is_encoder_decoder (
bool，可选，默认为True) — 指示该模型是否用作编码器/解码器。 - vocab_size (
int，可选，默认为16384) — 模型的词汇表大小。定义了input_ids可以表示的不同 token 数量。 - 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, 可选，默认为8) — 这是用于实现 Grouped Query Attention 的 key_value 头数。如果num_key_value_heads=num_attention_heads，模型将使用 Multi Head Attention (MHA)；如果num_key_value_heads=1，模型将使用 Multi Query Attention (MQA)；否则使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的 key 和 value 头应通过对该组内所有原始头进行 meanpooling 来构建。更多详情请参阅 这篇论文。如果未指定，则默认为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) — 模型是否应返回最后一次键/值注意力（并非所有模型都使用）。仅当config.is_decoder=True或模型为仅解码器生成式模型时相关。 - pad_token_id (
int，可选，默认为2) — 词表中用于填充的 token id。 - bos_token_id (
int，可选，默认为4) — 词汇表中用于表示流起始的 token id。 - eos_token_id (
int, 可选，默认为3) — 词汇表中用于表示流结束（end-of-stream）的 token id。 - attention_bias (
bool，可选，默认为True) — 在自注意力机制中，是否在查询、键、值以及输出投影层中使用偏置。 - attention_dropout (
Union[int, float]，可选，默认为0.0) — 注意力概率的 dropout 比率。 - head_dim (
int，可选，默认为128) — 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads
这是用于存储 CanaryModel 配置的类。它根据指定的参数实例化 Canary 模型，并定义模型架构。使用默认值实例化配置将生成与 nvidia/canary-1b-v2 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
>>> 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.configCanaryProcessor
class transformers.CanaryProcessor
< source >( feature_extractor = Nonetokenizer = Nonechat_template = None )
构造一个 CanaryProcessor，它将特征提取器和分词器封装为单个处理器。
CanaryProcessor 提供了 ParakeetFeatureExtractor 和 TokenizersBackend 的所有功能。有关更多信息，请参阅 ~ParakeetFeatureExtractor 和 ~TokenizersBackend。
apply_transcription_request
< source >( 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 = Nonepunctuation: bool = Truetranscription: str | list[str] | None = Nonetokenize: bool = True**kwargs: *<class 'transformers.models.canary.processing_canary.CanaryProcessorKwargs'> ) → BatchFeature or list[str]
参数
- 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) — 是否要求在输出中包含标点和首字母大写。 - transcription (
str或list[str]，可选) — 用于训练的目标转录文本（或译文），每个音频对应一个。提供时，每个转录文本将作为助手轮次写入，并返回labels（参见__call__()中的output_labels）。 - tokenize (
bool，可选，默认为True) — 是否对提示词进行分词并处理音频。如果为False，则不会加载音频，提示词将以字符串形式返回，其中包含未展开的音频占位符。将这些提示词与音频一起传递给处理器，即processor(text=prompts, audio=audio)，其输出与tokenize=True时相同。 - **kwargs —
转发给 apply_chat_template() 的额外关键字参数。
处理器关键字参数（例如
text_kwargs、audio_kwargs、……）应通过processor_kwargs={...}传递。
返回值
BatchFeature 或 list[str]
当 tokenize=False 时，每个音频对应一个提示；否则，处理器会输出可直接传递给 CanaryForConditionalGeneration.generate() 的结果，或在给定 transcription 时传递给 CanaryForConditionalGeneration.forward() 以计算损失。
在无需手动编写聊天模板的情况下，为推理或（当提供 transcription 时）为训练准备转录或翻译的输入。
CanaryModel
class transformers.CanaryModel
< source >( config: CanaryConfig )
参数
- config (CanaryConfig) — 包含模型所有参数的模型配置类。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
裸的 Canary 模型（FastConformer 编码器 + Transformer 解码器），输出原始隐藏状态，顶部未添加任何特定头。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.LongTensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: tuple[tuple[torch.Tensor]] | None = Nonepast_key_values: transformers.cache_utils.EncoderDecoderCache | None = Nonedecoder_inputs_embeds: tuple[torch.Tensor] | None = Nonedecoder_position_ids: tuple[torch.LongTensor] | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqModelOutput or tuple(torch.Tensor)
参数
- input_features (
torch.Tensor，形状为(batch_size, audio_length)) — 原始语音波形的浮点值。可以通过将.flac或.wav音频文件加载为list[float]、numpy.ndarray或torch.Tensor类型的数组来获取原始语音波形，例如 使用 torchcodec 库（pip install torchcodec）或 soundfile 库（pip install soundfile）。要将该数组处理为input_features，应使用 AutoFeatureExtractor 进行填充并将其转换为torch.Tensor类型的张量。 - attention_mask (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 [0, 1]：1 表示未屏蔽的标记，0 表示被屏蔽的标记。什么是注意力掩码？[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- decoder_input_ids (
torch.LongTensor形状为(batch_size, target_sequence_length), ，可选) — 解码器输入序列中各 token 在词汇表中的索引。可通过 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。什么是解码器输入 ID？可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- decoder_attention_mask（形状为
(batch_size, target_sequence_length)的torch.LongTensor，可选） — 用于避免对特定 token 索引执行注意力的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。 - 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, 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由past_key_values在解码的先前阶段返回，当use_cache=True或config.use_cache=True.仅允许将 Cache 实例作为输入，请参阅我们的 kv cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - 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)) — 输入序列中每个 token 在位置嵌入中的位置索引。 用于计算直至config.decoder_config.max_position_embeddings的位置嵌入。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。
返回值
Seq2SeqModelOutput 或 tuple(torch.Tensor)
一个 Seq2SeqModelOutput 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（CanaryConfig）和输入。
CanaryModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型解码器最后一层输出的隐藏状态序列。如果使用了
past_key_values，则仅输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。past_key_values（
EncoderDecoderCache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 EncoderDecoderCache 实例。更多详情，请参阅我们的 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（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选）— 模型编码器最后一层输出的隐藏状态序列。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 之后的注意力权重，用于在自注意力头中计算加权平均值。
示例：
>>> 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
class transformers.CanaryForConditionalGeneration
< source >( config: CanaryConfig )
参数
- config (CanaryConfig) — 包含模型所有参数的模型配置类。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
带有语言建模头的 Canary 模型。可用于多语言自动语音识别和语音转文本翻译。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.LongTensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: tuple[tuple[torch.Tensor]] | None = Nonepast_key_values: transformers.cache_utils.EncoderDecoderCache | None = Nonedecoder_inputs_embeds: tuple[torch.Tensor] | None = Nonedecoder_position_ids: tuple[torch.LongTensor] | None = Noneuse_cache: bool | None = Nonelabels: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqLMOutput or tuple(torch.Tensor)
参数
- input_features (
torch.Tensor，形状为(batch_size, audio_length)) — 原始语音波形的浮点值。可以通过将.flac或.wav音频文件加载为list[float]、numpy.ndarray或torch.Tensor类型的数组来获取原始语音波形，例如 使用 torchcodec 库（pip install torchcodec）或 soundfile 库（pip install soundfile）。要将该数组处理为input_features，应使用 AutoFeatureExtractor 进行填充并将其转换为torch.Tensor类型的张量。 - attention_mask (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 [0, 1]：1 表示未屏蔽的标记，0 表示被屏蔽的标记。什么是注意力掩码？[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- decoder_input_ids (
torch.LongTensor形状为(batch_size, target_sequence_length), ，可选) — 解码器输入序列中各 token 在词汇表中的索引。可通过 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。什么是解码器输入 ID？可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- decoder_attention_mask（形状为
(batch_size, target_sequence_length)的torch.LongTensor，可选） — 用于避免对特定 token 索引执行注意力的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。 - 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, 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由past_key_values在解码的先前阶段返回，当use_cache=True或config.use_cache=True.仅允许将 Cache 实例作为输入，请参阅我们的 kv cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - 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)) — 输入序列中每个 token 在位置嵌入中的位置索引。 用于计算直至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（参见input_ids的文档字符串）。索引值设为-100的 token 将被忽略（即被掩码），损失仅针对标签位于[0, ..., config.vocab_size]范围内的 token 进行计算。
返回值
Seq2SeqLMOutput 或 tuple(torch.Tensor)
一个 Seq2SeqLMOutput 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（CanaryConfig）和输入。
CanaryForConditionalGeneration 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss（形状为
(1,)的torch.Tensor，可选，在提供labels时返回）— 语言建模损失。logits（形状为
(batch_size, sequence_length, config.vocab_size)的torch.Tensor）— 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。past_key_values（
EncoderDecoderCache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 EncoderDecoderCache 实例。更多详情，请参阅我们的 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（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选）— 模型编码器最后一层输出的隐藏状态序列。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 之后的注意力权重，用于在自注意力头中计算加权平均值。
示例：
>>> 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.'