Transformers 文档

生成

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

生成

每个框架在其各自的GenerationMixin类中都实现了用于文本生成的生成方法

无论您选择哪种框架,都可以使用 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 (boolstr, 可选, 默认为 False) — 控制基于束的方法(如束搜索)的停止条件。它接受以下值:True,生成在有 num_beams 个完整候选时立即停止;False,应用启发式方法,当找到更好候选的可能性很小时停止生成;"never",束搜索过程仅在无法找到更好候选时停止(规范束搜索算法)。
  • max_time (float, 可选) — 您允许计算运行的最长时间(秒)。生成仍将在分配时间过后完成当前传递。
  • stop_strings (strlist[str], 可选) — 如果模型输出这些字符串,则应终止生成的字符串或字符串列表。

控制所用生成策略的参数

  • do_sample (bool, 可选, 默认为 False) — 是否使用采样;否则使用贪婪解码。
  • num_beams (int, 可选, 默认为 1) — 束搜索的束数。1 表示没有束搜索。
  • num_beam_groups (int, 可选, 默认为 1) — 将 num_beams 分成组的数量,以确保不同束组之间的多样性。有关更多详细信息,请参阅这篇论文
  • penalty_alpha (float, 可选) — 对比搜索解码中用于平衡模型置信度和退化惩罚的值。
  • dola_layers (strlist[int], 可选) — 用于DoLa解码的层。如果为 None,则不使用DoLa解码。如果为字符串,则必须是“low”或“high”之一,分别表示使用模型层的前半部分或后半部分。“low”表示前20层的前半部分,而“high”表示后20层的后半部分。如果为整数列表,则必须包含用于DoLa中候选过早层的层索引。第0层是模型的词嵌入层。设置为 'low' 可改善长答案推理任务,设置为 'high' 可改善短答案任务。有关更多详细信息,请查看文档论文

控制缓存的参数

  • use_cache (bool, 可选, 默认为 True) — 模型是否应使用过去的键/值注意力(如果适用于模型)来加快解码速度。
  • cache_implementation (str, 可选, 默认为 None) — 在 generate 中实例化的缓存类的名称,用于加快解码速度。可能的值有:

    如果未指定,我们将使用模型的默认缓存(通常是 DynamicCache)。有关更多信息,请参阅我们的缓存文档

  • cache_config (CacheConfigdict, 可选, 默认为 None) — 用于键值缓存类的参数可以通过 cache_config 传入。可以作为 Dict 传入,它将在内部转换为相应的 CacheConfig。否则,可以作为与指定 cache_implementation 匹配的 CacheConfig 类传入。
  • return_legacy_cache (bool, 可选, 默认为 True) — 默认使用 DynamicCache 时是否返回旧版或新格式的缓存。

