Transformers 文档

生成工具 (Utilities for Generation)

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

生成工具

本页面列出了 generate() 使用的所有实用函数。

生成输出

generate() 的输出是 ModelOutput 子类的实例。此输出是一个包含 generate() 返回的所有信息的数据结构,但也可以作为元组或字典使用。

这是一个例子

from transformers import GPT2Tokenizer, GPT2LMHeadModel

tokenizer = GPT2Tokenizer.from_pretrained("openai-community/gpt2")
model = GPT2LMHeadModel.from_pretrained("openai-community/gpt2")

inputs = tokenizer("Hello, my dog is cute and ", return_tensors="pt")
generation_output = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)

generation_output 对象是一个 GenerateDecoderOnlyOutput,正如我们在下方的该类文档中看到的,这意味着它具有以下属性

  • sequences:生成的 token 序列
  • scores (可选):语言模型头在每个生成步骤的预测得分
  • hidden_states (可选):模型在每个生成步骤的隐藏状态
  • attentions (可选):模型在每个生成步骤的注意力权重

这里我们得到了 scores,因为我们传递了 output_scores=True,但我们没有 hidden_statesattentions,因为我们没有传递 output_hidden_states=Trueoutput_attentions=True

你可以像平常一样访问每个属性,如果该属性未由模型返回,你将得到 None。例如,这里的 generation_output.scores 是语言模型头生成的所有预测得分,而 generation_output.attentionsNone

当将我们的 generation_output 对象用作元组时,它仅保留不为 None 值的属性。例如,这里它有两个元素,先是 loss 然后是 logits,所以

generation_output[:2]

例如将返回元组 (generation_output.sequences, generation_output.scores)

当将我们的 generation_output 对象用作字典时,它仅保留不为 None 值的属性。例如,这里它有两个键,分别是 sequencesscores

我们在此记录所有输出类型。

class transformers.generation.GenerateDecoderOnlyOutput

< >

( sequences: LongTensor scores: tuple[torch.FloatTensor] | None = None logits: tuple[torch.FloatTensor] | None = None attentions: tuple[tuple[torch.FloatTensor]] | None = None hidden_states: tuple[tuple[torch.FloatTensor]] | None = None past_key_values: transformers.cache_utils.Cache | None = None )

参数

  • sequences (形状为 (batch_size, sequence_length)torch.LongTensor) — 生成的序列。第二维 (sequence_length) 等于 max_length,或者如果所有 batch 都因为 eos_token_id 而提前结束,则该维度会更短。
  • scores (tuple(torch.FloatTensor) 可选,当 output_scores=True 时返回) — 语言模型头在每个生成步骤的处理后预测得分(SoftMax 之前每个词表 token 的得分)。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size, config.vocab_size)
  • logits (tuple(torch.FloatTensor) 可选,当 output_logits=True 时返回) — 语言模型头在每个生成步骤的未处理预测得分(SoftMax 之前每个词表 token 的得分)。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size, config.vocab_size)
  • attentions (tuple(tuple(torch.FloatTensor)), 可选,当 output_attentions=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size, num_heads, generated_length, sequence_length)torch.FloatTensor
  • hidden_states (tuple(tuple(torch.FloatTensor)), 可选,当 output_hidden_states=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size, generated_length, hidden_size)torch.FloatTensor
  • past_key_values (Cache, 可选,当 use_cache=True 时返回) — 返回模型缓存,用于加速解码。不同的模型有不同的缓存格式,请查看模型的文档。通常是一个 Cache 实例。

仅解码器生成模型在使用非束搜索 (non-beam) 方法时的输出。

class transformers.generation.GenerateEncoderDecoderOutput

< >

( sequences: LongTensor scores: tuple[torch.FloatTensor] | None = None logits: tuple[torch.FloatTensor] | None = None encoder_attentions: tuple[torch.FloatTensor] | None = None encoder_hidden_states: tuple[torch.FloatTensor] | None = None decoder_attentions: tuple[tuple[torch.FloatTensor]] | None = None cross_attentions: tuple[tuple[torch.FloatTensor]] | None = None decoder_hidden_states: tuple[tuple[torch.FloatTensor]] | None = None past_key_values: transformers.cache_utils.Cache | None = None )

参数

  • sequences (形状为 (batch_size*num_return_sequences, sequence_length)torch.LongTensor) — 生成的序列。第二维 (sequence_length) 等于 max_length,或者如果所有 batch 都因为 eos_token_id 而提前结束,则该维度会更短。
  • scores (tuple(torch.FloatTensor) 可选,当 output_scores=True 时返回) — 语言模型头在每个生成步骤的处理后预测得分(SoftMax 之前每个词表 token 的得分)。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size, config.vocab_size)
  • logits (tuple(torch.FloatTensor) 可选,当 output_logits=True 时返回) — 语言模型头在每个生成步骤的未处理预测得分(SoftMax 之前每个词表 token 的得分)。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size, config.vocab_size)
  • encoder_attentions (tuple(torch.FloatTensor), 可选,当 output_attentions=True 时返回) — torch.FloatTensor 组成的元组(解码器每一层一个元素),形状为 (batch_size, num_heads, sequence_length, sequence_length)
  • encoder_hidden_states (tuple(torch.FloatTensor), 可选,当 output_hidden_states=True 时返回) — torch.FloatTensor 组成的元组(一个用于嵌入层输出 + 一个用于每一层输出),形状为 (batch_size, sequence_length, hidden_size)
  • decoder_attentions (tuple(tuple(torch.FloatTensor)), 可选,当 output_attentions=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size, num_heads, generated_length, sequence_length)torch.FloatTensor
  • cross_attentions (tuple(tuple(torch.FloatTensor)), 可选,当 output_attentions=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size, num_heads, generated_length, sequence_length)torch.FloatTensor
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), 可选,当 output_hidden_states=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size, generated_length, hidden_size)torch.FloatTensor
  • past_key_values (Cache, 可选,当 use_cache=True 时返回) — 返回模型缓存,用于加速解码。不同的模型有不同的缓存格式,请查看模型的文档。通常是一个 Cache 实例。

编码器-解码器生成模型在使用非束搜索 (non-beam) 方法时的输出。

class transformers.generation.GenerateBeamDecoderOnlyOutput

< >

( sequences: LongTensor sequences_scores: torch.FloatTensor | None = None scores: tuple[torch.FloatTensor] | None = None logits: tuple[torch.FloatTensor] | None = None beam_indices: torch.LongTensor | None = None attentions: tuple[tuple[torch.FloatTensor]] | None = None hidden_states: tuple[tuple[torch.FloatTensor]] | None = None past_key_values: transformers.cache_utils.Cache | None = None )

参数

  • sequences (形状为 (batch_size*num_return_sequences, sequence_length)torch.LongTensor) — 生成的序列。第二维 (sequence_length) 等于 max_length,或者如果所有 batch 都因为 eos_token_id 而提前结束,则该维度会更短。
  • sequences_scores (形状为 (batch_size*num_return_sequences)torch.FloatTensor可选,当 output_scores=True 时返回) — 生成序列 sequences 的最终束得分。
  • scores (tuple(torch.FloatTensor) 可选,当 output_scores=True 时返回) — 每个生成步骤中每个词表 token 的束转移得分。束转移得分由以该束中先前生成的 token 的对数 softmax 为条件的 token 对数概率组成。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size*num_beams, config.vocab_size)
  • logits (tuple(torch.FloatTensor) 可选,当 output_logits=True 时返回) — 语言模型头在每个生成步骤的未处理预测得分(SoftMax 之前每个词表 token 的得分)。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size*num_beams, config.vocab_size)
  • beam_indices (torch.LongTensor可选,当 output_scores=True 时返回) — 每个生成步骤中生成 token id 的束索引。形状为 (batch_size*num_return_sequences, sequence_length)torch.LongTensor
  • attentions (tuple(tuple(torch.FloatTensor)), 可选,当 output_attentions=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size*num_beams, num_heads, generated_length, sequence_length)torch.FloatTensor
  • hidden_states (tuple(tuple(torch.FloatTensor)), 可选,当 output_hidden_states=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size*num_beams*num_return_sequences, generated_length, hidden_size)torch.FloatTensor
  • past_key_values (Cache, 可选,当 use_cache=True 时返回) — 返回模型缓存,用于加速解码。不同的模型有不同的缓存格式,请查看模型的文档。通常是一个 Cache 实例。

仅解码器生成模型在使用束搜索 (beam) 方法时的输出。

class transformers.generation.GenerateBeamEncoderDecoderOutput

< >

( sequences: LongTensor sequences_scores: torch.FloatTensor | None = None scores: tuple[torch.FloatTensor] | None = None logits: tuple[torch.FloatTensor] | None = None beam_indices: torch.LongTensor | None = None encoder_attentions: tuple[torch.FloatTensor] | None = None encoder_hidden_states: tuple[torch.FloatTensor] | None = None decoder_attentions: tuple[tuple[torch.FloatTensor]] | None = None cross_attentions: tuple[tuple[torch.FloatTensor]] | None = None decoder_hidden_states: tuple[tuple[torch.FloatTensor]] | None = None past_key_values: transformers.cache_utils.Cache | None = None )

参数

  • sequences (形状为 (batch_size*num_return_sequences, sequence_length)torch.LongTensor) — 生成的序列。第二维 (sequence_length) 等于 max_length,或者如果所有 batch 都因为 eos_token_id 而提前结束,则该维度会更短。
  • sequences_scores (形状为 (batch_size*num_return_sequences)torch.FloatTensor可选,当 output_scores=True 时返回) — 生成序列 sequences 的最终束得分。
  • scores (tuple(torch.FloatTensor) 可选,当 output_scores=True 时返回) — 每个生成步骤中每个词表 token 的束转移得分。束转移得分由以该束中先前生成的 token 的对数 softmax 为条件的 token 对数概率组成。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size*num_beams, config.vocab_size)
  • logits (tuple(torch.FloatTensor) 可选,当 output_logits=True 时返回) — 语言模型头在每个生成步骤的未处理预测得分(SoftMax 之前每个词表 token 的得分)。由 torch.FloatTensor 组成的元组,最多包含 max_new_tokens 个元素(每个生成的 token 一个元素),每个张量的形状为 (batch_size*num_beams, config.vocab_size)
  • beam_indices (torch.LongTensor可选,当 output_scores=True 时返回) — 每个生成步骤中生成 token id 的束索引。形状为 (batch_size*num_return_sequences, sequence_length)torch.LongTensor
  • encoder_attentions (tuple(torch.FloatTensor), 可选,当 output_attentions=True 时返回) — torch.FloatTensor 组成的元组(解码器每一层一个元素),形状为 (batch_size, num_heads, sequence_length, sequence_length)
  • encoder_hidden_states (tuple(torch.FloatTensor), 可选,当 output_hidden_states=True 时返回) — torch.FloatTensor 组成的元组(一个用于嵌入层输出 + 一个用于每一层输出),形状为 (batch_size*num_beams*num_return_sequences, sequence_length, hidden_size)
  • decoder_attentions (tuple(tuple(torch.FloatTensor)), 可选,当 output_attentions=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length)torch.FloatTensor
  • cross_attentions (tuple(tuple(torch.FloatTensor)), 可选,当 output_attentions=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size, num_heads, generated_length, sequence_length)torch.FloatTensor
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), 可选,当 output_hidden_states=True 时返回) — 由元组(每个生成的 token 一个元素)组成的元组(解码器的每一层一个元素),包含形状为 (batch_size*num_beams*num_return_sequences, generated_length, hidden_size)torch.FloatTensor
  • past_key_values (Cache, 可选,当 use_cache=True 时返回) — 返回模型缓存,用于加速解码。不同的模型有不同的缓存格式,请查看模型的文档。通常是一个 Cache 实例。

编码器-解码器生成模型在使用束搜索 (beam) 方法时的输出。

LogitsProcessor

LogitsProcessor 可用于修改生成时语言模型头的预测得分。

class transformers.AlternatingCodebooksLogitsProcessor

< >

( input_start_len: int semantic_vocab_size: int codebook_size: int )

参数

  • input_start_len (int) — 初始输入序列的长度。
  • semantic_vocab_size (int) — 语义部分的词汇表大小,即与语义词汇表相关联的 token 数量。
  • codebook_size (int) — 与码本(codebook)相关联的 token 数量。

LogitsProcessor 强制在 Bark 的两个码本之间交替生成。

此 logits 处理器仅与 Bark 的 fine 子模型兼容。有关示例,请参阅模型文档。

__call__

< >

( input_ids: LongTensor scores: FloatTensor )

class transformers.ClassifierFreeGuidanceLogitsProcessor

< >

( guidance_scale )

参数

  • guidance_scale (float) — 无分类器指导(CFG)的指导刻度。通过设置 guidance_scale > 1 启用 CFG。较高的指导刻度会促使模型生成与输入提示词更紧密相关的样本,但通常会以降低质量为代价。

LogitsProcessor 用于无分类器指导(CFG)。分数在 batch 维度上被拆分,其中前半部分对应于条件 logits(从输入提示词预测),后半部分对应于无条件 logits(从空提示词或“null”提示词预测)。该处理器根据 guidance_scale 参数计算条件和无条件 logits 的加权平均值。

更多信息请参见 论文

此 logits 处理器仅与 MusicGen 兼容。

示例

>>> from transformers import AutoProcessor, MusicgenForConditionalGeneration

>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
>>> model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")

>>> inputs = processor(
...     text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
...     padding=True,
...     return_tensors="pt",
... )
>>> audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索(beam search)时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.EncoderNoRepeatNGramLogitsProcessor

< >

( encoder_ngram_size: int encoder_input_ids: LongTensor )

