Transformers documentation
语音编码器-解码器模型
该模型于 2021-04-14 在 HF papers 上发布，并于 2021-09-01 贡献至 Hugging Face Transformers。
语音编码器-解码器模型
SpeechEncoderDecoderModel 可用于初始化语音转文本模型，其中编码器可以是任意预训练的语音自编码模型（例如 Wav2Vec2、Hubert），解码器可以是任意预训练的自回归模型。
使用预训练检查点初始化语音序列到文本序列模型，在语音识别和语音翻译任务中的有效性已在 Changhan Wang、Anne Wu、Juan Pino、Alexei Baevski、Michael Auli 和 Alexis Conneau 的论文 Large-Scale Self- and Semi-Supervised Learning for Speech Translation 中得到了例如的验证。
使用 SpeechEncoderDecoderModel 进行推理的示例，可以参考 Speech2Text2 解码器。
从模型配置中随机初始化 SpeechEncoderDecoderModel
SpeechEncoderDecoderModel 可以通过编码器和解码器的配置进行随机初始化。在下面的示例中，我们展示了如何使用默认的 Wav2Vec2Model 配置作为编码器，以及默认的 BertForCausalLM 配置作为解码器来实现这一点。
from transformers import BertConfig, SpeechEncoderDecoderConfig, SpeechEncoderDecoderModel, Wav2Vec2Config
config_encoder = Wav2Vec2Config()
config_decoder = BertConfig()
config = SpeechEncoderDecoderConfig.from_encoder_decoder_configs(config_encoder, config_decoder)
model = SpeechEncoderDecoderModel(config=config)从预训练编码器和预训练解码器初始化 SpeechEncoderDecoderModel
SpeechEncoderDecoderModel 可以从预训练的编码器检查点和预训练的解码器检查点进行初始化。请注意，任何基于 Transformer 的预训练语音模型，例如 Wav2Vec2、Hubert，都可以用作编码器；而预训练的自编码模型（例如 BERT）、预训练的因果语言模型（例如 GPT2），以及序列到序列模型中预训练的解码器部分（例如 BART 的解码器），都可以用作解码器。
根据您选择作为解码器的架构，交叉注意力层可能会被随机初始化。
从预训练的编码器和解码器检查点初始化 SpeechEncoderDecoderModel 后，需要在下游任务上对模型进行微调，这一点已在 Warm-starting-encoder-decoder 博客文章 中展示。
为此，SpeechEncoderDecoderModel 类提供了一个 SpeechEncoderDecoderModel.from_encoder_decoder_pretrained() 方法。
from transformers import SpeechEncoderDecoderModel
model = SpeechEncoderDecoderModel.from_encoder_decoder_pretrained(
"facebook/hubert-large-ll60k", "google-bert/bert-base-uncased"
)加载现有的 SpeechEncoderDecoderModel 检查点并执行推理
要加载 SpeechEncoderDecoderModel 类的微调检查点，SpeechEncoderDecoderModel 与 Transformers 中的其他模型架构一样，提供了 from_pretrained(...) 方法。
要进行推理，请使用 generate 方法，该方法允许你自回归地生成文本。此方法支持多种解码形式，例如贪心解码、束搜索和多项式采样。
from transformers import Wav2Vec2Processor, SpeechEncoderDecoderModel
from datasets import load_dataset
import torch
# load a fine-tuned speech translation model and corresponding processor
model = SpeechEncoderDecoderModel.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15", device_map="auto")
processor = Wav2Vec2Processor.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15")
# let's perform inference on a piece of English speech (which we'll translate to German)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
input_values = processor(ds[0]["audio"]["array"], return_tensors="pt").to(model.device).input_values
# autoregressively generate transcription (uses greedy decoding by default)
generated_ids = model.generate(input_values)
generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(generated_text)
Mr. Quilter ist der Apostel der Mittelschicht und wir freuen uns, sein Evangelium willkommen heißen zu können.训练
模型创建完成后，可以像 BART、T5 或其他任何编码器-解码器模型一样，在（语音，文本）配对数据集上进行微调。
如您所见，模型计算损失只需要 2 个输入：input_values（即语音输入）和 labels（即编码后的目标序列的 input_ids）。
from datasets import load_dataset
from transformers import AutoFeatureExtractor, AutoTokenizer, SpeechEncoderDecoderModel
encoder_id = "facebook/wav2vec2-base-960h" # acoustic model encoder
decoder_id = "google-bert/bert-base-uncased" # text decoder
feature_extractor = AutoFeatureExtractor.from_pretrained(encoder_id)
tokenizer = AutoTokenizer.from_pretrained(decoder_id)
# Combine pre-trained encoder and pre-trained decoder to form a Seq2Seq model
model = SpeechEncoderDecoderModel.from_encoder_decoder_pretrained(encoder_id, decoder_id)
model.config.decoder_start_token_id = tokenizer.cls_token_id
model.config.pad_token_id = tokenizer.pad_token_id
# load an audio input and pre-process (normalise mean/std to 0/1)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
input_values = feature_extractor(ds[0]["audio"]["array"], return_tensors="pt").to(model.device).input_values
# load its corresponding transcription and tokenize to generate labels
labels = tokenizer(ds[0]["text"], return_tensors="pt").to(model.device).input_ids
# the forward function automatically creates the correct decoder_input_ids
loss = model(input_values=input_values, labels=labels).loss
loss.backward()SpeechEncoderDecoderConfig
class transformers.SpeechEncoderDecoderConfig
< 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 | None = Trueencoder: transformers.configuration_utils.PreTrainedConfig | dict | None = Nonedecoder: transformers.configuration_utils.PreTrainedConfig | dict | None = None )
这是用于存储语音编码器-解码器模型配置的类。它根据指定的参数实例化语音编码器-解码器模型，并定义模型架构。使用默认值实例化配置将得到与 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import BertConfig, Wav2Vec2Config, SpeechEncoderDecoderConfig, SpeechEncoderDecoderModel
>>> # Initializing a Wav2Vec2 & BERT style configuration
>>> config_encoder = Wav2Vec2Config()
>>> config_decoder = BertConfig()
>>> config = SpeechEncoderDecoderConfig(encoder=config_encoder, decoder=config_decoder)
>>> # Initializing a Wav2Vec2Bert model from a Wav2Vec2 & google-bert/bert-base-uncased style configurations
>>> model = SpeechEncoderDecoderModel(config=config)
>>> # Accessing the model configuration
>>> config_encoder = model.config.encoder
>>> config_decoder = model.config.decoder
>>> # set decoder config to causal lm
>>> config_decoder.is_decoder = True
>>> config_decoder.add_cross_attention = True
>>> # Saving the model, including its configuration
>>> model.save_pretrained("my-model")
>>> # loading model and config from pretrained folder
>>> encoder_decoder_config = SpeechEncoderDecoderConfig.from_pretrained("my-model")
>>> model = SpeechEncoderDecoderModel.from_pretrained("my-model", config=encoder_decoder_config)from_encoder_decoder_configs
< source >( encoder_config: PreTrainedConfigdecoder_config: PreTrainedConfig**kwargs ) → SpeechEncoderDecoderConfig
配置对象的实例
从预训练的编码器模型配置和解码器模型配置实例化一个 SpeechEncoderDecoderConfig（或其派生类）。
SpeechEncoderDecoderModel
class transformers.SpeechEncoderDecoderModel
< source >( config: transformers.configuration_utils.PreTrainedConfig | None = Noneencoder: transformers.modeling_utils.PreTrainedModel | None = Nonedecoder: transformers.modeling_utils.PreTrainedModel | None = None )
参数
- config (PreTrainedConfig, 可选) — 包含模型所有参数的模型配置类。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
- encoder (
PreTrainedModel，可选) — 要使用的编码器模型。 - decoder (
PreTrainedModel，可选) — 要使用的解码器模型。
输出原始隐藏状态、顶部未附加任何特定头部的裸语音编码器-解码器模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( inputs: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.BoolTensor] = Noneencoder_outputs: tuple[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonedecoder_inputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Noneinput_values: typing.Optional[torch.Tensor] = Noneinput_features: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = None**kwargs ) → Seq2SeqLMOutput or tuple(torch.Tensor)
参数
- inputs (
torch.Tensor，形状为(batch_size, sequence_length)或(batch_size, sequence_length, feature_dim)，可选) — 输入原始语音波形或语音特征的浮点数值。这些值可以通过将.flac或.wav音频文件加载为list[float]、numpy.ndarray或torch.Tensor类型的数组来获得，例如 使用 torchcodec 库（pip install torchcodec）或 soundfile 库（pip install soundfile）。 要将数组准备为inputs，应使用 Wav2Vec2Processor 或 Speech2TextProcessor 进行填充并转换为torch.Tensor类型的张量。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- decoder_input_ids (
torch.LongTensor形状为(batch_size, target_sequence_length), 可选) — 解码器输入序列中各 token 在词汇表中的索引。可通过 PreTrainedTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。什么是输入 ID？如果使用 past_key_values，则只需输入最后一个 decoder_input_ids（参见 past_key_values）。在训练时，模型会自动通过将 labels 向右移位、用 pad_token_id 替换 -100，并在前面添加 decoder_start_token_id 来创建 decoder_input_ids。可以使用 PreTrainedTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
如果使用了
past_key_values，则可以选择性地仅输入最后几个decoder_input_ids（参见past_key_values）。在训练过程中，模型会自动将
labels向右移位，用pad_token_id替换 -100，并在前面添加decoder_start_token_id，从而生成decoder_input_ids。 - decoder_attention_mask（形状为
(batch_size, target_sequence_length)的torch.BoolTensor，可选） — 默认行为：生成一个忽略decoder_input_ids中填充标记的张量。默认情况下也会使用因果掩码。 - encoder_outputs (
tuple[torch.Tensor]，可选) — 元组由 (last_hidden_state，可选：hidden_states，可选：attentions)last_hidden_state的形状为(batch_size, sequence_length, hidden_size)，可选)，是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力。 - past_key_values (
~cache_utils.Cache, 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由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 (
torch.Tensor，形状为(batch_size, target_sequence_length, hidden_size)，可选) — 可选地，您可以选择直接传入嵌入表示，而不是传入decoder_input_ids。如果您希望对decoder_input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - labels（形状为
(batch_size, sequence_length)的torch.LongTensor，可选）— 用于计算解码器掩码语言建模损失的标签。索引应在[-100, 0, ..., config.vocab_size]范围内（参见input_ids的文档字符串）。索引设置为-100的令牌将被忽略（即被掩码），损失仅针对标签位于[0, ..., config.vocab_size]范围内的令牌进行计算。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。 - output_attentions (
bool, 可选) — 是否返回所有注意力层的注意力张量。有关详细信息，请参阅返回张量中的attentions。 - output_hidden_states (
bool，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的hidden_states。 - input_values (
torch.Tensor，形状为(batch_size, sequence_length)，可选) — 输入原始语音波形的浮点值。可以通过将 .flac 或 .wav 音频文件加载为 list[float] 或 numpy.ndarray 类型的数组来获取这些值，例如 使用 torchcodec 库（pip install torchcodec）或 soundfile 库（pip install soundfile）。要将该数组处理为 input_values，应使用 Wav2Vec2Processor 进行填充并转换为 torch.Tensor 类型的张量。详情请参见 Wav2Vec2Processor.call()。 - input_features (
torch.Tensor，形状为(batch_size, sequence_length, feature_dim)，可选) — 与输入音频特征对应的张量。可以使用feature_extractor_class获取音频特征。有关详细信息，请参阅feature_extractor_class.__call__（processor_class使用feature_extractor_class来处理音频）。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
Seq2SeqLMOutput 或 tuple(torch.Tensor)
一个 Seq2SeqLMOutput 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（SpeechEncoderDecoderConfig）和输入。
SpeechEncoderDecoderModel 的 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 之后的注意力权重，用于在自注意力头中计算加权平均值。
示例：
>>> from transformers import SpeechEncoderDecoderModel, AutoProcessor
>>> from datasets import load_dataset
>>> import torch
>>> processor = AutoProcessor.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15")
>>> model = SpeechEncoderDecoderModel.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> input_values = processor(ds[0]["audio"]["array"], return_tensors="pt").input_values
>>> # Inference: Translate English speech to German
>>> generated = model.generate(input_values)
>>> decoded = processor.batch_decode(generated, skip_special_tokens=True)[0]
>>> decoded
'Mr. Quilter ist der Apostel der Mittelschicht und wir freuen uns, sein Evangelium willkommen heißen zu können.'
>>> # Training: Train model on English transcription
>>> labels = processor(text=ds[0]["text"], return_tensors="pt").input_ids
>>> loss = model(input_values, labels=labels).loss
>>> loss.backward()from_encoder_decoder_pretrained
< source >( encoder_pretrained_model_name_or_path: str | None = Nonedecoder_pretrained_model_name_or_path: str | None = None*model_args**kwargs )
参数
- encoder_pretrained_model_name_or_path (
str, 可选) — 初始化编码器所需的信息。可以是以下之一：- 一个字符串，表示托管在 huggingface.co 模型仓库中的预训练模型的 model id。
- 指向一个目录的路径，该目录包含使用 save_pretrained() 保存的模型权重，例如
./my_model_directory/。
- decoder_pretrained_model_name_or_path (
str, 可选, 默认为None) — 启动解码器所需的信息。可以是：- 一个字符串，表示托管在 huggingface.co 模型仓库中的预训练模型的 model id。
- 指向一个目录的路径，该目录包含使用 save_pretrained() 保存的模型权重，例如
./my_model_directory/。
- model_args（其余位置参数，可选）—
所有其余位置参数都会传递给底层模型的
__init__方法。 - kwargs (其余关键字参数字典， 可选) —
可用于更新配置对象（在加载之后）并初始化模型（例如，
output_attentions=True).- 要更新编码器配置，请为每个配置参数使用前缀 encoder_。
- 要更新解码器配置，请为每个配置参数使用前缀 decoder_。
- 要更新父模型配置，请勿为每个配置参数使用前缀。
行为取决于是否提供了
config或自动加载。
从库中的一个或两个基础类实例化编码器和解码器，并使用预训练模型检查点。
模型默认使用 model.eval() 设置为评估模式（Dropout 模块被禁用）。若要训练模型，需先使用 model.train() 将其切换回训练模式。
示例：
>>> from transformers import SpeechEncoderDecoderModel
>>> # initialize a wav2vec2bert from a pretrained Wav2Vec2 and a pretrained BERT model. Note that the cross-attention layers will be randomly initialized
>>> model = SpeechEncoderDecoderModel.from_encoder_decoder_pretrained(
... "facebook/wav2vec2-base-960h", "google-bert/bert-base-uncased"
... )
>>> # saving model after fine-tuning
>>> model.save_pretrained("./wav2vec2bert")
>>> # load fine-tuned model
>>> model = SpeechEncoderDecoderModel.from_pretrained("./wav2vec2bert")