用于生成的工具
此页面列出了所有由 generate(), greedy_search(), contrastive_search(), sample(), beam_search(), beam_sample(), group_beam_search(), 和 constrained_beam_search()使用的实用函数。
其中大多数仅在您研究库中生成方法的代码时才有用。
生成输出
generate() 的输出是 ModelOutput 的一个子类的实例。这个输出是一种包含 generate() 返回的所有信息数据结构,但也可以作为元组或字典使用。 这里是一个例子:
from transformers import GPT2Tokenizer, GPT2LMHeadModel
tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
model = GPT2LMHeadModel.from_pretrained("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
: 生成的tokens序列scores
(可选): 每个生成步骤的语言建模头的预测分数hidden_states
(可选): 每个生成步骤模型的hidden statesattentions
(可选): 每个生成步骤模型的注意力权重
在这里,由于我们传递了 output_scores=True
,我们具有 scores
属性。但我们没有 hidden_states
和 attentions
,因为没有传递 output_hidden_states=True
或 output_attentions=True
。
您可以像通常一样访问每个属性,如果该属性未被模型返回,则将获得 None
。例如,在这里 generation_output.scores
是语言建模头的所有生成预测分数,而 generation_output.attentions
为 None
。
当我们将 generation_output
对象用作元组时,它只保留非 None
值的属性。例如,在这里它有两个元素,loss
然后是 logits
,所以
generation_output[:2]
将返回元组(generation_output.sequences, generation_output.scores)
。
当我们将generation_output
对象用作字典时,它只保留非None
的属性。例如,它有两个键,分别是sequences
和scores
。
我们在此记录所有输出类型。
PyTorch
class transformers.generation.GenerateDecoderOnlyOutput
< source >( sequences: LongTensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None past_key_values: Optional = None )
Parameters
- sequences (
torch.LongTensor
of shape(batch_size, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(torch.FloatTensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftorch.FloatTensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size, config.vocab_size)
. - attentions (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size, generated_length, hidden_size)
. - past_key_values (
tuple(tuple(torch.FloatTensor)))
, optional, returned whenuse_cache=True
is passed or whenconfig.use_cache=True
) — NOTE: some models have a differentpast_key_values
format, confirm with the model’s documentation. Usually a Tuple (one element for each layer of the decoder) of tuples (two elements, key tensor and value tensor). The first Tuple is of lengthconfig.n_layers
, with each tuple having 2 tensors of shape(batch_size, num_heads, sequence_length, embed_size_per_head)
) and optionally ifconfig.is_encoder_decoder=True
2 additional tensors of shape(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)
.
Outputs of decoder-only generation models, when using non-beam methods.
class transformers.generation.GenerateEncoderDecoderOutput
< source >( sequences: LongTensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None past_key_values: Optional = None )
Parameters
- sequences (
torch.LongTensor
of shape(batch_size, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(torch.FloatTensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftorch.FloatTensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size, config.vocab_size)
. - encoder_attentions (
tuple(torch.FloatTensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftorch.FloatTensor
(one for each layer of the decoder) of shape(batch_size, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(torch.FloatTensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftorch.FloatTensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size, generated_length, hidden_size)
. - past_key_values (
tuple(tuple(torch.FloatTensor)))
, optional, returned whenuse_cache=True
is passed or whenconfig.use_cache=True
) — NOTE: some models have a differentpast_key_values
format, confirm with the model’s documentation. Usually a Tuple (one element for each layer of the decoder) of tuples (two elements, key tensor and value tensor). The first Tuple is of lengthconfig.n_layers
, with each tuple having 2 tensors of shape(batch_size, num_heads, sequence_length, embed_size_per_head)
) and optionally ifconfig.is_encoder_decoder=True
2 additional tensors of shape(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)
.
Outputs of encoder-decider generation models, when using non-beam methods.
class transformers.generation.GenerateBeamDecoderOnlyOutput
< source >( sequences: LongTensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None attentions: Optional = None hidden_states: Optional = None past_key_values: Optional = None )
Parameters
- sequences (
torch.LongTensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - sequences_scores (
torch.FloatTensor
of shape(batch_size*num_return_sequences)
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Final beam scores of the generatedsequences
. - scores (
tuple(torch.FloatTensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam transition scores for each vocabulary token at each generation step. Beam transition scores consisting of log probabilities of tokens conditioned on log softmax of previously generated tokens in this beam. Tuple oftorch.FloatTensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_beams*num_return_sequences, config.vocab_size)
. - beam_indices (
torch.LongTensor
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam indices of generated token id at each generation step.torch.LongTensor
of shape(batch_size*num_return_sequences, sequence_length)
. - attentions (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size*num_beams, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)
. - past_key_values (
tuple(tuple(torch.FloatTensor)))
, optional, returned whenuse_cache=True
is passed or whenconfig.use_cache=True
) — NOTE: some models have a differentpast_key_values
format, confirm with the model’s documentation. Usually a Tuple (one element for each layer of the decoder) of tuples (two elements, key tensor and value tensor). The first Tuple is of lengthconfig.n_layers
, with each tuple having 2 tensors of shape(batch_size, num_heads, sequence_length, embed_size_per_head)
) and optionally ifconfig.is_encoder_decoder=True
2 additional tensors of shape(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)
.
Outputs of decoder-only generation models, when using beam methods.
class transformers.generation.GenerateBeamEncoderDecoderOutput
< source >( sequences: LongTensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None past_key_values: Optional = None )
Parameters
- sequences (
torch.LongTensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - sequences_scores (
torch.FloatTensor
of shape(batch_size*num_return_sequences)
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Final beam scores of the generatedsequences
. - scores (
tuple(torch.FloatTensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam transition scores for each vocabulary token at each generation step. Beam transition scores consisting of log probabilities of tokens conditioned on log softmax of previously generated tokens in this beam. Tuple oftorch.FloatTensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_beams, config.vocab_size)
. - beam_indices (
torch.LongTensor
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam indices of generated token id at each generation step.torch.LongTensor
of shape(batch_size*num_return_sequences, sequence_length)
. - encoder_attentions (
tuple(torch.FloatTensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftorch.FloatTensor
(one for each layer of the decoder) of shape(batch_size, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(torch.FloatTensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftorch.FloatTensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size*num_beams*num_return_sequences, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(torch.FloatTensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftorch.FloatTensor
of shape(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)
. - past_key_values (
tuple(tuple(torch.FloatTensor)))
, optional, returned whenuse_cache=True
is passed or whenconfig.use_cache=True
) — NOTE: some models have a differentpast_key_values
format, confirm with the model’s documentation. Usually a Tuple (one element for each layer of the decoder) of tuples (two elements, key tensor and value tensor). The first Tuple is of lengthconfig.n_layers
, with each tuple having 2 tensors of shape(batch_size, num_heads, sequence_length, embed_size_per_head)
) and optionally ifconfig.is_encoder_decoder=True
2 additional tensors of shape(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)
.
Outputs of encoder-decoder generation models, when using beam methods.
TensorFlow
class transformers.generation.TFGreedySearchEncoderDecoderOutput
< source >( sequences: Tensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size, config.vocab_size)
. - encoder_attentions (
tuple(tf.Tensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftf.Tensor
(one for each layer of the decoder) of shape(batch_size, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(tf.Tensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftf.Tensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, generated_length, hidden_size)
.
Base class for outputs of encoder-decoder generation models using greedy search. Hidden states and attention weights of the decoder (respectively the encoder) can be accessed via the encoder_attentions and the encoder_hidden_states attributes (respectively the decoder_attentions and the decoder_hidden_states attributes)
class transformers.generation.TFGreedySearchDecoderOnlyOutput
< source >( sequences: Tensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size, config.vocab_size)
. - attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, generated_length, hidden_size)
.
Base class for outputs of decoder-only generation models using greedy search.
class transformers.generation.TFSampleEncoderDecoderOutput
< source >( sequences: Tensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_return_sequences, config.vocab_size)
. - encoder_attentions (
tuple(tf.Tensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftf.Tensor
(one for each layer of the decoder) of shape(batch_size*num_return_sequences, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(tf.Tensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftf.Tensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size*num_return_sequences, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_return_sequences, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_return_sequences, generated_length, hidden_size)
.
Base class for outputs of encoder-decoder generation models using sampling. Hidden states and attention weights of the decoder (respectively the encoder) can be accessed via the encoder_attentions and the encoder_hidden_states attributes (respectively the decoder_attentions and the decoder_hidden_states attributes)
class transformers.generation.TFSampleDecoderOnlyOutput
< source >( sequences: Tensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_return_sequences, config.vocab_size)
. - attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(num_return_sequences*batch_size, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(num_return_sequences*batch_size, generated_length, hidden_size)
.
Base class for outputs of decoder-only generation models using sampling.
class transformers.generation.TFBeamSearchEncoderDecoderOutput
< source >( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - sequences_scores (
tf.Tensor
of shape(batch_size*num_return_sequences)
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Final beam scores of the generatedsequences
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed beam scores for each vocabulary token at each generation step. Beam scores consisting of log softmax scores for each vocabulary token and sum of log softmax of previously generated tokens in this beam.Tuple of
tf.Tensorwith up to
max_new_tokenselements (one element for each generated token), with each tensor of shape
(batch_size*num_beams, config.vocab_size)`. - beam_indices (
tf.Tensor
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam indices of generated token id at each generation step.tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
. - encoder_attentions (
tuple(tf.Tensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftf.Tensor
(one for each layer of the decoder) of shape(batch_size, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(tf.Tensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftf.Tensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size*num_beams*num_return_sequences, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)
.
Base class for outputs of encoder-decoder generation models using beam search. Hidden states and attention weights of the decoder (respectively the encoder) can be accessed via the encoder_attentions and the encoder_hidden_states attributes (respectively the decoder_attentions and the decoder_hidden_states attributes)
class transformers.generation.TFBeamSearchDecoderOnlyOutput
< source >( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None attentions: Optional = None hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - sequences_scores (
tf.Tensor
of shape(batch_size*num_return_sequences)
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Final beam scores of the generatedsequences
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed beam scores for each vocabulary token at each generation step. Beam scores consisting of log softmax scores for each vocabulary token and sum of log softmax of previously generated tokens in this beam. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_beams*num_return_sequences, config.vocab_size)
. - beam_indices (
tf.Tensor
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam indices of generated token id at each generation step.tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
. - attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)
.
Base class for outputs of decoder-only generation models using beam search.
class transformers.generation.TFBeamSampleEncoderDecoderOutput
< source >( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size*num_beams, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - sequences_scores (
tf.Tensor
of shape(batch_size * num_return_sequence)
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Final beam scores of the generatedsequences
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed beam scores for each vocabulary token at each generation step. Beam scores consisting of log softmax scores for each vocabulary token and sum of log softmax of previously generated tokens in this beam. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_beams, config.vocab_size)
. - beam_indices (
tf.Tensor
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam indices of generated token id at each generation step.tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
. - encoder_attentions (
tuple(tf.Tensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftf.Tensor
(one for each layer of the decoder) of shape(batch_size, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(tf.Tensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftf.Tensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size*num_beams, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams, generated_length, hidden_size)
.
Base class for outputs of encoder-decoder generation models using beam sampling. Hidden states and attention weights of the decoder (respectively the encoder) can be accessed via the encoder_attentions and the encoder_hidden_states attributes (respectively the decoder_attentions and the decoder_hidden_states attributes)
class transformers.generation.TFBeamSampleDecoderOnlyOutput
< source >( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None attentions: Optional = None hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - sequences_scores (
tf.Tensor
of shape(batch_size * num_return_sequence)
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Final beam scores of the generatedsequences
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed beam scores for each vocabulary token at each generation step. Beam scores consisting of log softmax scores for each vocabulary token and sum of log softmax of previously generated tokens in this beam. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size*num_beams*num_return_sequences, config.vocab_size)
. - beam_indices (
tf.Tensor
, optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Beam indices of generated token id at each generation step.tf.Tensor
of shape(batch_size*num_return_sequences, sequence_length)
. - attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size*num_beams, generated_length, hidden_size)
.
Base class for outputs of decoder-only generation models using beam sample.
class transformers.generation.TFContrastiveSearchEncoderDecoderOutput
< source >( sequences: Tensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size, config.vocab_size)
. - encoder_attentions (
tuple(tf.Tensor)
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple oftf.Tensor
(one for each layer of the decoder) of shape(batch_size, num_heads, sequence_length, sequence_length)
. - encoder_hidden_states (
tuple(tf.Tensor)
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple oftf.Tensor
(one for the output of the embeddings + one for the output of each layer) of shape(batch_size, sequence_length, hidden_size)
. - decoder_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - cross_attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - decoder_hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, generated_length, hidden_size)
.
Base class for outputs of encoder-decoder generation models using contrastive search. Hidden states and attention weights of the decoder (respectively the encoder) can be accessed via the encoder_attentions and the encoder_hidden_states attributes (respectively the decoder_attentions and the decoder_hidden_states attributes)
class transformers.generation.TFContrastiveSearchDecoderOnlyOutput
< source >( sequences: Tensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None )
Parameters
- sequences (
tf.Tensor
of shape(batch_size, sequence_length)
) — The generated sequences. The second dimension (sequence_length) is either equal tomax_length
or shorter if all batches finished early due to theeos_token_id
. - scores (
tuple(tf.Tensor)
optional, returned whenoutput_scores=True
is passed or whenconfig.output_scores=True
) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple oftf.Tensor
with up tomax_new_tokens
elements (one element for each generated token), with each tensor of shape(batch_size, config.vocab_size)
. - attentions (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_attentions=True
is passed orconfig.output_attentions=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, num_heads, generated_length, sequence_length)
. - hidden_states (
tuple(tuple(tf.Tensor))
, optional, returned whenoutput_hidden_states=True
is passed or whenconfig.output_hidden_states=True
) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) oftf.Tensor
of shape(batch_size, generated_length, hidden_size)
.
Base class for outputs of decoder-only generation models using contrastive search.
FLAX
class transformers.generation.FlaxSampleOutput
< source >( sequences: Array = None )
Flax Base class for outputs of decoder-only generation models using sampling.
“Returns a new object replacing the specified fields with new values.
class transformers.generation.FlaxGreedySearchOutput
< source >( sequences: Array = None )
Flax Base class for outputs of decoder-only generation models using greedy search.
“Returns a new object replacing the specified fields with new values.
class transformers.generation.FlaxBeamSearchOutput
< source >( sequences: Array = None scores: Array = None )
Flax Base class for outputs of decoder-only generation models using greedy search.
“Returns a new object replacing the specified fields with new values.
LogitsProcessor
LogitsProcessor 可以用于修改语言模型头的预测分数以进行生成
PyTorch
class transformers.AlternatingCodebooksLogitsProcessor
< source >( input_start_len: int semantic_vocab_size: int codebook_size: int )
LogitsProcessor enforcing alternated generation between the two codebooks of Bark.
This logits processor is exclusively compatible with Bark’s fine submodel. See the model documentation for examples.
class transformers.ClassifierFreeGuidanceLogitsProcessor
< source >( guidance_scale )
LogitsProcessor for classifier free guidance (CFG). The scores are split over the batch dimension,
where the first half correspond to the conditional logits (predicted from the input prompt) and the second half
correspond to the unconditional logits (predicted from an empty or ‘null’ prompt). The processor computes a
weighted average across the conditional and unconditional logits, parameterised by the guidance_scale
.
See the paper for more information.
This logits processor is exclusively compatible with MusicGen
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.EncoderNoRepeatNGramLogitsProcessor
< source >( encoder_ngram_size: int encoder_input_ids: LongTensor )
LogitsProcessor that works similarly to NoRepeatNGramLogitsProcessor, but applied exclusively to prevent the repetition of n-grams present in the prompt.
It was designed to promote chattiness in a language model, by preventing the generation of n-grams present in previous conversation rounds.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.EncoderRepetitionPenaltyLogitsProcessor
< source >( penalty: float encoder_input_ids: LongTensor )
LogitsProcessor that works similarly to RepetitionPenaltyLogitsProcessor, but with an inverse penalty that is applied to the tokens present in the prompt. In other words, a penalty above 1.0 increases the odds of selecting tokens that were present in the prompt.
It was designed to avoid hallucination in input-grounded tasks, like summarization. Although originally intended for encoder-decoder models, it can also be used with decoder-only models like LLMs.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.EpsilonLogitsWarper
< source >( epsilon: float filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- epsilon (
float
) — If set to > 0, only the most tokens with probabilitiesepsilon
or higher are kept for generation. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
LogitsWarper that performs epsilon-sampling, i.e. restricting to tokens with prob >= epsilon
. Takes the
largest min_tokens_to_keep tokens if no tokens satisfy this constraint. See Truncation Sampling as Language Model
Desmoothing for more information.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed
>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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, 0, 2, 2. 2, 2, 2, 2
>>> # 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 recomends 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.EtaLogitsWarper
< source >( epsilon: float filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- epsilon (
float
) — A float value in the range (0, 1). Hyperparameter used to calculate the dynamic cutoff value,eta
. The suggested values from the paper ranges from 3e-4 to 4e-3 depending on the size of the model. - filter_value (
float
, optional, defaults to -inf) — All values that are found to be below the dynamic cutoff value,eta
, are set to this float value. This parameter is useful when logits need to be modified for very low probability tokens that should be excluded from generation entirely. - min_tokens_to_keep (
int
, optional, defaults to 1) — Specifies the minimum number of tokens that must be kept for generation, regardless of their probabilities. For example, ifmin_tokens_to_keep
is set to 1, at least one token will always be kept for generation, even if all tokens have probabilities below the cutoffeta
.
LogitsWarper that performs eta-sampling, a technique to filter out tokens with probabilities below a dynamic
cutoff value, eta
, which is calculated based on a combination of the hyperparameter epsilon
and the entropy of
the token probabilities, i.e. eta := min(epsilon, sqrt(epsilon * e^-entropy(probabilities)))
. Takes the largest
min_tokens_to_keep tokens if no tokens satisfy this constraint. It addresses the issue of poor quality in long
samples of text generated by neural language models leading to more coherent and fluent text. See Truncation
Sampling as Language Model Desmoothing for more information. Note: do_sample
must be set to True
for this LogitsWarper
to work.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed
>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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, 0, 2, 2. 2, 2, 2, 2
>>> # 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 recomends 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.ExponentialDecayLengthPenalty
< source >( exponential_decay_length_penalty: Tuple eos_token_id: Union input_ids_seq_length: int )
Parameters
- exponential_decay_length_penalty (
tuple(int, float)
) — This tuple shall consist of:(start_index, decay_factor)
wherestart_index
indicates where penalty starts anddecay_factor
represents the factor of exponential decay - eos_token_id (
Union[int, List[int]]
) — The id of the end-of-sequence token. Optionally, use a list to set multiple end-of-sequence tokens. - input_ids_seq_length (
int
) — The length of the input sequence.
LogitsProcessor that exponentially increases the score of the eos_token_id
after start_index
has been
reached. This allows generating shorter sequences without having a hard cutoff, allowing the eos_token
to be
predicted in a meaningful position.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.ForcedBOSTokenLogitsProcessor
< source >( bos_token_id: int )
LogitsProcessor that enforces the specified token as the first generated token. Used with encoder-decoder models.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.ForcedEOSTokenLogitsProcessor
< source >( max_length: int eos_token_id: Union )
LogitsProcessor that enforces the specified token as the last generated token when max_length
is reached.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
This processor takes a list of pairs of integers which indicates a mapping from generation indices to token
indices that will be forced before generation. The processor will set their log probs to inf
so that they are
sampled at their corresponding index. Originally created for
Whisper.
Examples:
>>> 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")
>>> # This Whisper model forces the generation to start with `50362` at the first position by default, i.e.
>>> # `"forced_decoder_ids": [[1, 50362]]`. This means all other tokens are masked out.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(
... all(outputs.scores[0][0, i] == float("-inf") for i in range(processor.tokenizer.vocab_size) if i != 50362)
... )
True
>>> print(outputs.scores[0][0, 50362])
tensor(0.)
>>> # If we disable `forced_decoder_ids`, we stop seeing that effect
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True, forced_decoder_ids=None)
>>> print(
... all(outputs.scores[0][0, i] == float("-inf") for i in range(processor.tokenizer.vocab_size) if i != 50362)
... )
False
>>> print(outputs.scores[0][0, 50362])
tensor(19.3140)
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.HammingDiversityLogitsProcessor
< source >( diversity_penalty: float num_beams: int num_beam_groups: int )
Parameters
- diversity_penalty (
float
) — This value is subtracted from a beam’s score if it generates a token same as any beam from other group at a particular time. A higherdiversity_penalty
will enforce greater diversity among the beams. Adjusting this value can help strike a balance between diversity and natural likelihood. - num_beams (
int
) — Number of beams for beam search. 1 means no beam search. - num_beam_groups (
int
) — Number of groups to dividenum_beams
into in order to ensure diversity among different groups of beams. this paper for more details.
LogitsProcessor that enforces diverse beam search.
Note that this logits processor is only effective for PreTrainedModel.group_beam_search(). See Diverse Beam Search: Decoding Diverse Solutions from Neural Sequence Models for more details.
Traditional beam search often generates very similar sequences across different beams.
HammingDiversityLogitsProcessor
addresses this by penalizing beams that generate tokens already chosen by other
beams in the same time step.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
>>> import torch
>>> # Initialize the model and tokenizer
>>> tokenizer = AutoTokenizer.from_pretrained("t5-base")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> # A long text about the solar system
>>> text = (
... "The Solar System is a gravitationally bound system comprising the Sun and the objects that orbit it, "
... "either directly or indirectly. Of the objects that orbit the Sun directly, the largest are the eight "
... "planets, with the remainder being smaller objects, such as the five dwarf planets and small Solar System "
... "bodies. The Solar System formed 4.6 billion years ago from the gravitational collapse of a giant "
... "interstellar molecular cloud."
... )
>>> inputs = tokenizer("summarize: " + text, return_tensors="pt")
>>> # Generate diverse summary
>>> outputs_diverse = model.generate(
... **inputs,
... num_beam_groups=2,
... diversity_penalty=10.0,
... max_length=100,
... num_beams=4,
... num_return_sequences=2,
... )
>>> summaries_diverse = tokenizer.batch_decode(outputs_diverse, skip_special_tokens=True)
>>> # Generate non-diverse summary
>>> outputs_non_diverse = model.generate(
... **inputs,
... max_length=100,
... num_beams=4,
... num_return_sequences=2,
... )
>>> summary_non_diverse = tokenizer.batch_decode(outputs_non_diverse, skip_special_tokens=True)
>>> # With `diversity_penalty`, the resulting beams are much more diverse
>>> print(summary_non_diverse)
['the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.',
'the Solar System formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.']
>>> print(summaries_diverse)
['the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.',
'the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets. the rest of the objects are smaller objects, such as the five dwarf planets and small solar system bodies.']
__call__
< source >( input_ids: LongTensor scores: FloatTensor current_tokens: LongTensor beam_group_idx: int ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search - current_tokens (
torch.LongTensor
of shape(batch_size)
) — Indices of input sequence tokens in the vocabulary, corresponding to the tokens selected by the other beam groups in the current generation step. - beam_group_idx (
int
) — The index of the beam group currently being processed.
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
LogitsProcessor that removes all nan
and inf
values to avoid the generation method to fail. Note that using
the logits processor should only be used if necessary since it can slow down the generation method.
This logits processor has no generate
example, as there shouldn’t be a correct combination of flags that warrants
its use.
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
LogitsWarper and LogitsProcessor for normalizing the scores using log-softmax. It’s important to normalize the scores during beam search, after applying the logits processors or warpers, since the search algorithm used in this library doesn’t do it (it only does it before, but they may need re-normalization) but it still supposes that the scores are normalized when comparing the hypotheses.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> import torch
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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.sum(torch.exp(outputs.scores[-1])))
tensor(816.3250)
>>> # 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.sum(torch.exp(outputs.scores[-1])))
tensor(1.0000)
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
Abstract base class for all logit processors that can be applied during generation.
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
This class can be used to create a list of LogitsProcessor or LogitsWarper to subsequently process a
scores
input tensor. This class inherits from list and adds a specific call method to apply each
LogitsProcessor or LogitsWarper to the inputs.
__call__
< source >( input_ids: LongTensor scores: FloatTensor **kwargs ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search - kwargs (
Dict[str, Any]
, optional) — Additional kwargs that are specific to a logits processor.
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
Abstract base class for all logit warpers that can be applied during generation with multinomial sampling.
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.MinLengthLogitsProcessor
< source >( min_length: int eos_token_id: Union )
LogitsProcessor enforcing a min-length by setting EOS probability to 0. Note that, for decoder-only models like most LLMs, the length includes the prompt.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.MinNewTokensLengthLogitsProcessor
< source >( prompt_length_to_skip: int min_new_tokens: int eos_token_id: Union )
Parameters
- prompt_length_to_skip (
int
) — The input tokens length. Not a valid argument when used withgenerate
as it will automatically assign the input length. - min_new_tokens (
int
) — The minimum new tokens length below which the score ofeos_token_id
is set to-float("Inf")
. - eos_token_id (
Union[int, List[int]]
) — The id of the end-of-sequence token. Optionally, use a list to set multiple end-of-sequence tokens.
LogitsProcessor enforcing a min-length of new tokens by setting EOS (End-Of-Sequence) token probability to 0. Contrarily to MinLengthLogitsProcessor, this processor ignores the prompt.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.NoBadWordsLogitsProcessor
< source >( bad_words_ids: List eos_token_id: Union )
LogitsProcessor that enforces that specified sequences will never be selected.
In order to get the token ids of the words that should not appear in the generated text, make sure to set
add_prefix_space=True
when initializing the tokenizer, and use tokenizer(bad_words, add_special_tokens=False).input_ids
. The add_prefix_space
argument is only supported for some slow tokenizers,
as fast tokenizers’ prefixing behaviours come from pre tokenizers
. Read more
here.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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("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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.NoRepeatNGramLogitsProcessor
< source >( ngram_size: int )
N-grams are groups of “n” consecutive words, characters, or tokens taken from a sequence of text. Given the sentence: “She runs fast”, the bi-grams (n=2) would be (“she”, “runs”) and (“runs”, “fast”). In text generation, avoiding repetitions of word sequences provides a more diverse output. This LogitsProcessor enforces no repetition of n-grams by setting the scores of banned tokens to negative infinity which eliminates those tokens from consideration when further processing the scores. Note that, for decoder-only models like most LLMs, the prompt is also considered to obtain the n-grams. Fairseq.
Use n-gram penalties with care. For instance, penalizing 2-grams (bigrams) in an article about the city of New York might lead to undesirable outcomes where the city’s name appears only once in the entire text. Reference
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.PrefixConstrainedLogitsProcessor
< source >( prefix_allowed_tokens_fn: Callable num_beams: int )
Parameters
- prefix_allowed_tokens_fn (
Callable[[int, torch.Tensor], List[int]]
) — This function constraints the beam search to allowed tokens only at each step. This function takes 2 argumentsinputs_ids
and the batch IDbatch_id
. It has to return a list with the allowed tokens for the next generation step conditioned on the previously generated tokensinputs_ids
and the batch IDbatch_id
.
LogitsProcessor that enforces constrained generation and is useful for prefix-conditioned constrained generation. See Autoregressive Entity Retrieval for more information.
Examples:
>>> 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 contrain 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]
... elif input_ids[-2] == entity[0] and input_ids[-1] == entity[1]:
... return entity[2]
... 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.RepetitionPenaltyLogitsProcessor
< source >( penalty: float )
LogitsProcessor that prevents the repetition of previous tokens through a penalty. This penalty is applied at most once per token. Note that, for decoder-only models like most LLMs, the considered tokens include the prompt.
In the original paper, the authors suggest the use of a penalty of around
1.2 to achieve a good balance between truthful generation and lack of repetition. To penalize and reduce
repetition, use penalty
values above 1.0, where a higher value penalizes more strongly. To reward and encourage
repetition, use penalty
values between 0.0 and 1.0, where a lower value rewards more strongly.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> # Initializing the model and tokenizer for it
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.SequenceBiasLogitsProcessor
< source >( sequence_bias: Dict )
Parameters
- sequence_bias (
Dict[Tuple[int], float]
) — Dictionary that maps a sequence of tokens to its bias term. Positive biases increase the odds of the sequence being selected, while negative biases do the opposite. If a sequence has a length of 1, its bias will always be applied. Otherwise, the bias will only be applied if the sequence in question is about to be completed (in the token selection step after this processor is applied).
LogitsProcessor that applies an additive bias on sequences. The bias is applied to the last token of a sequence when the next generated token can complete it. Consequently, to take the most of biasing sequences with more than one token, consider using beam methods (to gracefully work around partially completed sequences that have a negative bias) and applying the bias to their prefixes (to ensure the bias is applied earlier).
In order to get the token ids of the sequences that you want to bias, make sure to set add_prefix_space=True
when
initializing the tokenizer, and use tokenizer(bad_words, add_special_tokens=False).input_ids
. The
add_prefix_space
argument is only supported for some slow tokenizers, as fast tokenizers’ prefixing behaviours
come from pre tokenizers
. Read more here.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> inputs = tokenizer(["The full name of Donald is Donald"], return_tensors="pt")
>>> summary_ids = model.generate(inputs["input_ids"], max_new_tokens=4)
>>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald J. Trump Jr
>>> # Now let's control generation through a bias. Please note that the tokenizer is initialized differently!
>>> tokenizer_with_prefix_space = AutoTokenizer.from_pretrained("gpt2", add_prefix_space=True)
>>> def get_tokens_as_tuple(word):
... return tuple(tokenizer_with_prefix_space([word], add_special_tokens=False).input_ids[0])
>>> # If we add a negative bias without beam search, it may become "stuck" in a prefix without good continuations
>>> sequence_bias = {get_tokens_as_tuple("Trump"): -10.0}
>>> biased_ids = model.generate(inputs["input_ids"], max_new_tokens=4, sequence_bias=sequence_bias)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald J. Donald,
>>> biased_ids = model.generate(inputs["input_ids"], max_new_tokens=4, num_beams=4, sequence_bias=sequence_bias)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald Rumsfeld,
>>> # We can also add a positive bias to nudge the model towards specific tokens or continuations
>>> sequence_bias = {get_tokens_as_tuple("Donald Duck"): 10.0}
>>> biased_ids = model.generate(inputs["input_ids"], max_new_tokens=4, num_beams=4, sequence_bias=sequence_bias)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald Duck.
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.SuppressTokensAtBeginLogitsProcessor
< source >( begin_suppress_tokens begin_index )
SuppressTokensAtBeginLogitsProcessor supresses a list of tokens as soon as the generate
function starts
generating using begin_index
tokens. This should ensure that the tokens defined by begin_suppress_tokens
are
not generated at the begining. Originally created for
Whisper.
Examples:
>>> 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[1][0, 50256]) # 1 (and not 0) is the first freely generated token
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[1][0, 50256])
tensor(11.2027)
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
This processor can be used to suppress a list of tokens. The processor will set their log probs to -inf
so
that they are not generated. Originally created for
Whisper.
Examples:
>>> 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(5.7738)
__call__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.TemperatureLogitsWarper
< source >( temperature: float )
LogitsWarper for temperature (exponential scaling output probability distribution), which effectively means that it can control the randomness of the predicted tokens. Often used together with TopPLogitsWarper and TopKLogitsWarper.
Make sure that do_sample=True
is included in the generate
arguments otherwise the temperature value won’t have
any effect.
Examples:
>>> import torch
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed
>>> set_seed(0) # for reproducibility
>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("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 a joint venture between GEO Group, one of',
'Hugging Face Company is not an exact science – but what we believe does']
>>> # 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.TopKLogitsWarper
< source >( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_k (
int
) — The number of highest probability vocabulary tokens to keep for top-k-filtering. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
LogitsWarper that performs top-k, i.e. restricting to the k highest probability elements. Often used together with TemperatureLogitsWarper and TopPLogitsWarper.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed
>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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, G, H, I. A, M
>>> # 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.TopPLogitsWarper
< source >( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_p (
float
) — If set to < 1, only the smallest set of most probable tokens with probabilities that add up totop_p
or higher are kept for generation. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
LogitsWarper that performs top-p, i.e. restricting to top tokens summing to prob_cut_off <= prob_cut_off. Often used together with TemperatureLogitsWarper and TopKLogitsWarper.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed
>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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, 0, 2, 2. 2, 2, 2, 2
>>> # 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.TypicalLogitsWarper
< source >( mass: float = 0.9 filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- mass (
float
, optional, defaults to 0.9) — Value of typical_p between 0 and 1 inclusive, defaults to 0.9. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
LogitsWarper that performs typical decoding. Inspired on how humans use language, it prioritizes tokens whose log probability is close to the entropy of the token probability distribution. This means that the most likely tokens may be discarded in the process.
See Typical Decoding for Natural Language Generation for more information.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
class transformers.UnbatchedClassifierFreeGuidanceLogitsProcessor
< source >( guidance_scale: float model unconditional_ids: Optional = None unconditional_attention_mask: Optional = None use_cache: Optional = True )
Parameters
- guidance_scale (
float
) — The guidance scale for classifier free guidance (CFG). CFG is enabled by settingguidance_scale != 1
. Higher guidance scale encourages the model to generate samples that are more closely linked to the input prompt, usually at the expense of poorer quality. A value smaller than 1 has the opposite effect, while making the negative prompt provided with negative_prompt_ids (if any) act as a positive prompt. - model (
PreTrainedModel
) — The model computing the unconditional scores. Supposedly the same as the one computing the conditional scores. Both models must use the same tokenizer. - unconditional_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
, optional) — Indices of input sequence tokens in the vocabulary for the unconditional branch. If unset, will default to the last token of the prompt. - unconditional_attention_mask (
torch.LongTensor
of shape(batch_size, sequence_length)
, optional) — Attention mask for unconditional_ids. - use_cache (
bool
, optional, defaults toTrue
) — Whether to cache key/values during the negative prompt forward pass.
Logits processor for Classifier-Free Guidance (CFG). The processors computes a weighted average across scores
from prompt conditional and prompt unconditional (or negative) logits, parameterized by the guidance_scale
.
The unconditional scores are computed internally by prompting model
with the unconditional_ids
branch.
See the paper for more information.
Examples:
>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("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"
class transformers.WhisperTimeStampLogitsProcessor
< source >( generate_config begin_index: Optional = None _detect_timestamp_from_logprob: Optional = None )
Parameters
- generate_config (
GenerateConfig
) — The generate config used to generate the output. The following parameters are required: eos_token_id (int
, optional, defaults to 50257): The id of the end-of-sequence token. no_timestamps_token_id (int
, optional, defaults to 50363): The id of the"<|notimestamps|>"
token. max_initial_timestamp_index (int
, optional, defaults to 1): Used to set the maximum value of the initial timestamp. This is used to prevent the model from predicting timestamps that are too far in the future. - begin_index (
Optional
, optional) — Token index of the first token that is generated by the model. - _detect_timestamp_from_logprob (
bool
, optional) — Whether timestamps can be predicted from logprobs over all timestamps.
LogitsProcessor that modifies the logits for the generation of timestamps in the transcription. When the input tokens are at a specific threshold, the processor sets the scores to negative infinity. The processor makes sure that timestamp tokens appear in pairs, by masking out the logits that would break this pairing pattern. This is done to maintain the consistency and structure of generated timestamps. It also ensures that when the predicted probability of sampling any of the timestamp token is greater than any individual non-timestamp token, those non-timestamp logits are set to negative infinity. This is done to ensure the generation of timestamps over other potential tokens.
See the paper for more information.
Examples:
>>> 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__
< source >( input_ids: LongTensor scores: FloatTensor ) → torch.FloatTensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary. What are input IDs? - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search
Returns
torch.FloatTensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
TensorFlow
class transformers.TFForcedBOSTokenLogitsProcessor
< source >( bos_token_id: int )
TFLogitsProcessor that enforces the specified token as the first generated token.
class transformers.TFForcedEOSTokenLogitsProcessor
< source >( max_length: int eos_token_id: int )
TFLogitsProcessor that enforces the specified token as the last generated token when max_length
is reached.
This processor takes a list of pairs of integers which indicates a mapping from generation indices to token
indices that will be forced before sampling. The processor will set their log probs to 0
and all other tokens to
-inf
so that they are sampled at their corresponding index.
Abstract base class for all logit processors that can be applied during generation.
__call__
< source >( input_ids: Tensor scores: Tensor cur_len: int ) → tf.Tensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
tf.Tensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- scores (
tf.Tensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search. - cur_len (
int
) — The current length of valid input sequence tokens. In the TF implementation, the input_ids’ sequence length is the maximum length generate can produce, and we need to know which of its tokens are valid. - kwargs (
Dict[str, Any]
, optional) — Additional logits processor specific kwargs.
Returns
tf.Tensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
TF method for processing logits.
This class can be used to create a list of TFLogitsProcessor to subsequently process a scores
input tensor.
This class inherits from list and adds a specific call method to apply each TFLogitsProcessor to the
inputs.
__call__
< source >( input_ids: Tensor scores: Tensor cur_len: int **kwargs ) → tf.Tensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
tf.Tensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- scores (
tf.Tensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search. - cur_len (
int
) — The current length of valid input sequence tokens. In the TF implementation, the input_ids’ sequence length is the maximum length generate can produce, and we need to know which of its tokens are valid. - kwargs (
Dict[str, Any]
, optional) — Additional logits processor specific kwargs.
Returns
tf.Tensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
Abstract base class for all logit warpers that can be applied during generation with multinomial sampling.
__call__
< source >( input_ids: Tensor scores: Tensor cur_len: int ) → tf.Tensor
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
tf.Tensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- scores (
tf.Tensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search. - cur_len (
int
) — The current length of valid input sequence tokens. In the TF implementation, the input_ids’ sequence length is the maximum length generate can produce, and we need to know which of its tokens are valid. - kwargs (
Dict[str, Any]
, optional) — Additional logits processor specific kwargs.
Returns
tf.Tensor
of shape (batch_size, config.vocab_size)
The processed prediction scores.
TF method for warping logits.
class transformers.TFMinLengthLogitsProcessor
< source >( min_length: int eos_token_id: int )
TFLogitsProcessor enforcing a min-length by setting EOS probability to 0.
class transformers.TFNoBadWordsLogitsProcessor
< source >( bad_words_ids: List eos_token_id: int )
Parameters
- bad_words_ids (
List[List[int]]
) — List of list of token ids that are not allowed to be generated. In order to get the tokens of the words that should not appear in the generated text, make sure to setadd_prefix_space=True
when initializing the tokenizer, and usetokenizer(bad_words, add_special_tokens=False).input_ids
. Theadd_prefix_space
argument is only supported for some slow tokenizers, as fast tokenizers’ prefixing behaviours come frompre tokenizers
. Read more here. - eos_token_id (
int
) — The id of the end-of-sequence token.
TFLogitsProcessor that enforces that specified sequences will never be sampled.
class transformers.TFNoRepeatNGramLogitsProcessor
< source >( ngram_size: int )
TFLogitsProcessor that enforces no repetition of n-grams. See Fairseq.
class transformers.TFRepetitionPenaltyLogitsProcessor
< source >( penalty: float )
Parameters
- repetition_penalty (
float
) — The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details.
TFLogitsProcessor enforcing an exponential penalty on repeated sequences.
class transformers.TFSuppressTokensAtBeginLogitsProcessor
< source >( begin_suppress_tokens begin_index )
TFSuppressTokensAtBeginLogitsProcessor suppresses a list of tokens as soon as the generate
function starts
generating using begin_index
tokens. This should ensure that the tokens defined by begin_suppress_tokens
at not
sampled at the begining of the generation.
This processor can be used to suppress a list of tokens. The processor will set their log probs to -inf
so that they
are not sampled.
class transformers.TFTemperatureLogitsWarper
< source >( temperature: float )
TFLogitsWarper for temperature (exponential scaling output probability distribution).
class transformers.TFTopKLogitsWarper
< source >( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_k (
int
) — The number of highest probability vocabulary tokens to keep for top-k-filtering. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
TFLogitsWarper that performs top-k, i.e. restricting to the k highest probability elements.
class transformers.TFTopPLogitsWarper
< source >( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_p (
float
) — If set to < 1, only the smallest set of most probable tokens with probabilities that add up totop_p
or higher are kept for generation. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
TFLogitsWarper that performs top-p, i.e. restricting to top tokens summing to <= prob_cut_off.
FLAX
class transformers.FlaxForcedBOSTokenLogitsProcessor
< source >( bos_token_id: int )
FlaxLogitsProcessor that enforces the specified token as the first generated token.
class transformers.FlaxForcedEOSTokenLogitsProcessor
< source >( max_length: int eos_token_id: int )
FlaxLogitsProcessor that enforces the specified token as the last generated token when max_length
is reached.
class transformers.FlaxForceTokensLogitsProcessor
< source >( force_token_map )
FlaxLogitsProcessor that takes a list of pairs of integers which indicates a mapping from generation indices to
token indices that will be forced before sampling. The processor will set their log probs to 0 and all other tokens
to -inf
so that they are sampled at their corresponding index.
Abstract base class for all logit processors that can be applied during generation.
__call__
< source >( input_ids: Array scores: Array ) → jnp.ndarray
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
jnp.ndarray
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- scores (
jnp.ndarray
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search - kwargs (
Dict[str, Any]
, optional) — Additional logits processor specific kwargs.
Returns
jnp.ndarray
of shape (batch_size, config.vocab_size)
The processed prediction scores.
Flax method for processing logits.
This class can be used to create a list of FlaxLogitsProcessor or FlaxLogitsWarper to subsequently process
a scores
input tensor. This class inherits from list and adds a specific call method to apply each
FlaxLogitsProcessor or FlaxLogitsWarper to the inputs.
__call__
< source >( input_ids: Array scores: Array cur_len: int **kwargs ) → jnp.ndarray
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
jnp.ndarray
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- scores (
jnp.ndarray
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search - kwargs (
Dict[str, Any]
, optional) — Additional logits processor specific kwargs.
Returns
jnp.ndarray
of shape (batch_size, config.vocab_size)
The processed prediction scores.
Abstract base class for all logit warpers that can be applied during generation with multinomial sampling.
__call__
< source >( input_ids: Array scores: Array ) → jnp.ndarray
of shape (batch_size, config.vocab_size)
Parameters
- input_ids (
jnp.ndarray
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- scores (
jnp.ndarray
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be logits for each vocabulary when not using beam search or log softmax for each vocabulary token when using beam search - kwargs (
Dict[str, Any]
, optional) — Additional logits processor specific kwargs.
Returns
jnp.ndarray
of shape (batch_size, config.vocab_size)
The processed prediction scores.
Flax method for warping logits.
class transformers.FlaxMinLengthLogitsProcessor
< source >( min_length: int eos_token_id: int )
FlaxLogitsProcessor enforcing a min-length by setting EOS probability to 0.
class transformers.FlaxSuppressTokensAtBeginLogitsProcessor
< source >( begin_suppress_tokens begin_index )
FlaxLogitsProcessor supressing a list of tokens as soon as the generate
function starts generating using
begin_index
tokens. This should ensure that the tokens defined by begin_suppress_tokens
are not sampled at the
begining of the generation.
class transformers.FlaxSuppressTokensLogitsProcessor
< source >( suppress_tokens: list )
FlaxLogitsProcessor suppressing a list of tokens at each decoding step. The processor will set their log probs
to be -inf
so they are not sampled.
class transformers.FlaxTemperatureLogitsWarper
< source >( temperature: float )
FlaxLogitsWarper for temperature (exponential scaling output probability distribution).
class transformers.FlaxTopKLogitsWarper
< source >( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_k (
int
) — The number of highest probability vocabulary tokens to keep for top-k-filtering. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
FlaxLogitsWarper that performs top-k, i.e. restricting to the k highest probability elements.
class transformers.FlaxTopPLogitsWarper
< source >( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_p (
float
) — If set to < 1, only the smallest set of most probable tokens with probabilities that add up totop_p
or higher are kept for generation. - filter_value (
float
, optional, defaults to -inf) — All filtered values will be set to this float value. - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimum number of tokens that cannot be filtered.
FlaxLogitsWarper that performs top-p, i.e. restricting to top tokens summing to prob_cut_off <= prob_cut_off.
class transformers.FlaxWhisperTimeStampLogitsProcessor
< source >( generate_config model_config decoder_input_length )
Parameters
- generate_config (
GenerateConfig
) — The generate config used to generate the output. The following parameters are required: eos_token_id (int
, optional, defaults to 50257): The id of the end-of-sequence token. no_timestamps_token_id (int
, optional, defaults to 50363): The id of the"<|notimestamps|>"
token. max_initial_timestamp_index (int
, optional, defaults to 1): Used to set the maximum value of the initial timestamp. This is used to prevent the model from predicting timestamps that are too far in the future.
Whisper specific Processor. This processor can be used to force a list of tokens. The processor will set their log
probs to inf
so that they are sampled at their corresponding index.
StoppingCriteria
可以使用StoppingCriteria来更改停止生成的时间(除了EOS token以外的方法)。请注意,这仅适用于我们的PyTorch实现。
Abstract base class for all stopping criteria that can be applied during generation.
If your stopping criteria depends on the scores
input, make sure you pass return_dict_in_generate=True, output_scores=True
to generate
.
__call__
< source >( input_ids: LongTensor scores: FloatTensor **kwargs )
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using
AutoTokenizer
. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details. - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be scores for each vocabulary token before SoftMax or scores for each vocabulary token after SoftMax. If this stopping criteria depends on thescores
input, make sure you passreturn_dict_in_generate=True, output_scores=True
togenerate
. - kwargs (
Dict[str, Any]
, optional) — Additional stopping criteria specific kwargs.
__call__
< source >( input_ids: LongTensor scores: FloatTensor **kwargs )
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using
AutoTokenizer
. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details. - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be scores for each vocabulary token before SoftMax or scores for each vocabulary token after SoftMax. If this stopping criteria depends on thescores
input, make sure you passreturn_dict_in_generate=True, output_scores=True
togenerate
. - kwargs (
Dict[str, Any]
, optional) — Additional stopping criteria specific kwargs.
class transformers.MaxLengthCriteria
< source >( max_length: int max_position_embeddings: Optional = None )
This class can be used to stop generation whenever the full generated number of tokens exceeds max_length
. Keep
in mind for decoder-only type of transformers, this will include the initial prompted tokens.
__call__
< source >( input_ids: LongTensor scores: FloatTensor **kwargs )
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using
AutoTokenizer
. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details. - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be scores for each vocabulary token before SoftMax or scores for each vocabulary token after SoftMax. If this stopping criteria depends on thescores
input, make sure you passreturn_dict_in_generate=True, output_scores=True
togenerate
. - kwargs (
Dict[str, Any]
, optional) — Additional stopping criteria specific kwargs.
class transformers.MaxTimeCriteria
< source >( max_time: float initial_timestamp: Optional = None )
This class can be used to stop generation whenever the full generation exceeds some amount of time. By default, the
time will start being counted when you initialize this function. You can override this by passing an
initial_time
.
__call__
< source >( input_ids: LongTensor scores: FloatTensor **kwargs )
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using
AutoTokenizer
. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details. - scores (
torch.FloatTensor
of shape(batch_size, config.vocab_size)
) — Prediction scores of a language modeling head. These can be scores for each vocabulary token before SoftMax or scores for each vocabulary token after SoftMax. If this stopping criteria depends on thescores
input, make sure you passreturn_dict_in_generate=True, output_scores=True
togenerate
. - kwargs (
Dict[str, Any]
, optional) — Additional stopping criteria specific kwargs.
Constraints
可以使用Constraint来强制生成结果包含输出中的特定tokens或序列。请注意,这仅适用于我们的PyTorch实现。
Abstract base class for all constraints that can be applied during generation. It must define how the constraint can be satisfied.
All classes that inherit Constraint must follow the requirement that
will always terminate (halt).
advance
< source >( ) → token_ids(torch.tensor
)
Returns
token_ids(torch.tensor
)
Must be a tensor of a list of indexable tokens, not some integer.
When called, returns the token that would take this constraint one step closer to being fulfilled.
copy
< source >( stateful = False ) → constraint(Constraint
)
Returns
constraint(Constraint
)
The same constraint as the one being called from.
Creates a new instance of this constraint.
Reads in a token and returns whether it creates progress.
Returns the number of remaining steps of advance()
in order to complete this constraint.
Resets the state of this constraint to its initialization. We would call this in cases where the fulfillment of a constraint is abrupted by an unwanted token.
Tests whether this constraint has been properly defined.
update
< source >( token_id: int ) → stepped(bool
)
Returns
stepped(bool
)
Whether this constraint has become one step closer to being fulfuilled.
completed(bool
):
Whether this constraint has been completely fulfilled by this token being generated.
reset (bool
):
Whether this constraint has reset its progress by this token being generated.
Reads in a token and returns booleans that indicate the progress made by it. This function will update the
state of this object unlikes does_advance(self, token_id: int)
.
This isn’t to test whether a certain token will advance the progress; it’s to update its state as if it has been generated. This becomes important if token_id != desired token (refer to else statement in PhrasalConstraint)
class transformers.PhrasalConstraint
< source >( token_ids: List )
Constraint enforcing that an ordered sequence of tokens is included in the output.
class transformers.DisjunctiveConstraint
< source >( nested_token_ids: List )
A special Constraint that is fulfilled by fulfilling just one of several constraints.
class transformers.ConstraintListState
< source >( constraints: List )
Parameters
- constraints (
List[Constraint]
) — A list of Constraint objects that must be fulfilled by the beam scorer.
A class for beam scorers to track its progress through a list of constraints.
The list of tokens to generate such that we can make progress. By “list” we don’t mean the list of token that will fully fulfill a constraint.
Given constraints c_i = {t_ij | j == # of tokens}
, If we’re not in the middle of progressing through a
specific constraint c_i
, we return:
[t_k1 for k in indices of unfulfilled constraints]
If we are in the middle of a constraint, then we return:
[t_ij]
, where i
is the index of the inprogress constraint, j
is the next step for the constraint.
Though we don’t care which constraint is fulfilled first, if we are in the progress of fulfilling a constraint, that’s the only one we’ll return.
token_ids: the tokens generated thus far to reset the state of the progress through constraints.
BeamSearch
Abstract base class for all beam scorers that are used for beam_search() and beam_sample().
process
< source >( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor **kwargs ) → UserDict
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size * num_beams, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using any class inheriting from PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- next_scores (
torch.FloatTensor
of shape(batch_size, 2 * num_beams)
) — Current scores of the top2 * num_beams
non-finished beam hypotheses. - next_tokens (
torch.LongTensor
of shape(batch_size, 2 * num_beams)
) —input_ids
of the tokens corresponding to the top2 * num_beams
non-finished beam hypotheses. - next_indices (
torch.LongTensor
of shape(batch_size, 2 * num_beams)
) — Beam indices indicating to which beam hypothesis thenext_tokens
correspond. - pad_token_id (
int
, optional) — The id of the padding token. - eos_token_id (
Union[int, List[int]]
, optional) — The id of the end-of-sequence token. Optionally, use a list to set multiple end-of-sequence tokens. - beam_indices (
torch.LongTensor
, optional) — Beam indices indicating to which beam hypothesis each token correspond. - group_index (
int
, optional) — The index of the group of beams. Used with group_beam_search().
Returns
UserDict
A dictionary composed of the fields as defined above:
- next_beam_scores (
torch.FloatTensor
of shape(batch_size * num_beams)
) — Updated scores of all non-finished beams. - next_beam_tokens (
torch.FloatTensor
of shape(batch_size * num_beams)
) — Next tokens to be added to the non-finished beam_hypotheses. - next_beam_indices (
torch.FloatTensor
of shape(batch_size * num_beams)
) — Beam indices indicating to which beam the next tokens shall be added.
finalize
< source >( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor max_length: int **kwargs ) → torch.LongTensor
of shape (batch_size * num_return_sequences, sequence_length)
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size * num_beams, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using any class inheriting from PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- final_beam_scores (
torch.FloatTensor
of shape(batch_size * num_beams)
) — The final scores of all non-finished beams. - final_beam_tokens (
torch.FloatTensor
of shape(batch_size * num_beams)
) — The last tokens to be added to the non-finished beam_hypotheses. - final_beam_indices (
torch.FloatTensor
of shape(batch_size * num_beams)
) — The beam indices indicating to which beam thefinal_beam_tokens
shall be added. - pad_token_id (
int
, optional) — The id of the padding token. - eos_token_id (
Union[int, List[int]]
, optional) — The id of the end-of-sequence token. Optionally, use a list to set multiple end-of-sequence tokens.
Returns
torch.LongTensor
of shape (batch_size * num_return_sequences, sequence_length)
The generated sequences.
The second dimension (sequence_length) is either equal to max_length
or shorter if all batches finished early
due to the eos_token_id
.
class transformers.BeamSearchScorer
< source >( batch_size: int num_beams: int device: device length_penalty: Optional = 1.0 do_early_stopping: Union = False num_beam_hyps_to_keep: Optional = 1 num_beam_groups: Optional = 1 max_length: Optional = None )
Parameters
- batch_size (
int
) — Batch Size ofinput_ids
for which standard beam search decoding is run in parallel. - num_beams (
int
) — Number of beams for beam search. - device (
torch.device
) — Defines the device type (e.g.,"cpu"
or"cuda"
) on which this instance ofBeamSearchScorer
will be allocated. - length_penalty (
float
, optional, defaults to 1.0) — Exponential penalty to the length that is used with beam-based generation. It is applied as an exponent to the sequence length, which in turn is used to divide the score of the sequence. Since the score is the log likelihood of the sequence (i.e. negative),length_penalty
> 0.0 promotes longer sequences, whilelength_penalty
< 0.0 encourages shorter sequences. - do_early_stopping (
bool
orstr
, optional, defaults toFalse
) — Controls the stopping condition for beam-based methods, like beam-search. It accepts the following values:True
, where the generation stops as soon as there arenum_beams
complete candidates;False
, where an heuristic is applied and the generation stops when is it very unlikely to find better candidates;"never"
, where the beam search procedure only stops when there cannot be better candidates (canonical beam search algorithm). - num_beam_hyps_to_keep (
int
, optional, defaults to 1) — The number of beam hypotheses that shall be returned upon calling finalize(). - num_beam_groups (
int
, optional, defaults to 1) — Number of groups to dividenum_beams
into in order to ensure diversity among different groups of beams. See this paper for more details. - max_length (
int
, optional) — The maximum length of the sequence to be generated.
BeamScorer implementing standard beam search decoding.
Adapted in part from Facebook’s XLM beam search code.
Reference for the diverse beam search algorithm and implementation Ashwin Kalyan’s DBS implementation
process
< source >( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None group_index: Optional = 0 decoder_prompt_len: Optional = 0 )
finalize
< source >( input_ids: LongTensor final_beam_scores: FloatTensor final_beam_tokens: LongTensor final_beam_indices: LongTensor max_length: int pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None decoder_prompt_len: Optional = 0 )
class transformers.ConstrainedBeamSearchScorer
< source >( batch_size: int num_beams: int constraints: List device: device length_penalty: Optional = 1.0 do_early_stopping: Union = False num_beam_hyps_to_keep: Optional = 1 num_beam_groups: Optional = 1 max_length: Optional = None )
Parameters
- batch_size (
int
) — Batch Size ofinput_ids
for which standard beam search decoding is run in parallel. - num_beams (
int
) — Number of beams for beam search. - constraints (
List[Constraint]
) — A list of positive constraints represented asConstraint
objects that must be fulfilled in the generation output. For more information, the documentation of Constraint should be read. - device (
torch.device
) — Defines the device type (e.g.,"cpu"
or"cuda"
) on which this instance ofBeamSearchScorer
will be allocated. - length_penalty (
float
, optional, defaults to 1.0) — Exponential penalty to the length that is used with beam-based generation. It is applied as an exponent to the sequence length, which in turn is used to divide the score of the sequence. Since the score is the log likelihood of the sequence (i.e. negative),length_penalty
> 0.0 promotes longer sequences, whilelength_penalty
< 0.0 encourages shorter sequences. - do_early_stopping (
bool
orstr
, optional, defaults toFalse
) — Controls the stopping condition for beam-based methods, like beam-search. It accepts the following values:True
, where the generation stops as soon as there arenum_beams
complete candidates;False
, where an heuristic is applied and the generation stops when is it very unlikely to find better candidates;"never"
, where the beam search procedure only stops when there cannot be better candidates (canonical beam search algorithm). - num_beam_hyps_to_keep (
int
, optional, defaults to 1) — The number of beam hypotheses that shall be returned upon calling finalize(). - num_beam_groups (
int
, optional, defaults to 1) — Number of groups to dividenum_beams
into in order to ensure diversity among different groups of beams. See this paper for more details. - max_length (
int
, optional) — The maximum length of the sequence to be generated.
BeamScorer implementing constrained beam search decoding.
process
< source >( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor scores_for_all_vocab: FloatTensor pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None decoder_prompt_len: Optional = 0 ) → UserDict
Parameters
- input_ids (
torch.LongTensor
of shape(batch_size * num_beams, sequence_length)
) — Indices of input sequence tokens in the vocabulary.Indices can be obtained using any class inheriting from PreTrainedTokenizer. See PreTrainedTokenizer.encode() and PreTrainedTokenizer.call() for details.
- next_scores (
torch.FloatTensor
of shape(batch_size, 2 * num_beams)
) — Current scores of the top2 * num_beams
non-finished beam hypotheses. - next_tokens (
torch.LongTensor
of shape(batch_size, 2 * num_beams)
) —input_ids
of the tokens corresponding to the top2 * num_beams
non-finished beam hypotheses. - next_indices (
torch.LongTensor
of shape(batch_size, 2 * num_beams)
) — Beam indices indicating to which beam hypothesis thenext_tokens
correspond. - scores_for_all_vocab (
torch.FloatTensor
of shape(batch_size * num_beams, sequence_length)
) — The scores of all tokens in the vocabulary for each of the beam hypotheses. - pad_token_id (
int
, optional) — The id of the padding token. - eos_token_id (
Union[int, List[int]]
, optional) — The id of the end-of-sequence token. Optionally, use a list to set multiple end-of-sequence tokens. - beam_indices (
torch.LongTensor
, optional) — Beam indices indicating to which beam hypothesis each token correspond. - decoder_prompt_len (
int
, optional) — The length of prompt that is included in the input to decoder.
Returns
UserDict
A dictionary composed of the fields as defined above:
-
next_beam_scores (
torch.FloatTensor
of shape(batch_size * num_beams)
) — Updated scores of all non-finished beams. -
next_beam_tokens (
torch.FloatTensor
of shape(batch_size * num_beams)
) — Next tokens to be added to the non-finished beam_hypotheses. -
next_beam_indices (
torch.FloatTensor
of shape(batch_size * num_beams)
) — Beam indices indicating to which beam the next tokens shall be added.
finalize
< source >( input_ids: LongTensor final_beam_scores: FloatTensor final_beam_tokens: LongTensor final_beam_indices: LongTensor max_length: int pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None decoder_prompt_len: Optional = 0 )
Utilities
transformers.top_k_top_p_filtering
< source >( logits: FloatTensor top_k: int = 0 top_p: float = 1.0 filter_value: float = -inf min_tokens_to_keep: int = 1 )
Parameters
- top_k (
int
, optional, defaults to 0) — If > 0, only keep the top k tokens with highest probability (top-k filtering) - top_p (
float
, optional, defaults to 1.0) — If < 1.0, only keep the top tokens with cumulative probability >= top_p (nucleus filtering). Nucleus filtering is described in Holtzman et al. (http://arxiv.org/abs/1904.09751) - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimumber of tokens we keep per batch example in the output.
Filter a distribution of logits using top-k and/or nucleus (top-p) filtering
From: https://gist.github.com/thomwolf/1a5a29f6962089e871b94cbd09daf317
transformers.tf_top_k_top_p_filtering
< source >( logits top_k = 0 top_p = 1.0 filter_value = -inf min_tokens_to_keep = 1 )
Parameters
- top_k (
int
, optional, defaults to 0) — If > 0, only keep the top k tokens with highest probability (top-k filtering) - top_p (
float
, optional, defaults to 1.0) — If < 1.0, only keep the top tokens with cumulative probability >= top_p (nucleus filtering). Nucleus filtering is described in Holtzman et al. (http://arxiv.org/abs/1904.09751) - min_tokens_to_keep (
int
, optional, defaults to 1) — Minimumber of tokens we keep per batch example in the output.
Filter a distribution of logits using top-k and/or nucleus (top-p) filtering
From: https://gist.github.com/thomwolf/1a5a29f6962089e871b94cbd09daf317
Streamers
class transformers.TextStreamer
< source >( tokenizer: AutoTokenizer skip_prompt: bool = False **decode_kwargs )
Parameters
Simple text streamer that prints the token(s) to stdout as soon as entire words are formed.
The API for the streamer classes is still under development and may change in the future.
Examples:
>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer
>>> tok = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("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,
Flushes any remaining cache and prints a newline to stdout.
Prints the new text to stdout. If the stream is ending, also prints a newline.
Receives tokens, decodes them, and prints them to stdout as soon as they form entire words.
class transformers.TextIteratorStreamer
< source >( tokenizer: AutoTokenizer skip_prompt: bool = False timeout: Optional = None **decode_kwargs )
Parameters
- tokenizer (
AutoTokenizer
) — The tokenized used to decode the tokens. - skip_prompt (
bool
, optional, defaults toFalse
) — Whether to skip the prompt to.generate()
or not. Useful e.g. for chatbots. - timeout (
float
, optional) — The timeout for the text queue. IfNone
, the queue will block indefinitely. Useful to handle exceptions in.generate()
, when it is called in a separate thread. - decode_kwargs (
dict
, optional) — Additional keyword arguments to pass to the tokenizer’sdecode
method.
Streamer that stores print-ready text in a queue, to be used by a downstream application as an iterator. This is useful for applications that benefit from acessing the generated text in a non-blocking way (e.g. in an interactive Gradio demo).
The API for the streamer classes is still under development and may change in the future.
Examples:
>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
>>> from threading import Thread
>>> tok = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("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,'
Put the new text in the queue. If the stream is ending, also put a stop signal in the queue.