Transformers 4.37 中文文档（十五）

原文：huggingface.co/docs/transformers

生成

原文链接：huggingface.co/docs/transformers/v4.37.2/en/main_classes/text_generation

每个框架都有一个用于文本生成的GenerationMixin类中实现的生成方法：

• PyTorch 的 generate()在 GenerationMixin 中实现。

• TensorFlow 的 generate()在 TFGenerationMixin 中实现。

• Flax/JAX 的 generate()在 FlaxGenerationMixin 中实现。

无论您选择哪个框架，您都可以使用 GenerationConfig 类实例对生成方法进行参数化。请参考此类以获取完整的生成参数列表，这些参数控制生成方法的行为。

要了解如何检查模型的生成配置，了解默认值，如何临时更改参数以及如何创建和保存自定义生成配置，请参考文本生成策略指南。该指南还解释了如何使用相关功能，如标记流。

GenerationConfig

class transformers.GenerationConfig

<来源>

( **kwargs )

控制输出长度的参数

• max_length（int，可选，默认为 20）— 生成的标记可以具有的最大长度。对应于输入提示的长度+max_new_tokens。如果也设置了max_new_tokens，则其效果将被覆盖。

• max_new_tokens（int，可选）— 生成的最大标记数，忽略提示中的标记数。

• min_length（int，可选，默认为 0）— 要生成的序列的最小长度。对应于输入提示的长度+min_new_tokens。如果也设置了min_new_tokens，则其效果将被覆盖。

• min_new_tokens（int，可选）— 生成的最小标记数，忽略提示中的标记数。

• early_stopping（bool或str，可选，默认为False）— 控制基于束搜索的方法的停止条件，如束搜索。它接受以下值：True，表示一旦有num_beams个完整候选项就停止生成；False，应用启发式方法，当很难找到更好的候选项时停止生成；"never"，束搜索过程仅在不能有更好的候选项时停止（经典的束搜索算法）。

• max_time(float, 可选) — 允许计算运行的最长时间（以秒为单位）。在分配的时间已过后，生成仍将完成当前传递。

控制生成策略使用的参数

• do_sample（bool，可选，默认为False）— 是否使用采样；否则使用贪婪解码。

• num_beams（int，可选，默认为 1）— 用于束搜索的束数。1 表示不进行束搜索。

• num_beam_groups（int，可选，默认为 1）— 将num_beams分成多个组以确保不同组的束之间的多样性。有关更多详细信息，请参阅此论文。

• penalty_alpha (float, optional) — 这些值平衡了对比搜索解码中模型置信度和退化惩罚。

• use_cache (bool, optional, defaults to True) — 模型是否应使用过去的最后键/值注意力（如果适用于模型）来加快解码速度。

用于操纵模型输出 logits 的参数

• temperature (float, optional, defaults to 1.0) — 用于调节下一个标记概率的值。

• top_k (int, optional, defaults to 50) — 要保留的最高概率词汇标记的数量，用于进行 top-k 过滤。

• top_p (float, optional, defaults to 1.0) — 如果设置为小于 1 的浮点数，则仅保留概率加起来达到top_p或更高的最可能标记集合以进行生成。

• typical_p (float, optional, defaults to 1.0) — 本地典型性衡量了预测下一个目标标记的条件概率与预测随机下一个标记的条件概率之间的相似程度，给定已生成的部分文本。如果设置为小于 1 的浮点数，则保留概率加起来达到typical_p或更高的最典型标记集合以进行生成。有关更多详细信息，请参见此论文。

• epsilon_cutoff (float, optional, defaults to 0.0) — 如果设置为 0 和 1 之间的浮点数，只有条件概率大于epsilon_cutoff的标记才会被采样。在论文中，建议的值范围从 3e-4 到 9e-4，取决于模型的大小。有关更多详细信息，请参见截断采样作为语言模型去平滑。

• eta_cutoff (float, optional, defaults to 0.0) — Eta 采样是局部典型采样和 epsilon 采样的混合。如果设置为 0 和 1 之间的浮点数，仅当一个标记大于eta_cutoff或sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits))时才考虑。后一项直观上是下一个标记概率的期望，乘以sqrt(eta_cutoff)。在论文中，建议的值范围从 3e-4 到 2e-3，取决于模型的大小。有关更多详细信息，请参见截断采样作为语言模型去平滑。

• diversity_penalty (float, optional, defaults to 0.0) — 如果一个 beam 在特定时间生成与其他组中的任何 beam 相同的标记，则从该 beam 的得分中减去此值。请注意，只有在启用group beam search时，diversity_penalty才有效。

• repetition_penalty (float, optional, defaults to 1.0) — 重复惩罚的参数。1.0 表示没有惩罚。有关更多详细信息，请参见此论文。

• encoder_repetition_penalty (float, optional, defaults to 1.0) — 编码器重复惩罚的参数。对于不在原始输入中的序列施加指数惩罚。1.0 表示没有惩罚。

• length_penalty (float, optional, defaults to 1.0) — 用于基于 beam 的生成的长度的指数惩罚。它作为指数应用于序列长度，然后用于分割序列的得分。由于得分是序列的对数似然（即负数），length_penalty > 0.0 会促进更长的序列，而length_penalty < 0.0 会鼓励更短的序列。

• no_repeat_ngram_size (int, optional, defaults to 0) — 如果设置为大于 0 的整数，那么该大小的所有 ngram 只能出现一次。

• bad_words_ids(List[List[int]], optional) — 不允许生成的标记 id 列表。查看 NoBadWordsLogitsProcessor 以获取更多文档和示例。

• force_words_ids(List[List[int]] 或 List[List[List[int]]], optional) — 必须生成的标记 id 列表。如果给定 List[List[int]]，则将其视为必须包含的简单单词列表，与 bad_words_ids 相反。如果给定 List[List[List[int]]]，这将触发一个分离约束，其中可以允许每个单词的不同形式。

• renormalize_logits (bool, optional, 默认为 False) — 在应用所有标记处理器或包装器（包括自定义的）后是否重新归一化标记。强烈建议将此标志设置为 True，因为搜索算法假定得分标记已归一化，但某些标记处理器或包装器会破坏归一化。

• constraints (List[Constraint], optional) — 可以添加到生成中的自定义约束，以确保输出将包含由 Constraint 对象定义的某些标记的使用，以最合理的方式。

• forced_bos_token_id (int, optional, 默认为 model.config.forced_bos_token_id) — 在 decoder_start_token_id 后强制作为第一个生成的标记的标记 id。对于像 mBART 这样的多语言模型很有用，其中第一个生成的标记需要是目标语言标记。

• forced_eos_token_id (Union[int, List[int]], optional, 默认为 model.config.forced_eos_token_id) — 当达到 max_length 时，强制作为最后生成的标记的标记 id。可选择使用列表设置多个 end-of-sequence 标记。

• remove_invalid_values (bool, optional, 默认为 model.config.remove_invalid_values) — 是否删除模型可能的 nan 和 inf 输出，以防止生成方法崩溃。请注意，使用 remove_invalid_values 可以减慢生成速度。

• exponential_decay_length_penalty (tuple(int, float), optional) — 此元组在生成一定数量的标记后添加指数增长的长度惩罚。元组应包含：(start_index, decay_factor)，其中 start_index 表示惩罚开始的位置，decay_factor 表示指数衰减的因子。

• suppress_tokens (List[int], optional) — 生成时将被抑制的标记列表。SupressTokens 标记处理器将将它们的对数概率设置为 -inf，以便它们不被抽样。

• begin_suppress_tokens (List[int], optional) — 生成开始时将被抑制的标记列表。SupressBeginTokens 标记处理器将将它们的对数概率设置为 -inf，以便它们不被抽样。

• forced_decoder_ids (List[List[int]], optional) — 一对整数的列表，指示在抽样之前将强制执行的生成索引到标记索引的映射。例如，[[1, 123]] 表示第二个生成的标记将始终是索引为 123 的标记。

• sequence_bias (Dict[Tuple[int], float], optional)) — 将标记序列映射到其偏差项的字典。正偏差增加选择该序列的几率，而负偏差则相反。查看 SequenceBiasLogitsProcessor 以获取更多文档和示例。

• guidance_scale (float, optional) — 分类器自由引导（CFG）的引导比例。通过设置 guidance_scale > 1 启用 CFG。更高的引导比例鼓励模型生成与输入提示更紧密相关的样本，通常以牺牲质量为代价。

• low_memory (bool, optional) — 用于对比搜索的顺序 topk 开关，以减少内存峰值。与对比搜索一起使用。

generate 输出变量的定义参数

• num_return_sequences(int, optional, 默认为 1) — 每个批次中每个元素独立计算返回序列的数量。

• output_attentions (bool, optional, defaults to False) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量中的 attentions。

• output_hidden_states (bool, optional, defaults to False) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的 hidden_states。

• output_scores (bool, optional, defaults to False) — 是否返回预测分数。有关更多详细信息，请参阅返回张量中的 scores。

• return_dict_in_generate (bool, optional, defaults to False) — 是否返回 ModelOutput 而不是普通元组。

可在生成时使用的特殊标记

• pad_token_id (int, optional) — 填充标记的 id。

• bos_token_id (int, optional) — 序列开始标记的 id。

• eos_token_id (Union[int, List[int]], optional) — 序列结束标记的 id。可选择使用列表设置多个序列结束标记。

专属于编码器-解码器模型的生成参数

• encoder_no_repeat_ngram_size (int, optional, defaults to 0) — 如果设置为大于 0 的整数，则在 encoder_input_ids 中出现的该大小的所有 n 元组不能出现在 decoder_input_ids 中。

• decoder_start_token_id (int, optional) — 如果编码器-解码器模型开始解码时使用与 bos 不同的标记，则为该标记的 id。

专属于 助手生成 — 定义助手模型在每次迭代之前生成的推测标记数量。num_assistant_tokens 的值越高，生成的推测性越强：如果助手模型表现良好，可以实现更大的加速，如果助手模型需要大量修正，则实现的加速度较低。

• num_assistant_tokens_schedule (str, optional, defaults to "heuristic") — 定义推断期间最大助手标记应该如何更改的计划。

  • "_heuristic_: 当所有推测标记都正确时，将 num_assistant_tokens 增加 2，否则减少 1

  • "constant": 在生成期间 num_assistant_tokens 保持不变

通配符

用于生成任务配置的类。generate 调用支持以下文本解码器、文本到文本、语音到文本和视觉到文本模型的生成方法：

• 通过调用 greedy_search() 实现贪婪解码，如果 num_beams=1 且 do_sample=False

• 通过调用 contrastive_search() 实现对比搜索，如果 penalty_alpha>0. 且 top_k>1

• 通过调用 sample() 实现多项式采样，如果 num_beams=1 且 do_sample=True