参数

  • encoder_ngram_size (int) — 所有大小为 ngram_size 的 n-gram 只能出现在编码器输入 ID 中。
  • encoder_input_ids (int) — 不应在解码器 ID 中重复出现的 encoder_input_ids

LogitsProcessor 的工作方式与 NoRepeatNGramLogitsProcessor 类似,但专门用于防止重复出现在提示词中的 n-gram。

它的设计目的是通过防止生成前几轮对话中出现的 n-gram,来提升语言模型的聊天互动性。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")
>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("Alice: I love cats. What do you love?\nBob:", return_tensors="pt")

>>> # With greedy decoding, we see Bob repeating Alice's opinion. If Bob was a chatbot, it would be a poor one.
>>> outputs = model.generate(**inputs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice: I love cats. What do you love?
Bob: I love cats. What do you

>>> # With this logits processor, we can prevent Bob from repeating Alice's opinion.
>>> outputs = model.generate(**inputs, encoder_no_repeat_ngram_size=2)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice: I love cats. What do you love?
Bob: My cats are very cute.

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.EncoderRepetitionPenaltyLogitsProcessor

< >

( penalty: float encoder_input_ids: LongTensor )

参数

  • penalty (float) — 重复惩罚参数。1.0 表示没有惩罚。大于 1.0 会奖励提示词中的 token。0.0 到 1.0 之间会惩罚提示词中的 token。
  • encoder_input_ids (torch.LongTensor) — 解码器 ID 中应重复出现的 encoder_input_ids

LogitsProcessor 的工作方式与 RepetitionPenaltyLogitsProcessor 类似,但具有应用于提示词中 token 的逆向惩罚。换句话说,大于 1.0 的惩罚会增加选择提示词中已出现 token 的几率。

它的设计目的是为了避免在摘要提取等基于输入的任务中出现幻觉。虽然最初是为编码器-解码器模型设计的,但它也可以用于像 LLM 这样的仅解码器模型。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")
>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer(["Alice and Bob. The third member's name was"], return_tensors="pt")
>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
Alice and Bob. The third member's name was not mentioned.

>>> # With the `encoder_repetition_penalty` argument we can trigger this logits processor in `generate`, which can
>>> # promote the use of prompt tokens ("Bob" in this example)
>>> gen_out = model.generate(**inputs, encoder_repetition_penalty=1.2)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
Alice and Bob. The third member's name was Bob. The third member's name was Bob.

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.EpsilonLogitsWarper

< >

( epsilon: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

  • epsilon (float) — 如果设置为 > 0,则仅保留概率为 epsilon 或更高的 token 用于生成。
  • filter_value (float, 可选, 默认为 -inf) — 所有被过滤的值都将设置为此浮点值。
  • min_tokens_to_keep (int, 可选, 默认为 1) — 不能被过滤的最少 token 数量。

LogitsProcessor 执行 epsilon 采样,即限制为 prob >= epsilon 的 token。如果没有 token 满足此约束,则提取最大的 min_tokens_to_keep 个 token。更多信息请参见 Truncation Sampling as Language Model Desmoothing

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(1)
>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3 | < 4 (left-hand pointer) ;
<BLANKLINE>
<BLANKLINE>

>>> # With epsilon sampling, the output gets restricted to high-probability tokens. Note that this is similar to
>>> # Top P sampling, which restricts tokens based on their cumulative probability.
>>> # Pro tip: The paper recommends using `epsilon_cutoff` values between 3e-4 and 9e-4
>>> outputs = model.generate(**inputs, do_sample=True, epsilon_cutoff=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.EtaLogitsWarper

< >

( epsilon: float filter_value: float = -inf min_tokens_to_keep: int = 1 device: str = 'cpu' )

参数

  • epsilon (float) — (0, 1) 范围内的浮点值。用于计算动态截断值 eta 的超参数。论文建议的值根据模型大小在 3e-4 到 4e-3 之间。
  • filter_value (float, 可选, 默认为 -inf) — 所有被发现低于动态截断值 eta 的值都将设置为此浮点值。当需要修改应从生成中完全排除的极低概率 token 的 logits 时,此参数很有用。
  • min_tokens_to_keep (int, 可选, 默认为 1) — 指定必须保留用于生成的最小 token 数量,与其概率无关。例如,如果 min_tokens_to_keep 设置为 1,则始终会保留至少一个 token 用于生成,即使所有 token 的概率都低于截断值 eta
  • device (str, 可选, 默认为 "cpu") — 分配 tensor 的设备。

LogitsProcessor 执行 eta 采样,这是一种过滤掉概率低于动态截断值 eta 的 token 的技术。eta 的计算基于超参数 epsilon 和 token 概率熵的组合,即 eta := min(epsilon, sqrt(epsilon * e^-entropy(probabilities)))。如果没有 token 满足此约束,则提取最大的 min_tokens_to_keep 个 token。它解决了神经网络语言模型生成的长文本样本质量差的问题,从而生成更连贯、更流畅的文本。更多信息请参见 Truncation Sampling as Language Model Desmoothing。注意:必须将 do_sample 设置为 True,此 LogitsProcessor 才能工作。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(1)
>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3 | < 4 (left-hand pointer) ;
<BLANKLINE>
<BLANKLINE>

>>> # With eta sampling, the output gets restricted to high-probability tokens. You can see it as a dynamic form of
>>> # epsilon sampling that adapts its cutoff probability based on the entropy (high entropy = lower cutoff).
>>> # Pro tip: The paper recommends using `eta_cutoff` values between 3e-4 to 4e-3
>>> outputs = model.generate(**inputs, do_sample=True, eta_cutoff=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.ExponentialDecayLengthPenalty

< >

( exponential_decay_length_penalty: tuple eos_token_id: int | list[int] | torch.Tensor input_ids_seq_length: int )

参数

  • exponential_decay_length_penalty (tuple(int, float)) — 此元组应包含:(start_index, decay_factor),其中 start_index 指示惩罚开始的位置,decay_factor 表示指数衰减因子。
  • eos_token_id (Union[int, list[int], torch.Tensor]) — *序列结束* token 的 ID。
  • input_ids_seq_length (int) — 输入序列的长度。

LogitsProcessor 在达到 start_index 后指数级增加 eos_token_id 的分数。这允许在没有硬性截断的情况下生成较短的序列,从而使 eos_token 能够在有意义的位置被预测。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2")

>>> text = "Just wanted to let you know, I"
>>> inputs = tokenizer(text, return_tensors="pt")

>>> # Let's consider that we want short sentences, so we limit `max_length=30`. However, we observe that the answer
>>> # tends to end abruptly.
>>> set_seed(1)
>>> outputs = model.generate(**inputs, do_sample=True, temperature=0.9, max_length=30, pad_token_id=50256)
>>> print(tokenizer.batch_decode(outputs)[0])
Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which was
published in 2010. Although

>>> # To promote the appearance of the EOS token at the right time, we add the `exponential_decay_length_penalty =
>>> # (start_index, decay_factor)`. Instead of cutting at max_tokens, the output comes to an end before and usually
>>> # with more meaning. What happens is that starting from `start_index` the EOS token score will be increased
>>> # by `decay_factor` exponentially. However, if you set a high decay factor, you may also end up with abruptly
>>> # ending sequences.
>>> set_seed(1)
>>> outputs = model.generate(
...     **inputs,
...     do_sample=True,
...     temperature=0.9,
...     max_length=30,
...     pad_token_id=50256,
...     exponential_decay_length_penalty=(15, 1.6),
... )
>>> print(tokenizer.batch_decode(outputs)[0])
Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network
which<|endoftext|>

>>> # With a small decay factor, you will have a higher chance of getting a meaningful sequence.
>>> set_seed(1)
>>> outputs = model.generate(
...     **inputs,
...     do_sample=True,
...     temperature=0.9,
...     max_length=30,
...     pad_token_id=50256,
...     exponential_decay_length_penalty=(15, 1.01),
... )
>>> print(tokenizer.batch_decode(outputs)[0])
Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which was
published in 2010.<|endoftext|>

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.ForcedBOSTokenLogitsProcessor

< >

( bos_token_id: int )

参数

  • bos_token_id (int) — 强制作为第一个生成的 token 的 ID。

LogitsProcessor 强制将指定的 token 作为第一个生成的 token。用于编码器-解码器模型。

示例

>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

>>> model = AutoModelForSeq2SeqLM.from_pretrained("google/flan-t5-small")
>>> tokenizer = AutoTokenizer.from_pretrained("google/flan-t5-small")

>>> inputs = tokenizer("Translate from English to German: I love cats.", return_tensors="pt")

>>> # By default, it continues generating according to the model's logits
>>> outputs = model.generate(**inputs, max_new_tokens=10)
>>> print(tokenizer.batch_decode(outputs)[0])
<pad> Ich liebe Kitty.</s>

>>> # We can use `forced_bos_token_id` to force the start of generation with an encoder-decoder model
>>> # (including forcing it to end straight away with an EOS token)
>>> outputs = model.generate(**inputs, max_new_tokens=10, forced_bos_token_id=tokenizer.eos_token_id)
>>> print(tokenizer.batch_decode(outputs)[0])
<pad></s>

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。当不使用束搜索时,这些可以是每个词汇的 logits;当使用束搜索时,则是每个词汇 token 的 log softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.ForcedEOSTokenLogitsProcessor

< >

( max_length: int eos_token_id: int | list[int] | torch.Tensor device: str = 'cpu' )

参数

  • max_length (int) — 要生成的序列的最大长度。
  • eos_token_id (Union[int, list[int], torch.Tensor]) — *序列结束* token 的 ID。
  • device (str, 可选, 默认为 "cpu") — 分配 tensor 的设备。

LogitsProcessor 强制在达到 max_length 时将指定的 token 作为最后一个生成的 token。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2, 3", return_tensors="pt")

>>> # By default, it continues generating according to the model's logits
>>> outputs = model.generate(**inputs, max_new_tokens=10)
>>> print(tokenizer.batch_decode(outputs)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8

>>> # `forced_eos_token_id` ensures the generation ends with a EOS token
>>> outputs = model.generate(**inputs, max_new_tokens=10, forced_eos_token_id=tokenizer.eos_token_id)
>>> print(tokenizer.batch_decode(outputs)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7,<|endoftext|>

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索(beam search)时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记(token)的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.InfNanRemoveLogitsProcessor

< >

( )

LogitsProcessor,用于移除所有 naninf 值,以避免生成方法失败。请注意,仅在必要时才应使用此 Logits 处理器,因为它可能会降低生成速度。

此 Logits 处理器没有 generate 示例,因为不应存在需要使用它的正确参数组合。

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.LogitNormalization

< >

( )

LogitsProcessor,用于使用 log-softmax 对分数进行归一化。在束搜索期间,在应用 Logits 处理器或变形器(warpers)后对分数进行归一化非常重要。因为此库中使用的搜索算法在应用之后不会自动执行归一化(它仅在之前执行,但之后可能需要重新归一化),但在比较假设时仍假设分数已归一化。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> import torch

>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2, 3", return_tensors="pt")

>>> # By default, the scores are not normalized -- the sum of their exponentials is NOT a normalized probability
>>> # distribution, summing to 1
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(torch.allclose(torch.sum(torch.exp(outputs.scores[-1])), torch.Tensor((1.000,)), rtol=1e-4))
False

>>> # Normalizing them may have a positive impact on beam methods, or when using the scores on your application
>>> outputs = model.generate(**inputs, renormalize_logits=True, return_dict_in_generate=True, output_scores=True)
>>> print(torch.allclose(torch.sum(torch.exp(outputs.scores[-1])), torch.Tensor((1.000,)), rtol=1e-4))
True

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.LogitsProcessor

< >

( )

所有可在生成过程中应用的 Logit 处理器的抽象基类。

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.LogitsProcessorList

< >

( iterable = () )

此类可用于创建 LogitsProcessor 列表,以便随后处理 scores 输入张量。此类继承自 list,并添加了一个特定的 call 方法,用于将每个 LogitsProcessor 应用到输入中。

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。
  • kwargs (dict[str, Any], 可选) — 针对特定 Logits 处理器的额外关键字参数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.MinLengthLogitsProcessor

< >

( min_length: int eos_token_id: int | list[int] | torch.Tensor device: str = 'cpu' )

参数

  • min_length (int) — 最小长度阈值,在此长度以下,eos_token_id 的分数将被设置为 -float("Inf")
  • eos_token_id (Union[int, list[int], torch.Tensor]) — 序列结束(end-of-sequence)标记的 ID。
  • device (str, 可选, 默认为 "cpu") — 分配张量的设备。

LogitsProcessor,通过将 EOS 概率设置为 0 来强制执行最小长度。请注意,对于像大多数 LLM 这样的仅解码器(decoder-only)模型,长度包含提示词(prompt)。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")
>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("A number:", return_tensors="pt")
>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one

>>> # setting `min_length` to a value smaller than the uncontrolled output length has no impact
>>> gen_out = model.generate(**inputs, min_length=3)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one

>>> # setting a larger `min_length` will force the model to generate beyond its natural ending point, which is not
>>> # necessarily incorrect
>>> gen_out = model.generate(**inputs, min_length=10)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one thousand, nine hundred and ninety-four

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.MinNewTokensLengthLogitsProcessor

< >

( prompt_length_to_skip: int min_new_tokens: int eos_token_id: int | list[int] | torch.Tensor device: str = 'cpu' )

参数

  • prompt_length_to_skip (int) — 输入标记的长度。当与 generate 一起使用时,这不是一个有效的参数,因为 generate 会自动分配输入长度。
  • min_new_tokens (int) — 最小新生成的标记长度阈值,在此长度以下,eos_token_id 的分数将被设置为 -float("Inf")
  • eos_token_id (Union[int, list[int], torch.Tensor]) — 序列结束标记的 ID。
  • device (str, 可选, 默认为 "cpu") — 分配张量的设备。

LogitsProcessor,通过将 EOS(序列结束)标记的概率设置为 0 来强制执行最小新生成的标记长度。与 MinLengthLogitsProcessor 不同,此处理器不考虑提示词。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")
>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer(["A number:"], return_tensors="pt")
>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one

>>> # setting `min_new_tokens` will force the model to generate beyond its natural ending point, which is not
>>> # necessarily incorrect
>>> gen_out = model.generate(**inputs, min_new_tokens=2)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one thousand

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.MinPLogitsWarper

< >

( min_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

  • min_p (float) — 最小标记概率,将根据最可能标记的概率进行缩放。它必须是 0 到 1 之间的值。典型值在 0.01-0.2 范围内,其选择性相当于将 top_p 设置在 0.99-0.8 范围内(使用与常规 top_p 相反的值)。
  • filter_value (float, 可选, 默认为 -inf) — 所有被过滤掉的值都将被设置为此浮点值。
  • min_tokens_to_keep (int, 可选, 默认为 1) — 不会被过滤掉的最小标记数量。

LogitsProcessor 执行 min-p 操作,即保留所有高于最小概率的标记,该最小概率根据最可能标记的概率进行缩放。因此,在出现高概率标记时,过滤器会变得更具强制性,这标志着输出非常可信,我们不应偏离。

通常与 TemperatureLogitsWarper 一起使用。作为 TopPLogitsWarperTopKLogitsWarper 的替代方案。

由 @menhguin 和 @kalomaze (GitHub 用户名) 创建。代码改编自 此外部 PR

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(1)
>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3 | < 4 (left-hand pointer) ;
<BLANKLINE>
<BLANKLINE>

>>> # With `min_p` sampling, the output gets restricted to high-probability tokens.
>>> # Pro tip: In practice, LLMs use `min_p` in the 0.01-0.2 range.
>>> outputs = model.generate(**inputs, do_sample=True, min_p=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

< >

( input_ids: LongTensor scores: FloatTensor )

class transformers.NoBadWordsLogitsProcessor

< >

( bad_words_ids: list eos_token_id: int | list[int] | torch.Tensor | None = None )

参数

  • bad_words_ids (list[list[int]]) — 不允许生成的标记 ID 列表的列表。
  • eos_token_id (Union[int, list[int], torch.Tensor], 可选) — 序列结束标记的 ID。

LogitsProcessor,强制永远不会选择指定的序列。

为了获取不应在生成文本中出现的词语的标记 ID,请确保在初始化分词器时设置 add_prefix_space=True,并使用 tokenizer(bad_words, add_special_tokens=False).input_idsadd_prefix_space 参数仅支持某些慢速分词器,因为快速分词器的前缀行为来自 pre tokenizers。点击 此处 了解更多信息。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> inputs = tokenizer(["In a word, the cake is a"], return_tensors="pt")

>>> output_ids = model.generate(inputs["input_ids"], max_new_tokens=5, pad_token_id=tokenizer.eos_token_id)
>>> print(tokenizer.batch_decode(output_ids, skip_special_tokens=True)[0])
In a word, the cake is a bit of a mess.

>>> # Now let's take the bad words out. Please note that the tokenizer is initialized differently
>>> tokenizer_with_prefix_space = AutoTokenizer.from_pretrained("openai-community/gpt2", add_prefix_space=True)


>>> def get_tokens_as_list(word_list):
...     "Converts a sequence of words into a list of tokens"
...     tokens_list = []
...     for word in word_list:
...         tokenized_word = tokenizer_with_prefix_space([word], add_special_tokens=False).input_ids[0]
...         tokens_list.append(tokenized_word)
...     return tokens_list


>>> bad_words_ids = get_tokens_as_list(word_list=["mess"])
>>> output_ids = model.generate(
...     inputs["input_ids"], max_new_tokens=5, bad_words_ids=bad_words_ids, pad_token_id=tokenizer.eos_token_id
... )
>>> print(tokenizer.batch_decode(output_ids, skip_special_tokens=True)[0])
In a word, the cake is a bit of a surprise.

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入序列标记在词表中的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测分数。当不使用束搜索时,这些可以是每个词表的 Logits;当使用束搜索时,则是每个词表标记的 Log Softmax 分数。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.NoRepeatNGramLogitsProcessor

< >

( ngram_size: int )

参数

  • ngram_size (int) — 所有大小为 ngram_size 的 n-gram 只能出现一次。

N-gram 是从文本序列中提取的“n”个连续单词、字符或标记的组合。例如句子:“She runs fast”,其 bi-gram (n=2) 分别为 (“she”, “runs”) 和 (“runs”, “fast”)。在文本生成中,避免词语序列的重复可以提供更多样化的输出。此 LogitsProcessor 通过将禁用的标记分数设置为负无穷大来强制执行 n-gram 不重复,从而在进一步处理分数时排除这些标记。请注意,对于像大多数 LLM 这样的仅解码器模型,获取 n-gram 时也会考虑提示词。参考 Fairseq

请谨慎使用 n-gram 惩罚。例如,在关于“New York”市的文章中惩罚 2-gram(bi-gram)可能会导致不理想的结果,使得城市名称在全文中仅出现一次。参考 Reference

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")
>>> inputs = tokenizer(["Today I"], return_tensors="pt")

>>> output = model.generate(**inputs)
>>> print(tokenizer.decode(output[0], skip_special_tokens=True))
Today I'm not sure if I'm going to be able to do it.

>>> # Now let's add ngram size using `no_repeat_ngram_size`. This stops the repetitions ("I'm") in the output.
>>> output = model.generate(**inputs, no_repeat_ngram_size=2)
>>> print(tokenizer.decode(output[0], skip_special_tokens=True))
Today I'm not sure if I can get a better understanding of the nature of this issue

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID (input IDs)?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索 (beam search) 时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.PrefixConstrainedLogitsProcessor

< >

( prefix_allowed_tokens_fn: Callable num_beams: int )

参数

  • prefix_allowed_tokens_fn (Callable[[int, torch.Tensor], list[int]]) — 此函数在每一步将束搜索限制为仅允许的标记。该函数接受两个参数:inputs_ids 和批次 ID batch_id。它必须返回一个列表,其中包含在以之前生成的标记 inputs_ids 和批次 ID batch_id 为条件的下一个生成步骤中允许的标记。

LogitsProcessor 强制执行约束生成,对前缀条件的约束生成非常有用。有关更多信息,请参阅 Autoregressive Entity Retrieval

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")
>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("Alice and Bob", return_tensors="pt")

>>> # By default, it continues generating according to the model's logits
>>> outputs = model.generate(**inputs, max_new_tokens=5)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice and Bob are friends

>>> # We can constrain it with `prefix_allowed_tokens_fn` to force a certain behavior based on a prefix.
>>> # For instance, we can force an entire entity to be generated when its beginning is detected.
>>> entity = tokenizer(" Bob Marley", return_tensors="pt").input_ids[0]  # 3 tokens
>>> def prefix_allowed_tokens_fn(batch_id, input_ids):
...     '''
...     Attempts to generate 'Bob Marley' when 'Bob' is detected.
...     In this case, `batch_id` is not used, but you can set rules for each batch member.
...     '''
...     if input_ids[-1] == entity[0]:
...         return [entity[1].item()]
...     elif input_ids[-2] == entity[0] and input_ids[-1] == entity[1]:
...         return [entity[2].item()]
...     return list(range(tokenizer.vocab_size))  # If no match, allow all tokens

>>> outputs = model.generate(**inputs, max_new_tokens=5, prefix_allowed_tokens_fn=prefix_allowed_tokens_fn)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice and Bob Marley

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.RepetitionPenaltyLogitsProcessor

< >

( penalty: float prompt_ignore_length: int | None = None )

参数

  • penalty (float) — 重复惩罚参数。1.0 表示没有惩罚。大于 1.0 会惩罚之前生成的标记。0.0 到 1.0 之间则奖励之前生成的标记。
  • prompt_ignore_length (int, 可选) — 原始输入 ID 序列长度,如果提供,将不参与惩罚计算。

LogitsProcessor 通过惩罚防止重复之前的标记。此惩罚对每个标记最多应用一次。请注意,对于像大多数 LLM 这样的仅解码器 (decoder-only) 模型,默认情况下考虑的标记包括提示 (prompt)。

在原论文中,作者建议使用 1.2 左右的惩罚值,以在真实生成和减少重复之间取得良好平衡。要惩罚并减少重复,请使用大于 1.0 的 penalty 值,值越高惩罚越强。要奖励并鼓励重复,请使用 0.0 到 1.0 之间的 penalty 值,值越低奖励越强。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, RepetitionPenaltyLogitsProcessor

>>> # Initializing the model and tokenizer for it
>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")
>>> inputs = tokenizer(["I'm not going to"], return_tensors="pt")

>>> # This shows a normal generate without any specific parameters
>>> summary_ids = model.generate(**inputs)
>>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0])
I'm not going to be able to do that. I'm going to be able to do that

>>> # This generates a penalty for repeated tokens
>>> penalized_ids = model.generate(**inputs, repetition_penalty=1.1)
>>> print(tokenizer.batch_decode(penalized_ids, skip_special_tokens=True)[0])
I'm not going to be able to do that. I'll just have to go out and play

>>> # We can also exclude the input prompt by creating an instance of this class
>>> # with a `prompt_ignore_length` and passing it as a custom logit processor
>>> rep_pen_processor = RepetitionPenaltyLogitsProcessor(
...     penalty=1.1,
...     prompt_ignore_length=inputs["input_ids"].shape[-1]
... )
>>> penalized_ids = model.generate(**inputs, logits_processor=[rep_pen_processor])
>>> print(tokenizer.batch_decode(penalized_ids, skip_special_tokens=True)[0])
I'm not going to be able to do that. I'm going to have to go through a lot of things, and

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.SequenceBiasLogitsProcessor

< >

( sequence_bias: list )

参数

  • sequence_bias (list[list[Union[list[int], float]]]) — 将标记序列映射到其偏置项的列表嵌套列表 (例如 [[[10, 45], -2.0], [[64], -7.5]])。正偏置增加序列被选中的几率,而负偏置则相反。如果序列长度为 1,其偏置将始终应用。否则,只有当该序列即将完成时 (在应用此处理器后的标记选择步骤中) 才会应用偏置。

LogitsProcessor 对序列应用加性偏置。当下一个生成的标记可以完成该序列时,偏置将应用于序列的最后一个标记。因此,为了充分利用对超过一个标记的序列进行偏置,请考虑使用束搜索方法 (以优雅地处理具有负偏置的部分完成序列) 并将其偏置应用于其前缀 (以确保偏置更早应用)。

在标记级别上,对一个单词设置偏置与对一个前面带空格的单词设置偏置是不同的。如果你想在句中对 “foo” 设置偏置,你可能需要添加前缀空格并改为对 “ foo” 设置偏置。查看我们 NLP 课程的标记生成器 (tokenizer) 章节以了解原因:https://huggingface.co/learn/nlp-course/chapter2/4#pt

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
>>> tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
>>> inputs = tokenizer(["The full name of Donald is Donald"], return_tensors="pt")

>>> summary_ids = model.generate(inputs["input_ids"], max_new_tokens=4, do_sample=False)
>>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald John Trump Sr.

>>> def get_tokens(word):
...     return tokenizer([word], add_special_tokens=False).input_ids[0]

>>> # IMPORTANT: Remember our tip about adding spaces before words to bias them correctly.
>>> sequence_bias = [[get_tokens("Trump"), -10.0],]  # will fail to apply bias
>>> biased_ids = model.generate(
...     inputs["input_ids"], max_new_tokens=4, do_sample=False, sequence_bias=sequence_bias
... )
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald John Trump Sr.

>>> sequence_bias = [[get_tokens(" Trump"), -10.0],]  # will work
>>> biased_ids = model.generate(
...     inputs["input_ids"], max_new_tokens=4, do_sample=False, sequence_bias=sequence_bias
... )
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald John Harper. He

>>> # We can also add a positive bias to nudge the model towards specific tokens or continuations. This technique
>>> # is also more effective when paired up with beam search.
>>> sequence_bias = [[get_tokens(" Donald Duck"), 10.0],]
>>> biased_ids = model.generate(
...     inputs["input_ids"], max_new_tokens=4, num_beams=4, do_sample=False, sequence_bias=sequence_bias
... )
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald Duck. He is

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.SuppressTokensAtBeginLogitsProcessor

< >

( begin_suppress_tokens begin_index device: str = 'cpu' )

SuppressTokensAtBeginLogitsProcessor 一旦 generate 函数开始使用 begin_index 标记进行生成,就抑制标记列表。这应确保由 begin_suppress_tokens 定义的标记不会在开始时生成。最初是为 Whisper 创建的。

示例

>>> from transformers import AutoProcessor, WhisperForConditionalGeneration
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")

>>> # Whisper has `begin_suppress_tokens` set by default (= `[220, 50256]`). 50256 is the EOS token, so this means
>>> # it can't generate and EOS token in the first iteration, but it can in the others.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(outputs.scores[0][0, 50256])
tensor(-inf)
>>> print(outputs.scores[-1][0, 50256])  # in other places we can see some probability mass for EOS
tensor(29.9010)

>>> # If we disable `begin_suppress_tokens`, we can generate EOS in the first iteration.
>>> outputs = model.generate(
...     **inputs, return_dict_in_generate=True, output_scores=True, begin_suppress_tokens=None
... )
>>> print(outputs.scores[0][0, 50256])
tensor(11.2027)

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.SuppressTokensLogitsProcessor

< >

( suppress_tokens device: str = 'cpu' )

此处理器可用于抑制标记列表。处理器将其 log probs 设置为 -inf,以便不生成它们。最初是为 Whisper 创建的。

示例

>>> from transformers import AutoProcessor, WhisperForConditionalGeneration
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")

>>> # Whisper has a long list of suppressed tokens. For instance, in this case, the token 1 is suppressed by default.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(outputs.scores[1][0, 1])  # 1 (and not 0) is the first freely generated token
tensor(-inf)

>>> # If we disable `suppress_tokens`, we can generate it.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True, suppress_tokens=None)
>>> print(outputs.scores[1][0, 1])
tensor(6.0678)

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.SynthIDTextWatermarkLogitsProcessor

< >

( ngram_len: int keys: list sampling_table_size: int sampling_table_seed: int context_history_size: int device: device skip_first_ngram_calls: bool = False debug_mode: bool = False )

参数

  • ngram_len (int) — N-gram 长度。
  • keys (list[int]) — 水印密钥序列,每个深度对应一个。
  • sampling_table_size (int) — 采样表大小。
  • sampling_table_seed (int) — 生成采样表的随机种子。
  • context_history_size (int) — 用于追踪已见上下文的张量大小。
  • device (torch.device) — 使用的设备。
  • skip_first_ngram_calls (bool, 可选, 默认为 False) — 是否跳过前几次 N-gram 调用。
  • debug_mode (bool, 可选, 默认为 False) — Logits 被修改为在应用水印修改之前获得的均匀分布。这用于测试实现。

Logits 处理器,为文本生成模型实现了水印技术。该类促进了 SynthID 文本水印的应用,这是一种在生成文本中嵌入难以察觉的信号的方法,有助于检测合成内容。它通过在文本生成过程中以一种以后可以可靠恢复进行验证的方式,微妙地操纵标记选择的概率来运行。

主要功能

  • 状态管理: 维护内部状态以跟踪标记序列并动态生成水印密钥。

  • 密钥生成: 根据标记序列和水印参数计算哈希值,为每个位置创建唯一的密钥。

  • G 值采样: 采用预先计算的采样表,根据生成的密钥对水印值 (g 值) 进行采样。

  • 分数调整: 应用计算出的 g 值来在生成期间修改标记概率,从而嵌入水印。

  • 上下文重复处理: 包含在重复上下文中避免为标记添加水印的逻辑,从而保持自然性。

  • EOS 标记遮罩: 支持遮罩句末标记,以防止将其包含在水印计算中。

  • 实用功能: 提供直接计算 g 值、检查上下文重复、创建 EOS 标记遮罩以及估计预期平均 g 值的函数。

有关此内容的更多详情,请参阅论文地址:https://www.nature.com/articles/s41586-024-08025-4

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, SynthIDTextWatermarkingConfig

>>> tokenizer = AutoTokenizer.from_pretrained('google/gemma-2-2b', padding_side="left")
>>> model = AutoModelForCausalLM.from_pretrained('google/gemma-2-2b')

>>> # SynthID Text configuration
>>> watermarking_config = SynthIDTextWatermarkingConfig(
...     keys=[654, 400, 836, 123, 340, 443, 597, 160, 57],
...     ngram_len=5,
... )

>>> # Generation with watermarking
>>> tokenized_prompts = tokenizer(["Once upon a time, "], return_tensors="pt", padding=True)
>>> output_sequences = model.generate(
...     **tokenized_prompts, watermarking_config=watermarking_config, do_sample=True, max_new_tokens=10
... )
>>> watermarked_text = tokenizer.batch_decode(output_sequences, skip_special_tokens=True)

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.TemperatureLogitsWarper

< >

( temperature: float )

参数

  • temperature (float) — 用于调制 Logits 分布的严格正浮点值。小于 1 的值会减少随机性 (反之亦然),0 相当于将所有概率质量转移到最可能的标记。

用于温度 (指数缩放输出概率分布) 的 LogitsProcessor,这实际上意味着它可以控制预测标记的随机性。通常与 TopPLogitsWarperTopKLogitsWarper 一起使用。

确保 generate 参数中包含 do_sample=True,否则温度值将不会产生任何效果。

示例

>>> import torch
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(0)  # for reproducibility

>>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> model.config.pad_token_id = model.config.eos_token_id
>>> inputs = tokenizer(["Hugging Face Company is"], return_tensors="pt")

>>> # With temperature=1.0, the default, we consistently get random outputs due to random sampling.
>>> generate_kwargs = {"max_new_tokens": 10, "do_sample": True, "temperature": 1.0, "num_return_sequences": 2}
>>> outputs = model.generate(**inputs, **generate_kwargs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True))
['Hugging Face Company is one of these companies that is going to take a',
"Hugging Face Company is a brand created by Brian A. O'Neil"]

>>> # However, with temperature close to 0, it approximates greedy decoding strategies (invariant)
>>> generate_kwargs["temperature"] = 0.0001
>>> outputs = model.generate(**inputs, **generate_kwargs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True))
['Hugging Face Company is a company that has been around for over 20 years',
'Hugging Face Company is a company that has been around for over 20 years']

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列标记的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言建模头的预测分数。不使用束搜索时,这些可以是每个词表的 Logits;使用束搜索时,则是每个词表标记的 Log Softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

transformers.TopHLogitsWarper

< >

( top_h: float filter_value: float = -inf )

参数

  • top_h (float) — 基于熵的阈值 (tau) 的缩放系数。必须在 (0, 1] 范围内。
  • filter_value (float, 可选, 默认为 -inf) — 所有被过滤的值都将被设置为此浮点值。

LogitsProcessor 实现了 Top-H 采样,这是一种根据熵和累积概率约束自适应地选择高概率标记子集的解码方法。

此方法通过分析所选分布的熵差异,动态确定要保留多少个标记,从而平衡探索和利用。它确保生成的文本同时保持多样性和连贯性。

参考:有关详情,请参见 Top-H Decoding: Adapting the Creativity and Coherence with Bounded Entropy in Text Generation (NeurIPS 2025): https://arxiv.org/abs/2509.02510

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B")
>>> tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> outputs = model.generate(**inputs, do_sample=True, top_h=0.4)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 输入 token ID。
  • scores (形状为 (batch_size, vocab_size)torch.FloatTensor) — 模型的原始 logits。

返回

形状为 (batch_size, vocab_size)torch.FloatTensor

经过处理的 logits,其中无效的 token 被掩码为 -inf

使用 Top-H 采样过滤 logits。

class transformers.TopKLogitsWarper

< >

( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

  • top_k (int) — 用于 top-k 过滤的最高概率词汇 token 的数量。
  • filter_value (float, 可选, 默认为 -inf) — 所有被过滤的值都将设置为此浮点值。
  • min_tokens_to_keep (int, 可选, 默认为 1) — 无法被过滤的最小 token 数量。

执行 top-k 的 LogitsProcessor,即限制为 k 个最高概率元素。常与 TemperatureLogitsWarperTopPLogitsWarper 一起使用。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(1)
>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: A, B, C, D", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: A, B, C, D, E — S — O, P — R

>>> # With `top_k` sampling, the output gets restricted the k most likely tokens.
>>> # Pro tip: In practice, LLMs use `top_k` in the 5-50 range.
>>> outputs = model.generate(**inputs, do_sample=True, top_k=2)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: A, B, C, D, E, F, G, H, I

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。在不使用束搜索(beam search)时,这些可以是每个词汇的 logits;在使用束搜索时,则是每个词汇 token 的对数 softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.TopPLogitsWarper

< >

( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

  • top_p (float) — 如果设置为 < 1,则仅保留概率总和达到 top_p 或更高的最小词元集合用于生成。
  • filter_value (float, 可选, 默认为 -inf) — 所有被过滤的值都将设置为此浮点值。
  • min_tokens_to_keep (int, 可选, 默认为 1) — 无法被过滤的最小 token 数量。

执行 top-p 的 LogitsProcessor,即限制为总概率之和满足 prob_cut_off <= prob_cut_off 的最高概率词元。常与 TemperatureLogitsWarperTopKLogitsWarper 一起使用。

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(1)
>>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3 | < 4 (left-hand pointer) ;
<BLANKLINE>
<BLANKLINE>

>>> # With `top_p` sampling, the output gets restricted to high-probability tokens.
>>> # Pro tip: In practice, LLMs use `top_p` in the 0.9-0.95 range.
>>> outputs = model.generate(**inputs, do_sample=True, top_p=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。在不使用束搜索时,这些可以是每个词汇的 logits;在使用束搜索时,则是每个词汇 token 的对数 softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.TypicalLogitsWarper

< >

( mass: float = 0.9 filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

  • mass (float, 可选, 默认为 0.9) — typical_p 的值,在 0 到 1 之间(含 0 和 1),默认为 0.9。
  • filter_value (float, 可选, 默认为 -inf) — 所有被过滤的值都将设置为此浮点值。
  • min_tokens_to_keep (int, 可选, 默认为 1) — 无法被过滤的最小 token 数量。

执行典型解码(typical decoding)的 LogitsProcessor。灵感来自人类使用语言的方式,它优先选择对数概率接近词元概率分布熵的词元。这意味着在这个过程中,概率最高的词元可能会被丢弃。

更多信息请参见 Typical Decoding for Natural Language Generation

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")
>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("1, 2, 3", return_tensors="pt")

>>> # We can see that greedy decoding produces a sequence of numbers
>>> outputs = model.generate(**inputs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
1, 2, 3, 4, 5, 6, 7, 8, 9, 10,

>>> # For this particular seed, we can see that sampling produces nearly the same low-information (= low entropy)
>>> # sequence
>>> set_seed(18)
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
1, 2, 3, 4, 5, 6, 7, 8, 9 and 10

>>> # With `typical_p` set, the most obvious sequence is no longer produced, which may be good for your problem
>>> set_seed(18)
>>> outputs = model.generate(
...     **inputs, do_sample=True, typical_p=0.1, return_dict_in_generate=True, output_scores=True
... )
>>> print(tokenizer.batch_decode(outputs.sequences, skip_special_tokens=True)[0])
1, 2, 3 and 5

>>> # We can see that the token corresponding to "4" (token 934) in the second position, the most likely token
>>> # as seen with greedy decoding, was entirely blocked out
>>> print(outputs.scores[1][0, 934])
tensor(-inf)

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。在不使用束搜索时,这些可以是每个词汇的 logits;在使用束搜索时,则是每个词汇 token 的对数 softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.UnbatchedClassifierFreeGuidanceLogitsProcessor

< >

( guidance_scale: float model unconditional_ids: torch.LongTensor | None = None unconditional_attention_mask: torch.LongTensor | None = None use_cache: bool = True )

参数

  • guidance_scale (float) — 无分类器引导(CFG)的引导尺度。通过设置 guidance_scale != 1 启用 CFG。较高的引导尺度会促使模型生成与输入提示词更紧密相关的样本,通常以牺牲质量为代价。小于 1 的值具有相反的效果,同时使通过 negative_prompt_ids 提供的负面提示词(如果有)起到正面提示词的作用。
  • model (PreTrainedModel) — 计算无条件得分的模型。通常与计算有条件得分的模型相同。两个模型必须使用相同的分词器(tokenizer)。
  • unconditional_ids (形状为 (batch_size, sequence_length)torch.LongTensor, 可选) — 无条件分支的词汇表中输入序列 token 的索引。如果未设置,将默认为提示词的最后一个 token。
  • unconditional_attention_mask (形状为 (batch_size, sequence_length)torch.LongTensor, 可选) — unconditional_ids 的注意力掩码(attention mask)。
  • use_cache (bool, 可选, 默认为 True) — 在负面提示词的前向传播过程中是否缓存 key/value。

无分类器引导(CFG)的 Logits 处理器。该处理器计算由提示词有条件和提示词无条件(或负面)logits 组成的加权平均得分,由 guidance_scale 参数化。无条件得分通过内部以 unconditional_ids 分支提示 model 来计算。

更多信息请参见 论文

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> inputs = tokenizer(["Today, a dragon flew over Paris, France,"], return_tensors="pt")
>>> out = model.generate(inputs["input_ids"], guidance_scale=1.5)
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
'Today, a dragon flew over Paris, France, killing at least 50 people and injuring more than 100'

>>> # with a negative prompt
>>> neg_inputs = tokenizer(["A very happy event happened,"], return_tensors="pt")
>>> out = model.generate(inputs["input_ids"], guidance_scale=2, negative_prompt_ids=neg_inputs["input_ids"])
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
'Today, a dragon flew over Paris, France, killing at least 130 people. French media reported that'

>>> # with a positive prompt
>>> neg_inputs = tokenizer(["A very happy event happened,"], return_tensors="pt")
>>> out = model.generate(inputs["input_ids"], guidance_scale=0, negative_prompt_ids=neg_inputs["input_ids"])
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
"Today, a dragon flew over Paris, France, and I'm very happy to be here. I"

__call__

< >

( input_ids scores )

class transformers.WhisperTimeStampLogitsProcessor

< >

( generate_config: GenerationConfig begin_index: int _detect_timestamp_from_logprob: bool | None = None )

参数

  • generate_config (GenerateConfig) — 用于生成输出的生成配置。需要以下参数:eos_token_id (int, 可选, 默认为 50257): 序列结束词元的 ID。no_timestamps_token_id (int, 可选, 默认为 50363): "<|notimestamps|>" 词元的 ID。max_initial_timestamp_index (int, 可选, 默认为 1): 用于设置初始时间戳的最大值。这用于防止模型预测过远的时间戳。
  • begin_index (int) — 模型生成的第一个词元的索引。
  • _detect_timestamp_from_logprob (bool, 可选) — 是否可以根据所有时间戳的对数概率来预测时间戳。

在语音转录中修改生成时间戳的 logits 的 LogitsProcessor。当输入词元处于特定阈值时,处理器会将得分设置为负无穷。处理器通过掩盖掉会破坏配对模式的 logits,确保时间戳词元成对出现。这样做是为了保持生成时间戳的一致性和结构。它还确保当采样任何时间戳词元的预测概率大于任何单个非时间戳词元时,那些非时间戳的 logits 将被设置为负无穷。这样做是为了确保生成时间戳优先于其他潜在词元。

更多信息请参见 论文

示例

>>> import torch
>>> from transformers import AutoProcessor, WhisperForConditionalGeneration, GenerationConfig
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[3]["audio"]["array"], return_tensors="pt")
>>> input_features = inputs.input_features

>>> #Displaying timestamps
>>> generated_ids = model.generate(inputs=input_features, return_timestamps=True)
>>> transcription = processor.batch_decode(generated_ids, decode_with_timestamps=True)[0]
>>> print("Transcription:", transcription)
Transcription: <|startoftranscript|><|0.00|> He has grave doubts whether Sir Frederick Layton's work is really Greek after all, and can<|6.44|><|6.44|> discover in it but little of rocky Ithaca.<|9.44|><|endoftext|>


>>> #No timestamps & change EOS:
>>> #This allows the user to select a specific token to terminate the sequence on, in this case it's the word "can"(460)
>>> model.generation_config.eos_token_id = 460
>>> generated_ids = model.generate(inputs=input_features,return_timestamps=False)
>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> print("Transcription:", transcription)
Transcription:  He has grave doubts whether Sir Frederick Layton's work is really Greek after all and can

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。在不使用束搜索时,这些可以是每个词汇的 logits;在使用束搜索时,则是每个词汇 token 的对数 softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

class transformers.WatermarkLogitsProcessor

< >

( vocab_size device greenlist_ratio: float = 0.25 bias: float = 2.0 hashing_key: int = 15485863 seeding_scheme: str = 'lefthash' context_width: int = 1 )

参数

  • vocab_size (int) — 模型分词器的词汇表大小。用于计算“绿名单”词元的比例。
  • device (str) — 分配模型的设备。
  • greenlist_ratio (float, 可选, 默认为 0.25) — 使用的“绿名单”词元与词汇表大小的比例。默认为 0.25。
  • bias (float, 可选, 默认为 2.0) — 添加到选定“绿名单”词元 logits 的偏置。如果文本生成质量下降,请考虑降低 bias。推荐值在 [0.5, 2.0] 范围内。默认为 2.0。
  • hashing_key (int, 可选, 默认为 15485863) — 用于哈希的密钥。如果您部署此水印,我们建议使用另一个私钥。默认为 15485863(第 100 万个素数)。
  • seeding_scheme (str, 可选, 默认为 "lefthash") — 用于选择“绿名单”词元的种子方案。接受以下值:
    • “lefthash”(默认):“绿名单”词元的选择取决于最后一个词元(论文中的算法 2)
    • “selfhash”:“绿名单”词元的选择取决于当前词元本身(论文中的算法 3)。此方案的缺点是它需要考虑所有可能的下一个词元,并且可能比 “lefthash” 慢。种子设定中使用的先前词元的上下文长度。较高的上下文长度使水印更鲁棒。
  • context_width (int, 可选, 默认为 1) — 设置种子时要使用的先前词元数量。

用于为生成文本添加水印的 Logits 处理器。该处理器在生成下一个词元之前,通过为随机的一组“绿名单”词元的输出得分添加一个小偏置来修改模型输出得分。“绿名单”词元的选择过程取决于所使用的 seeding_scheme。代码基于原始仓库

由该 LogitsProcessor 生成的文本可以使用 WatermarkDetector 检测。详情请见 call()

更多信息请参见 论文

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, WatermarkingConfig

>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> inputs = tokenizer(["Alice and Bob are"], return_tensors="pt")

>>> # normal generation
>>> out = model.generate(inputs["input_ids"], max_length=20, do_sample=False)
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
'Alice and Bob are both in the same room.\n\n"I\'m not sure if you\'re'

>>> # watermarked generation
>>> watermarking_config = WatermarkingConfig(bias=2.5, context_width=2, seeding_scheme="selfhash")
>>> out = model.generate(inputs["input_ids"], watermarking_config=watermarking_config, max_length=20, do_sample=False)
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
'Alice and Bob are both still alive and well and the story is pretty much a one-hour adventure'

>>> # to detect watermarked text use the WatermarkDetector class
>>> from transformers import WatermarkDetector
>>> detector = WatermarkDetector(model_config=model.config, device="cpu", watermarking_config= watermarking_config)
>>> detection_preds = detector(out)
>>> detection_preds
array([ True])

__call__

< >

( input_ids: LongTensor scores: FloatTensor ) 形状为 (batch_size, config.vocab_size)torch.FloatTensor

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词汇表中输入序列 token 的索引。什么是输入 ID?
  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。在不使用束搜索时,这些可以是每个词汇的 logits;在使用束搜索时,则是每个词汇 token 的对数 softmax。

返回

形状为 (batch_size, config.vocab_size)torch.FloatTensor

处理后的预测分数。

StoppingCriteria

StoppingCriteria 可以用来更改何时停止生成(除 EOS 词元之外)。请注意,这仅适用于我们的 PyTorch 实现。

class transformers.StoppingCriteria

< >

( )

可在生成过程中应用的所有停止标准的抽象基类。

如果您的停止标准取决于 scores 输入,请确保将 return_dict_in_generate=True, output_scores=True 传递给 generate 方法。

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) torch.BoolTensor. (形状为 (batch_size, 1)torch.BoolTensor)

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列 token 的索引。

    可以使用 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。这些可以是 SoftMax 之前每个词表 token 的得分,也可以是 SoftMax 之后每个词表 token 的得分。如果此停止标准依赖于 scores 输入,请确保在调用 generate 时传递 return_dict_in_generate=True, output_scores=True
  • kwargs (dict[str, Any], 可选) — 特定停止标准所需的附加关键字参数。

返回

torch.BoolTensor。(形状为 (batch_size, 1)torch.BoolTensor)

True 表示停止特定行的生成。False 表示应继续生成。

class transformers.StoppingCriteriaList

< >

( iterable = () )

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) torch.BoolTensor. (形状为 (batch_size, 1)torch.BoolTensor)

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列 token 的索引。

    可以使用 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。这些可以是 SoftMax 之前每个词表 token 的得分,也可以是 SoftMax 之后每个词表 token 的得分。如果此停止标准依赖于 scores 输入,请确保在调用 generate 时传递 return_dict_in_generate=True, output_scores=True
  • kwargs (dict[str, Any], 可选) — 特定停止标准所需的附加关键字参数。

返回

torch.BoolTensor。(形状为 (batch_size, 1)torch.BoolTensor)

True 表示停止特定行的生成。False 表示应继续生成。

class transformers.MaxLengthCriteria

< >

( max_length: int max_position_embeddings: int | None = None )

参数

  • max_length (int) — 输出序列允许的最大 token 数量。
  • max_position_embeddings (int, 可选) — 模型的最大长度,由模型的 config.max_position_embeddings 属性定义。

当生成的总 token 数超过 max_length 时,可以使用此类停止生成。请记住,对于仅解码器(decoder-only)类型的 transformer,这会包含初始 prompt 的 token。

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) torch.BoolTensor. (形状为 (batch_size, 1)torch.BoolTensor)

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列 token 的索引。

    可以使用 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。这些可以是 SoftMax 之前每个词表 token 的得分,也可以是 SoftMax 之后每个词表 token 的得分。如果此停止标准依赖于 scores 输入,请确保在调用 generate 时传递 return_dict_in_generate=True, output_scores=True
  • kwargs (dict[str, Any], 可选) — 特定停止标准所需的附加关键字参数。

返回

torch.BoolTensor。(形状为 (batch_size, 1)torch.BoolTensor)

True 表示停止特定行的生成。False 表示应继续生成。

class transformers.MaxTimeCriteria

< >

( max_time: float initial_timestamp: float | None = None )

参数

  • max_time (float) — 允许生成的最大时间(以秒为单位)。
  • initial_time (float, 可选, 默认为 time.time()) — 允许生成时间的起始点。

当总生成时间超过一定量时,可以使用此类停止生成。默认情况下,时间将在您初始化此函数时开始计算。您可以通过传递 initial_time 来覆盖此设置。

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) torch.BoolTensor. (形状为 (batch_size, 1)torch.BoolTensor)

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列 token 的索引。

    可以使用 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。这些可以是 SoftMax 之前每个词表 token 的得分,也可以是 SoftMax 之后每个词表 token 的得分。如果此停止标准依赖于 scores 输入,请确保在调用 generate 时传递 return_dict_in_generate=True, output_scores=True
  • kwargs (dict[str, Any], 可选) — 特定停止标准所需的附加关键字参数。

返回

torch.BoolTensor。(形状为 (batch_size, 1)torch.BoolTensor)

True 表示停止特定行的生成。False 表示应继续生成。

class transformers.StopStringCriteria

< >

( tokenizer: PreTrainedTokenizerBase stop_strings: str | list[str] )

参数

  • tokenizer (PreTrainedTokenizer) — 模型关联的分词器(用于提取词表并对终止序列进行分词)。
  • stop_strings (Union[str, list[str]]) — 应当结束生成的字符串列表。如果传递单个字符串,它将被视为仅包含一个元素的列表。

每当生成特定的字符串序列时,可以使用此类停止生成。它会将字符串与分词器词表一起预处理,以找到 token 可以有效完成停止字符串的位置。

一旦生成的 token 完成了任何停止字符串,就会停止生成。我们希望捕捉解码输出中出现停止字符串的任何情况,这意味着我们还必须捕捉一端或两端有“悬出部分”的情况。更具体地说,对于停止字符串“stop”,以下任何 token 序列都会触发匹配:

  • [“st”, “op”]
  • [“stop”]
  • [“st”, “opera”]
  • [“sto”, “pper”]
  • [“las”, “topper”]
  • [“s”, “to”, “pped”]

请注意,只有当停止字符串位于生成序列的末尾时才会触发匹配。换句话说,这些序列不会触发匹配:

  • [“stop”, “at”]
  • [“st”, “op”, “at”]
  • [“st”, “opera”, “tion”]

这些不匹配的原因是停止字符串与最后一个 token 没有重叠。如果您可以从序列末尾移除一个或多个 token 而不破坏停止字符串,那么此标准将不会匹配该停止字符串。这是有意设计的;因为此检查在每个 token 生成后运行,如果生成了有效的停止字符串,我们不会错过它,但我们不想仅仅因为停止字符串存在于过去的 input_ids 中就停止生成。

那么匹配到底是如何执行的呢?我们使用一种相当令人困惑的方式,因为我们希望整个匹配过程可以用 Torch 或 XLA 编译,这意味着我们不能使用标准的字符串方法。然而,通过一些努力,可以使用纯张量操作进行字符串匹配。我们将首先描述我们使用标准字符串操作的算法,最后解释如何将其转换为纯张量操作。

算法的关键在于一个观察:因为停止字符串必须与 token 序列的末尾重叠,我们可以从序列的末尾开始反向进行。具体来说,我们检查最后一个 token 的开头与 stop_string 的结尾是否存在重叠,或者换句话说,对于某些 i > 0,满足 stop_string[-i:] == token[:i]。如果您查看上面的正例,您会发现所有正例中的最后一个 token 都满足这一性质:

  • [“st”, “op”] (重叠部分是 “op”,重叠长度 == 2)
  • [“stop”] (重叠部分是 “stop”,重叠长度 == 4)
  • [“st”, “opera”] (重叠部分是 “op”,重叠长度 == 2)
  • [“sto”, “pper”] (重叠部分是 “p”,重叠长度 == 1)
  • [“las”, “topper”] (重叠部分是 “top”,重叠长度 == 3)
  • [“s”, “to”, “pped”] (重叠部分是 “p”,重叠长度 == 1)

构造一个不具备此性质的匹配序列是不可能的(您可以自行验证)。然而,虽然最后一个 token 的开头与停止字符串的结尾之间的重叠是匹配的必要条件,但它并不充分。我们还需要检查 token 序列的其余部分是否与停止字符串一致。

我们如何做到这一点?让我们以 [“s”, “to”, “pped”] 为例。我们知道最后一个 token “pped” 与停止字符串 “stop” 有 1 个重叠。然后我们回到前一个 token “to”。由于我们已经匹配了停止字符串中的 1 个字符,剩下的要检查的是 “sto”。我们检查下一个 token “to” 是否与剩余部分的末尾匹配,结果是匹配的。我们现在已经匹配了停止字符串中的 3 个字符,剩余要匹配的是 “s”。我们再次回到前一个 token,也是 “s”。这是一个匹配,因此我们匹配了整个停止字符串。

那么当 token 超出停止字符串的开头时,它是如何工作的呢?让我们考虑 [“las”, “topper”] 的例子。最后一个 token “topper” 与停止字符串 “stop” 有 3 个重叠。因此,剩余要匹配的停止字符串是 “s”。我们回到前一个 token “las”。因为剩余要匹配的只是长度为 1 的 “s”,所以我们只考虑该 token 的最后 1 个字符,即 “s”。这与停止字符串匹配,因此匹配了整个字符串。

那么我们如何用张量操作来计算这些匹配呢?简单:我们高效地预计算所有 token 的必要信息!对于每个 token,我们计算:

  • 它与停止字符串末尾的重叠部分(如果有)
  • 该 token 在停止字符串内部匹配的位置,包括超出开头的匹配。
  • token 的总长度

例如,对于 token “pped”,我们将计算出末尾重叠为 1,无内部匹配位置,长度为 4。对于 token “to”,我们将计算出无末尾重叠,单个内部匹配位置为 1(从末尾开始计数),长度为 2。对于 token “s”,我们将计算出无末尾重叠,单个内部匹配位置为 3(同样从末尾开始计数),长度为 1。

只要我们拥有这些信息,我们就可以在没有任何字符串比较操作的情况下执行上述算法。我们只需执行以下步骤:

  • 检查最后一个 token 是否与起始字符串有末尾重叠
  • 继续反向追踪,记录到目前为止我们匹配了多少停止字符串
  • 在每个点,检查下一个 token 是否具有当前位置作为其有效位置之一
  • 继续,直到匹配失败,或者我们完全匹配了整个停止字符串

再次以 [“s”, “to”, “pped”] 为例。“pped” 有 1 个末尾重叠,所以我们可以开始匹配。到目前为止我们已经匹配了 1 个字符,所以我们检查下一个 token “to” 是否以 1 为有效位置(同样从末尾计数)。它是有效的,所以我们将 “to” 的长度加到我们的位置追踪器上。我们现在已经匹配了 3 个字符,所以我们检查下一个 token “s” 是否以 3 为有效位置。它是有效的,所以我们将其长度加到位置追踪器上。位置追踪器现在是 4,即停止字符串的长度。我们已经匹配了整个停止字符串。

在第二个例子 [“las”, “topper”] 中,“topper” 有 3 个末尾重叠,所以我们可以开始匹配。到目前为止我们已经匹配了 3 个字符,所以我们检查下一个 token “las” 是否以 3 为有效位置。它是有效的,因为我们允许 token 匹配超出停止字符串开头的位置。我们将其长度加到位置追踪器上。位置追踪器现在是 6,这大于停止字符串的长度!不过别担心——这也算作停止字符串的匹配。我们已经匹配了整个停止字符串。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/phi-2")
>>> model = AutoModelForCausalLM.from_pretrained("microsoft/phi-2")
>>> inputs = tokenizer("The biggest states in the USA by land area:", return_tensors="pt")

>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
The biggest states in the USA by land area:
- Alaska
- Texas
- California

>>> # Passing one or more stop strings will halt generation after those strings are emitted
>>> # Note that generating with stop strings requires you to pass the tokenizer too
>>> gen_out = model.generate(**inputs, stop_strings=["Texas"], tokenizer=tokenizer)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
The biggest states in the USA by land area:
- Alaska
- Texas

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) torch.BoolTensor. (形状为 (batch_size, 1)torch.BoolTensor)

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列 token 的索引。

    可以使用 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。这些可以是 SoftMax 之前每个词表 token 的得分,也可以是 SoftMax 之后每个词表 token 的得分。如果此停止标准依赖于 scores 输入,请确保在调用 generate 时传递 return_dict_in_generate=True, output_scores=True
  • kwargs (dict[str, Any], 可选) — 特定停止标准所需的附加关键字参数。

返回

torch.BoolTensor。(形状为 (batch_size, 1)torch.BoolTensor)

True 表示停止特定行的生成。False 表示应继续生成。

class transformers.EosTokenCriteria

< >

( eos_token_id: int | list[int] | torch.Tensor )

参数

  • eos_token_id (Union[int, list[int], torch.Tensor]) — 序列结束 token 的 ID。

当生成“序列结束” token 时,可以使用此类停止生成。默认情况下,它使用 model.generation_config.eos_token_id

__call__

< >

( input_ids: LongTensor scores: FloatTensor **kwargs ) torch.BoolTensor. (形状为 (batch_size, 1)torch.BoolTensor)

参数

  • input_ids (形状为 (batch_size, sequence_length)torch.LongTensor) — 词表中输入序列 token 的索引。

    可以使用 AutoTokenizer 获取索引。详情请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • scores (形状为 (batch_size, config.vocab_size)torch.FloatTensor) — 语言模型头的预测得分。这些可以是 SoftMax 之前每个词表 token 的得分,也可以是 SoftMax 之后每个词表 token 的得分。如果此停止标准依赖于 scores 输入,请确保在调用 generate 时传递 return_dict_in_generate=True, output_scores=True
  • kwargs (dict[str, Any], 可选) — 特定停止标准所需的附加关键字参数。

返回

torch.BoolTensor。(形状为 (batch_size, 1)torch.BoolTensor)

True 表示停止特定行的生成。False 表示应继续生成。

Streamers (流式传输器)

class transformers.TextStreamer

< >

( tokenizer: AutoTokenizer skip_prompt: bool = False **decode_kwargs )

参数

  • tokenizer (AutoTokenizer) — 用于解码 token 的分词器。
  • skip_prompt (bool, 可选, 默认为 False) — 是否跳过传递给 .generate() 的 prompt。对聊天机器人等场景很有用。
  • decode_kwargs (dict, 可选) — 传递给分词器 decode 方法的附加关键字参数。

简单的文本流式传输器,一旦形成完整的单词,就会将 token 打印到标准输出(stdout)。

流式传输器类的 API 仍在开发中,未来可能会发生变化。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer

>>> tok = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> inputs = tok(["An increasing sequence: one,"], return_tensors="pt")
>>> streamer = TextStreamer(tok)

>>> # Despite returning the usual output, the streamer will also print the generated text to stdout.
>>> _ = model.generate(**inputs, streamer=streamer, max_new_tokens=20)
An increasing sequence: one, two, three, four, five, six, seven, eight, nine, ten, eleven,

结束

< >

( )

刷新所有剩余缓存并在标准输出(stdout)中打印换行符。

on_finalized_text

< >

( text: str stream_end: bool = False )

将新文本打印到标准输出。如果流即将结束,还会打印一个换行符。

put

< >

( value )

接收 token,对其进行解码,并在其构成完整单词后立即将其打印到标准输出。

class transformers.TextIteratorStreamer

< >

( tokenizer: AutoTokenizer skip_prompt: bool = False timeout: float | None = None **decode_kwargs )

参数

  • tokenizer (AutoTokenizer) — 用于解码 token 的分词器。
  • skip_prompt (bool, 可选, 默认为 False) — 是否跳过 .generate() 的提示文本。例如对聊天机器人很有用。
  • timeout (float, 可选) — 文本队列的超时时间。如果为 None,队列将无限期阻塞。当 .generate() 在单独线程中调用时,这对处理其中的异常很有用。
  • decode_kwargs (dict, 可选) — 传递给分词器 decode 方法的其他关键字参数。

一种将可打印文本存储在队列中的 Streamer,下游应用可将其作为迭代器使用。这对于需要以非阻塞方式访问生成的文本的应用(例如交互式 Gradio 演示)非常有用。

流式传输器类的 API 仍在开发中,未来可能会发生变化。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
>>> from threading import Thread

>>> tok = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> inputs = tok(["An increasing sequence: one,"], return_tensors="pt")
>>> streamer = TextIteratorStreamer(tok)

>>> # Run the generation in a separate thread, so that we can fetch the generated text in a non-blocking way.
>>> generation_kwargs = dict(inputs, streamer=streamer, max_new_tokens=20)
>>> thread = Thread(target=model.generate, kwargs=generation_kwargs)
>>> thread.start()
>>> generated_text = ""
>>> for new_text in streamer:
...     generated_text += new_text
>>> generated_text
'An increasing sequence: one, two, three, four, five, six, seven, eight, nine, ten, eleven,'

on_finalized_text

< >

( text: str stream_end: bool = False )

将新文本放入队列。如果流即将结束,还会在队列中放入一个停止信号。

class transformers.AsyncTextIteratorStreamer

< >

( tokenizer: AutoTokenizer skip_prompt: bool = False timeout: float | None = None **decode_kwargs )

参数

  • tokenizer (AutoTokenizer) — 用于解码 token 的分词器。
  • skip_prompt (bool, 可选, 默认为 False) — 是否跳过 .generate() 的提示文本。例如对聊天机器人很有用。
  • timeout (float, 可选) — 文本队列的超时时间。如果为 None,队列将无限期阻塞。当 .generate() 在单独线程中调用时,这对处理其中的异常很有用。
  • decode_kwargs (dict, 可选) — 传递给分词器 decode 方法的其他关键字参数。

引发

TimeoutError

  • TimeoutError — 如果 token 生成时间超过超时值。

一种将可打印文本存储在队列中的 Streamer,下游应用可将其作为异步迭代器使用。这对于需要异步访问生成的文本的应用(例如交互式 Gradio 演示)非常有用。

流式传输器类的 API 仍在开发中,未来可能会发生变化。

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, AsyncTextIteratorStreamer
>>> from threading import Thread
>>> import asyncio

>>> tok = AutoTokenizer.from_pretrained("openai-community/gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> inputs = tok(["An increasing sequence: one,"], return_tensors="pt")

>>> # Run the generation in a separate thread, so that we can fetch the generated text in a non-blocking way.
>>> async def main():
...     # Important: AsyncTextIteratorStreamer must be initialized inside a coroutine!
...     streamer = AsyncTextIteratorStreamer(tok)
...     generation_kwargs = dict(inputs, streamer=streamer, max_new_tokens=20)
...     thread = Thread(target=model.generate, kwargs=generation_kwargs)
...     thread.start()
...     generated_text = ""
...     async for new_text in streamer:
...         generated_text += new_text
>>>     print(generated_text)
>>> asyncio.run(main())
An increasing sequence: one, two, three, four, five, six, seven, eight, nine, ten, eleven,

on_finalized_text

< >

( text: str stream_end: bool = False )

将新文本放入队列。如果流即将结束,还会在队列中放入一个停止信号。

Caches (缓存)

class transformers.CacheLayerMixin

< >

( )

单个层缓存的基础抽象类。

update

< >

( key_states: Tensor value_states: Tensor cache_kwargs: dict[str, typing.Any] | None = None )

get_seq_length (获取序列长度)

< >

( )

get_mask_sizes (获取掩码大小)

< >

( cache_position: Tensor )

get_max_cache_shape (获取最大缓存形状)

< >

( )

重置

< >

( )

重置缓存值,同时保留对象本身。

reorder_cache (重新排列缓存)

< >

( beam_idx: LongTensor )

为束搜索 (beam search) 重新排列此层的缓存。

lazy_initialization (延迟初始化)

< >

( key_states: Tensor value_states: Tensor )

class transformers.DynamicLayer

< >

( )

一种随着生成更多 token 而动态增长的缓存层。这是生成模型的默认设置。它将键 (key) 和值 (value) 状态存储为形状为 [batch_size, num_heads, seq_len, head_dim] 的张量。

update

< >

( key_states: Tensor value_states: Tensor cache_kwargs: dict[str, typing.Any] | None = None ) tuple[torch.Tensor, torch.Tensor]

参数

  • key_states (torch.Tensor) — 要缓存的新键状态。
  • value_states (torch.Tensor) — 要缓存的新值状态。
  • cache_kwargs (dict[str, Any], 可选) — 缓存的其他参数。

返回

tuple[torch.Tensor, torch.Tensor]

键和值状态。

就地 (in-place) 更新键和值缓存,并返回所需的键和值状态。

lazy_initialization (延迟初始化)

< >

( key_states: Tensor value_states: Tensor )

crop (裁剪)

< >

( max_length: int )

将过去的键值 (past key values) 按照 token 数量裁剪到新的 max_lengthmax_length 也可以是负数,表示移除 max_length 个 token。

batch_repeat_interleave (批次重复交错)

< >

( repeats: int )

在批次 (batch) 维度上将缓存重复 repeats 次。

batch_select_indices (批次索引选择)

< >

( indices: Tensor )

仅在缓存的批次维度中保留 indices 指定的索引。

class transformers.StaticLayer

< >

( max_cache_len: int )

参数

  • max_cache_len (int) — 可存储的最大 token 数量,用于张量预分配。

一种静态缓存层,它将键和值状态存储为形状为 [batch_size, num_heads, max_cache_len), head_dim] 的静态张量。它采用延迟分配完整的后备张量,然后对其进行就地修改。专为支持 torch.compile 而构建。

update

< >

( key_states: Tensor value_states: Tensor cache_kwargs: dict[str, typing.Any] | None = None ) tuple[torch.Tensor, torch.Tensor]

参数

  • key_states (torch.Tensor) — 要缓存的新键状态。
  • value_states (torch.Tensor) — 要缓存的新值状态。
  • cache_kwargs (dict[str, Any], 可选) — 缓存的其他参数。

返回

tuple[torch.Tensor, torch.Tensor]

键和值状态。

就地 (in-place) 更新键和值缓存,并返回所需的键和值状态。

lazy_initialization (延迟初始化)

< >

( key_states: Tensor value_states: Tensor )

键和值张量的延迟初始化。这允许在运行时直接获取所有属性(数据类型、设备、张量并行情况下的头数等),非常实用,因为它避免了以后在每次 update 时移动设备、更改数据类型等操作(这些操作也可能破坏静态 dynamo 地址)。

如果不需要这种行为,可以直接在 Cache 上调用 early_initialization(...),它会提前调用此函数(例如 torch.export 就需要这样做)。请注意,对于 compile,由于我们内部不编译预填充 (prefill),因此在编译时保证已经调用了此函数。如果也要编译预填充(例如在带有静态缓存的 generate 之前调用 model.compile(...)),通常仍受支持,但取决于编译选项(例如已知 mode="reduce-overhead" 的 cuda 图会失败),不提供保证。但在通常情况下它可以正常工作,且为了性能考虑,本就不应该编译预填充!

class transformers.StaticSlidingWindowLayer

< >

( max_cache_len: int sliding_window: int )

参数

  • max_cache_len (int) — 可存储的最大 token 数量,用于张量预分配。
  • sliding_window (int) — 滑动窗口的大小。

一种静态缓存层,它将键和值状态存储为形状为 [batch_size, num_heads, min(max_cache_len, sliding_window), head_dim] 的静态张量。它采用延迟分配完整的后备张量,然后对其进行就地修改。专为支持 torch.compile 而构建。

update

< >

( key_states: Tensor value_states: Tensor cache_kwargs: dict[str, typing.Any] | None = None ) tuple[torch.Tensor, torch.Tensor]

参数

  • key_states (torch.Tensor) — 要缓存的新键状态。
  • value_states (torch.Tensor) — 要缓存的新值状态。
  • cache_kwargs (dict[str, Any], 可选) — 缓存的其他参数。

返回

tuple[torch.Tensor, torch.Tensor]

键和值状态。

就地 (in-place) 更新键和值缓存,并返回所需的键和值状态。

lazy_initialization (延迟初始化)

< >

( key_states: Tensor value_states: Tensor )

键和值张量的延迟初始化。这允许在运行时直接获取所有属性(数据类型、设备、张量并行情况下的头数等),非常实用,因为它避免了以后在每次 update 时移动设备、更改数据类型等操作(这些操作也可能破坏静态 dynamo 地址)。

如果不需要这种行为,可以直接在 Cache 上调用 early_initialization(...),它会提前调用此函数(例如 torch.export 就需要这样做)。请注意,对于 compile,由于我们内部不编译预填充 (prefill),因此在编译时保证已经调用了此函数。如果也要编译预填充(例如在带有静态缓存的 generate 之前调用 model.compile(...)),通常仍受支持,但取决于编译选项(例如已知 mode="reduce-overhead" 的 cuda 图会失败),不提供保证。但在通常情况下它可以正常工作,且为了性能考虑,本就不应该编译预填充!

class transformers.QuantoQuantizedLayer

< >

( nbits: int = 4 axis_key: int = 0 axis_value: int = 0 q_group_size: int = 64 residual_length: int = 128 )

update

< >

( key_states: Tensor value_states: Tensor cache_kwargs: dict[str, typing.Any] | None = None ) tuple[torch.Tensor, torch.Tensor]

参数

  • key_states (torch.Tensor) — 要缓存的新 key 状态。
  • value_states (torch.Tensor) — 要缓存的新 value 状态。
  • cache_kwargs (dict[str, Any], 可选) — 缓存的附加参数。

返回

tuple[torch.Tensor, torch.Tensor]

键和值状态。

就地 (in-place) 更新键和值缓存,并返回所需的键和值状态。

lazy_initialization (延迟初始化)

< >

( key_states: Tensor value_states: Tensor )

class transformers.HQQQuantizedLayer

< >

( nbits: int = 4 axis_key: int = 0 axis_value: int = 0 q_group_size: int = 64 residual_length: int = 128 )

update

< >

( key_states: Tensor value_states: Tensor cache_kwargs: dict[str, typing.Any] | None = None ) tuple[torch.Tensor, torch.Tensor]

参数

  • key_states (torch.Tensor) — 要缓存的新 key 状态。
  • value_states (torch.Tensor) — 要缓存的新 value 状态。
  • cache_kwargs (dict[str, Any], 可选) — 缓存的附加参数。

返回

tuple[torch.Tensor, torch.Tensor]

键和值状态。

就地 (in-place) 更新键和值缓存,并返回所需的键和值状态。

lazy_initialization (延迟初始化)

< >

( key_states: Tensor value_states: Tensor )

class transformers.Cache

< >

( layers: list[transformers.cache_utils.CacheLayerMixin] | None = None layer_class_to_replicate: type[transformers.cache_utils.CacheLayerMixin] | None = None offloading: bool = False offload_only_non_sliding: bool = True )

参数

  • layers (Optional, 可选) — 预创建的 CacheLayerMixin 列表。如果省略 (None),则将使用 layer_class_to_replicate
  • layer_class_to_replicate (type[CacheLayerMixin], 可选) — 仅在 layers 被省略 (None) 时使用。在这种情况下,它将作为每个层的基类,一旦调用 updatelayer_idx 大于当前层列表长度时,将延迟添加新层。
  • offloading (bool, 可选, 默认为 False) — 是否将层卸载 (offload) 到 cpu 以节省 GPU 显存。
  • offload_only_non_sliding (bool, 可选, 默认为 True) — 如果 offloadingTrue,则进一步决定是否仅卸载非滑动窗口 (non-sliding) 层(因为滑动窗口层通常体积较小,无需卸载,跳过卸载速度更快)。

Cache 主要是 CacheLayerMixin 对象的列表,每个模型层对应一个。它作为每一层缓存的容器。

update

< >

( key_states: Tensor value_states: Tensor layer_idx: int cache_kwargs: dict[str, typing.Any] | None = None )

参数

  • key_states (torch.Tensor) — 要缓存的新 key 状态。
  • value_states (torch.Tensor) — 要缓存的新 value 状态。
  • layer_idx (int) — 要为其缓存状态的层索引。
  • cache_kwargs (dict[str, Any], 可选) — 缓存子类的附加参数。这些参数针对每个子类特定,允许创建新型缓存。

使用层 layer_idx 的新 key_statesvalue_states 更新缓存。

early_initialization

< >

( batch_size: int num_heads: int head_dim: int dtype: dtype device: device )

提前初始化所有层(否则在第一次 update 调用时延迟初始化)。这对于我们的 export 方案很有用,因为 export 需要预先确定所有内容。

get_seq_length (获取序列长度)

< >

( layer_idx: int = 0 )

返回给定层的缓存序列长度。

get_mask_sizes (获取掩码大小)

< >

( cache_position: Tensor layer_idx: int )

返回一个元组 (kv_length, kv_offset),对应于在 layer_idx 给定层返回的长度和偏移量。然后根据给定的长度 (kv_length, kv_offset) 和每一层的模式准备掩码。

get_max_cache_shape (获取最大缓存形状)

< >

( layer_idx: int = 0 )

返回缓存对象的最大序列长度。动态缓存没有最大长度限制。

重置

< >

( )

递归重置所有层的张量。

reorder_cache (重新排列缓存)

< >

( beam_idx: LongTensor )

为束搜索 (beam search) 重新排序缓存。

crop (裁剪)

< >

( max_length: int )

将缓存裁剪到给定长度。

batch_repeat_interleave (批次重复交错)

< >

( repeats: int )

重复并交错 (interleave) 缓存。

batch_select_indices (批次索引选择)

< >

( indices: Tensor )

从缓存中选择特定索引。

class transformers.DynamicCache

< >

( ddp_cache_data: collections.abc.Iterable[tuple[torch.Tensor | None, ...]] | None = None config: transformers.configuration_utils.PreTrainedConfig | None = None offloading: bool = False offload_only_non_sliding: bool = False )

参数

  • ddp_cache_data (Iterable[tuple[torch.Tensor, torch.Tensor]], 可选) — 最初为兼容 torch.distributed (DDP) 而添加。简而言之,它是 map(gather_map, zip(*caches)),即迭代器中的每一项都包含由 torch.distributed 在副本间收集的某层的 key 和 value 状态 (shape=[global batch size, num_heads, seq_len, head_dim])。注意:它也需要作为第一个参数才能正常工作。
  • config (PreTrainedConfig, 可选) — 使用此缓存的模型的配置。如果传递,它将用于检查滑动窗口或混合层结构,从而将缓存张量的显存需求大大降低至 [batch_size, num_heads, min(seq_len, sliding_window), head_dim]
  • offloading (bool, 可选, 默认为 False) — 是否将层卸载到 cpu 以节省 GPU 显存。
  • offload_only_non_sliding (bool, 可选, 默认为 False) — 如果 offloadingTrue,则进一步决定是否仅卸载非滑动窗口层(因为滑动窗口层通常体积较小,无需卸载,跳过卸载速度更快)。

随着生成更多 token 而动态增长的缓存。这是生成式模型的默认选项。它将 key 和 value 状态存储为 CacheLayer 列表,每层一个。CacheLayer 中每个张量的预期形状为 [batch_size, num_heads, seq_len, head_dim]。如果传递了配置 (config),它将额外检查滑动窗口或混合缓存结构,从而将缓存张量的显存需求大大降低至 [batch_size, num_heads, min(seq_len, sliding_window), head_dim]

有关所有缓存类实现的通用方法的详细信息,请参阅 Cache

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, DynamicCache

>>> model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B-Instruct")
>>> tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2-0.5B-Instruct")

>>> inputs = tokenizer(text="My name is Qwen2", return_tensors="pt")

>>> # Prepare a cache class and pass it to model's forward
>>> past_key_values = DynamicCache(config=model.config)
>>> outputs = model(**inputs, past_key_values=past_key_values, use_cache=True)
>>> outputs.past_key_values # access cache filled with key/values from generation

class transformers.StaticCache

< >

( config: PreTrainedConfig max_cache_len: int offloading: bool = False offload_only_non_sliding: bool = True **kwargs )

参数

  • config (PreTrainedConfig) — 使用此缓存的模型的配置。它将用于检查是否存在滑动窗口或混合层结构,并相应地初始化每一层。
  • max_cache_len (int) — 此缓存应保存的最大 token 数量。
  • offloading (bool, 可选, 默认为 False) — 是否将层卸载到 cpu 以节省 GPU 显存。
  • offload_only_non_sliding (bool, 可选, 默认为 True) — 如果 offloadingTrue,则进一步决定是否仅卸载非滑动窗口层(因为滑动窗口层通常体积较小,无需卸载,跳过卸载速度更快)。

用于 torch.compile(model)torch.export() 的静态缓存类。它将检查 config 中潜在的混合缓存结构,并相应地初始化每一层。

有关所有缓存类实现的通用方法的详细信息,请参阅 Cache

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, StaticCache

>>> model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-chat-hf")
>>> tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-chat-hf")

>>> inputs = tokenizer(text="My name is Llama", return_tensors="pt")

>>> # Prepare a cache class and pass it to model's forward
>>> # Leave empty space for 10 new tokens, which can be used when calling forward iteratively 10 times to generate
>>> max_generated_length = inputs.input_ids.shape[1] + 10
>>> past_key_values = StaticCache(config=model.config, max_cache_len=max_generated_length)
>>> outputs = model(**inputs, past_key_values=past_key_values, use_cache=True)
>>> outputs.past_key_values # access cache filled with key/values from generation
StaticCache()

class transformers.QuantizedCache

< >

( backend: str config: PreTrainedConfig nbits: int = 4 axis_key: int = 0 axis_value: int = 0 q_group_size: int = 64 residual_length: int = 128 )

参数

  • backend (str) — 要使用的量化后端。可选 `(“quanto”, “hqq”) 之一。
  • config (PreTrainedConfig) — 使用此缓存的模型的配置。
  • nbits (int, 可选, 默认为 4) — 量化位数。
  • axis_key (int, 可选, 默认为 0) — 量化 key 的轴。
  • axis_value (int, 可选, 默认为 0) — 量化 value 的轴。
  • q_group_size (int, 可选, 默认为 64) — key 和 value 均根据设定的 q_group_size 进行逐通道 (per-channel) 量化。
  • residual_length (int, 可选, 默认为 128) — 原始精度缓存的最大容量。

一种类似于 KIVI: A Tuning-Free Asymmetric 2bit Quantization for KV Cache 论文 中描述的量化缓存。它允许模型通过应用量化来生成更长的序列,而不会为 key 和 value 分配过多显存。该缓存有两种存储类型:一种用于原始精度,一种用于量化缓存。residual length 被设定为原始精度缓存的最大容量。当长度超过最大容量时,原始精度缓存将被弃用并移入量化缓存。与论文描述不同的是,这里的量化是针对 key 和 value 按设定的 q_group_size 逐通道进行的。

有关所有缓存类实现的通用方法的详细信息,请参阅 Cache

class transformers.EncoderDecoderCache

< >

( *caches )

参数

  • caches (Iterable) — 通常是长度为 2 的迭代器,包含 2 个 Cache 对象,第一个用于自注意力 (self-attention),第二个用于交叉注意力 (cross-attention)。也可以是长度为 1 的迭代器,包含一个 tuple[tuple[torch.Tensor]](通常用于兼容 torch dp 和 ddp)。

所有编码器-解码器 (encoder-decoder) 缓存的基础抽象类。可用于保存自注意力缓存和交叉注意力缓存的组合。

有关所有缓存类实现的通用方法的详细信息,请参阅 Cache

示例

>>> from transformers import AutoProcessor, AutoModelForCausalLM, DynamicCache, EncoderDecoderCache

>>> model = AutoModelForCausalLM.from_pretrained("openai/whisper-small")
>>> processor = AutoProcessor.from_pretrained("openai/whisper-small")

>>> inputs = processor(audio=YOUR-AUDIO, return_tensors="pt")

>>> # Prepare cache classes for encoder and decoder and pass it to model's forward
>>> self_attention_cache = DynamicCache(config=self.config)
>>> cross_attention_cache = DynamicCache(config=self.config)
>>> past_key_values = EncoderDecoderCache(self_attention_cache, cross_attention_cache)
>>> outputs = model(**inputs, past_key_values=past_key_values, use_cache=True)
>>> outputs.past_key_values # access cache filled with key/values from generation
EncoderDecoderCache()

batch_repeat_interleave (批次重复交错)

< >

( repeats: int )

在 batch 维度上将缓存重复 repeats 次。用于对比搜索 (contrastive search)(在 Hub 上)。

batch_select_indices (批次索引选择)

< >

( indices: Tensor )

仅在缓存的 batch 维度上保留 indices。用于对比搜索(在 Hub 上)。

batch_split

< >

( full_batch_size: int split_size: int )

按 batch size 将当前实例拆分为 DynamicCache 列表。这将被 generation.utils 中的 _split_model_inputs() 使用。

crop (裁剪)

< >

( maximum_length: int )

将 past key values 裁剪到新的 maximum_length(以 token 为单位)。maximum_length 也可以为负数,表示移除 maximum_length 个 token。这用于辅助解码 (assisted decoding) 和对比搜索(在 Hub 上)。

get_max_cache_shape (获取最大缓存形状)

< >

( )

返回缓存对象的最大序列长度(即最大容量)。

get_seq_length (获取序列长度)

< >

( layer_idx: int = 0 )

返回缓存状态的序列长度。可以可选地传递层索引。

reorder_cache (重新排列缓存)

< >

( beam_idx: LongTensor )

根据选定的束搜索索引,重新排列束搜索的缓存。

水印工具

class transformers.WatermarkingConfig

< >

( greenlist_ratio: float = 0.25 bias: float = 2.0 hashing_key: int = 15485863 seeding_scheme: str = 'lefthash' context_width: int = 1 )

该类用于保存水印生成的参数,并应在 generate 期间传递到 GenerationConfig 中。有关参数的更多详细信息,请参阅这篇论文

接受以下键值

  • greenlist_ratio (float):用于水印。使用的“绿色”token 数量与词汇表大小的比率。默认为 0.25。
  • bias (float):配合水印使用。添加到选定的“绿色”token logits 的偏置。默认为 2.0。
  • hashing_key (int):用于水印的哈希键。默认为 15485863(第一百万个质数)。
  • seeding_scheme (str):用于水印的算法。接受以下值:
    • “lefthash”(默认):“绿色”token 的选择取决于最后一个 token(论文中的算法 2)
    • “selfhash”:“绿色”token 的选择取决于当前 token 本身(论文中的算法 3)。该方案的缺点是它会考虑所有可能的下一个 token,可能比“lefthash”慢。
  • context_width(int):在播种(seeding)中使用的先前 token 的上下文长度。较高的上下文长度使水印更具鲁棒性。

__call__

( *args **kwargs )

将自身作为函数调用。

class transformers.WatermarkDetector

< >

( model_config: PreTrainedConfig device: str watermarking_config: typing.Union[ForwardRef('WatermarkingConfig'), dict, NoneType] ignore_repeated_ngrams: bool = False max_cache_size: int = 128 )

参数

  • model_config (PreTrainedConfig) — 模型配置,用于获取生成时使用的模型特定参数。
  • device (str) — 生成水印文本时使用的设备。
  • watermarking_config (Union[WatermarkingConfig, Dict]) — 生成文本时使用的完全相同的水印配置和参数。
  • ignore_repeated_ngrams (bool, 可选,默认为 False) — 是否仅计算每个唯一的 n-gram 一次。
  • max_cache_size (int, 可选,默认为 128) — 为每个 token 调用的播种/采样算法进行 LRU 缓存的最大尺寸。

用于检测水印生成文本的检测器。该检测器需要提供与文本生成期间完全相同的设置,以复制水印绿名单的生成,从而检测水印。这包括生成期间使用的正确设备、正确的水印参数和正确的分词器词汇表大小。代码基于原始仓库

更多信息请参见 论文

示例

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, WatermarkDetector, WatermarkingConfig

>>> model_id = "openai-community/gpt2"
>>> model = AutoModelForCausalLM.from_pretrained(model_id)
>>> tok = AutoTokenizer.from_pretrained(model_id)
>>> tok.pad_token_id = tok.eos_token_id
>>> tok.padding_side = "left"

>>> inputs = tok(["This is the beginning of a long story", "Alice and Bob are"], padding=True, return_tensors="pt")
>>> input_len = inputs["input_ids"].shape[-1]

>>> # first generate text with watermark and without
>>> watermarking_config = WatermarkingConfig(bias=2.5, seeding_scheme="selfhash")
>>> out_watermarked = model.generate(**inputs, watermarking_config=watermarking_config, do_sample=False, max_length=20)
>>> out = model.generate(**inputs, do_sample=False, max_length=20)

>>> # now we can instantiate the detector and check the generated text
>>> detector = WatermarkDetector(model_config=model.config, device="cpu", watermarking_config=watermarking_config)
>>> detection_out_watermarked = detector(out_watermarked, return_dict=True)
>>> detection_out = detector(out, return_dict=True)
>>> detection_out_watermarked.prediction
array([ True,  True])

>>> detection_out.prediction
array([False,  False])

__call__

< >

( input_ids: LongTensor z_threshold: float = 3.0 return_dict: bool = False ) WatermarkDetectorOutputnp.ndarray

参数

  • input_ids (torch.LongTensor) — 带水印生成的文本。建议移除提示词(prompt),因为它可能会影响检测效果。
  • z_threshold (Dict, 可选,默认为 3.0) — 更改此阈值会改变检测器的灵敏度。较高的 z 阈值灵敏度较低,反之亦然。
  • return_dict (bool, 可选,默认为 False) — 是否返回 ~generation.WatermarkDetectorOutput。如果为 False,它将返回布尔值预测。

返回

WatermarkDetectorOutputnp.ndarray

如果 return_dict=True,则返回 WatermarkDetectorOutput,否则返回 np.ndarray

ma

class transformers.BayesianDetectorConfig

< >

( watermarking_depth: int | None = None base_rate: float = 0.5 **kwargs )

参数

  • watermarking_depth (int, 可选) — 锦标赛层数(tournament layers)。
  • base_rate (float1, 可选,默认为 0.5) — 文本带有水印的先验概率 P(w)。

这是用于存储 BayesianDetectorModel 配置的配置类。它用于根据指定的参数实例化贝叶斯检测器模型。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请阅读 PreTrainedConfig 的文档。

class transformers.BayesianDetectorModel

< >

( config model_args: ~utils.generic.ModelArgs | None = None adapter_args: ~utils.generic.AdapterArgs | None = None lora_args: ~utils.generic.LoRAArgs | None = None tokenizer_args: ~utils.generic.TokenizerArgs | None = None dataset_args: ~utils.generic.DatasetArgs | None = None data_args: ~utils.generic.DataArgs | None = None training_args: ~utils.generic.TrainingArgs | None = None generation_args: ~utils.generic.GenerationArgs | None = None vision_tower_args: ~utils.generic.VisionTowerArgs | None = None qlora_args: ~utils.generic.QLoRAArgs | None = None vision_tower_template_args: ~utils.generic.VisionTowerTemplateArgs | None = None video_tower_args: ~utils.generic.VideoTowerArgs | None = None vision_config: ~utils.generic.VisionConfig | None = None video_config: ~utils.generic.VideoConfig | None = None load_dataset: bool | None = None load_data_collator: bool | None = None load_processor: bool | None = None load_lora_adapter: bool | None = None load_adapter: bool | None = None load_qlora_adapter: bool | None = None **kwargs: typing_extensions.Unpack[transformers.modeling_utils.PreTrainedModelKwargs] )

参数

  • config (BayesianDetectorConfig) — 包含模型所有参数的模型配置类。使用配置文件初始化不会加载模型相关的权重,仅加载配置。请查看 from_pretrained() 方法来加载模型权重。

用于水印检测的贝叶斯分类器。

该检测器使用贝叶斯法则计算水印分数,即后验概率 P(watermarked|g_values) 与 P(unwatermarked|g_values) 之比的对数的 sigmoid 值。有关 BayesianScore 的更多详细信息,请参阅论文中的相关章节。论文 URL:https://www.nature.com/articles/s41586-024-08025-4

请注意,该检测器仅适用于使用 Bernoulli(0.5) g-value 分布的非畸变锦标赛(Tournament-based)水印。

此模型继承自 PreTrainedModel。查看其父类文档,了解库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、修剪头等)。

此模型也是一个 PyTorch torch.nn.Module 子类。像普通的 PyTorch Module 一样使用它,并参考 PyTorch 文档了解一般用法和行为的所有相关信息。

forward

< >

( g_values: Tensor mask: Tensor labels: torch.Tensor | None = None loss_batch_weight = 1 return_dict = False )

参数

  • g_values (形状为 (batch_size, seq_len, watermarking_depth, ...)torch.Tensor) — g-values(值为 0 或 1)。
  • mask — 形状为 [batch_size, seq_len] 的二进制数组,指示应使用哪些 g-values。掩码值为 0 的 g-values 将被丢弃。

计算带水印的后验概率 P(watermarked|g_values)。

class transformers.SynthIDTextWatermarkingConfig

< >

( ngram_len: int keys: list context_history_size: int = 1024 sampling_table_seed: int = 0 sampling_table_size: int = 65536 skip_first_ngram_calls: bool = False debug_mode: bool = False )

参数

  • ngram_len (int) — N-gram 长度。
  • keys (list[int]) — 水印键序列,每个深度对应一个。
  • context_history_size (int, 可选,默认为 1024) — 用于追踪已见上下文的张量大小。
  • sampling_table_seed (int, 可选,默认为 0) — 生成采样表的随机种子。
  • sampling_table_size (int, 可选,默认为 65536) — 采样表的大小。
  • skip_first_ngram_calls (bool, 可选,默认为 False) — 是否跳过前几个 n-gram 调用。
  • debug_mode (bool, 可选,默认为 False) — Logits 会被修改为应用水印修改之前的统一形式。这用于测试实现情况。

该类用于保存水印生成的参数,并应在 generate 期间传递到 GenerationConfig 中。有关参数的更多详细信息,请参阅这篇论文

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, SynthIDTextWatermarkingConfig

>>> tokenizer = AutoTokenizer.from_pretrained('google/gemma-2-2b', padding_side="left")
>>> model = AutoModelForCausalLM.from_pretrained('google/gemma-2-2b')

>>> # SynthID Text configuration
>>> watermarking_config = SynthIDTextWatermarkingConfig(
...     keys=[654, 400, 836, 123, 340, 443, 597, 160, 57],
...     ngram_len=5,
... )

>>> # Generation with watermarking
>>> tokenized_prompts = tokenizer(["Once upon a time, "], return_tensors="pt", padding=True)
>>> output_sequences = model.generate(
...     **tokenized_prompts, watermarking_config=watermarking_config, do_sample=True, max_new_tokens=10
... )
>>> watermarked_text = tokenizer.batch_decode(output_sequences, skip_special_tokens=True)

class transformers.SynthIDTextWatermarkDetector

< >

( detector_module: BayesianDetectorModel logits_processor: SynthIDTextWatermarkLogitsProcessor tokenizer: typing.Any )

参数

SynthID 文本水印检测器类。

该类必须使用训练好的贝叶斯检测器模块进行初始化。有关训练/保存/加载该检测器模块的示例,请查看 examples/synthid_text/detector_training.py。该文件夹还展示了该检测器的示例用法。

示例

>>> from transformers import (
...     AutoTokenizer, BayesianDetectorModel, SynthIDTextWatermarkLogitsProcessor, SynthIDTextWatermarkDetector
... )

>>> # Load the detector. See https://github.com/huggingface/transformers-research-projects/tree/main/synthid_text for training a detector.
>>> detector_model = BayesianDetectorModel.from_pretrained("joaogante/dummy_synthid_detector")
>>> logits_processor = SynthIDTextWatermarkLogitsProcessor(
...     **detector_model.config.watermarking_config, device="cpu"
... )
>>> tokenizer = AutoTokenizer.from_pretrained(detector_model.config.model_name)
>>> detector = SynthIDTextWatermarkDetector(detector_model, logits_processor, tokenizer)

>>> # Test whether a certain string is watermarked
>>> test_input = tokenizer(["This is a test input"], return_tensors="pt")
>>> is_watermarked = detector(test_input.input_ids)

__call__

< >

( tokenized_outputs: Tensor )

编译工具

class transformers.CompileConfig

< >

( fullgraph: bool = False dynamic: bool | None = None backend: str | collections.abc.Callable = 'inductor' mode: str = 'reduce-overhead' options: dict | None = None )

参数

  • fullgraph (bool, 可选,默认为 False) — 如果为 False(默认值),尝试发现可优化的可编译区域。如果为 True,则要求整个函数都能被捕获进单个计算图中。如果无法做到(即存在计算图中断),则会抛出错误。
  • dynamic (boolNone, 可选) — 是否尝试使用动态形状图(dynamic shape graphs)。
  • backend (strCallable, 可选,默认为 "inductor") — 要使用的后端。
  • mode (str, 可选,默认为 "reduce-overhead") — 控制性能与开销之间的平衡。
  • options (dict, 可选) — 传递给后端的选项字典。

该类保存了在 generate 中使用自动编译时与 torch.compile 行为相关的参数。有关参数的更多详细信息,请参阅 torch.compile

示例

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, CompileConfig

>>> tokenizer = AutoTokenizer.from_pretrained('google/gemma-2-2b')
>>> model = AutoModelForCausalLM.from_pretrained('google/gemma-2-2b').cuda()

>>> # Automatic compile configuration, used with static cache
>>> compile_config = CompileConfig(dynamic=True)

>>> # Generation with static cache and compile config
>>> input = tokenizer.encode("Hello there, how", return_tensors="pt").cuda()
>>> output = model.generate(
...     input, do_sample=False, max_new_tokens=300, cache_implementation="static", compile_config=compile_config
... )
>>> output_text = tokenizer.batch_decode(output, skip_special_tokens=True)[0]

__call__

( *args **kwargs )

将自身作为函数调用。

在 GitHub 上更新

© . This site is unofficial and not affiliated with Hugging Face, Inc.