模型输出 logits 操作参数

  • temperature (float, 可选, 默认为 1.0) — 用于调整下一个标记概率的值。此值在模型的 generation_config.json 文件中设置。如果未设置,默认值为 1.0。
  • top_k (int, 可选, 默认为 50) — 为 top-k 过滤保留的最高概率词汇标记数。此值在模型的 generation_config.json 文件中设置。如果未设置,默认值为 50。
  • top_p (float, 可选, 默认为 1.0) — 如果设置为浮点数 < 1,则仅保留概率之和为 top_p 或更高的最小概率词汇标记集用于生成。此值在模型的 generation_config.json 文件中设置。如果未设置,默认值为 1.0。
  • min_p (float, 可选) — 最小标记概率,将按最可能标记的概率进行缩放。它必须是 0 到 1 之间的值。典型值在 0.01-0.2 范围内,与将 top_p 设置在 0.99-0.8 范围内具有可比的选择性(使用与正常 top_p 值相反的值)。
  • typical_p (float, 可选, 默认为 1.0) — 局部典型性衡量了给定已生成的部分文本,预测下一个目标标记的条件概率与预测下一个随机标记的预期条件概率的相似程度。如果设置为浮点数 < 1,则保留最小的局部典型标记集,其概率之和为 typical_p 或更高,用于生成。有关更多详细信息,请参阅这篇论文
  • epsilon_cutoff (float, 可选, 默认为 0.0) — 如果设置为严格介于 0 和 1 之间的浮点数,则仅对条件概率大于 epsilon_cutoff 的标记进行采样。在论文中,建议的值范围为 3e-4 到 9e-4,具体取决于模型的大小。有关更多详细信息,请参阅截断采样作为语言模型去平滑化
  • eta_cutoff (float, 可选, 默认为 0.0) — Eta 采样是局部典型采样和 epsilon 采样的混合。如果设置为严格介于 0 和 1 之间的浮点数,则仅当标记大于 eta_cutoffsqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits))) 时才考虑该标记。后一项直观地表示预期下一个标记概率,按 sqrt(eta_cutoff) 缩放。在论文中,建议的值范围为 3e-4 到 2e-3,具体取决于模型的大小。有关更多详细信息,请参阅截断采样作为语言模型去平滑化
  • diversity_penalty (float, 可选, 默认为 0.0) — 如果光束在某个特定时间生成与其他组中的任何光束相同的标记,则从该光束的分数中减去此值。请注意,diversity_penalty 仅在启用 group beam search 时有效。
  • repetition_penalty (float, 可选, 默认为 1.0) — 重复惩罚的参数。1.0 表示无惩罚。有关更多详细信息,请参阅这篇论文
  • encoder_repetition_penalty (float, 可选, 默认为 1.0) — 编码器重复惩罚的参数。对不在原始输入中的序列进行指数惩罚。1.0 表示无惩罚。
  • length_penalty (float, 可选, 默认为 1.0) — 对基于束的生成使用的长度进行指数惩罚。它以序列长度的指数形式应用,然后用于除以序列的分数。由于分数是序列的对数似然(即负值),因此 length_penalty > 0.0 促进较长序列,而 length_penalty < 0.0 鼓励较短序列。
  • no_repeat_ngram_size (int, 可选, 默认为 0) — 如果设置为大于 0 的整数,则该大小的所有 n-gram 只能出现一次。
  • bad_words_ids (list[list[int]], 可选) — 不允许生成的标记 ID 列表的列表。有关更多文档和示例,请查看NoBadWordsLogitsProcessor
  • force_words_ids (list[list[int]]list[list[list[int]]], 可选) — 必须生成的标记 ID 列表。如果给定 list[list[int]],则将其视为必须包含的单词的简单列表,与 bad_words_ids 相反。如果给定 list[list[list[int]]],则会触发不相交约束,其中可以允许每个单词的不同形式。
  • renormalize_logits (bool, 可选, 默认为 False) — 是否在应用所有 logits 处理器(包括自定义处理器)后重新规范化 logits。强烈建议将此标志设置为 True,因为搜索算法假设分数 logits 已规范化,但某些 logits 处理器会破坏规范化。
  • constraints (list[Constraint], 可选) — 可以添加到生成中的自定义约束,以确保输出将以最合理的方式包含 Constraint 对象定义的某些标记的使用。
  • forced_bos_token_id (int, 可选, 默认为 model.config.forced_bos_token_id) — 在 decoder_start_token_id 之后强制作为第一个生成标记的标记 ID。对于像 mBART 这样的多语言模型很有用,其中第一个生成的标记需要是目标语言标记。
  • forced_eos_token_id (int 或 list[int], *可选*, 默认为 model.config.forced_eos_token_id) -- 达到 max_length` 时强制作为最后一个生成标记的标记 ID。可选地,使用列表来设置多个序列结束标记。
  • remove_invalid_values (bool, 可选, 默认为 model.config.remove_invalid_values) — 是否移除模型可能存在的 naninf 输出,以防止生成方法崩溃。请注意,使用 remove_invalid_values 可能会减慢生成速度。
  • exponential_decay_length_penalty (tuple(int, float), 可选) — 此元组在生成一定数量的标记后添加指数递增的长度惩罚。元组应包含:(start_index, decay_factor),其中 start_index 指示惩罚开始的位置,decay_factor 表示指数衰减的因子。
  • suppress_tokens (list[int], 可选) — 在生成时将被抑制的标记列表。SupressTokens logit 处理器将它们的对数概率设置为 -inf,以便它们不被采样。
  • begin_suppress_tokens (list[int], 可选) — 在生成开始时将被抑制的标记列表。SupressBeginTokens logit 处理器将它们的对数概率设置为 -inf,以便它们不被采样。
  • sequence_bias (dict[tuple[int], float], 可选)) — 将标记序列映射到其偏差项的字典。正偏差会增加序列被选择的几率,而负偏差则相反。有关更多文档和示例,请查看SequenceBiasLogitsProcessor
  • token_healing (bool, 可选, 默认为 False) — 通过将提示的尾部标记替换为其适当的扩展来修复提示的尾部标记。这可以提高受贪婪分词偏差影响的提示的完成质量。
  • guidance_scale (float, 可选) — 用于无分类器引导 (CFG) 的引导比例。通过设置 guidance_scale > 1 启用 CFG。更高的引导比例会鼓励模型生成与输入提示更紧密相关的样本,通常以牺牲较差质量为代价。
  • low_memory (bool, 可选) — 切换到顺序束搜索和顺序 topk,用于对比搜索以减少峰值内存。与束搜索和对比搜索一起使用。
  • watermarking_config (BaseWatermarkingConfigdict, 可选) — 通过对随机选择的“绿色”标记集添加少量偏差来为模型输出加水印的参数。有关更多详细信息,请参阅 SynthIDTextWatermarkingConfigWatermarkingConfig 的文档。如果作为 Dict 传入,它将在内部转换为 WatermarkingConfig

定义生成输出变量的参数

  • num_return_sequences (int, optional, 默认为 1) — 批次中每个元素独立计算的返回序列的数量。
  • output_attentions (bool, optional, 默认为 False) — 是否返回所有注意力层的注意力张量。更多详细信息请参阅返回张量中的 attentions
  • output_hidden_states (bool, optional, 默认为 False) — 是否返回所有层的隐藏状态。更多详细信息请参阅返回张量中的 hidden_states
  • output_scores (bool, optional, 默认为 False) — 是否返回预测分数。更多详细信息请参阅返回张量中的 scores
  • output_logits (bool, optional) — 是否返回未经处理的预测对数分数。更多详细信息请参阅返回张量中的 logits
  • return_dict_in_generate (bool, optional, 默认为 False) — 是否返回 ModelOutput 对象,而不是仅返回生成的序列。要返回生成缓存(当 use_cacheTrue 时)或可选输出(请参阅以 output_ 开头的标志),此标志必须设置为 True

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

  • 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, 默认为 0) — 如果设置为大于 0 的整数,则 encoder_input_ids 中出现的所有该大小的 n-gram 都不能出现在 decoder_input_ids 中。
  • decoder_start_token_id (int or list[int], optional) — 如果编码器-解码器模型以与 bos 不同的标记开始解码,则此标记的 ID 或长度为 batch_size 的列表。指定列表可以为批次中的每个元素设置不同的起始 ID(例如,在一个批次中使用不同目标语言的多语言模型)。

与辅助生成相关的参数

  • is_assistant (bool, optional, 默认为 False) — 模型是否为辅助(草稿)模型。
  • num_assistant_tokens (int, optional, 默认为 20) — 定义了辅助模型在每次迭代中被目标模型检查之前应生成的推测性标记的数量。num_assistant_tokens 的值越高,生成越具有推测性:如果辅助模型性能良好,可以实现更大的加速;如果辅助模型需要大量校正,则加速较小。
  • num_assistant_tokens_schedule (str, optional, 默认为 "constant") — 定义了在推理过程中最大辅助标记将如何变化的调度。
    • "heuristic":当所有推测性标记都正确时,将 num_assistant_tokens 增加 2,否则减少 1。num_assistant_tokens 的值在多次使用相同辅助模型的生成调用中保持不变。
    • "heuristic_transient":与 "heuristic" 相同,但每次生成调用后,num_assistant_tokens 会重置为其初始值。
    • "constant":在生成过程中 num_assistant_tokens 保持不变。
  • assistant_confidence_threshold (float, optional, 默认为 0.4) — 辅助模型的置信度阈值。如果辅助模型对其当前标记的预测置信度低于此阈值,则辅助模型将停止当前标记生成迭代,即使尚未达到推测性标记的数量(由 num_assistant_tokens 定义)。辅助模型的置信度阈值在整个推测迭代过程中进行调整,以减少不必要的草稿和目标前向传播次数,偏向于避免假阴性。assistant_confidence_threshold 的值在多次使用相同辅助模型的生成调用中保持不变。它是《动态推测提前加速大型语言模型推测性解码》https://huggingface.co/papers/2405.04304 中动态推测提前的无监督版本。
  • prompt_lookup_num_tokens (int, optional) — 要作为候选标记输出的标记数量。
  • max_matching_ngram_size (int, optional) — 用于在提示中匹配的最大 n-gram 大小。如果未提供,默认为 2。
  • assistant_early_exit(int, optional) — 如果设置为正整数,模型将用作辅助模型时将使用提前退出。只能与支持提前退出(即中间层 logits 可以由 LM head 解释的模型)的模型一起使用。
  • assistant_lookbehind(int, optional, 默认为 10) — 如果设置为正整数,重新编码过程将额外考虑最后 assistant_lookbehind 个辅助标记以正确对齐标记。只能与推测性解码中不同的分词器一起使用。有关更多详细信息,请参阅此博客
  • target_lookbehind(int, optional, 默认为 10) — 如果设置为正整数,重新编码过程将额外考虑最后 target_lookbehind 个目标标记以正确对齐标记。只能与推测性解码中不同的分词器一起使用。有关更多详细信息,请参阅此博客

与性能和编译相关的参数

  • compile_config (CompileConfig, optional) — 如果使用可编译缓存,这将控制 generate 如何编译前向传播以实现更快推理。
  • disable_compile (bool, optional) — 是否禁用前向传播的自动编译。当满足特定条件(包括使用可编译缓存)时,会发生自动编译。如果您发现需要使用此标志,请提出问题。

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

  • 如果 num_beams=1do_sample=False,则为 贪婪解码
  • 如果 penalty_alpha>0.top_k>1,则为 对比搜索
  • 如果 num_beams=1do_sample=True,则为 多项式抽样
  • 如果 num_beams>1do_sample=False,则为 束搜索解码
  • 如果 num_beams>1do_sample=True,则为 束搜索多项式抽样
  • 如果 num_beams>1num_beam_groups>1,则为 多样化束搜索解码
  • 如果 constraints!=Noneforce_words_ids!=None,则为 受约束束搜索解码
  • 如果 assistant_modelprompt_lookup_num_tokens 传递给 .generate(),则为 辅助解码
  • 如果 dola_layers 传递给 .generate(),则为 dola 解码

要了解有关解码策略的更多信息,请参阅文本生成策略指南

这些标志中的大部分都控制着生成的 logits 或停止条件。请务必查看生成相关类以获取可能操作的完整描述以及其用法示例。

from_pretrained

< >

( pretrained_model_name: typing.Union[str, os.PathLike] config_file_name: typing.Union[str, os.PathLike, NoneType] = None cache_dir: typing.Union[str, os.PathLike, NoneType] = None force_download: bool = False local_files_only: bool = False token: typing.Union[bool, str, NoneType] = None revision: str = 'main' **kwargs ) GenerationConfig

参数

  • pretrained_model_name (stros.PathLike) — 可以是:

    • 字符串,huggingface.co 上模型仓库中托管的预训练模型配置的 模型 ID
    • 包含使用 save_pretrained() 方法保存的配置文件的 目录 路径,例如 ./my_model_directory/
  • config_file_name (stros.PathLike, optional, 默认为 "generation_config.json") — 要从 pretrained_model_name 加载的生成配置文件 JSON 文件的名称。
  • cache_dir (stros.PathLike, optional) — 如果不应使用标准缓存,则为下载的预训练模型配置的缓存目录路径。
  • force_download (bool, optional, 默认为 False) — 是否强制(重新)下载配置文件并覆盖现有缓存版本。
  • resume_download — 已弃用并忽略。现在默认情况下,所有下载都将在可能的情况下恢复。将在 Transformers v5 中删除。
  • proxies (dict[str, str], optional) — 要按协议或端点使用的代理服务器字典,例如 {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。代理用于每个请求。
  • token (strbool, optional) — 用作远程文件 HTTP 持有者授权的令牌。如果为 True 或未指定,将使用运行 huggingface-cli login 时生成的令牌(存储在 ~/.huggingface 中)。
  • revision (str, optional, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID,因为我们在 huggingface.co 上使用基于 Git 的系统存储模型和其他工件,因此 revision 可以是 Git 允许的任何标识符。

    要在 Hub 上测试您创建的拉取请求,您可以传递 revision="refs/pr/<pr_number>"

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

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

  • subfolder (str, optional, 默认为 "") — 如果相关文件位于 huggingface.co 上模型仓库的子文件夹中,您可以在此处指定文件夹名称。
  • kwargs (dict[str, Any], optional) — kwargs 中任何键的配置属性值将用于覆盖已加载的值。对于其键不是配置属性的键/值对,其行为由 return_unused_kwargs 关键字参数控制。

返回

GenerationConfig

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

从生成配置文件实例化 GenerationConfig

示例

>>> from transformers import GenerationConfig

>>> # Download configuration from huggingface.co and cache.
>>> generation_config = GenerationConfig.from_pretrained("openai-community/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(
...     "openai-community/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 ) GenerationConfig

参数

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

返回

GenerationConfig

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

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

save_pretrained

< >

( save_directory: typing.Union[str, os.PathLike] config_file_name: typing.Union[str, os.PathLike, NoneType] = None push_to_hub: bool = False **kwargs )

参数

  • save_directory (stros.PathLike) — 配置文件 JSON 将保存的目录(如果不存在,将创建)。
  • config_file_name (stros.PathLike, optional, 默认为 "generation_config.json") — 要保存到 save_directory 的生成配置文件 JSON 的名称。
  • push_to_hub (bool, optional, 默认为 False) — 是否在保存模型后将其推送到 Hugging Face 模型中心。您可以使用 repo_id 指定要推送到的仓库(默认为您命名空间中 save_directory 的名称)。
  • kwargs (dict[str, Any], optional) — 传递给 push_to_hub() 方法的其他关键字参数。

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

update

< >

( **kwargs ) dict[str, Any]

参数

  • kwargs (dict[str, Any]) — 用于尝试更新此类的属性字典。

返回

dict[str, Any]

包含所有未用于更新实例的键值对的字典。

使用 kwargs 中的属性更新此类的属性(如果它们与现有属性匹配),并返回所有未使用的 kwargs

validate

< >

( strict = False )

参数

  • strict (bool) — 如果为 True,则针对发现的任何问题引发异常。如果为 False,则仅记录问题。

验证 GenerationConfig 实例属性的值。当仅从配置实例即可检测到参数设置不正确时,将引发异常。

请注意,此处未验证的一些参数最好在生成运行时验证,因为它们可能取决于其他输入和/或模型,例如与生成长度相关的参数。

get_generation_mode

< >

( assistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = None ) GenerationMode

参数

  • assistant_model (PreTrainedModel, optional) — 用于辅助生成的辅助模型。如果设置,生成模式将是辅助生成。

返回

GenerationMode

实例触发的生成模式。

返回由 GenerationConfig 实例触发的生成模式。

GenerationMixin

class transformers.GenerationMixin

< 来源 >

( )

一个包含所有自回归文本生成功能的类,用作模型类中的混入(mixin)。继承此类的模型将具有特殊的生成相关行为,例如在初始化时加载 `GenerationConfig` 或确保在 `transformers` CI 中运行生成相关测试。

模型类应继承 `GenerationMixin` 以启用调用 `generate` 等方法,或者当它定义了直接或间接依赖于 `GenerationMixin` 的自定义 `generate` 方法时,该方法与 `generate` 等公共方法共享大致相同的接口。以下是三个示例:

  • `LlamaForCausalLM` 应继承 `GenerationMixin` 以启用调用混入中的 `generate` 和其他公共方法;
  • `BlipForQuestionAnswering` 有一个自定义的 `generate` 方法,它与 `GenerationMixin.generate` 的接口大致相同(它有一些额外的参数,并且输出相同)。该函数还通过内部模型间接调用 `GenerationMixin.generate`。因此,`BlipForQuestionAnswering` 应继承 `GenerationMixin`,以便受益于我们代码库中所有与生成相关的自动化;
  • `BarkModel` 有一个自定义的 `generate` 方法,其内部模型之一调用 `GenerationMixin.generate`。然而,它的 `generate` 不与 `GenerationMixin.generate` 共享相同的接口。在这种情况下,`BarkModel` 不应继承 `GenerationMixin`,因为它破坏了 `generate` 接口。

该类公开了 generate(),可用于

  • 如果 num_beams=1do_sample=False,则为 贪婪解码
  • 如果 `penalty_alpha > 0` 且 `top_k > 1`,则为*对比搜索*
  • 如果 num_beams=1do_sample=True,则为 多项式抽样
  • 如果 num_beams>1do_sample=False,则为 束搜索解码
  • 如果 num_beams>1do_sample=True,则为 束搜索多项式抽样
  • 如果 num_beams>1num_beam_groups>1,则为 多样化束搜索解码
  • 如果 constraints!=Noneforce_words_ids!=None,则为 受约束束搜索解码
  • 如果 assistant_modelprompt_lookup_num_tokens 传递给 .generate(),则为 辅助解码

要了解有关解码策略的更多信息,请参阅文本生成策略指南

生成

< 来源 >

( inputs: typing.Optional[torch.Tensor] = None generation_config: typing.Optional[transformers.generation.configuration_utils.GenerationConfig] = None logits_processor: typing.Optional[transformers.generation.logits_process.LogitsProcessorList] = None stopping_criteria: typing.Optional[transformers.generation.stopping_criteria.StoppingCriteriaList] = None prefix_allowed_tokens_fn: typing.Optional[typing.Callable[[int, torch.Tensor], list[int]]] = None synced_gpus: typing.Optional[bool] = None assistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = None streamer: typing.Optional[ForwardRef('BaseStreamer')] = None negative_prompt_ids: typing.Optional[torch.Tensor] = None negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None use_model_defaults: typing.Optional[bool] = None custom_generate: typing.Optional[str] = None **kwargs ) ModelOutput or torch.LongTensor

参数

  • inputs (torch.Tensor,形状根据模态变化,可选) — 用作生成提示或编码器模型输入的序列。如果为 None,该方法将使用 bos_token_id 和批处理大小为 1 的值对其进行初始化。对于仅解码器模型,inputs 应为 input_ids 格式。对于编码器-解码器模型,inputs 可以表示 input_idsinput_valuesinput_featurespixel_values 中的任何一个。
  • generation_config (GenerationConfig可选) — 用作生成调用基础参数化的生成配置。传递给 `generate` 的与 `generation_config` 属性匹配的 `**kwargs` 将覆盖它们。如果未提供 `generation_config`,将使用默认值,其加载优先级如下:1) 如果存在 `generation_config.json` 模型文件,则从中加载;2) 从模型配置中加载。请注意,未指定的参数将继承 GenerationConfig 的默认值,应查阅其文档以参数化生成。
  • logits_processor (LogitsProcessorList可选) — 自定义 logits 处理器,补充从参数和生成配置构建的默认 logits 处理器。如果传入的 logit 处理器已用参数或生成配置创建,则会抛出错误。此功能适用于高级用户。
  • stopping_criteria (StoppingCriteriaList可选) — 自定义停止条件,补充从参数和生成配置构建的默认停止条件。如果传入的停止条件已用参数或生成配置创建,则会抛出错误。如果您的停止条件依赖于 `scores` 输入,请确保向 `generate` 传入 `return_dict_in_generate=True, output_scores=True`。此功能适用于高级用户。
  • prefix_allowed_tokens_fn (Callable[[int, torch.Tensor], list[int]]可选) — 如果提供,此函数会在每一步限制束搜索仅限于允许的词元。如果未提供,则不应用任何限制。此函数接受 2 个参数:批处理 ID batch_idinput_ids。它必须返回一个列表,其中包含在批处理 ID batch_id 和先前生成的词元 inputs_ids 的条件下,下一步生成允许的词元。此参数对于基于前缀的受限生成很有用,如 Autoregressive Entity Retrieval 中所述。
  • synced_gpus (bool可选) — 是否继续运行 while 循环直到达到 `max_length`。除非被覆盖,否则在使用 `FullyShardedDataParallel` 或 DeepSpeed ZeRO Stage 3 与多个 GPU 时,此标志将设置为 `True`,以避免在一个 GPU 比其他 GPU 更早完成生成时发生死锁。否则,默认为 `False`。
  • assistant_model (PreTrainedModel可选) — 可用于加速生成的辅助模型。辅助模型必须具有完全相同的分词器。当使用辅助模型预测候选词元比使用您调用的生成模型运行生成快得多时,即可实现加速。因此,辅助模型应该小得多。
  • streamer (BaseStreamer可选) — 用于流式传输生成序列的流式传输器对象。生成的词元通过 `streamer.put(token_ids)` 传递,流式传输器负责任何进一步的处理。
  • 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。
  • use_model_defaults (bool可选) — 当为 `True` 时,generation_config 中未设置的参数将设置为模型特有的默认生成配置 (model.generation_config),而不是全局默认值 (GenerationConfig())。如果未设置,从 v4.50 开始保存的模型将认为此标志为 True
  • custom_generate (str可选) — 包含 huggingface.co 仓库名称的字符串。如果提供,将执行该仓库中 `custom_generate/generate.py` 文件中定义的自定义 `generate` 函数,而不是标准 `generate` 方法。请注意,生成逻辑完全由该仓库定义,并且返回类型可能与标准 `generate` 方法不同。
  • kwargs (dict[str, Any]可选) — generation_config 的临时参数化和/或将转发到模型 `forward` 函数的其他模型特定 kwargs。如果模型是编码器-解码器模型,编码器特定的 kwargs 不应加前缀,解码器特定的 kwargs 应加 `decoder_` 前缀。

返回

ModelOutputtorch.LongTensor

一个 ModelOutput(如果 return_dict_in_generate=Trueconfig.return_dict_in_generate=True)或一个 torch.LongTensor

如果模型不是编码器-解码器模型(model.config.is_encoder_decoder=False),则可能的 ModelOutput 类型为

如果模型是编码器-解码器模型(model.config.is_encoder_decoder=True),则可能的 ModelOutput 类型为

为具有语言建模头的模型生成词元 ID 序列。

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

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

计算转换分数

< 来源 >

( sequences: Tensor scores: tuple beam_indices: typing.Optional[torch.Tensor] = None normalize_logits: bool = False ) torch.Tensor

参数

  • sequences (torch.LongTensor) — 生成的序列。第二个维度(sequence_length)等于 `max_length`,如果所有批次因 `eos_token_id` 而提前完成,则更短。
  • scores (tuple(torch.FloatTensor)) — 在每个生成步骤中每个词汇词元的转换分数。束转换分数包括词元在束中先前生成的词元对数 softmax 条件下的对数概率。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的词元一个元素),每个张量的形状为 (batch_size*num_beams, config.vocab_size)
  • 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("openai-community/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 | log probability | 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

TFGenerationMixin

class transformers.TFGenerationMixin

< 来源 >

( )

一个包含所有支持生成功能的类,用作 TFPreTrainedModel 中的混入。

该类公开了 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”。要了解有关解码策略的更多信息,请参阅文本生成策略指南

生成

< 来源 >

( inputs: typing.Optional[tensorflow.python.framework.tensor.Tensor] = None generation_config: typing.Optional[transformers.generation.configuration_utils.GenerationConfig] = None logits_processor: typing.Optional[transformers.generation.tf_logits_process.TFLogitsProcessorList] = None seed = None **kwargs ) ModelOutput or tf.Tensor

参数

  • inputs (tf.Tensor,形状根据模态变化,可选) — 用作生成提示或编码器模型输入的序列。如果为 None,该方法将使用 bos_token_id 和批处理大小为 1 的值对其进行初始化。对于仅解码器模型,inputs 应为 input_ids 格式。对于编码器-解码器模型,inputs 可以表示 input_idsinput_valuesinput_featurespixel_values 中的任何一个。
  • generation_config (~generation.GenerationConfig可选) — 用作生成调用基础参数化的生成配置。传递给 `generate` 的与 `generation_config` 属性匹配的 `**kwargs` 将覆盖它们。如果未提供 `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]可选) — generate_config 的临时参数化和/或将转发到模型 `forward` 函数的其他模型特定 kwargs。如果模型是编码器-解码器模型,编码器特定的 kwargs 不应加前缀,解码器特定的 kwargs 应加 `decoder_` 前缀。