• 通过调用 beam_search() 实现束搜索解码，如果 num_beams>1 且 do_sample=False

• 通过调用 beam_sample() 实现束搜索多项式采样，如果 num_beams>1 且 do_sample=True

• 通过调用 group_beam_search() 实现多样束搜索解码，如果 num_beams>1 且 num_beam_groups>1

• 通过调用 constrained_beam_search() 实现受限束搜索解码，如果 constraints!=None 或 force_words_ids!=None

• 通过将assistant_model传递给.generate()来进行辅助解码调用assisted_decoding()。

您不需要直接调用上述任何方法。将自定义参数值传递给‘.generate()‘。要了解更多关于解码策略的信息，请参考文本生成策略指南。

这些标志中的大部分控制生成的对数或停止标准。确保您查看生成相关类以获取可能操作的完整描述，以及它们用法的示例。

from_pretrained

<来源>

( pretrained_model_name: Union config_file_name: Union = None cache_dir: Union = None force_download: bool = False local_files_only: bool = False token: Union = None revision: str = 'main' **kwargs ) → export const metadata = 'undefined';GenerationConfig

参数

• pretrained_model_name (str或os.PathLike) — 这可以是：

  • 一个字符串，预训练模型配置的模型 ID，托管在 huggingface.co 模型存储库中。有效的模型 ID 可以位于根级别，如bert-base-uncased，或命名空间在用户或组织名称下，如dbmdz/bert-base-german-cased。

  • 一个目录的路径，其中包含使用 save_pretrained()方法保存的配置文件，例如，./my_model_directory/。

• config_file_name (str或os.PathLike，可选，默认为"generation_config.json") — 要从pretrained_model_name加载的生成配置 JSON 文件的名称。

• cache_dir (str或os.PathLike，可选) — 下载预训练模型配置文件时应缓存的目录路径，如果不应使用标准缓存。

• force_download (bool，可选，默认为False) — 是否强制（重新）下载配置文件并覆盖缓存版本（如果存在）。

• resume_download (bool，可选，默认为False) — 是否删除接收不完整的文件。如果存在这样的文件，则尝试恢复下载。

