Transformers documentation
编码器-解码器模型
该模型于 2017-06-12 在 HF papers 上发表，并于 2020-11-16 贡献至 Hugging Face Transformers。
编码器-解码器模型
EncoderDecoderModel 使用任意预训练自编码器和预训练自回归模型初始化一个序列到序列模型。如使用预训练编码器进行文本摘要所示，该模型在序列生成任务中表现有效，其中使用BertModel作为编码器和解码器。
该模型由 thomwolf 贡献。
点击右侧边栏中的 Encoder Decoder 模型，以查看更多将 Encoder Decoder 应用于不同语言任务的示例。
以下示例演示了如何使用 Pipeline、AutoModel 以及命令行来生成文本。
from transformers import AutoModelForCausalLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("patrickvonplaten/bert2bert-cnn_dailymail-fp16")
model = AutoModelForCausalLM.from_pretrained("patrickvonplaten/bert2bert-cnn_dailymail-fp16", device_map="auto",attn_implementation="sdpa")
text = "Plants create energy through a process known as photosynthesis. This involves capturing sunlight and converting carbon dioxide and water into glucose and oxygen."
inputs = tokenizer(text, return_tensors="pt", truncation=True, padding=True).to(model.device)
summary = model.generate(**inputs, max_length=60, num_beams=4, early_stopping=True)
print(tokenizer.decode(summary[0], skip_special_tokens=True))备注
- EncoderDecoderModel 可以使用任意预训练的编码器和解码器进行初始化。但根据解码器架构的不同，交叉注意力层可能会被随机初始化。
这些模型需要下游微调，如这篇博客文章中所述。使用from_encoder_decoder_pretrained()来组合编码器和解码器检查点。
from transformers import BertTokenizer, EncoderDecoderModel
tokenizer = BertTokenizer.from_pretrained("google-bert/bert-base-uncased")
model = EncoderDecoderModel.from_encoder_decoder_pretrained(
"google-bert/bert-base-uncased",
"google-bert/bert-base-uncased"
)- Encoder Decoder 模型可以像 BART、T5 或其他任何 encoder-decoder 模型一样进行微调。计算损失只需要两个输入：
input_ids和labels。有关更详细的训练示例，请参阅此 notebook。
from transformers import BertTokenizer, EncoderDecoderModel
tokenizer = BertTokenizer.from_pretrained("google-bert/bert-base-uncased")
model = EncoderDecoderModel.from_encoder_decoder_pretrained("google-bert/bert-base-uncased", "google-bert/bert-base-uncased")
model.config.decoder_start_token_id = tokenizer.cls_token_id
model.config.pad_token_id = tokenizer.pad_token_id
input_ids = tokenizer(
"The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side.During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930. It was the first structure to reach a height of 300 metres. Due to the addition of a broadcasting aerial at the top of the tower in 1957, it is now taller than the Chrysler Building by 5.2 metres (17 ft).Excluding transmitters, the Eiffel Tower is the second tallest free-standing structure in France after the Millau Viaduct.",
return_tensors="pt",
).input_ids
labels = tokenizer(
"the eiffel tower surpassed the washington monument to become the tallest structure in the world. it was the first structure to reach a height of 300 metres in paris in 1930. it is now taller than the chrysler building by 5. 2 metres ( 17 ft ) and is the second tallest free - standing structure in paris.",
return_tensors="pt",
).input_ids
# the forward function automatically creates the correct decoder_input_ids
loss = model(input_ids=input_ids, labels=labels).loss- EncoderDecoderModel 可以通过编码器配置和解码器配置进行随机初始化，如下所示。
from transformers import BertConfig, EncoderDecoderConfig, EncoderDecoderModel
config_encoder = BertConfig()
config_decoder = BertConfig()
config = EncoderDecoderConfig.from_encoder_decoder_configs(config_encoder, config_decoder)
model = EncoderDecoderModel(config=config)- Encoder Decoder Model 也可以用于翻译，如下所示。
from transformers import AutoTokenizer, EncoderDecoderModel
# Load a pre-trained translation model
model_name = "google/bert2bert_L-24_wmt_en_de"
tokenizer = AutoTokenizer.from_pretrained(model_name, pad_token="<pad>", eos_token="</s>", bos_token="<s>")
model = EncoderDecoderModel.from_pretrained(model_name, device_map="auto")
# Input sentence to translate
input_text = "Plants create energy through a process known as"
# Encode the input text
inputs = tokenizer(input_text, return_tensors="pt", add_special_tokens=False).to(model.device).input_ids
# Generate the translated output
outputs = model.generate(inputs)[0]
# Decode the output tokens to get the translated sentence
translated_text = tokenizer.decode(outputs, skip_special_tokens=True)
print("Translated text:", translated_text)EncoderDecoderConfig
class transformers.EncoderDecoderConfig
< 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 = Nonepad_token_id: int | None = Nonedecoder_start_token_id: int | None = None )
参数
- is_encoder_decoder (
bool，可选，默认为True) — 指示该模型是否用作编码器/解码器。 - encoder (
Union[~configuration_utils.PreTrainedConfig, dict], 可选) — 编码器骨干网络的配置对象或字典。 - decoder (
Union[~configuration_utils.PreTrainedConfig, dict]，可选) — 解码器骨干网络的配置对象或字典。 - pad_token_id (
int, 可选) — 词表中用于填充的 token id。 - decoder_start_token_id (
int, 可选) — 如果编码器-解码器模型使用不同于bos的 token 开始解码，则指定该 token 的 id。
这是用于存储 Encoder Decoder 模型配置的类。它根据指定的参数实例化 Encoder Decoder 模型，并定义模型架构。使用默认值实例化配置将生成与 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import BertConfig, EncoderDecoderConfig, EncoderDecoderModel
>>> # Initializing a BERT google-bert/bert-base-uncased style configuration
>>> config_encoder = BertConfig()
>>> config_decoder = BertConfig()
>>> config = EncoderDecoderConfig(encoder=config_encoder, decoder=config_decoder)
>>> # Initializing a Bert2Bert model (with random weights) from the google-bert/bert-base-uncased style configurations
>>> model = EncoderDecoderModel(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 = EncoderDecoderConfig.from_pretrained("my-model")
>>> model = EncoderDecoderModel.from_pretrained("my-model", config=encoder_decoder_config)from_encoder_decoder_configs
< source >( encoder_config: PreTrainedConfigdecoder_config: PreTrainedConfig**kwargs ) → EncoderDecoderConfig
配置对象的实例
从预训练的编码器模型配置和 解码器模型配置实例化一个 EncoderDecoderConfig（或其派生类）。
EncoderDecoderModel
class transformers.EncoderDecoderModel
< 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，可选) — 要使用的解码器模型。
未添加任何特定头部的裸 Encoder Decoder Model，直接输出原始 hidden-states。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.FloatTensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.BoolTensor] = Noneencoder_outputs: tuple[torch.FloatTensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonedecoder_inputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs ) → Seq2SeqLMOutput or tuple(torch.FloatTensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.FloatTensor形状为(batch_size, sequence_length), 可选) — 用于避免对填充（padding）标记索引执行注意力计算的掩码。掩码值取自[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.FloatTensor]，可选) — 元组由 (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。 - inputs_embeds (
torch.FloatTensor，形状为(batch_size, sequence_length, hidden_size)，可选) — 可选地，您可以选择直接传入嵌入表示，而不是传入input_ids。如果您希望对input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - decoder_inputs_embeds (
torch.FloatTensor，形状为(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）。
返回值
Seq2SeqLMOutput 或 tuple(torch.FloatTensor)
一个 Seq2SeqLMOutput，或者一个由 torch.FloatTensor 组成的元组（如果传入了 return_dict=False，或者当 config.return_dict=False 时），其包含的元素取决于配置（EncoderDecoderConfig）和输入。
EncoderDecoderModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.FloatTensor，形状为(1,)，可选，在提供labels时返回) — 语言建模损失。logits（形状为
(batch_size, sequence_length, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。past_key_values（
EncoderDecoderCache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 EncoderDecoderCache 实例。更多详情，请参阅我们的 kv cache 指南。包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见
past_key_values输入）加速顺序解码。decoder_hidden_states (
tuple(torch.FloatTensor)，可选，在传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.FloatTensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。解码器在每一层输出处的隐藏状态，以及初始嵌入输出。
decoder_attentions（
tuple(torch.FloatTensor)，可选，在传入output_attentions=True或config.output_attentions=True时返回）—— 一个torch.FloatTensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
cross_attentions（
tuple(torch.FloatTensor)，可选，在传入output_attentions=True或config.output_attentions=True时返回）—— 一个torch.FloatTensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
encoder_last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.FloatTensor，可选）— 模型编码器最后一层输出的隐藏状态序列。encoder_hidden_states (
tuple(torch.FloatTensor)，可选，在传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.FloatTensor元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每一层输出的一个张量），形状为(batch_size, sequence_length, hidden_size)。编码器在每一层输出处的隐藏状态，以及初始嵌入输出。
encoder_attentions（
tuple(torch.FloatTensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回）—— 一个torch.FloatTensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
示例：
>>> from transformers import EncoderDecoderModel, BertTokenizer
>>> import torch
>>> tokenizer = BertTokenizer.from_pretrained("google-bert/bert-base-uncased")
>>> model = EncoderDecoderModel.from_encoder_decoder_pretrained(
... "google-bert/bert-base-uncased", "google-bert/bert-base-uncased"
... ) # initialize Bert2Bert from pre-trained checkpoints
>>> # training
>>> model.config.decoder_start_token_id = tokenizer.cls_token_id
>>> model.config.pad_token_id = tokenizer.pad_token_id
>>> model.config.vocab_size = model.config.decoder.vocab_size
>>> input_ids = tokenizer("This is a really long text", return_tensors="pt").input_ids
>>> labels = tokenizer("This is the corresponding summary", return_tensors="pt").input_ids
>>> outputs = model(input_ids=input_ids, labels=labels)
>>> loss, logits = outputs.loss, outputs.logits
>>> # save and load from pretrained
>>> model.save_pretrained("bert2bert")
>>> model = EncoderDecoderModel.from_pretrained("bert2bert")
>>> # generation
>>> generated = model.generate(input_ids)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 EncoderDecoderModel
>>> # initialize a bert2bert from two pretrained BERT models. Note that the cross-attention layers will be randomly initialized
>>> model = EncoderDecoderModel.from_encoder_decoder_pretrained("google-bert/bert-base-uncased", "google-bert/bert-base-uncased")
>>> # saving model after fine-tuning
>>> model.save_pretrained("./bert2bert")
>>> # load fine-tuned model
>>> model = EncoderDecoderModel.from_pretrained("./bert2bert")