Transformers documentation
生成
生成
每个框架都在其各自的 GenerationMixin 类中实现了用于文本生成的 generate 方法：
- PyTorch 的 generate() 在 GenerationMixin 中实现。
你可以使用 GenerationConfig 类的实例来参数化 generate 方法。有关控制生成方法行为的完整生成参数列表，请参阅该类。
要了解如何检查模型的生成配置、默认值是什么、如何临时更改参数，以及如何创建并保存自定义的生成配置，请参阅文本生成策略指南。该指南还介绍了如何使用相关功能，例如 token 流式传输。
GenerationConfig
类 transformers.GenerationConfig
< source >( **kwargs )
控制输出长度的参数
- max_length (
int, 可选) — 建议使用max_new_tokens来控制模型生成的 token 数量。max_length仅用于向后兼容。 - max_new_tokens (
int, 可选) — 要生成的最大 token 数量，忽略提示词中的 token 数量。 - min_length (
int，可选) — 要生成的序列的最小长度。对应于输入提示的长度 +min_new_tokens。如果同时设置了min_new_tokens，则其效果会被min_new_tokens覆盖。 - min_new_tokens (
int, 可选) — 要生成的最小 token 数量，忽略提示词中的 token 数量。 - early_stopping (
bool或str，可选) — 控制基于 beam 的方法（如 beam-search）的停止条件。它接受以下值：True，当存在num_beams个完整候选项时立即停止生成；False，应用启发式方法，当找到更优候选项的可能性极低时停止生成；"never"，beam search 过程仅在无法找到更优候选项时才停止（标准 beam search 算法）。 - max_time (
float, 可选) — 允许计算运行的最长时间（以秒为单位）。在分配的时间用尽后，generation 仍会完成当前这一轮处理。 - stop_strings（
str或list[str]，可选）— 一个字符串或字符串列表，如果模型输出了这些内容，则终止生成。
控制所使用生成策略的参数
- do_sample (
bool) — 是否使用采样；否则使用贪心解码。 - num_beams (
int, 可选) — 束搜索的束数量。1 表示不使用束搜索。 - use_mtp — (
bool)： 如果模型支持，是否使用 Multi-Token Prediction (MTP)。
控制缓存的参数
- use_cache (
bool) — 是否让模型使用过去最后的关键/值注意力（如果该模型支持）来加速解码。 - cache_implementation (
str, 可选) — 将在generate, 中实例化的缓存类名称，用于加速解码。可能的取值如下："dynamic"：DynamicCache"static"：StaticCache"offloaded":DynamicCache(offloaded=True)"offloaded_static":StaticCache(offloaded=True)"quantized"：QuantizedCache
如果未指定，我们将使用模型的默认缓存（通常是 DynamicCache）。有关更多信息，请参阅我们的 缓存文档。
- cache_config (
dict，可选，默认为None) — 键值缓存类中使用的参数可以通过cache_config传入。 - max_cache_len (
int, 可选) — 仅在使用静态缓存（cache_implementation设置为"static"或"offloaded_static"）时生效。 将缓存预分配为此长度，而不是当前调用的max_length。请将其一次性设置为预期中最大的调用长度，这样当重复调用generate()且提示词更长或max_new_tokens更大（不超过此上限）时，可以复用同一缓存，而无需触发重新分配和torch.compile重新编译。
用于操作模型输出 logits 的参数
- temperature (
float, 可选) — 用于调节下一个 token 概率的值。该值在模型的generation_config.json文件中设置。如果未设置，默认值为 1.0 - top_k (
int, 可选) — 用于 top-k 过滤时保留的最高概率词表 token 数量。该值在模型的generation_config.json文件中设置。如果未设置，默认值为 50。 - top_p (
float, 可选) — 如果设置为小于 1 的浮点数，则仅保留概率之和达到或超过top_p的最小最可能 token 集合用于生成。该值在模型的generation_config.json文件中设置。如果未设置，默认值为 1.0 - min_p (
float, 可选) — 最小 token 概率，该值会按最可能 token 的概率进行缩放。它必须是 0 到 1 之间的值。典型值在 0.01-0.2 范围内，其选择性类似于将top_p设置在 0.99-0.8 范围内（使用与常规top_p值相反的值）。 - top_h (
float, 可选) — 熵预算缩放因子，用于控制在采样过程中保留分布中多少熵。 取值必须在 0 到 1 之间。在每一步中，token 按概率排序，并保留最小的 token 前缀，使其重归一化熵小于或等于完整分布熵的top_h倍。 较小的值（例如 0.2–0.5）会产生更集中、更确定性的输出，而接近 1.0 的值则允许更多的随机性和多样性。典型取值范围在 0.3–0.6 之间。 - typical_p (
float, 可选) — 局部典型性衡量了在已生成部分文本的条件下，预测下一个目标 token 的条件概率与预测下一个随机 token 的期望条件概率之间的相似程度。如果设置为小于 1 的 float 值，则保留概率之和达到typical_p或更高的、最局部典型的 token 集合用于生成。有关更多详细信息，请参阅 这篇论文。 - epsilon_cutoff (
float, 可选) — 如果设置为严格介于 0 和 1 之间的浮点数，则仅会采样条件概率大于epsilon_cutoff的 token。论文中建议的取值范围在 3e-4 到 9e-4 之间，具体取决于模型的大小。有关更多详细信息，请参阅 Truncation Sampling as Language Model Desmoothing。 - eta_cutoff (
float, 可选) — Eta 采样是局部典型采样（locally typical sampling）与 epsilon 采样的混合。如果设置为严格介于 0 和 1 之间的浮点数，则仅当某个 token 大于eta_cutoff或sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits)))时，该 token 才会被考虑。后一项在直观上表示期望的下一个 token 概率，并按sqrt(eta_cutoff)进行缩放。论文中建议的取值范围为 3e-4 到 2e-3，具体取决于模型的大小。有关更多详细信息，请参阅 Truncation Sampling as Language Model Desmoothing。 - repetition_penalty (
float，可选) — 重复惩罚参数。1.0 表示无惩罚。有关更多详细信息，请参阅这篇论文。 - encoder_repetition_penalty (
float, 可选) — encoder_repetition_penalty 的参数。对不在原始输入中的序列施加指数惩罚。1.0 表示无惩罚。 - length_penalty (
float, 可选) — 用于基于 beam 的生成过程中，对序列长度施加的指数惩罚。它作为指数作用于序列长度，进而用于除以序列的得分。由于得分是序列的对数似然（即为负值），length_penalty> 0.0 会促进生成更长的序列，而length_penalty< 0.0 则鼓励生成更短的序列。 - no_repeat_ngram_size (
int, 可选) — 如果设置为大于 0 的整数，则所有该大小的 n-gram 只能出现一次。 - bad_words_ids（
list[list[int]]，可选）— 不允许生成的 token id 列表的列表。有关更多文档和示例，请参阅 NoBadWordsLogitsProcessor。 - renormalize_logits (
bool) — 是否在对所有 logits 处理器（包括自定义处理器）应用之后重新归一化 logits。强烈建议将此标志设置为True，因为搜索算法假设分数 logits 已归一化，但某些 logits 处理器会破坏归一化。 - forced_bos_token_id (
int，可选，默认为model.config.forced_bos_token_id) — 在decoder_start_token_id之后强制作为首个生成 token 的 token id。对于像 mBART 这样的多语言模型非常有用，因为首个生成的 token 需要是目标语言的 token。 - forced_eos_token_id (
intor list[int], *optional*, defaults tomodel.config.forced_eos_token_id) -- The id of the token to force as the last generated token whenmax_length` is reached. Optionally, use a list to set multiple end-of-sequence tokens. - remove_invalid_values (
bool) — 是否移除模型可能产生的 nan 和 inf 输出，以防止生成方法崩溃。请注意，使用remove_invalid_values可能会降低生成速度。 - exponential_decay_length_penalty (
tuple(int, float)，可选) — 此元组在生成一定数量的 token 后，添加一个指数增长的长度惩罚。该元组应包含：(start_index, decay_factor)，其中start_index指示惩罚开始的位置，decay_factor表示指数衰减的因子 - suppress_tokens (
list[int], 可选) — 生成时将被抑制的 token 列表。SuppressTokenslogit 处理器会将它们的 log probs 设置为-inf，从而确保它们不会被采样。 - begin_suppress_tokens (
list[int], 可选) — 在生成开始时将被抑制的 token 列表。SuppressBeginTokenslogit 处理器会将它们的 log prob 设置为-inf，从而避免对其进行采样。 - sequence_bias (
dict[tuple[int], float]，可选) — 一个字典，将 token 序列映射到其偏置项。正偏置会增加该序列被选中的概率，而负偏置则相反。有关更多文档和示例，请参阅 SequenceBiasLogitsProcessor。 - token_healing (
bool) — 通过用相应的扩展替换提示的尾部 token 来修复它们。 这可以提升受贪心分词偏差影响的提示的补全质量。 - guidance_scale (
float, 可选) — 无分类器引导（CFG）的引导尺度。将guidance_scale > 1设置为大于 1 即可启用 CFG。 较高的引导尺度会促使模型生成与输入提示词关联更紧密的样本，但通常以牺牲生成质量为代价。 - watermarking_config (
BaseWatermarkingConfig或dict，可选) — 用于通过向随机选定的“绿色”token 集合添加微小偏差，从而为模型输出添加水印的参数。有关更多详细信息，请参阅 SynthIDTextWatermarkingConfig 和 WatermarkingConfig 的文档。如果以Dict形式传入，内部会将其转换为WatermarkingConfig。
定义 generate 输出变量的参数
- num_return_sequences (
int, 可选) — 批次中每个元素独立计算并返回的序列数量。 - output_attentions (
bool) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量中的attentions。 - output_hidden_states (
bool) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的hidden_states。 - output_scores (
bool) — 是否返回预测分数。有关更多详细信息，请参阅返回张量中的scores。 - output_logits (
bool) — 是否返回未经处理的预测 logit 分数。有关更多详细信息，请参阅返回张量中的logits。 - return_dict_in_generate (
bool) — 是否返回 ModelOutput，而不是仅返回生成的序列。若要返回生成缓存（当use_cache为True时）或可选输出（参见以output_开头的标志），必须将此标志设置为True。
可在生成时使用的特殊标记
- pad_token_id (
int，可选) — padding 令牌的 id。 - bos_token_id (
int，可选) — 序列起始令牌的 id。 - eos_token_id (
Union[int, list[int]], 可选) — 序列结束标记的 id。可选地，使用列表来设置多个 序列结束标记。
仅适用于编码器-解码器模型的生成参数
- encoder_no_repeat_ngram_size (
int, 可选) — 如果设置为大于 0 的整数，则encoder_input_ids中出现的所有该大小的 n-gram 都不能出现在decoder_input_ids中。 - decoder_start_token_id (
int或list[int]，可选) — 如果编码器-解码器模型使用与 bos 不同的 token 开始解码，则指定该 token 的 id，或一个长度为batch_size的列表。指定列表可为批次中的每个元素设置不同的起始 id（例如，在一个批次中包含不同目标语言的多语言模型）。
专用于助手生成的生成参数
- is_assistant (
bool) — 模型是否为助手（草稿）模型。 - num_assistant_tokens (
int, 可选) — 定义在每次迭代中，由 assistant 模型生成、随后交由 target 模型校验的 speculative tokens 数量。num_assistant_tokens的值越大，生成过程就越具 speculative 特性：如果 assistant 模型表现良好，可以获得更大的加速效果；如果 assistant 模型需要大量修正，则加速效果会较小。 - num_assistant_tokens_schedule (
str, 可选) — 定义在推理过程中更改最大助手 token 数的调度策略。"heuristic"：当所有推测 token 均正确时，将num_assistant_tokens增加 2，否则减少 1。num_assistant_tokens的值在多次使用相同 assistant 模型的生成调用中保持不变。"heuristic_transient"：与"heuristic"相同，但每次生成调用后，num_assistant_tokens会重置为其初始值。"constant"：num_assistant_tokens在生成过程中保持不变
- assistant_confidence_threshold (
float, 可选) — 助手模型的置信度阈值。如果助手模型对当前 token 预测的置信度低于此阈值，即使尚未达到 speculative tokens（由num_assistant_tokens定义）的数量，助手模型也会停止当前的 token 生成迭代。助手模型的置信度阈值会在推测迭代过程中动态调整，以减少不必要的 draft 和 target 前向传播次数，并倾向于避免假阴性。assistant_confidence_threshold的值在使用相同助手模型的多次生成调用中保持不变。 它是 Dynamic Speculation Lookahead Accelerates Speculative Decoding of Large Language Models https://huggingface.co/papers/2405.04304 中动态推测前瞻的无监督版本。 - prompt_lookup_num_tokens (
int, 可选) — 要作为候选 token 输出的 token 数量。 - max_matching_ngram_size (
int, 可选) — 用于提示中匹配的 ngram 最大尺寸。如果未提供，默认为 2。 - assistant_early_exit(
int, optional) — 如果设置为正整数，将使用模型的 early exit 作为 assistant。仅适用于支持 early exit 的模型（即中间层的 logits 可以被 LM head 解释的模型）。 - assistant_lookbehind(
int, optional) — 如果设置为正整数，重新编码过程将额外考虑最后assistant_lookbehind个 assistant token，以正确对齐 token。此参数仅可用于在推测解码中使用不同 tokenizer 的场景。 有关更多详细信息，请参阅此 博客。 - target_lookbehind(
int, 可选) — 如果设置为正整数，重新编码过程将额外考虑最后target_lookbehind个目标 token，以正确对齐 token。此参数仅可用于在推测解码中使用不同 tokenizer 的场景。 有关更多详细信息，请参阅此 博客。 - assistant_ensemble_weight (
float, 可选) — 在推测解码中启用静态集成验证。如果设置为(0.0, 1.0)范围内的值，验证器将针对混合分布w * p_target + (1 - w) * q_draft而非p_target来接受 token，以可控的分布偏差换取更高的接受率。默认值为None，可保持解码无损。要求 assistant 模型返回 logits，因此与 prompt lookup decoding 不兼容。 - speculation_type (
str, 可选) — 请求的推测类型。可接受的值为dflash。
与性能和编译相关的参数
用于保存生成任务配置的类。generate 调用支持以下生成方法，适用于文本解码器、文本到文本、语音到文本以及视觉到文本模型：
- 当
num_beams=1且do_sample=False时，使用 greedy decoding - 当
num_beams=1且do_sample=True时，使用 多项式采样 - 当
num_beams>1且do_sample=False时，使用 beam-search decoding - 当
num_beams>1且do_sample=True时，使用 beam-search 多项式采样 - 如果向
.generate()传入了assistant_model或prompt_lookup_num_tokens，则使用 assisted decoding
要了解有关解码策略的更多信息，请参阅文本生成策略指南。
这些标志中的许多用于控制生成过程中的 logits 或停止条件。请务必查阅 generate 相关类，以获取所有可能操作的完整说明及其使用示例。
注意：在生成循环中，配置中仍为 None 的字段会被 GenerationConfig._get_default_generation_params() 覆盖。如果你希望这些字段使用不同的值，请确保在生成配置中显式设置它们。
from_pretrained
< source >( pretrained_model_name: str | os.PathLikeconfig_file_name: str | os.PathLike | None = Nonecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs ) → GenerationConfig
参数
- pretrained_model_name (
str或os.PathLike) — 可以是以下之一：- 一个字符串，即托管在 huggingface.co 模型仓库中的预训练模型配置的 model id。
- 指向一个目录的路径，该目录包含使用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) — 是否强制（重新）下载配置文件，并在存在缓存版本时覆盖它们。 - proxies (
dict[str, str], 可选) — 按协议或端点使用的代理服务器字典，例如{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}.每次请求都会使用这些代理。 - token (
str或bool，可选) — 用于远程文件的 HTTP bearer 授权令牌。如果为True或未指定，则使用运行hf auth login时生成的令牌（存储在~/.huggingface中）。 - revision (
str, 可选, 默认为"main") — 要使用的特定模型版本。由于我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件，因此它可以是分支名称、标签名称或提交 ID，所以revision可以是 git 允许的任何标识符。要测试您在 Hub 上创建的拉取请求，可以传入
revision="refs/pr/<pr_number>"。 - return_unused_kwargs (
bool, 可选, 默认值为False) — 如果False, 为 False，则此函数仅返回最终的配置对象。如果为 True，则此函数返回一个 Tuple(config, unused_kwargs)，其中 unused_kwargs 是一个字典，包含那些键不是配置属性的键值对：即 kwargs 中未用于更新 config 且被忽略的部分。如果
True，则此函数返回一个Tuple(config, unused_kwargs)，其中 unused_kwargs 是一个字典，包含键不是配置属性的键值对：即kwargs中未用于更新config且被忽略的部分。 - subfolder (
str，可选，默认为"") — 如果相关文件位于 huggingface.co 上模型仓库的子文件夹中，您可以在此处指定该文件夹的名称。 - kwargs (
dict[str, Any], 可选) — kwargs 中任何作为配置属性的键的值，将用于覆盖已加载的值。对于键不是配置属性的键值对，其行为由return_unused_kwargs关键字参数控制。
返回值
从此预训练模型实例化的配置对象。
从生成配置文件中实例化一个 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
< source >( model_config: typing.Union[ForwardRef('PreTrainedConfig'), dict] ) → GenerationConfig
从 PreTrainedConfig 实例化一个 GenerationConfig。此函数用于将可能包含生成参数的旧版 PreTrainedConfig 对象转换为独立的 GenerationConfig。
save_pretrained
< source >( save_directory: str | os.PathLikeconfig_file_name: str | os.PathLike | None = Nonepush_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() 类方法重新加载。
更新
< source >( defaults_only = Falseallow_custom_entries = False**kwargs ) → dict[str, Any]
如果 kwargs 中的属性与现有属性匹配，则使用它们更新此类实例的属性，并返回所有未使用的 kwargs。
验证
< source >( strict = Falseuser_set_attributes: set[str] | None = None )
验证 GenerationConfig 实例中各属性的值。如果仅从配置实例本身即可检测到参数化存在错误，则抛出异常。
请注意，某些未在此处进行验证的参数最好在 generate 运行时进行验证，因为它们可能依赖于其他输入和/或模型，例如与生成长度相关的参数。
get_generation_mode
< source >( assistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = None ) → GenerationMode
返回由 GenerationConfig 实例触发的生成模式。
GenerationMixin
一个包含所有自回归文本生成函数的类，用作模型类中的混入（mixin）。
继承此类会使模型具备与生成相关的特殊行为，例如在初始化时加载 GenerationConfig，或确保在 transformers CI 中运行与 generate 相关的测试。
模型类应继承自 GenerationMixin，以便能够调用诸如 generate 之类的方法；或者，当它定义了一个自定义的 generate 方法，且该方法直接或间接依赖于 GenerationMixin 时，也应如此，因为 GenerationMixin 与诸如 generate 等公开方法大致共享相同的接口。以下是三个示例：
LlamaForCausalLM应继承自GenerationMixin，以便调用该 mixin 中的generate及其他公共方法；BlipForQuestionAnswering拥有一个自定义的generate方法，其接口与GenerationMixin.generate大致相同（它包含一些额外的参数，且输出相同）。该函数还会通过内部模型间接调用GenerationMixin.generate。因此，BlipForQuestionAnswering应当继承自GenerationMixin，以利用我们代码库中所有与生成相关的自动化功能；BarkModel具有自定义的generate方法，且其内部的一个模型会调用GenerationMixin.generate。 然而，它的generate与GenerationMixin.generate并不共享相同的接口。在这种情况下，BarkModel不应继承自GenerationMixin，因为这会破坏generate接口。
该类暴露了 generate()，可用于：
- 当
num_beams=1且do_sample=False时，使用 greedy decoding - 当
num_beams=1且do_sample=True时，使用 多项式采样 - 当
num_beams>1且do_sample=False时，使用 beam-search decoding - 当
num_beams>1且do_sample=True时，使用 beam-search 多项式采样 - 如果向
.generate()传入了assistant_model或prompt_lookup_num_tokens，则使用 assisted decoding
要了解有关解码策略的更多信息，请参阅文本生成策略指南。
generate
< source >( inputs: typing.Optional[torch.Tensor] = Nonegeneration_config: transformers.generation.configuration_utils.GenerationConfig | None = Nonelogits_processor: transformers.generation.logits_process.LogitsProcessorList | None = Nonestopping_criteria: transformers.generation.stopping_criteria.StoppingCriteriaList | None = Noneprefix_allowed_tokens_fn: collections.abc.Callable[[int, torch.Tensor], list[int]] | None = Nonesynced_gpus: bool | None = Noneassistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = Nonestreamer: typing.Optional[ForwardRef('BaseStreamer')] = Nonenegative_prompt_ids: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonecustom_generate: str | collections.abc.Callable | None = None**kwargs ) → 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 (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]], 可选) — 如果提供，此函数会在每一步将束搜索限制为仅使用允许的 token。如果未提供，则不施加任何约束。此函数接受 2 个参数：批次 IDbatch_id和input_ids。它必须返回一个列表，其中包含根据批次 IDbatch_id和之前生成的 tokeninputs_ids条件化后，用于下一步生成的允许 token。此参数对于基于前缀的约束生成非常有用，如 Autoregressive Entity Retrieval 中所述。 - synced_gpus (
bool, 可选) — 是否继续执行 while 循环直到达到 max_length。除非被覆盖，否则在使用FullyShardedDataParallel或 DeepSpeed ZeRO Stage 3 且涉及多 GPU 时，此标志将设置为True，以避免某个 GPU 在其他 GPU 之前完成生成时发生死锁。否则，默认为False。 - assistant_model (
PreTrainedModel, 可选) — 可用于加速生成的辅助模型。辅助模型必须使用完全相同的 tokenizer。当使用辅助模型预测候选 token 的速度远快于从你调用 generate 的模型运行生成时，即可实现加速。因此，辅助模型应小得多。 - streamer (
BaseStreamer，可选) — 用于流式传输生成序列的 Streamer 对象。生成的 token 会通过streamer.put(token_ids)传入，由 streamer 负责后续处理。 - negative_prompt_ids（形状为
(batch_size, sequence_length)的torch.LongTensor，可选） — 某些处理器（例如 CFG）所需的负面提示。批处理大小必须与输入批处理大小相匹配。这是一个实验性功能，未来版本中可能会发生破坏性的 API 变更。 - negative_prompt_attention_mask（形状为
(batch_size, sequence_length)的torch.LongTensor，可选）—negative_prompt_ids的 attention_mask。 - custom_generate (
str或Callable, 可选) — 以下之一：str（Hugging Face Hub 仓库名称）：运行该仓库中custom_generate/generate.py定义的自定义generate函数，而不是标准的generate方法。该仓库会完全替换生成逻辑，且返回类型可能有所不同。str（本地仓库路径）：与上述相同，但来自本地路径。本地目录也需要trust_remote_code=True，因为会执行本地的custom_generate/generate.py。Callable：generate将执行常规的输入准备步骤，然后调用提供的可调用对象来运行解码循环。 有关更多信息，请参阅 文档。
- kwargs (
dict[str, Any], 可选) —generation_config的临时参数设置，和/或将被转发给模型forward函数的额外模型特定 kwargs。如果模型是编码器-解码器模型，编码器特定的 kwargs 不应添加前缀，而解码器特定的 kwargs 应以 decoder_ 作为前缀。
返回值
ModelOutput 或 torch.LongTensor
ModelOutput（当 return_dict_in_generate=True 或 config.return_dict_in_generate=True 时）或 torch.LongTensor。
如果模型不是编码器-解码器模型（model.config.is_encoder_decoder=False），可能的
ModelOutput 类型为：
如果模型是编码器-解码器模型（model.config.is_encoder_decoder=True），则可能的
ModelOutput 类型为：
为具有语言建模头的模型生成 token id 序列。
大多数生成控制参数都在
generation_config中设置，如果未传入该参数，则会使用模型的默认生成配置。你可以通过向 generate() 传入相应参数来覆盖generation_config中的任意设置，例如.generate(inputs, num_beams=4, do_sample=True)。有关生成策略和代码示例的概述，请参阅以下指南。
compute_transition_scores
< source >( sequences: Tensorscores: tuple[torch.Tensor]beam_indices: typing.Optional[torch.Tensor] = Nonenormalize_logits: bool = False ) → torch.Tensor
参数
- sequences (
torch.LongTensor) — 生成的序列。第二个维度（sequence_length）等于max_length，或者更短（如果所有批次都因eos_token_id而提前结束）。 - scores (
tuple(torch.Tensor)) — 每个生成步骤中每个词汇表 token 的转移分数。由 token 的对数概率组成的 beam 转移分数，这些概率以该 beam 中先前生成的 token 的 log softmax 为条件。torch.Tensor的元组，最多包含max_new_tokens个元素（每个生成的 token 对应一个元素），每个张量的形状为(batch_size*num_beams, config.vocab_size)。 - beam_indices (
torch.LongTensor, 可选) — 生成步骤中每个生成 token id 的 beam 索引。torch.LongTensor，形状为(batch_size*num_return_sequences, sequence_length)。仅在生成时num_beams>1的情况下需要。 - normalize_logits (
bool，可选，默认为False) — 是否对 logits 进行归一化（出于历史原因，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))
TrueContinuousMixin
用于为模型添加连续批处理能力的 Mixin 类。连续批处理有三个入口点：
init_continuous_batching，这是连续批处理的实际入口点continuous_batching_context_manager，它本身是init_continuous_batching的封装generate_batch，实际上是对continuous_batching_context_manager的封装
它们按此顺序定义。对这三个入口点中的任何一个所做的更改，都应反映在另外两个中。
continuous_batching_context_manager
< source >( generation_config: transformers.generation.configuration_utils.GenerationConfig | None = Noneblock: bool = Truetimeout: float | None = Nonecontinuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = Nonepersistent_manager: bool = Falsewarmup: bool = Trueworkload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None )
用于安全使用连续批处理管理器的上下文管理器。参数与 init_continuous_batching 的参数类似，但有以下例外：
- block: 是否在停止管理器时阻塞线程。默认值为 True。
- timeout: 等待线程停止的最大时间。默认值为 None（无超时）。
- warmup：是否在运行前以最大尺寸预捕获 CUDA 图。默认值为 True。
销毁缓存的连续批处理管理器并释放 GPU 资源。
generate_batch
< source >( inputs: list[list[int]]generation_config: transformers.generation.configuration_utils.GenerationConfig | None = Nonecontinuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = Nonerecord_timestamps: bool = Falseprogress_bar: bool = Falsepersistent_manager: bool = Falsewarmup: bool = True**kwargs ) → dict[str, GenerationOutput]
参数
- inputs — 输入 token 序列（提示词）列表
- generation_config — 可选的生成配置
- continuous_batching_config — 可选的连续批处理配置
- record_timestamps — 如果设置为 true，请求将为每个生成的 token 记录时间戳
- progress_bar — 如果设置为 true，将显示进度条
- persistent_manager — 生成结束后是否保留管理器。默认值为 False。
- warmup — 是否在处理请求之前预先捕获 CUDA 图。默认值为 True。
返回值
dict[str, GenerationOutput]
一个字典，将请求 ID 映射到 GenerationOutput 对象
使用连续批处理为一批提示生成序列。
init_continuous_batching
< source >( generation_config: transformers.generation.configuration_utils.GenerationConfig | None = Nonecontinuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = Noneworkload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None ) → ContinuousBatchingManager
初始化一个用于连续批处理推理的管理器。
ContinuousBatchingManager
class transformers.ContinuousBatchingManager
< source >( model: ProtoPretrainedModelgeneration_config: GenerationConfigcontinuous_batching_config: ContinuousBatchingConfigworkload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None )
用于处理生成请求连续批处理的 Manager。它提供了用于提交生成请求、获取结果以及管理后台生成线程的用户界面。不应直接创建此类，而应通过以下入口点之一（均为 ContinuousMixin 混入类的方法）进行创建：
init_continuous_batchingcontinuous_batching_context_managergenerate_batch
add_request
< source >( input_ids: list[int]request_id: str | None = Nonemax_new_tokens: int | None = Nonestreaming: bool = Falserecord_timestamps: bool = Falseeos_token_id: int | list[int] | None = None**logit_processor_kwargs: Any ) → str | None
向队列中添加一个新的生成请求。如果该进程不是 TP 驱动程序，则此操作无效。
add_requests
< source >( inputs: list[list[int]]max_new_tokens: int | None = Nonestreaming: bool = Falserecord_timestamps: bool = False**logit_processor_kwargs: Any )
用于批量执行 add_request 并返回其 ID 的实用函数。有关更多详细信息，请查阅其文档。
通过 ID 取消请求。如果此调用来自非 TP 驱动程序进程，则此操作无效：只有 TP 驱动程序进程会与管理器进行交互。
终止管理器并释放分布式资源。可以安全地多次调用。调用此方法后， 无法重新启动管理器。
从输出队列中获取一个结果。如果提供了 ID，则返回第一个匹配的请求。如果提供了超时时间，则在超时（以秒为单位）后返回 None。
如果后台生成线程已启动且仍然存活，则返回 True。
等待后台线程结束。可以使用 timeout 参数（以秒为单位）来设置等待的超时上限。
一个上下文管理器，用于暂停生成循环，以便调用线程可以使用该模型，通常是为了就地更新它。只有当循环暂停后，线程才会进入此上下文，并在退出时恢复循环，同时保留其缓存和正在处理的请求：不会清空任何内容，也不会丢失任何请求。 多个线程可以同时持有暂停状态，当最后一个线程退出时，循环才会恢复。 如果启用了 TP，所有 rank 都必须进入此上下文，否则其他 rank 将永远挂起。
register_result_handler
< source >( request_id: strcallback: Callable )
注册用于结果传递（流式或非流式）的回调。
每次为该请求生成结果时，回调都会通过 call_soon_threadsafe 在事件循环中被调用。对于流式请求，这会在每个 token 上发生；对于非流式请求，仅在完成时发生。请求结束时，处理程序会自动清理。
迭代与特定请求 ID 匹配的结果（阻塞）。
使用带有重新入队功能的共享输出队列。对于高并发服务，请改用 register_result_handler。
启动后台生成线程。
停止
< source >( block: bool = Truetimeout: float | None = Nonekeep_for_next_session: bool = Falsehard_stop: bool = False )
停止后台生成线程。如果 block 标志设置为 True，则此方法会等待线程停止，最长等待时间为 timeout 秒（None 表示无超时）。如果 keep_for_next_session 标志设置为 True，则管理器会被缓存在模型上以供后续使用。如果设置了 hard_stop 标志，后台生成线程将立即停止，且待处理请求将失败。
switch_to_cb_friendly_attn
< source >( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )
将 attn 实现切换为与 CB 兼容的实现。如果 auto_switch_to_flash 为 True，且 attn 实现为 SDPA 或 eager，则在支持且可用的情况下也切换到 flash。
通过运行虚拟批次，为变长和解码路径预捕获 CUDA 图。如果尚未初始化，则初始化批次处理器。
调度器
class transformers.generation.Scheduler
< source >( cache: PagedAttentionCachesafety_margin: floatmax_requests_per_batch: int )
用于在连续批处理器中调度请求的抽象基类。调度器管理请求的生命周期，从请求被加入等待队列开始，到被调度处理为止。不同的调度器实现了不同的策略，用于对请求进行优先级排序和批处理。
将请求添加到等待列表中。
从活动队列和等待队列中移除所有已取消的请求。
完成请求的处理并释放其已分配的缓存块。当请求完成生成或遇到错误时，会调用此方法。
获取活动请求的生成 token。
检查是否有待处理的请求。
检查请求是否已被取消或移除。
为新的生成循环重置调度器状态。
根据可用的 token 和缓存预算，为下一个批次调度请求。此方法会考虑预算以及调度器的优先级规则，选择当前批次中应处理的请求。其中，token_budget 是每个批次中可处理的最大 token 数，cache_budget 是每个批次中可读取的最大 KV 缓存条目数。 返回以 “FutureRequestState” 形式表示的已调度请求列表、一个指示是否可以使用解码快速路径的布尔值、查询 token 的总数以及读取的 kv token 的最大数量。
标记取消请求。
FIFOScheduler
class transformers.generation.FIFOScheduler
< source >( cache: PagedAttentionCachesafety_margin: float | Nonemax_requests_per_batch: int )
该调度器按请求到达的顺序处理请求，这意味着解码请求的优先级高于预填充请求。
PrefillFirstScheduler
class transformers.generation.PrefillFirstScheduler
< source >( cache: PagedAttentionCachesafety_margin: float | Nonemax_requests_per_batch: int )
一种优先处理拆分预填充请求而非解码请求的调度器。该调度器确保拆分预填充请求（即部分处理提示词的延续）在处理新的解码请求之前完成。