• proxies (Dict[str, str]，可选) — 一个按协议或端点使用的代理服务器字典，例如，{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。代理服务器在每个请求上使用。

• token (str或bool，可选) — 用作远程文件的 HTTP 令牌的令牌。如果为True，或未指定，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。

• revision (str，可选，默认为"main") — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID，因为我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件，所以revision可以是 git 允许的任何标识符。

  要测试您在 Hub 上提交的拉取请求，可以传递`revision=“refs/pr/<pr_number>“。</pr_number>

• return_unused_kwargs (bool，可选，默认为False) — 如果为False，则此函数仅返回最终的配置对象。

  如果为True，则此函数返回一个Tuple(config, unused_kwargs)，其中unused_kwargs是一个字典，其中键/值对的键不是配置属性：即，未使用来更新config的kwargs的部分，否则将被忽略。

• subfolder (str，可选，默认为"") — 如果相关文件位于 huggingface.co 模型存储库的子文件夹中，您可以在此处指定文件夹名称。

• kwargs (Dict[str, Any]，可选) — 任何键的 kwargs 值，这些键是配置属性，将用于覆盖加载的值。关于键/值对的行为，其键不是配置属性，由return_unused_kwargs关键字参数控制。

返回

GenerationConfig

从这个预训练模型实例化的配置对象。

从生成配置文件实例化 GenerationConfig。

示例：

>>> from transformers import GenerationConfig

>>> # Download configuration from huggingface.co and cache.
>>> generation_config = GenerationConfig.from_pretrained("gpt2")

>>> # E.g. config was saved using *save_pretrained('./test/saved_model/')*
>>> generation_config.save_pretrained("./test/saved_model/")
>>> generation_config = GenerationConfig.from_pretrained("./test/saved_model/")

>>> # You can also specify configuration names to your generation configuration file
>>> generation_config.save_pretrained("./test/saved_model/", config_file_name="my_configuration.json")
>>> generation_config = GenerationConfig.from_pretrained("./test/saved_model/", "my_configuration.json")

>>> # If you'd like to try a minor variation to an existing configuration, you can also pass generation
>>> # arguments to `.from_pretrained()`. Be mindful that typos and unused arguments will be ignored
>>> generation_config, unused_kwargs = GenerationConfig.from_pretrained(
...     "gpt2", top_k=1, foo=False, do_sample=True, return_unused_kwargs=True
... )
>>> generation_config.top_k
1

>>> unused_kwargs
{'foo': False}

from_model_config

<来源>

( model_config: PretrainedConfig ) → export const metadata = 'undefined';GenerationConfig

参数

• model_config (PretrainedConfig) — 将用于实例化生成配置的模型配置。

返回

GenerationConfig

从这些参数实例化的配置对象。

从 PretrainedConfig 实例化 GenerationConfig。此函数可用于将可能包含生成参数的旧 PretrainedConfig 对象转换为独立的 GenerationConfig。

save_pretrained

<来源>

( save_directory: Union config_file_name: Union = None push_to_hub: bool = False **kwargs )

参数

• save_directory (str或os.PathLike) — 将保存配置 JSON 文件的目录（如果不存在，将创建）。

• config_file_name (str或os.PathLike, 可选, 默认为"generation_config.json") — 要保存在save_directory中的生成配置 JSON 文件的名称。

• push_to_hub (bool, 可选, 默认为 False) — 在保存模型后是否将其推送到 Hugging Face 模型中心。您可以使用repo_id指定要推送到的存储库（将默认为您的命名空间中的save_directory的名称）。

• kwargs (Dict[str, Any], 可选) — 传递给 push_to_hub()方法的额外关键字参数。

将生成配置对象保存到目录save_directory，以便可以使用 from_pretrained()类方法重新加载它。

GenerationMixin

class transformers.GenerationMixin

<来源>

( )

一个包含自回归文本生成所有函数的类，可作为 PreTrainedModel 中的混合类使用。

该类公开 generate()，可用于：

• 通过调用 greedy_search()实现贪婪解码，如果num_beams=1且do_sample=False

• 通过调用 contrastive_search()实现对比搜索，如果penalty_alpha>0且top_k>1

• 通过调用 sample()实现多项式采样，如果num_beams=1且do_sample=True

• 通过调用 beam_search()实现束搜索解码，如果num_beams>1且do_sample=False

• 通过调用 beam_sample()实现束搜索多项式采样，如果num_beams>1且do_sample=True

• 通过调用 group_beam_search()实现多样化的束搜索解码，如果num_beams>1且num_beam_groups>1

• 通过调用 constrained_beam_search()实现受限束搜索解码，如果constraints!=None或force_words_ids!=None

您不需要直接调用上述任何方法。而是将自定义参数值传递给“generate”。要了解更多有关解码策略的信息，请参考文本生成策略指南。

generate

<来源>

( inputs: Optional = None generation_config: Optional = None logits_processor: Optional = None stopping_criteria: Optional = None prefix_allowed_tokens_fn: Optional = None synced_gpus: Optional = None assistant_model: Optional = None streamer: Optional = None negative_prompt_ids: Optional = None negative_prompt_attention_mask: Optional = None **kwargs ) → export const metadata = 'undefined';ModelOutput or torch.LongTensor

参数

• inputs（根据模态性质变化的torch.Tensor，可选）— 用作生成提示或模型输入到编码器的序列。如果为None，则该方法将使用bos_token_id和批量大小为 1 进行初始化。对于仅解码器模型，inputs应该是input_ids格式。对于编码器-解码器模型，inputs可以表示任何input_ids、input_values、input_features或pixel_values之一。

• generation_config（~generation.GenerationConfig，可选）— 用作生成调用的基本参数化的生成配置。传递给 generate 的**kwargs与generation_config的属性匹配将覆盖它们。如果未提供generation_config，将使用默认值，其加载优先级如下：1）从generation_config.json模型文件中，如果存在；2）从模型配置中。请注意，未指定的参数将继承 GenerationConfig 的默认值，应检查其文档以参数化生成。

• logits_processor（LogitsProcessorList，可选）— 自定义 logits 处理器，用于补充从参数和生成配置构建的默认 logits 处理器。如果传递了已经使用参数或生成配置创建的 logit 处理器，则会引发错误。此功能适用于高级用户。

• stopping_criteria（StoppingCriteriaList，可选）— 自定义停止标准，用于补充从参数和生成配置构建的默认停止标准。如果传递了已经使用参数或生成配置创建的停止标准，则会引发错误。如果您的停止标准取决于scores输入，请确保将return_dict_in_generate=True, output_scores=True传递给generate。此功能适用于高级用户。

• prefix_allowed_tokens_fn（Callable[[int, torch.Tensor], List[int]]，可选）— 如果提供了此函数，则将束搜索限制为每个步骤仅允许的令牌。如果未提供，则不应用任何约束。此函数接受 2 个参数：批次 ID batch_id 和 input_ids。它必须返回一个列表，其中包含下一代步骤的允许令牌，条件是批次 ID batch_id 和先前生成的令牌 inputs_ids。此参数对于基于前缀的受限生成很有用，如自回归实体检索中所述。

• synced_gpus（bool，可选）— 是否继续运行 while 循环直到 max_length。除非被覆盖，否则在 DeepSpeed ZeRO Stage 3 多 GPU 环境下，此标志将设置为True，以避免在其他 GPU 生成之前一个 GPU 完成生成时挂起。否则将设置为False。

• assistant_model（PreTrainedModel，可选）— 一个可以用来加速生成的助手模型。助手模型必须具有完全相同的分词器。当使用助手模型预测候选令牌比使用您调用 generate 的模型进行生成要快得多时，加速就会实现。因此，助手模型应该要小得多。

• streamer（BaseStreamer，可选）— 将用于流式传输生成的序列的 Streamer 对象。生成的令牌通过streamer.put(token_ids)传递，Streamer 负责任何进一步的处理。

• negative_prompt_ids（torch.LongTensor，形状为(batch_size, sequence_length)，可选）— 一些处理器（如 CFG）需要的负提示。批量大小必须与输入批量大小匹配。这是一个实验性功能，可能在未来版本中会有破坏性的 API 更改。

• negative_prompt_attention_mask（torch.LongTensor，形状为(batch_size, sequence_length)，可选）— 用于negative_prompt_ids的 Attention_mask。

• kwargs（Dict[str, Any]，可选）— generate_config的特定参数化和/或将转发到模型的forward函数的其他模型特定 kwargs。如果模型是编码器-解码器模型，则编码器特定的 kwargs 不应该有前缀，解码器特定的 kwargs 应该以*decoder_*为前缀。

返回

ModelOutput 或torch.LongTensor

一个 ModelOutput（如果return_dict_in_generate=True或当config.return_dict_in_generate=True时）或一个torch.FloatTensor。

如果模型不是编码器-解码器模型（model.config.is_encoder_decoder=False），可能的 ModelOutput 类型有：

• GenerateDecoderOnlyOutput

• GenerateBeamDecoderOnlyOutput

如果模型是一个编码器-解码器模型（model.config.is_encoder_decoder=True），可能的 ModelOutput 类型有：

• GenerateEncoderDecoderOutput,

• GenerateBeamEncoderDecoderOutput

为具有语言建模头的模型生成令牌 id 序列。

大多数控制生成的参数都在generation_config中设置，如果未传递，则将设置为模型的默认生成配置。您可以通过将相应的参数传递给 generate()来覆盖任何generation_config，例如.generate(inputs, num_beams=4, do_sample=True)。

有关生成策略和代码示例的概述，请查看以下指南。

compute_transition_scores

< source >

( sequences: Tensor scores: Tuple beam_indices: Optional = None normalize_logits: bool = False ) → export const metadata = 'undefined';torch.Tensor

参数

• sequences（torch.LongTensor）— 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则较短。

• scores（tuple(torch.FloatTensor)）— 每个生成步骤中每个词汇令牌的转移分数。由条件于先前生成令牌的对数 softmax 的令牌的对数概率组成的波束转移分数元组，其中每个张量的形状为(batch_size*num_beams, config.vocab_size)，最多有max_new_tokens个元素（每个生成的令牌一个元素）。

• beam_indices（torch.LongTensor，可选）— 在每个生成步骤生成的标记 id 的波束索引。形状为(batch_size*num_return_sequences, sequence_length)的torch.LongTensor。仅在生成时num_beams>1时需要。

• normalize_logits（bool，可选，默认为False）— 是否对 logits 进行归一化（由于历史原因，可能未归一化）。

返回

torch.Tensor

形状为(batch_size*num_return_sequences, sequence_length)的torch.Tensor，包含转换分数（logits）

计算给定生成分数的序列的转换分数（如果使用波束搜索，则还有波束索引）。这是一种方便的方法，在生成时快速获取所选标记的分数。

示例：

>>> from transformers import GPT2Tokenizer, AutoModelForCausalLM
>>> import numpy as np

>>> tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer.pad_token_id = tokenizer.eos_token_id
>>> inputs = tokenizer(["Today is"], return_tensors="pt")

>>> # Example 1: Print the scores for each token generated with Greedy Search
>>> outputs = model.generate(**inputs, max_new_tokens=5, return_dict_in_generate=True, output_scores=True)
>>> transition_scores = model.compute_transition_scores(
...     outputs.sequences, outputs.scores, normalize_logits=True
... )
>>> # input_length is the length of the input prompt for decoder-only models, like the GPT family, and 1 for
>>> # encoder-decoder models, like BART or T5.
>>> input_length = 1 if model.config.is_encoder_decoder else inputs.input_ids.shape[1]
>>> generated_tokens = outputs.sequences[:, input_length:]
>>> for tok, score in zip(generated_tokens[0], transition_scores[0]):
...     # | token | token string | logits | probability
...     print(f"| {tok:5d} | {tokenizer.decode(tok):8s} | {score.numpy():.3f} | {np.exp(score.numpy()):.2%}")
|   262 |  the     | -1.414 | 24.33%
|  1110 |  day     | -2.609 | 7.36%
|   618 |  when    | -2.010 | 13.40%
|   356 |  we      | -1.859 | 15.58%
|   460 |  can     | -2.508 | 8.14%

>>> # Example 2: Reconstruct the sequence scores from Beam Search
>>> outputs = model.generate(
...     **inputs,
...     max_new_tokens=5,
...     num_beams=4,
...     num_return_sequences=4,
...     return_dict_in_generate=True,
...     output_scores=True,
... )
>>> transition_scores = model.compute_transition_scores(
...     outputs.sequences, outputs.scores, outputs.beam_indices, normalize_logits=False
... )
>>> # If you sum the generated tokens' scores and apply the length penalty, you'll get the sequence scores.
>>> # Tip 1: recomputing the scores is only guaranteed to match with `normalize_logits=False`. Depending on the
>>> # use case, you might want to recompute it with `normalize_logits=True`.
>>> # Tip 2: the output length does NOT include the input length
>>> output_length = np.sum(transition_scores.numpy() < 0, axis=1)
>>> length_penalty = model.generation_config.length_penalty
>>> reconstructed_scores = transition_scores.sum(axis=1) / (output_length**length_penalty)
>>> print(np.allclose(outputs.sequences_scores, reconstructed_scores))
True

greedy_search

<来源>

( input_ids: LongTensor logits_processor: Optional = None stopping_criteria: Optional = None max_length: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: bool = False streamer: Optional = None **model_kwargs )

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 用作生成提示的序列。

• logits_processor（LogitsProcessorList，可选）— LogitsProcessorList 的实例。派生自 LogitsProcessor 类的实例列表，用于修改应用于每个生成步骤的语言建模头的预测分数。

• stopping_criteria（StoppingCriteriaList，可选）— StoppingCriteriaList 的实例。派生自 StoppingCriteria 类的实例列表，用于告知生成循环是否应该停止。

• max_length（int，可选，默认为 20）— 已弃用。直接使用logits_processor或stopping_criteria来限制生成标记的数量。要生成的序列的最大长度。

• pad_token_id（int，可选）— 填充标记的 id。

• eos_token_id（Union[int, List[int]]，可选）— 结束序列标记的 id。可选择使用列表设置多个结束序列标记。

• output_attentions（bool，可选，默认为False）— 是否返回所有注意力层的注意力张量。有关更多详细信息，请参见返回的张量下的attentions。

• output_hidden_states（bool，可选，默认为False）— 是否返回所有层的隐藏状态。有关更多详细信息，请参见返回的张量下的hidden_states。

• output_scores（bool，可选，默认为False）— 是否返回预测分数。有关更多详细信息，请参见返回的张量下的scores。

• return_dict_in_generate（bool，可选，默认为False）— 是否返回 ModelOutput 而不是普通元组。

• synced_gpus（bool，可选，默认为False）— 是否继续运行 while 循环直到 max_length（对于 ZeRO 阶段 3 需要）

• streamer（BaseStreamer，可选）— 将用于流式传输生成序列的 Streamer 对象。生成的标记通过streamer.put(token_ids)传递，streamer 负责任何进一步处理。model_kwargs — 附加的特定于模型的关键字参数将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

使用贪婪解码为具有语言建模头的模型生成标记 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 greedy_search()。请改用 generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForCausalLM,
...     LogitsProcessorList,
...     MinLengthLogitsProcessor,
...     StoppingCriteriaList,
...     MaxLengthCriteria,
... )

>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")

>>> # set pad_token_id to eos_token_id because GPT2 does not have a PAD token
>>> model.generation_config.pad_token_id = model.generation_config.eos_token_id

>>> input_prompt = "It might be possible to"
>>> input_ids = tokenizer(input_prompt, return_tensors="pt").input_ids

>>> # instantiate logits processors
>>> logits_processor = LogitsProcessorList(
...     [
...         MinLengthLogitsProcessor(10, eos_token_id=model.generation_config.eos_token_id),
...     ]
... )
>>> stopping_criteria = StoppingCriteriaList([MaxLengthCriteria(max_length=20)])

>>> outputs = model.greedy_search(
...     input_ids, logits_processor=logits_processor, stopping_criteria=stopping_criteria
... )

>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
["It might be possible to get a better understanding of the nature of the problem, but it's not"]

sample

<来源>

( input_ids: LongTensor logits_processor: Optional = None stopping_criteria: Optional = None logits_warper: Optional = None max_length: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: bool = False streamer: Optional = None **model_kwargs ) → export const metadata = 'undefined';GenerateDecoderOnlyOutput, GenerateEncoderDecoderOutput or torch.LongTensor

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 用作生成提示的序列。

• logits_processor（LogitsProcessorList，可选）— LogitsProcessorList 的实例。用于修改应用于每个生成步骤的语言建模头的预测分数的类派生自 LogitsProcessor 的实例列表。

• stopping_criteria（StoppingCriteriaList，可选）— StoppingCriteriaList 的实例。用于告知生成循环是否应停止的类派生自 StoppingCriteria 的实例列表。

• logits_warper（LogitsProcessorList，可选）— LogitsProcessorList 的实例。用于在每个生成步骤的多项式抽样之前应用于语言建模头的预测分数分布的类派生自 LogitsWarper 的实例列表。

• max_length（int，可选，默认为 20）— 已弃用。直接使用logits_processor或stopping_criteria来限制生成标记的数量。要生成的序列的最大长度。

• pad_token_id（int，可选）— 填充标记的 id。

• eos_token_id（Union[int, List[int]]，可选）— 结束序列标记的 id。可选择使用列表设置多个结束序列标记。

• output_attentions（bool，可选，默认为False）— 是否返回所有注意力层的注意力张量。有关更多详细信息，请参见返回张量下的attentions。

• output_hidden_states（bool，可选，默认为False）— 是否返回所有层的隐藏状态。有关更多详细信息，请参见返回张量下的hidden_states。

• output_scores（bool，可选，默认为False）— 是否返回预测分数。有关更多详细信息，请参见返回张量下的scores。

• return_dict_in_generate（bool，可选，默认为False）— 是否返回 ModelOutput 而不是普通元组。

• synced_gpus（bool，可选，默认为False）— 是否继续运行 while 循环直到 max_length（需要 ZeRO 阶段 3）

• streamer（BaseStreamer，可选）— 将用于流式传输生成的序列的 Streamer 对象。生成的标记通过streamer.put(token_ids)传递，streamer 负责任何进一步处理。model_kwargs — 附加的模型特定 kwargs 将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

返回

GenerateDecoderOnlyOutput，GenerateEncoderDecoderOutput 或torch.LongTensor

包含生成标记的torch.LongTensor（默认行为）或一个 GenerateDecoderOnlyOutput，如果model.config.is_encoder_decoder=False且return_dict_in_generate=True，或一个 GenerateEncoderDecoderOutput，如果model.config.is_encoder_decoder=True。

使用多项式采样为具有语言建模头的模型生成标记 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 sample()。请改用 generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForCausalLM,
...     LogitsProcessorList,
...     MinLengthLogitsProcessor,
...     TopKLogitsWarper,
...     TemperatureLogitsWarper,
...     StoppingCriteriaList,
...     MaxLengthCriteria,
... )
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")

>>> # set pad_token_id to eos_token_id because GPT2 does not have a EOS token
>>> model.config.pad_token_id = model.config.eos_token_id
>>> model.generation_config.pad_token_id = model.config.eos_token_id

>>> input_prompt = "Today is a beautiful day, and"
>>> input_ids = tokenizer(input_prompt, return_tensors="pt").input_ids

>>> # instantiate logits processors
>>> logits_processor = LogitsProcessorList(
...     [
...         MinLengthLogitsProcessor(15, eos_token_id=model.generation_config.eos_token_id),
...     ]
... )
>>> # instantiate logits processors
>>> logits_warper = LogitsProcessorList(
...     [
...         TopKLogitsWarper(50),
...         TemperatureLogitsWarper(0.7),
...     ]
... )

>>> stopping_criteria = StoppingCriteriaList([MaxLengthCriteria(max_length=20)])

>>> torch.manual_seed(0)
>>> outputs = model.sample(
...     input_ids,
...     logits_processor=logits_processor,
...     logits_warper=logits_warper,
...     stopping_criteria=stopping_criteria,
... )

>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
['Today is a beautiful day, and we must do everything possible to make it a day of celebration.']

beam_search

<来源>

( input_ids: LongTensor beam_scorer: BeamScorer logits_processor: Optional = None stopping_criteria: Optional = None max_length: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: bool = False **model_kwargs )

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 用作生成提示的序列。

• beam_scorer (BeamScorer) — 一个派生自 BeamScorer 的实例，定义了在生成过程中如何构建、存储和排序 beam 假设。有关更多信息，请阅读 BeamScorer 的文档。

• logits_processor (LogitsProcessorList，可选）— LogitsProcessorList 的实例。从 LogitsProcessor 派生的类的实例列表，用于修改应用于每个生成步骤的语言建模头的预测分数。

• stopping_criteria (StoppingCriteriaList，可选）— StoppingCriteriaList 的实例。从 StoppingCriteria 派生的类的实例列表，用于告知生成循环是否应该停止。

• max_length (int，可选，默认为 20) — 已弃用。直接使用logits_processor或stopping_criteria来限制生成的标记数量。要生成的序列的最大长度。

• pad_token_id (int，可选）— 填充 标记的 id。

• eos_token_id (Union[int, List[int]]，可选）— 序列结束 标记的 id。可选择使用列表设置多个序列结束 标记。

• output_attentions (bool，可选，默认为False) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量下的attentions。

• output_hidden_states (bool，可选，默认为False) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量下的hidden_states。

• output_scores (bool，可选，默认为False) — 是否返回预测分数。有关更多详细信息，请参阅返回张量下的scores。

• return_dict_in_generate (bool，可选，默认为False) — 是否返回一个 ModelOutput 而不是一个普通元组。

• synced_gpus (bool，可选，默认为False) — 是否继续运行 while 循环直到达到 max_length（ZeRO 阶段 3 所需）model_kwargs — 附加的模型特定 kwargs 将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

使用beam search 解码为具有语言建模头的模型生成标记 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 beam_search()。请改用generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForSeq2SeqLM,
...     LogitsProcessorList,
...     MinLengthLogitsProcessor,
...     BeamSearchScorer,
... )
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("t5-base")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")

>>> encoder_input_str = "translate English to German: How old are you?"
>>> encoder_input_ids = tokenizer(encoder_input_str, return_tensors="pt").input_ids

>>> # lets run beam search using 3 beams
>>> num_beams = 3
>>> # define decoder start token ids
>>> input_ids = torch.ones((num_beams, 1), device=model.device, dtype=torch.long)
>>> input_ids = input_ids * model.config.decoder_start_token_id

>>> # add encoder_outputs to model keyword arguments
>>> model_kwargs = {
...     "encoder_outputs": model.get_encoder()(
...         encoder_input_ids.repeat_interleave(num_beams, dim=0), return_dict=True
...     )
... }

>>> # instantiate beam scorer
>>> beam_scorer = BeamSearchScorer(
...     batch_size=1,
...     num_beams=num_beams,
...     device=model.device,
... )

>>> # instantiate logits processors
>>> logits_processor = LogitsProcessorList(
...     [
...         MinLengthLogitsProcessor(5, eos_token_id=model.config.eos_token_id),
...     ]
... )

>>> outputs = model.beam_search(input_ids, beam_scorer, logits_processor=logits_processor, **model_kwargs)

>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
['Wie alt bist du?']

beam_sample

< source >

( input_ids: LongTensor beam_scorer: BeamScorer logits_processor: Optional = None stopping_criteria: Optional = None logits_warper: Optional = None max_length: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: bool = False **model_kwargs )

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)） — 用作生成提示的序列。

• beam_scorer (BeamScorer) — BeamScorer 的派生实例，定义了在生成过程中如何构建、存储和排序 beam 假设。有关更多信息，请阅读 BeamScorer 的文档。

• logits_processor (LogitsProcessorList, optional) — LogitsProcessorList 的实例。用于修改每个生成步骤应用的语言建模头的预测分数的从 LogitsProcessor 派生类的实例列表。

• stopping_criteria (StoppingCriteriaList, optional) — StoppingCriteriaList 的实例。用于告知生成循环是否应该停止的从 StoppingCriteria 派生类的实例列表。

• logits_warper (LogitsProcessorList, optional) — LogitsProcessorList 的实例。用于在每个生成步骤的多项式抽样之前应用于语言建模头的预测分数分布的扭曲的从 LogitsWarper 派生类的实例列表。

• max_length (int, optional, defaults to 20) — 已弃用。直接使用logits_processor或stopping_criteria来限制生成的标记数量。要生成的序列的最大长度。

• pad_token_id (int, optional) — 填充标记的 id。

• eos_token_id (Union[int, List[int]], optional) — 序列结束标记的 id。可选择使用列表设置多个序列结束标记。

• output_attentions (bool, optional, defaults to False) — 是否返回所有注意力层的注意力张量。有关更多细节，请参见返回的张量中的attentions。

• output_hidden_states (bool, optional, defaults to False) — 是否返回所有层的隐藏状态。有关更多细节，请参见返回的张量中的hidden_states。

• output_scores (bool, optional, defaults to False) — 是否返回预测分数。有关更多细节，请参见返回的张量中的scores。

• return_dict_in_generate (bool, optional, defaults to False) — 是否返回 ModelOutput 而不是普通元组。

• synced_gpus (bool, optional, defaults to False) — 是否继续运行 while 循环直到达到max_length（对于 ZeRO 阶段 3 需要）。model_kwargs — 额外的特定于模型的 kwargs 将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

使用波束搜索多项式抽样为具有语言建模头的模型生成标记 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 beam_sample()。请改用 generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForSeq2SeqLM,
...     LogitsProcessorList,
...     MinLengthLogitsProcessor,
...     TopKLogitsWarper,
...     TemperatureLogitsWarper,
...     BeamSearchScorer,
... )
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("t5-base")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")

>>> encoder_input_str = "translate English to German: How old are you?"
>>> encoder_input_ids = tokenizer(encoder_input_str, return_tensors="pt").input_ids

>>> # lets run beam search using 3 beams
>>> num_beams = 3
>>> # define decoder start token ids
>>> input_ids = torch.ones((num_beams, 1), device=model.device, dtype=torch.long)
>>> input_ids = input_ids * model.config.decoder_start_token_id

>>> # add encoder_outputs to model keyword arguments
>>> model_kwargs = {
...     "encoder_outputs": model.get_encoder()(
...         encoder_input_ids.repeat_interleave(num_beams, dim=0), return_dict=True
...     )
... }

>>> # instantiate beam scorer
>>> beam_scorer = BeamSearchScorer(
...     batch_size=1,
...     max_length=model.config.max_length,
...     num_beams=num_beams,
...     device=model.device,
... )

>>> # instantiate logits processors
>>> logits_processor = LogitsProcessorList(
...     [MinLengthLogitsProcessor(5, eos_token_id=model.config.eos_token_id)]
... )
>>> # instantiate logits processors
>>> logits_warper = LogitsProcessorList(
...     [
...         TopKLogitsWarper(50),
...         TemperatureLogitsWarper(0.7),
...     ]
... )

>>> outputs = model.beam_sample(
...     input_ids, beam_scorer, logits_processor=logits_processor, logits_warper=logits_warper, **model_kwargs
... )

>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
['Wie alt bist du?']

对比搜索

<来源>

( input_ids: LongTensor top_k: Optional = 1 penalty_alpha: Optional = 0 logits_processor: Optional = None logits_warper: Optional = None stopping_criteria: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: bool = False streamer: Optional = None sequential: Optional = None **model_kwargs )

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 用作生成提示的序列。

• top_k (int, 可选，默认为 1) — 用于重新排名对比搜索的候选集的大小

• penalty_alpha (float, 可选，默认为 0) — 对比搜索的退化惩罚；当大于 0 时激活

• logits_processor (LogitsProcessorList, 可选) — LogitsProcessorList 的实例。派生自 LogitsProcessor 类的实例列表，用于修改每个生成步骤中应用的语言建模头的预测分数。

• logits_warper (LogitsProcessorList, 可选) — LogitsProcessorList 的实例。派生自 LogitsWarper 类的实例列表，用于在每个生成步骤之前应用于多项式抽样的语言建模头的预测分数分布。

• stopping_criteria (StoppingCriteriaList, 可选) — StoppingCriteriaList 的实例。派生自 StoppingCriteria 类的实例列表，用于告知生成循环是否应该停止。

• pad_token_id (int, 可选) — 填充标记的 id。

• eos_token_id (Union[int, List[int]], 可选) — 序列结束标记的 id。可选择使用列表设置多个序列结束标记。

• output_attentions (bool, 可选，默认为False) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请查看返回张量下的attentions。

• output_hidden_states (bool, 可选，默认为False) — 是否返回所有层的隐藏状态。有关更多详细信息，请查看返回张量下的hidden_states。

• output_scores (bool, 可选，默认为False) — 是否返回预测分数。有关更多详细信息，请查看返回张量下的scores。

• return_dict_in_generate (bool, 可选，默认为False) — 是否返回 ModelOutput 而不是普通元组。

• synced_gpus (bool, 可选，默认为False) — 是否继续运行 while 循环直到 max_length（需要 ZeRO 阶段 3）

• streamer (BaseStreamer, 可选) — 将用于流式传输生成序列的 Streamer 对象。生成的标记通过streamer.put(token_ids)传递，streamer 负责任何进一步处理。

• sequential (bool, optional) — 如果为 True，则将 topk 隐藏状态计算从并行切换到顺序以减少内存。model_kwargs — 附加的模型特定关键字参数将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

使用对比搜索为具有语言建模头的模型生成标记 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 contrastive_search()。请改用 generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForCausalLM,
...     StoppingCriteriaList,
...     MaxLengthCriteria,
... )

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/opt-125m")
>>> model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> # set pad_token_id to eos_token_id because OPT does not have a PAD token
>>> model.config.pad_token_id = model.config.eos_token_id
>>> input_prompt = "DeepMind Company is"
>>> input_ids = tokenizer(input_prompt, return_tensors="pt")
>>> stopping_criteria = StoppingCriteriaList([MaxLengthCriteria(max_length=64)])
>>> outputs = model.contrastive_search(
...     **input_ids, penalty_alpha=0.6, top_k=4, stopping_criteria=stopping_criteria
... )
>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
['DeepMind Company is a company that focuses on the development and commercialization of artificial intelligence (AI). DeepMind’s mission is to help people understand and solve problems that are difficult to solve in the world today.\n\nIn this post, we talk about the benefits of deep learning in business and how it']

group_beam_search

<来源>

( input_ids: LongTensor beam_scorer: BeamScorer logits_processor: Optional = None stopping_criteria: Optional = None max_length: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: bool = False **model_kwargs )

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 用作生成提示的序列。

• beam_scorer (BeamScorer) — 一个派生自 BeamScorer 的实例，定义了在生成过程中如何构建、存储和排序 beam 假设。有关更多信息，请阅读 BeamScorer 的文档。

• logits_processor (LogitsProcessorList, optional) — 一个 LogitsProcessorList 的实例。用于修改应用于每个生成步骤的语言建模头的预测分数的类派生自 LogitsProcessor 的实例列表。

• stopping_criteria (StoppingCriteriaList, optional) — 一个 StoppingCriteriaList 的实例。用于告诉生成循环是否应该停止的类派生自 StoppingCriteria 的实例列表。

• max_length (int, optional, 默认为 20) — 已弃用。直接使用logits_processor或stopping_criteria来限制生成标记的数量。要生成的序列的最大长度。

• pad_token_id (int, optional) — 填充标记的 id。

• eos_token_id (Union[int, List[int]], optional) — 序列结束标记的 id。可选择使用列表设置多个序列结束标记。

• output_attentions (bool, optional, 默认为False) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量下的attentions。

• output_hidden_states (bool, optional, 默认为False) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量下的hidden_states。

• output_scores (bool, optional, 默认为False) — 是否返回预测分数。有关更多详细信息，请参阅返回张量下的scores。

• return_dict_in_generate (bool, optional, 默认为False) — 是否返回 ModelOutput 而不是普通元组。

• synced_gpus (bool, optional, 默认为False) — 是否继续运行 while 循环直到 max_length（需要 ZeRO 阶段 3）

  model_kwargs — 附加的模型特定 kwargs 将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

使用多样化束搜索解码为具有语言建模头的模型生成令牌 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 group_beam_search()。请改用 generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForSeq2SeqLM,
...     LogitsProcessorList,
...     MinLengthLogitsProcessor,
...     HammingDiversityLogitsProcessor,
...     BeamSearchScorer,
... )
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("t5-base")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")

>>> encoder_input_str = "translate English to German: How old are you?"
>>> encoder_input_ids = tokenizer(encoder_input_str, return_tensors="pt").input_ids

>>> # lets run diverse beam search using 6 beams
>>> num_beams = 6
>>> # define decoder start token ids
>>> input_ids = torch.ones((num_beams, 1), device=model.device, dtype=torch.long)
>>> input_ids = input_ids * model.config.decoder_start_token_id

>>> # add encoder_outputs to model keyword arguments
>>> model_kwargs = {
...     "encoder_outputs": model.get_encoder()(
...         encoder_input_ids.repeat_interleave(num_beams, dim=0), return_dict=True
...     )
... }

>>> # instantiate beam scorer
>>> beam_scorer = BeamSearchScorer(
...     batch_size=1,
...     max_length=model.config.max_length,
...     num_beams=num_beams,
...     device=model.device,
...     num_beam_groups=3,
... )

>>> # instantiate logits processors
>>> logits_processor = LogitsProcessorList(
...     [
...         HammingDiversityLogitsProcessor(5.5, num_beams=6, num_beam_groups=3),
...         MinLengthLogitsProcessor(5, eos_token_id=model.config.eos_token_id),
...     ]
... )

>>> outputs = model.group_beam_search(
...     input_ids, beam_scorer, logits_processor=logits_processor, **model_kwargs
... )

>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
['Wie alt bist du?']

constrained_beam_search

< source >

( input_ids: LongTensor constrained_beam_scorer: ConstrainedBeamSearchScorer logits_processor: Optional = None stopping_criteria: Optional = None max_length: Optional = None pad_token_id: Optional = None eos_token_id: Union = None output_attentions: Optional = None output_hidden_states: Optional = None output_scores: Optional = None return_dict_in_generate: Optional = None synced_gpus: Optional = None **model_kwargs )

参数

• input_ids (torch.LongTensor，形状为 (batch_size, sequence_length)) — 用作生成提示的序列。

• constrained_beam_scorer (ConstrainedBeamSearchScorer) — 表示如何在生成过程中构建、存储和排序束假设的 BeamScorer 的派生实例，同时满足一系列正面约束。有关更多信息，请阅读 ConstrainedBeamSearchScorer 的文档。

• logits_processor (LogitsProcessorList, optional) — LogitsProcessorList 的实例。用于修改每个生成步骤应用的语言建模头的预测分数的类派生实例的列表。

• stopping_criteria (StoppingCriteriaList, optional) — StoppingCriteriaList 的实例。用于告知生成循环是否应该停止的类派生实例的列表。

• logits_warper (LogitsProcessorList, optional) — LogitsProcessorList 的实例。用于在每个生成步骤的多项式抽样之前应用于语言建模头的预测分数分布的类派生实例的列表。

• max_length (int, optional, 默认为 20) — 已弃用。直接使用 logits_processor 或 stopping_criteria 来限制生成的令牌数量。要生成的序列的最大长度。

• pad_token_id (int, optional) — 填充 令牌的 id。

• eos_token_id (Union[int, List[int]], optional) — 结束序列 令牌的 id。可选择使用列表设置多个 结束序列 令牌。

• output_attentions (bool, optional, 默认为 False) — 是否返回所有注意力层的注意力张量。有关更多细节，请参见返回张量中的 attentions。

• output_hidden_states (bool, optional, 默认为 False) — 是否返回所有层的隐藏状态。有关更多细节，请参见返回张量中的 hidden_states。

• output_scores (bool, optional, 默认为 False) — 是否返回预测分数。有关更多细节，请参见返回张量中的 scores。

• return_dict_in_generate (bool, optional, 默认为 False) — 是否返回一个 ModelOutput 而不是一个普通元组。

• synced_gpus（bool，可选，默认为False）- 是否继续运行 while 循环直到 max_length（需要 ZeRO 阶段 3）model_kwargs-其他特定于模型的 kwargs 将被转发到模型的forward函数。如果模型是编码器-解码器模型，则 kwargs 应包括encoder_outputs。

使用受限束搜索解码为具有语言建模头的模型生成令牌 id 序列，可用于文本解码器、文本到文本、语音到文本和视觉到文本模型。

在大多数情况下，您不需要直接调用 constrained_beam_search()。请改用 generate()。有关生成策略和代码示例的概述，请查看以下指南。

示例：

>>> from transformers import (
...     AutoTokenizer,
...     AutoModelForSeq2SeqLM,
...     LogitsProcessorList,
...     MinLengthLogitsProcessor,
...     ConstrainedBeamSearchScorer,
...     PhrasalConstraint,
... )
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("t5-base")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")

>>> encoder_input_str = "translate English to German: How old are you?"
>>> encoder_input_ids = tokenizer(encoder_input_str, return_tensors="pt").input_ids

>>> # lets run beam search using 3 beams
>>> num_beams = 3
>>> # define decoder start token ids
>>> input_ids = torch.ones((num_beams, 1), device=model.device, dtype=torch.long)
>>> input_ids = input_ids * model.config.decoder_start_token_id

>>> # add encoder_outputs to model keyword arguments
>>> model_kwargs = {
...     "encoder_outputs": model.get_encoder()(
...         encoder_input_ids.repeat_interleave(num_beams, dim=0), return_dict=True
...     )
... }

>>> constraint_str = "Sie"
>>> constraint_token_ids = tokenizer.encode(constraint_str)[:-1]  # slice to remove eos token
>>> constraints = [PhrasalConstraint(token_ids=constraint_token_ids)]

>>> # instantiate beam scorer
>>> beam_scorer = ConstrainedBeamSearchScorer(
...     batch_size=1, num_beams=num_beams, device=model.device, constraints=constraints
... )

>>> # instantiate logits processors
>>> logits_processor = LogitsProcessorList(
...     [
...         MinLengthLogitsProcessor(5, eos_token_id=model.config.eos_token_id),
...     ]
... )

>>> outputs = model.constrained_beam_search(
...     input_ids, beam_scorer, constraints=constraints, logits_processor=logits_processor, **model_kwargs
... )

>>> tokenizer.batch_decode(outputs, skip_special_tokens=True)
['Wie alt sind Sie?']

TFGenerationMixin

class transformers.TFGenerationMixin

<来源>

( )

包含支持生成的所有函数的类，可用作 TFPreTrainedModel 中的 mixin。

该类公开 generate()，可用于：

• 贪婪解码，如果num_beams=1且do_sample=False，则调用greedy_search()

• 对比搜索，如果penalty_alpha>0和top_k>1，则调用contrastive_search()

• 多项式采样，如果num_beams=1且do_sample=True，则调用sample()

• 束搜索解码，如果num_beams>1，则调用beam_search()

您不需要直接调用上述任何方法。请将自定义参数值传递给“generate”而不是。要了解有关解码策略的更多信息，请参考文本生成策略指南。

generate

<来源>

( inputs: Optional = None generation_config: Optional = None logits_processor: Optional = None seed = None **kwargs ) → export const metadata = 'undefined';ModelOutput or tf.Tensor

参数

• inputs（tf.Tensor，根据模态性质而变化的形状，可选）- 用作生成提示或作为编码器的模型输入的序列。如果为None，则该方法将使用bos_token_id和批量大小为 1 进行初始化。对于仅解码器模型，inputs应为input_ids格式。对于编码器-解码器模型，inputs可以表示input_ids、input_values、input_features或pixel_values中的任何一个。

• generation_config（~generation.GenerationConfig，可选）- 用作生成调用的基本参数化的生成配置。传递给生成的**kwargs与generation_config的属性匹配将覆盖它们。如果未提供generation_config，将使用默认值，其加载优先级如下：1）从generation_config.json模型文件中，如果存在；2）从模型配置中。请注意，未指定的参数将继承 GenerationConfig 的默认值，应检查其文档以参数化生成。

• logits_processor（LogitsProcessorList，可选）- 自定义 logits 处理器，补充从参数和生成配置构建的默认 logits 处理器。如果传递的 logit 处理器已经使用参数或生成配置创建，则会抛出错误。此功能适用于高级用户。

• seed（List[int]，可选）- 用于控制采样的随机种子，包含两个整数，在do_sample为True时使用。请参阅tf.random中无状态函数的seed参数。

• kwargs (Dict[str, Any], optional) — generate_config的特定参数化和/或将转发到模型的forward函数的其他模型特定 kwargs。如果模型是编码器-解码器模型，则不应该为编码器特定 kwargs 添加前缀，而应该为解码器特定 kwargs 添加前缀decoder_。

返回

ModelOutput 或 tf.Tensor

一个 ModelOutput（如果return_dict_in_generate=True或config.return_dict_in_generate=True）或一个tf.Tensor。

如果模型不是编码器-解码器模型（model.config.is_encoder_decoder=False），可能的 ModelOutput 类型为：

• TFGreedySearchDecoderOnlyOutput,

• TFSampleDecoderOnlyOutput,

• TFBeamSearchDecoderOnlyOutput,

• TFBeamSampleDecoderOnlyOutput

如果模型是编码器-解码器模型（model.config.is_encoder_decoder=True），可能的 ModelOutput 类型为：

• TFGreedySearchEncoderDecoderOutput,

• TFSampleEncoderDecoderOutput,

• TFBeamSearchEncoderDecoderOutput,

• TFBeamSampleEncoderDecoderOutput

为具有语言建模头的模型生成 token id 序列。

大多数控制生成的参数都在generation_config中设置，如果未传递，则将设置为模型的默认生成配置。您可以通过将相应的参数传递给 generate 来覆盖任何generation_config，例如.generate(inputs, num_beams=4, do_sample=True)。

有关生成策略和代码示例的概述，请查看以下指南。

compute_transition_scores

< source >

( sequences: Tensor scores: Tuple beam_indices: Optional = None normalize_logits: bool = False ) → export const metadata = 'undefined';tf.Tensor

参数

• sequences (tf.Tensor) — 生成的序列。第二维（序列长度）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短一些。

• scores (tuple(tf.Tensor)) — 每个生成步骤中每个词汇标记的转移分数。Beam 转移分数由 tokens 的 log 概率组成，条件是先前生成的 tokens 的 log softmax。形状为(batch_size*num_beams, config.vocab_size)的tf.Tensor元组，最多包含max_new_tokens个元素（每个生成的 token 一个元素）。

• beam_indices (tf.Tensor, optional) — 每个生成步骤中生成的 token id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor。在生成时如果num_beams>1则是必需的。

• normalize_logits (bool, optional, defaults to False) — 是否对 logits 进行归一化（由于历史原因，可能未归一化）。

返回

tf.Tensor

一个形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor，包含转移分数（logits）

计算给定生成分数的序列的转移分数（以及如果使用了束搜索，则为束索引）。这是一个方便的方法，在生成时快速获取所选标记的分数。

示例：

>>> from transformers import GPT2Tokenizer, TFAutoModelForCausalLM
>>> import numpy as np

>>> tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
>>> model = TFAutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer.pad_token_id = tokenizer.eos_token_id
>>> inputs = tokenizer(["Today is"], return_tensors="tf")

>>> # Example 1: Print the scores for each token generated with Greedy Search
>>> outputs = model.generate(**inputs, max_new_tokens=5, return_dict_in_generate=True, output_scores=True)
>>> transition_scores = model.compute_transition_scores(
...     outputs.sequences, outputs.scores, normalize_logits=True
... )
>>> # input_length is the length of the input prompt for decoder-only models, like the GPT family, and 1 for
>>> # encoder-decoder models, like BART or T5.
>>> input_length = 1 if model.config.is_encoder_decoder else inputs.input_ids.shape[1]
>>> generated_tokens = outputs.sequences[:, input_length:]
>>> for tok, score in zip(generated_tokens[0], transition_scores[0]):
...     # | token | token string | logits | probability
...     print(f"| {tok:5d} | {tokenizer.decode(tok):8s} | {score.numpy():.3f} | {np.exp(score.numpy()):.2%}")
|   262 |  the     | -1.413 | 24.33%
|  1110 |  day     | -2.609 | 7.36%
|   618 |  when    | -2.009 | 13.41%
|   356 |  we      | -1.859 | 15.58%
|   460 |  can     | -2.508 | 8.14%

>>> # Example 2: Reconstruct the sequence scores from Beam Search
>>> outputs = model.generate(
...     **inputs,
...     max_new_tokens=5,
...     num_beams=4,
...     num_return_sequences=4,
...     return_dict_in_generate=True,
...     output_scores=True,
... )
>>> transition_scores = model.compute_transition_scores(
...     outputs.sequences, outputs.scores, outputs.beam_indices, normalize_logits=False
... )
>>> # If you sum the generated tokens' scores and apply the length penalty, you'll get the sequence scores.
>>> # Tip: recomputing the scores is only guaranteed to match with `normalize_logits=False`. Depending on the
>>> # use case, you might want to recompute it with `normalize_logits=True`.
>>> output_length = input_length + np.sum(transition_scores.numpy() < 0, axis=1)
>>> length_penalty = model.generation_config.length_penalty
>>> reconstructed_scores = np.sum(transition_scores, axis=1) / (output_length**length_penalty)
>>> print(np.allclose(outputs.sequences_scores, reconstructed_scores))
True

FlaxGenerationMixin

class transformers.FlaxGenerationMixin

<来源>

( )

包含用于自回归文本生成的所有函数的类，可作为 FlaxPreTrainedModel 中的 mixin 使用。

该类公开了 generate()，可用于：

• 贪婪解码，如果num_beams=1且do_sample=False，则调用_greedy_search()

• 多项式采样，如果num_beams=1且do_sample=True，则调用_sample()。

• 束搜索解码，如果num_beams>1且do_sample=False，则调用_beam_search()

您无需直接调用上述任何方法。而是将自定义参数值传递给“generate”。要了解更多关于解码策略的信息，请参考文本生成策略指南。

generate

<来源>

( input_ids: Array generation_config: Optional = None prng_key: Optional = None trace: bool = True params: Optional = None logits_processor: Optional = None **kwargs )

参数

• input_ids（形状为(batch_size, sequence_length)的jnp.ndarray）—用作生成提示的序列。

• generation_config（~generation.GenerationConfig，可选）—用作生成调用的基本参数化的生成配置。传递给 generate 的**kwargs匹配generation_config的属性将覆盖它们。如果未提供generation_config，则将使用默认值，其加载优先级如下：1）从generation_config.json模型文件中，如果存在；2）从模型配置中。请注意，未指定的参数将继承 GenerationConfig 的默认值，应检查其文档以参数化生成。

• trace（bool，可选，默认为True）—是否跟踪生成。设置trace=False仅用于调试，会导致运行时间明显变慢。

• params（Dict[str, jnp.ndarray]，可选）—可选择传递模型参数。对于并行化生成可能会有用。

• logits_processor（FlaxLogitsProcessorList，可选）—自定义 logits 处理器，补充了从参数和生成配置构建的默认 logits 处理器。如果传递了已经使用参数或生成配置创建的 logit 处理器，则会抛出错误。此功能旨在供高级用户使用。

• kwargs（Dict[str, Any]，可选）—generate_config的临时参数化和/或将转发给模型的forward函数的其他特定于模型的 kwargs。如果模型是编码器-解码器模型，则不应添加编码器特定的 kwargs 前缀，而应为解码器特定的 kwargs 添加*decoder_*前缀。

为具有语言建模头的模型生成令牌 id 序列。

将🤗 Transformers 模型导出到 ONNX

原始文本：huggingface.co/docs/transformers/v4.37.2/en/main_classes/onnx

🤗 Transformers 提供了一个transformers.onnx包，通过利用配置对象，您可以将模型检查点转换为 ONNX 图。

查看有关导出🤗 Transformers 模型的更多详细信息的指南。

ONNX 配置

我们提供了三个抽象类，您应该根据希望导出的模型架构类型继承其中一个：

• 基于编码器的模型继承自 OnnxConfig

• 基于解码器的模型继承自 OnnxConfigWithPast

• 编码器-解码器模型继承自 OnnxSeq2SeqConfigWithPast

OnnxConfig

class transformers.onnx.OnnxConfig

< source >

( config: PretrainedConfig task: str = 'default' patching_specs: List = None )

用于描述通过 ONNX 格式导出模型的元数据的可导出模型的基类。

flatten_output_collection_property

< source >

( name: str field: Iterable ) → export const metadata = 'undefined';(Dict[str, Any])

返回

（Dict[str, Any])

具有扁平结构和映射到此新结构的键的输出。

展平任何潜在的嵌套结构，将字段的名称与结构中元素的索引扩展。

from_model_config

< source >

( config: PretrainedConfig task: str = 'default' )

为特定模型实例化一个 OnnxConfig

generate_dummy_inputs

< source >

( preprocessor: Union batch_size: int = -1 seq_length: int = -1 num_choices: int = -1 is_pair: bool = False framework: Optional = None num_channels: int = 3 image_width: int = 40 image_height: int = 40 sampling_rate: int = 22050 time_duration: float = 5.0 frequency: int = 220 tokenizer: PreTrainedTokenizerBase = None )

参数

• batch_size (int, 可选，默认为-1) — 用于导出模型的批量大小（-1 表示动态轴）。

• num_choices (int, 可选，默认为-1) — 为多选任务提供的候选答案数量（-1 表示动态轴）。

• seq_length (int, 可选，默认为-1) — 为导出模型指定的序列长度（-1 表示动态轴）。

• is_pair (bool, 可选，默认为False) — 指示输入是否为一对（句子 1，句子 2）

• framework (TensorType, 可选，默认为None) — 分词器将为其生成张量的框架（PyTorch 或 TensorFlow）。

• num_channels (int, 可选，默认为 3) — 生成图像的通道数。

• image_width (int, 可选，默认为 40) — 生成图像的宽度。

• image_height (int, 可选，默认为 40) — 生成图像的高度。

• sampling_rate (int, 可选 默认为 22050) — 用于音频数据生成的采样率。

• time_duration (float, 可选 默认为 5.0) — 用于音频数据生成的采样总秒数。

• frequency (int, 可选 默认为 220) — 生成音频的期望自然频率。

生成要提供给特定框架的 ONNX 导出器的输入

generate_dummy_inputs_onnxruntime

< source >

( reference_model_inputs: Mapping ) → export const metadata = 'undefined';Mapping[str, Tensor]

参数

• reference_model_inputs（[Mapping[str, Tensor]）— 模型的参考输入。

返回

Mapping[str, Tensor]

保存要提供给模型前向函数的 kwargs 的映射

使用参考模型输入为 ONNX Runtime 生成输入。覆盖此选项以使用将编码器和解码器导出为单独的 ONNX 文件的 seq2seq 模型进行推理。

use_external_data_format

< source >

( num_parameters: int )

标志，指示模型是否需要使用外部数据格式

OnnxConfigWithPast

class transformers.onnx.OnnxConfigWithPast

<来源>

( config: PretrainedConfig task: str = 'default' patching_specs: List = None use_past: bool = False )

fill_with_past_key_values_

<来源>

( inputs_or_outputs: Mapping direction: str inverted_values_shape: bool = False )

考虑填充具有过去键值动态轴的输入或输出映射。

with_past

<来源>

( config: PretrainedConfig task: str = 'default' )

实例化一个具有 use_past 属性设置为 True 的 OnnxConfig

OnnxSeq2SeqConfigWithPast

class transformers.onnx.OnnxSeq2SeqConfigWithPast

<来源>

( config: PretrainedConfig task: str = 'default' patching_specs: List = None use_past: bool = False )

ONNX 特性

每个 ONNX 配置都与一组 特性 关联，使您能够为不同类型的拓扑或任务导出模型。

FeaturesManager

class transformers.onnx.FeaturesManager

<来源>

( )

check_supported_model_or_raise

<来源>

( model: Union feature: str = 'default' )

检查模型是否具有请求的特征。

determine_framework

<来源>

( model: str framework: str = None )

参数

• model (str) — 要导出的模型的名称。

• framework (str, 可选, 默认为 None) — 用于导出的框架。如果未提供，则参见上文的优先级。

确定用于导出的框架。

优先级按以下顺序排列：

1. 通过 framework 的用户输入。

2. 如果提供了本地检查点，则使用与检查点相同的框架。

3. 环境中可用的框架，优先考虑 PyTorch。

get_config

<来源>

( model_type: str feature: str ) → export const metadata = 'undefined';OnnxConfig

参数

• model_type (str) — 要检索配置的模型类型。

• feature (str) — 要检索配置的特征。

返回

OnnxConfig

用于组合的配置

获取模型类型和特征组合的 OnnxConfig。

get_model_class_for_feature

<来源>

( feature: str framework: str = 'pt' )

参数

• feature (str) — 所需的特征。

• framework (str, 可选, 默认为 "pt") — 用于导出的框架。

尝试从特征名称中检索 AutoModel 类。

get_model_from_feature

<来源>

( feature: str model: str framework: str = None cache_dir: str = None )

参数

• feature (str) — 所需的特征。

• model (str) — 要导出的模型的名称。

• framework (str, 可选, 默认为 None) — 用于导出的框架。如果未提供，则参见 FeaturesManager.determine_framework 的优先级。

尝试从模型的名称和要启用的特征中检索模型。

get_supported_features_for_model_type

<来源>

( model_type: str model_name: Optional = None )

参数

• model_type (str) — 要检索支持特征的模型类型。

• model_name (str, 可选) — 模型对象的名称属性，仅用于异常消息。

尝试从模型类型中检索特征 -> OnnxConfig 构造函数映射。

优化

原始文本：huggingface.co/docs/transformers/v4.37.2/en/main_classes/optimizer_schedules

.optimization模块提供：

• 一个带有固定权重衰减的优化器，可用于微调模型，以及

• _LRSchedule继承的形式有几个调度对象：

• 一个梯度累积类，用于累积多个批次的梯度

AdamW（PyTorch）

class transformers.AdamW

<来源>

( params: Iterable lr: float = 0.001 betas: Tuple = (0.9, 0.999) eps: float = 1e-06 weight_decay: float = 0.0 correct_bias: bool = True no_deprecation_warning: bool = False )

参数

• params（Iterable[nn.parameter.Parameter]）— 要优化的参数的可迭代对象或定义参数组的字典。

• lr（float，可选，默认为 0.001）— 要使用的学习率。

• betas（Tuple[float,float]，可选，默认为(0.9, 0.999)）— Adam 的 betas 参数（b1，b2）。

• eps（float，可选，默认为 1e-06）— Adam 的数值稳定性 epsilon。

• weight_decay（float，可选，默认为 0.0）— 要应用的解耦权重衰减。

• correct_bias（bool，可选，默认为True）— 是否在 Adam 中校正偏差（例如，在 Bert TF 存储库中，它们使用False）。

• no_deprecation_warning（bool，可选，默认为False）— 用于禁用弃用警告的标志（设置为True以禁用警告）。

实现了带有权重衰减修复的 Adam 算法，该算法在解耦权重衰减正则化中引入。

step

<来源>

( closure: Callable = None )

参数

• closure（Callable，可选）— 重新评估模型并返回损失的闭包。

执行单个优化步骤。

AdaFactor（PyTorch）

class transformers.Adafactor

<来源>

( params lr = None eps = (1e-30, 0.001) clip_threshold = 1.0 decay_rate = -0.8 beta1 = None weight_decay = 0.0 scale_parameter = True relative_step = True warmup_init = False )

参数

• params（Iterable[nn.parameter.Parameter]）— 要优化的参数的可迭代对象或定义参数组的字典。

• lr（float，可选）— 外部学习率。

• eps（Tuple[float, float]，可选，默认为(1e-30, 0.001)）— 平方梯度和参数比例的正则化常数

• clip_threshold（float，可选，默认为 1.0）— 最终梯度更新的均方根阈值

• decay_rate（float，可选，默认为-0.8）— 用于计算平方运行平均值的系数

• beta1（float，可选）— 用于计算梯度的运行平均值的系数

• weight_decay（float，可选，默认为 0.0）— 权重衰减（L2 惩罚）

• scale_parameter（bool，可选，默认为True）— 如果为 True，则学习率将按均方根缩放

• relative_step（bool，可选，默认为True）— 如果为 True，则计算时间相关的学习率，而不是外部学习率

• warmup_init（bool，可选，默认为False）— 时间相关的学习率计算取决于是否使用了热身初始化

AdaFactor 的 PyTorch 实现可用作 Adam 原始 fairseq 代码的替代品：github.com/pytorch/fairseq/blob/master/fairseq/optim/adafactor.py

论文：Adafactor：自适应学习率与亚线性内存成本 arxiv.org/abs/1804.04235 请注意，此优化器根据scale_parameter、relative_step和warmup_init选项内部调整学习率。要使用手动（外部）学习率调度，您应将scale_parameter=False和relative_step=False。

此实现处理低精度（FP16，bfloat）值，但我们尚未进行彻底测试。

推荐的 T5 微调设置（discuss.huggingface.co/t/t5-finetuning-tips/684/3）：

• 不建议在没有 LR 热身或 clip_threshold 的情况下进行训练。

  • 使用计划的 LR 热身到固定的 LR

  • 使用 clip_threshold=1.0 (arxiv.org/abs/1804.04235)

• 禁用相对更新

• 使用 scale_parameter=False

• 不应该在 Adafactor 旁边使用额外的优化器操作，如梯度裁剪。

示例：

Adafactor(model.parameters(), scale_parameter=False, relative_step=False, warmup_init=False, lr=1e-3)

其他人报告以下组合效果很好：

Adafactor(model.parameters(), scale_parameter=True, relative_step=True, warmup_init=True, lr=None)

当使用lr=None与 Trainer 时，您很可能需要使用AdafactorSchedule

调度器如下：

from transformers.optimization import Adafactor, AdafactorSchedule

optimizer = Adafactor(model.parameters(), scale_parameter=True, relative_step=True, warmup_init=True, lr=None)
lr_scheduler = AdafactorSchedule(optimizer)
trainer = Trainer(..., optimizers=(optimizer, lr_scheduler))

用法：

# replace AdamW with Adafactor
optimizer = Adafactor(
    model.parameters(),
    lr=1e-3,
    eps=(1e-30, 1e-3),
    clip_threshold=1.0,
    decay_rate=-0.8,
    beta1=None,
    weight_decay=0.0,
    relative_step=False,
    scale_parameter=False,
    warmup_init=False,
)

步骤

<来源>

( closure = None )

参数

• 闭包（可调用，可选）— 重新评估模型并返回损失的闭包。

执行单个优化步骤

AdamWeightDecay（TensorFlow）

class transformers.AdamWeightDecay

<来源>

( learning_rate: Union = 0.001 beta_1: float = 0.9 beta_2: float = 0.999 epsilon: float = 1e-07 amsgrad: bool = False weight_decay_rate: float = 0.0 include_in_weight_decay: Optional = None exclude_from_weight_decay: Optional = None name: str = 'AdamWeightDecay' **kwargs )

参数

• learning_rate（Union[float, tf.keras.optimizers.schedules.LearningRateSchedule]，可选，默认为 0.001）— 要使用的学习率或计划。

• beta_1（float，可选，默认为 0.9）— Adam 中的 beta1 参数，即第 1 动量估计的指数衰减率。

• beta_2（float，可选，默认为 0.999）— Adam 中的 beta2 参数，即第 2 动量估计的指数衰减率。

• epsilon（float，可选，默认为 1e-07）— Adam 中的 epsilon 参数，这是用于数值稳定性的小常数。

• amsgrad（bool，可选，默认为False）— 是否应用 AMSGrad 变体的算法，参见关于 Adam 及其更多的收敛性。

• weight_decay_rate（float，可选，默认为 0.0）— 要应用的权重衰减。

• include_in_weight_decay（List[str]，可选）— 要应用权重衰减的参数名称（或 re 模式）的列表。如果没有传递，则默认情况下将权重衰减应用于所有参数（除非它们在exclude_from_weight_decay中）。

• exclude_from_weight_decay（List[str]，可选）— 要排除不应用权重衰减的参数名称（或 re 模式）的列表。如果传递了include_in_weight_decay，则其中的名称将取代此列表。

• name（str，可选，默认为"AdamWeightDecay"）— 应用梯度时创建的操作的可选名称。

• kwargs（Dict[str, Any]，可选）— 关键字参数。允许为{clipnorm，clipvalue，lr，decay}。clipnorm是按范数裁剪梯度；clipvalue是按值裁剪梯度，decay包含了向后兼容性，允许学习率的时间反转衰减。lr包含了向后兼容性，建议使用learning_rate代替。

Adam 启用 L2 权重衰减和梯度的全局范数裁剪。只是将权重的平方添加到损失函数中不是使用 Adam 进行 L2 正则化/权重衰减的正确方式，因为这将以奇怪的方式与 m 和 v 参数交互，如解耦权重衰减正则化所示。

相反，我们希望以一种不会与 m/v 参数交互的方式衰减权重。这相当于使用纯（非动量）SGD 将权重的平方添加到损失中。

from_config

<来源>

( config )

使用其配置创建具有 WarmUp 自定义对象的优化器。

transformers.create_optimizer

<来源>

( init_lr: float num_train_steps: int num_warmup_steps: int min_lr_ratio: float = 0.0 adam_beta1: float = 0.9 adam_beta2: float = 0.999 adam_epsilon: float = 1e-08 adam_clipnorm: Optional = None adam_global_clipnorm: Optional = None weight_decay_rate: float = 0.0 power: float = 1.0 include_in_weight_decay: Optional = None )

参数

• init_lr（float）—热身阶段结束时的期望学习率。

• num_train_steps（int）—训练步骤的总数。

• num_warmup_steps（int）—热身步骤的数量。

• min_lr_ratio（float，可选，默认为 0）—线性衰减结束时的最终学习率将为init_lr * min_lr_ratio。

• adam_beta1（float，可选，默认为 0.9）—Adam 中使用的 beta1。

• adam_beta2（float，可选，默认为 0.999）—Adam 中使用的 beta2。

• adam_epsilon（float，可选，默认为 1e-8）—Adam 中使用的 epsilon。

• adam_clipnorm（float，可选，默认为None）—如果不是None，则将每个权重张量的梯度范数剪裁为此值。

• adam_global_clipnorm（float，可选，默认为None）—如果不是None，则将梯度范数剪裁为此值。使用此参数时，规范是在所有权重张量上计算的，就好像它们被连接成一个单一向量。

• weight_decay_rate（float，可选，默认为 0）—要使用的权重衰减。

• power（float，可选，默认为 1.0）—用于 PolynomialDecay 的幂。

• include_in_weight_decay（List[str]，可选）—要应用权重衰减的参数名称（或 re 模式）的列表。如果未传递任何内容，则将权重衰减应用于除偏置和层归一化参数之外的所有参数。

创建一个使用热身阶段后跟线性衰减的学习率时间表的优化器。

时间表

学习率时间表（Pytorch）

class transformers.SchedulerType

<来源>

( value names = None module = None qualname = None type = None start = 1 )

一个枚举。

transformers.get_scheduler

<来源>

( name: Union optimizer: Optimizer num_warmup_steps: Optional = None num_training_steps: Optional = None scheduler_specific_kwargs: Optional = None )

参数

• name（str或SchedulerType）—要使用的调度程序的名称。

• optimizer（torch.optim.Optimizer）—训练期间将使用的优化器。

• num_warmup_steps（int，可选）—要执行的热身步骤数。并非所有调度程序都需要（因此参数是可选的），如果未设置并且调度程序类型需要，则函数将引发错误。

• num_training_steps（int，可选）—要执行的训练步骤数。并非所有调度程序都需要（因此参数是可选的），如果未设置并且调度程序类型需要，则函数将引发错误。

• scheduler_specific_kwargs（dict，可选）—用于诸如带重启的余弦等调度程序的额外参数。不匹配的调度程序类型和调度程序参数将导致调度程序函数引发 TypeError。

从其名称获取任何调度程序的统一 API。

transformers.get_constant_schedule

<来源>

( optimizer: Optimizer last_epoch: int = -1 )

参数

• optimizer（~torch.optim.Optimizer）—要为其调度学习率的优化器。

• last_epoch（int，可选，默认为-1）—恢复训练时的最后一个时期的索引。

使用优化器中设置的学习率创建一个具有恒定学习率的时间表。

transformers.get_constant_schedule_with_warmup

<来源>

( optimizer: Optimizer num_warmup_steps: int last_epoch: int = -1 )

参数

• optimizer（~torch.optim.Optimizer）—要为其调度学习率的优化器。

• num_warmup_steps（int）—热身阶段的步数。

• last_epoch（int，可选，默认为-1）—恢复训练时的最后一个时期的索引。

创建一个具有恒定学习率的时间表，在此期间学习率在 0 和优化器中设置的初始 lr 之间线性增加的热身期之前。

#### transformers.get_cosine_schedule_with_warmup

< source >

( optimizer: Optimizer num_warmup_steps: int num_training_steps: int num_cycles: float = 0.5 last_epoch: int = -1 )

参数

• optimizer (~torch.optim.Optimizer) — 要调整学习率的优化器。

• num_warmup_steps (int) — 热身阶段的步数。

• num_training_steps (int) — 总训练步数。

• num_cycles (float, optional, defaults to 0.5) — 余弦计划中波数的数量（默认值是从最大值到 0 按照半余弦减少）。

• last_epoch (int, optional, defaults to -1) — 恢复训练时的最后一个周期的索引。

创建一个学习率随余弦函数值下降的计划，从优化器中设置的初始 lr 到 0，经过一个热身阶段，在此期间学习率线性增加从 0 到优化器中设置的初始 lr。

#### transformers.get_cosine_with_hard_restarts_schedule_with_warmup

< source >

( optimizer: Optimizer num_warmup_steps: int num_training_steps: int num_cycles: int = 1 last_epoch: int = -1 )

参数

• optimizer (~torch.optim.Optimizer) — 要调整学习率的优化器。

• num_warmup_steps (int) — 热身阶段的步数。

• num_training_steps (int) — 总训练步数。

• num_cycles (int, optional, defaults to 1) — 要使用的硬重启次数。

• last_epoch (int, optional, defaults to -1) — 恢复训练时的最后一个周期的索引。

创建一个学习率随余弦函数值下降的计划，从优化器中设置的初始 lr 到 0，经过几次硬重启，在此期间学习率线性增加从 0 到优化器中设置的初始 lr。

#### transformers.get_linear_schedule_with_warmup

< source >

( optimizer num_warmup_steps num_training_steps last_epoch = -1 )

参数

• optimizer (~torch.optim.Optimizer) — 要调整学习率的优化器。

• num_warmup_steps (int) — 热身阶段的步数。

• num_training_steps (int) — 总训练步数。

• last_epoch (int, optional, defaults to -1) — 恢复训练时的最后一个周期的索引。

创建一个学习率从优化器中设置的初始 lr 线性下降到 0 的计划，在此期间学习率从 0 线性增加到优化器中设置的初始 lr。

#### transformers.get_polynomial_decay_schedule_with_warmup

< source >

( optimizer num_warmup_steps num_training_steps lr_end = 1e-07 power = 1.0 last_epoch = -1 )

参数

• optimizer (~torch.optim.Optimizer) — 要调整学习率的优化器。

• num_warmup_steps (int) — 热身阶段的步数。

• num_training_steps (int) — 总训练步数。

• lr_end (float, optional, defaults to 1e-7) — 最终 LR。

• power (float, optional, defaults to 1.0) — 功率因子。

• last_epoch (int, optional, defaults to -1) — 恢复训练时的最后一个周期的索引。

创建一个学习率从优化器中设置的初始 lr 按多项式衰减到由lr_end定义的最终 lr 的计划，在此期间学习率从 0 线性增加到优化器中设置的初始 lr。

注意：power 默认为 1.0，与 fairseq 实现相同，fairseq 实现又基于原始 BERT 实现 github.com/google-research/bert/blob/f39e881b169b9d53bea03d2d341b31707a6c052b/optimization.py#L37

transformers.get_inverse_sqrt_schedule

<来源>

( optimizer: Optimizer num_warmup_steps: int timescale: int = None last_epoch: int = -1 )

参数

• optimizer (~torch.optim.Optimizer) — 要调整学习率的优化器。

• num_warmup_steps (int) — 热身阶段的步数。

• timescale (int, 可选, 默认为 num_warmup_steps) — 时间尺度。

• last_epoch (int, 可选, 默认为 -1) — 恢复训练时的最后一个时代的索引。

创建一个具有反平方根学习率的调度，从优化器中设置的初始 lr 开始，在一个热身期间之后，该期间将使 lr 从 0 线性增加到优化器中设置的初始 lr。

Warmup（TensorFlow）

类 transformers.WarmUp

<来源>

( initial_learning_rate: float decay_schedule_fn: Callable warmup_steps: int power: float = 1.0 name: str = None )

参数

• initial_learning_rate (float) — 热身后调度的初始学习率（这将是热身结束时的学习率）。

• decay_schedule_fn (Callable) — 在热身后应用于剩余训练的调度函数。

• warmup_steps (int) — 训练中热身阶段的步数。

• power (float, 可选, 默认为 1.0) — 用于多项式热身的幂（默认为线性热身）。

• name (str, 可选) — 调度期间返回张量的可选名称前缀。

对给定学习率衰减调度应用热身调度。

梯度策略

GradientAccumulator（TensorFlow）

类 transformers.GradientAccumulator

<来源>

( )

梯度累积实用程序。与分布策略一起使用时，应在副本上下文中调用累加器。梯度将在每个副本上本地累积，无需同步。然后用户应调用.gradients，根据需要缩放梯度，并将结果传递给apply_gradients。

重置

<来源>

( )

重置当前副本上累积的梯度。
创建一个学习率从优化器中设置的初始 lr 按多项式衰减到由lr_end定义的最终 lr 的计划，在此期间学习率从 0 线性增加到优化器中设置的初始 lr。

注意：power 默认为 1.0，与 fairseq 实现相同，fairseq 实现又基于原始 BERT 实现 github.com/google-research/bert/blob/f39e881b169b9d53bea03d2d341b31707a6c052b/optimization.py#L37

transformers.get_inverse_sqrt_schedule

<来源>

( optimizer: Optimizer num_warmup_steps: int timescale: int = None last_epoch: int = -1 )

参数

• optimizer (~torch.optim.Optimizer) — 要调整学习率的优化器。

• num_warmup_steps (int) — 热身阶段的步数。

• timescale (int, 可选, 默认为 num_warmup_steps) — 时间尺度。

• last_epoch (int, 可选, 默认为 -1) — 恢复训练时的最后一个时代的索引。

创建一个具有反平方根学习率的调度，从优化器中设置的初始 lr 开始，在一个热身期间之后，该期间将使 lr 从 0 线性增加到优化器中设置的初始 lr。

Warmup（TensorFlow）

类 transformers.WarmUp

<来源>

( initial_learning_rate: float decay_schedule_fn: Callable warmup_steps: int power: float = 1.0 name: str = None )

参数

• initial_learning_rate (float) — 热身后调度的初始学习率（这将是热身结束时的学习率）。

• decay_schedule_fn (Callable) — 在热身后应用于剩余训练的调度函数。

• warmup_steps (int) — 训练中热身阶段的步数。

• power (float, 可选, 默认为 1.0) — 用于多项式热身的幂（默认为线性热身）。

• name (str, 可选) — 调度期间返回张量的可选名称前缀。

对给定学习率衰减调度应用热身调度。

梯度策略

GradientAccumulator（TensorFlow）

类 transformers.GradientAccumulator

<来源>

( )

梯度累积实用程序。与分布策略一起使用时，应在副本上下文中调用累加器。梯度将在每个副本上本地累积，无需同步。然后用户应调用.gradients，根据需要缩放梯度，并将结果传递给apply_gradients。

重置

<来源>

( )

重置当前副本上累积的梯度。