返回

ModelOutputtf.Tensor

一个 ModelOutput(如果 return_dict_in_generate=Trueconfig.return_dict_in_generate=True)或一个 tf.Tensor

如果模型不是编码器-解码器模型(model.config.is_encoder_decoder=False),则可能的 ModelOutput 类型为

如果模型是编码器-解码器模型(model.config.is_encoder_decoder=True),则可能的 ModelOutput 类型为

为具有语言建模头的模型生成词元 ID 序列。

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

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

计算转换分数

< 来源 >

( sequences: Tensor scores: tuple beam_indices: typing.Optional[tensorflow.python.framework.tensor.Tensor] = None normalize_logits: bool = False ) tf.Tensor

参数

  • sequences (tf.Tensor) — 生成的序列。第二个维度(sequence_length)等于 `max_length`,如果所有批次因 `eos_token_id` 而提前完成,则更短。
  • scores (tuple(tf.Tensor)) — 在每个生成步骤中每个词汇词元的转换分数。束转换分数包括词元在束中先前生成的词元对数 softmax 条件下的对数概率。由 tf.Tensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的词元一个元素),每个张量的形状为 (batch_size*num_beams, config.vocab_size)
  • beam_indices (tf.Tensor可选) — 在每个生成步骤中生成词元 ID 的束索引。形状为 (batch_size*num_return_sequences, sequence_length)tf.Tensor。仅在生成时 num_beams > 1 时需要。
  • normalize_logits (bool可选,默认为 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("openai-community/gpt2")
>>> model = TFAutoModelForCausalLM.from_pretrained("openai-community/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.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: 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 = 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 中的混入。

该类公开了 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”。要了解有关解码策略的更多信息,请参阅文本生成策略指南

生成

< 来源 >

( input_ids: Array generation_config: typing.Optional[transformers.generation.configuration_utils.GenerationConfig] = None prng_key: typing.Optional[jax.Array] = None trace: bool = True params: typing.Optional[dict[str, jax.Array]] = None logits_processor: typing.Optional[transformers.generation.flax_logits_process.FlaxLogitsProcessorList] = None **kwargs )

参数

  • input_ids (jnp.ndarray,形状为 (batch_size, sequence_length)) — 用作生成提示的序列。
  • generation_config (~generation.GenerationConfig可选) — 用作生成调用基础参数化的生成配置。传递给 `generate` 的与 `generation_config` 属性匹配的 `**kwargs` 将覆盖它们。如果未提供 `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 序列。

< > 在 GitHub 上更新