Hugging Face's logo

Transformers documentation

Utilities for Generation

You are viewing v4.32.1 version. A newer version v4.41.0 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Utilities for Generation

This page lists all the utility functions used by generate(), greedy_search(), contrastive_search(), sample(), beam_search(), beam_sample(), group_beam_search(), and constrained_beam_search().

Most of those are only useful if you are studying the code of the generate methods in the library.

Generate Outputs

The output of generate() is an instance of a subclass of ModelOutput. This output is a data structure containing all the information returned by generate(), but that can also be used as tuple or dictionary.

Here’s an example:

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)

The generation_output object is a GreedySearchDecoderOnlyOutput, as we can see in the documentation of that class below, it means it has the following attributes:

  • sequences: the generated sequences of tokens
  • scores (optional): the prediction scores of the language modelling head, for each generation step
  • hidden_states (optional): the hidden states of the model, for each generation step
  • attentions (optional): the attention weights of the model, for each generation step

Here we have the scores since we passed along output_scores=True, but we don’t have hidden_states and attentions because we didn’t pass output_hidden_states=True or output_attentions=True.

You can access each attribute as you would usually do, and if that attribute has not been returned by the model, you will get None. Here for instance generation_output.scores are all the generated prediction scores of the language modeling head, and generation_output.attentions is None.

When using our generation_output object as a tuple, it only keeps the attributes that don’t have None values. Here, for instance, it has two elements, loss then logits, so

generation_output[:2]

will return the tuple (generation_output.sequences, generation_output.scores) for instance.

When using our generation_output object as a dictionary, it only keeps the attributes that don’t have None values. Here, for instance, it has two keys that are sequences and scores.

We document here all output types.

PyTorch

class transformers.generation.GreedySearchEncoderDecoderOutput

< >

( sequences: LongTensor = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_attentions: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[torch.FloatTensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None )

Parameters

  • sequences (torch.LongTensor of shape (batch_size, 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.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of torch.FloatTensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of torch.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of torch.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.GreedySearchDecoderOnlyOutput

< >

( sequences: LongTensor = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None )

Parameters

  • sequences (torch.LongTensor of shape (batch_size, 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.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of torch.FloatTensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, generated_length, hidden_size).

Base class for outputs of decoder-only generation models using greedy search.

class transformers.generation.SampleEncoderDecoderOutput

< >

( sequences: LongTensor = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_attentions: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[torch.FloatTensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of torch.FloatTensor with up to max_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(torch.FloatTensor), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple of torch.FloatTensor (one for each layer of the decoder) of shape (batch_size*num_return_sequences, num_heads, sequence_length, sequence_length).
  • encoder_hidden_states (tuple(torch.FloatTensor), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of torch.FloatTensor (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(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size*num_return_sequences, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.SampleDecoderOnlyOutput

< >

( sequences: LongTensor = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of torch.FloatTensor with up to max_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(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (num_return_sequences*batch_size, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.BeamSearchEncoderDecoderOutput

< >

( sequences: LongTensor = None sequences_scores: typing.Optional[torch.FloatTensor] = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None beam_indices: typing.Optional[torch.LongTensor] = None encoder_attentions: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[torch.FloatTensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • sequences_scores (torch.FloatTensor of shape (batch_size*num_return_sequences), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.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 of torch.FloatTensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of torch.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of torch.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.BeamSearchDecoderOnlyOutput

< >

( sequences: LongTensor = None sequences_scores: typing.Optional[torch.FloatTensor] = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None beam_indices: typing.Optional[torch.LongTensor] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • sequences_scores (torch.FloatTensor of shape (batch_size*num_return_sequences), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.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 of torch.FloatTensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size*num_beams, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.BeamSampleEncoderDecoderOutput

< >

( sequences: LongTensor = None sequences_scores: typing.Optional[torch.FloatTensor] = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None beam_indices: typing.Optional[torch.LongTensor] = None encoder_attentions: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[torch.FloatTensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None )

Parameters

  • sequences (torch.LongTensor of shape (batch_size*num_beams, 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.
  • sequences_scores (torch.FloatTensor of shape (batch_size * num_return_sequence), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.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 of torch.FloatTensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of torch.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of torch.FloatTensor (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(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size*num_beams, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.BeamSampleDecoderOnlyOutput

< >

( sequences: LongTensor = None sequences_scores: typing.Optional[torch.FloatTensor] = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None beam_indices: typing.Optional[torch.LongTensor] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • sequences_scores (torch.FloatTensor of shape (batch_size * num_return_sequence), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.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 of torch.FloatTensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size*num_beams, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor 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.ContrastiveSearchEncoderDecoderOutput

< >

( sequences: LongTensor = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_attentions: typing.Optional[typing.Tuple[torch.FloatTensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[torch.FloatTensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None )

Parameters

  • sequences (torch.LongTensor of shape (batch_size, 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.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of torch.FloatTensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of torch.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of torch.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(torch.FloatTensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, generated_length, hidden_size).

Base class for outputs of decoder-only generation models using contrastive search.

class transformers.generation.ContrastiveSearchDecoderOnlyOutput

< >

( sequences: LongTensor = None scores: typing.Optional[typing.Tuple[torch.FloatTensor]] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[torch.FloatTensor]]] = None )

Parameters

  • sequences (torch.LongTensor of shape (batch_size, 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.
  • scores (tuple(torch.FloatTensor) optional, returned when output_scores=True is passed or when — config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of torch.FloatTensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(torch.FloatTensor)), optional, returned when output_hidden_states=True is —
  • passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of torch.FloatTensor of shape (batch_size, generated_length, hidden_size).

Base class for outputs of decoder-only generation models using contrastive search.

TensorFlow

class transformers.generation.TFGreedySearchEncoderDecoderOutput

< >

( sequences: Tensor = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_attentions: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None )

Parameters

  • sequences (tf.Tensor of shape (batch_size, 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.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of tf.Tensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of tf.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of tf.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(tf.Tensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None )

Parameters

  • sequences (tf.Tensor of shape (batch_size, 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.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of tf.Tensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_attentions: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of tf.Tensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of tf.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of tf.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size*num_return_sequences, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(tf.Tensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of tf.Tensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (num_return_sequences*batch_size, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None sequences_scores: typing.Optional[tensorflow.python.framework.ops.Tensor] = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None beam_indices: typing.Optional[tensorflow.python.framework.ops.Tensor] = None encoder_attentions: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • sequences_scores (tf.Tensor of shape (batch_size*num_return_sequences), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.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 tomax_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of tf.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of tf.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(tf.Tensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None sequences_scores: typing.Optional[tensorflow.python.framework.ops.Tensor] = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None beam_indices: typing.Optional[tensorflow.python.framework.ops.Tensor] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • sequences_scores (tf.Tensor of shape (batch_size*num_return_sequences), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.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.Tensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size*num_beams, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None sequences_scores: typing.Optional[tensorflow.python.framework.ops.Tensor] = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None beam_indices: typing.Optional[tensorflow.python.framework.ops.Tensor] = None encoder_attentions: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None )

Parameters

  • sequences (tf.Tensor of shape (batch_size*num_beams, 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.
  • sequences_scores (tf.Tensor of shape (batch_size * num_return_sequence), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.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.Tensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of tf.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of tf.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size*num_beams, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(tf.Tensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None sequences_scores: typing.Optional[tensorflow.python.framework.ops.Tensor] = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None beam_indices: typing.Optional[tensorflow.python.framework.ops.Tensor] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = 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 to max_length or shorter if all batches finished early due to the eos_token_id.
  • sequences_scores (tf.Tensor of shape (batch_size * num_return_sequence), optional, returned when output_scores=True is passed or when config.output_scores=True) — Final beam scores of the generated sequences.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.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.Tensor with up to max_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 when output_scores=True is passed or when config.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size*num_beams, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_attentions: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None encoder_hidden_states: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None decoder_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None cross_attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None decoder_hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None )

Parameters

  • sequences (tf.Tensor of shape (batch_size, 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.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of tf.Tensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple of tf.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 when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple of tf.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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • cross_attentions (tuple(tuple(tf.Tensor)), optional, returned when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Tensor = None scores: typing.Optional[typing.Tuple[tensorflow.python.framework.ops.Tensor]] = None attentions: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None hidden_states: typing.Optional[typing.Tuple[typing.Tuple[tensorflow.python.framework.ops.Tensor]]] = None )

Parameters

  • sequences (tf.Tensor of shape (batch_size, 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.
  • scores (tuple(tf.Tensor) optional, returned when output_scores=True is passed or when config.output_scores=True) — Processed prediction scores of the language modeling head (scores for each vocabulary token before SoftMax) at each generation step. Tuple of tf.Tensor with up to max_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 when output_attentions=True is passed or config.output_attentions=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.Tensor of shape (batch_size, num_heads, generated_length, sequence_length).
  • hidden_states (tuple(tuple(tf.Tensor)), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — Tuple (one element for each generated token) of tuples (one element for each layer of the decoder) of tf.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

< >

( sequences: Array = None )

Parameters

  • sequences (jnp.ndarray of shape (batch_size, max_length)) — The generated sequences.

Flax Base class for outputs of decoder-only generation models using sampling.

replace

< >

( **updates )

“Returns a new object replacing the specified fields with new values.

class transformers.generation.FlaxGreedySearchOutput

< >

( sequences: Array = None )

Parameters

  • sequences (jnp.ndarray of shape (batch_size, max_length)) — The generated sequences.

Flax Base class for outputs of decoder-only generation models using greedy search.

replace

< >

( **updates )

“Returns a new object replacing the specified fields with new values.

class transformers.generation.FlaxBeamSearchOutput

< >

( sequences: Array = None scores: Array = None )

Parameters

  • sequences (jnp.ndarray of shape (batch_size, max_length)) — The generated sequences.
  • scores (jnp.ndarray of shape (batch_size,)) — The scores (log probabilities) of the generated sequences.

Flax Base class for outputs of decoder-only generation models using greedy search.

replace

< >

( **updates )

“Returns a new object replacing the specified fields with new values.

LogitsProcessor

A LogitsProcessor can be used to modify the prediction scores of a language model head for generation.

PyTorch

class transformers.AlternatingCodebooksLogitsProcessor

< >

( input_start_len: int semantic_vocab_size: int codebook_size: int )

Parameters

  • input_start_len (int) — The length of the initial input sequence.
  • semantic_vocab_size (int) — Vocabulary size of the semantic part, i.e number of tokens associated to the semantic vocabulary.
  • codebook_size (int) — Number of tokens associated to the codebook.

LogitsProcessor enforcing alternated generation between the two codebooks of Bark’s fine submodel.

__call__

< >

( input_ids: LongTensor scores: FloatTensor )

class transformers.ClassifierFreeGuidanceLogitsProcessor

< >

( guidance_scale )

Parameters

  • guidance_scale (float) — The guidance scale for classifier free guidance (CFG). CFG is enabled by setting guidance_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.

Logits processor 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.

__call__

< >

( 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

< >

( encoder_ngram_size: int encoder_input_ids: LongTensor )

Parameters

  • encoder_ngram_size (int) — All ngrams of size ngram_size can only occur within the encoder input ids.
  • encoder_input_ids (int) — The encoder_input_ids that should not be repeated within the decoder ids.

LogitsProcessor that enforces no repetition of encoder input ids n-grams for the decoder ids. See ParlAI.

__call__

< >

( 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

< >

( penalty: float encoder_input_ids: LongTensor )

Parameters

  • hallucination_penalty (float) — The parameter for hallucination penalty. 1.0 means no penalty.
  • encoder_input_ids (torch.LongTensor) — The encoder_input_ids that should not be repeated within the decoder ids.

LogitsProcessor enforcing an exponential penalty on tokens that are not in the original input.

__call__

< >

( 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

< >

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

Parameters

  • epsilon (float) — If set to > 0, only the most tokens with probabilities epsilon or higher are kept for generation.
  • filter_value (float, optional, defaults to -float("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.

__call__

< >

( 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

< >

( 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 -float("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, if min_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 cutoff eta.

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:

>>> # Import required libraries
>>> from transformers import AutoModelForCausalLM, AutoTokenizer, set_seed

>>> # Set the model name
>>> model_name = "gpt2"

>>> # Initialize the model and tokenizer
>>> model = AutoModelForCausalLM.from_pretrained(model_name)
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)

>>> # Set the pad token to eos token
>>> model.config.pad_token_id = model.config.eos_token_id
>>> model.generation_config.pad_token_id = model.config.eos_token_id

>>> # The below sequence intentionally contains two subjects to show the difference between the two approaches
>>> sequence = "a quadcopter flight controller (RTFQ Flip MWC) that supports I2C sensors for adding things like a barometer, magnetometer, and GPS system. The officially supported sensor block (BMP180, HMC5883L on one board) is discontinued, as far as I know, everyone involved lived to sing another day. . . disorder and an extreme state of dysmetabolism characterized by extensive erythema and a significant reduction in uncovered"

>>> # Tokenize the sequence
>>> inputs = tokenizer(sequence, return_tensors="pt")

>>> set_seed(0)

>>> # We can see that the model is generating repeating text and also is not able to continue the sequence properly
>>> outputs = model.generate(inputs["input_ids"], max_length=128)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
a quadcopter flight controller (RTFQ Flip MWC) that supports I2C sensors for adding things like a barometer, magnetometer, and GPS system. The officially supported sensor block (BMP180, HMC5883L on one board) is discontinued, as far as I know, everyone involved lived to sing another day... disorder and an extreme state of dysmetabolism characterized by extensive erythema and a significant reduction in uncovered muscle mass. The patient was diagnosed with a severe erythema and a severe erythema-like condition. The patient was treated with a combination

>>> # The result is much better and coherent when we use the `eta_cutoff` parameter
>>> outputs = model.generate(
...     inputs["input_ids"], max_length=128, do_sample=True, eta_cutoff=2e-2
... )  # need to set do_sample=True for eta_cutoff to work
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
a quadcopter flight controller (RTFQ Flip MWC) that supports I2C sensors for adding things like a barometer, magnetometer, and GPS system. The officially supported sensor block (BMP180, HMC5883L on one board) is discontinued, as far as I know, everyone involved lived to sing another day... disorder and an extreme state of dysmetabolism characterized by extensive erythema and a significant reduction in uncovered fatty acids. A significant loss of brain development. The individual also experienced high levels of a common psychiatric condition called schizophrenia, with an important and life threatening consequence.

__call__

< >

( 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

< >

( exponential_decay_length_penalty: typing.Tuple[int, float] eos_token_id: typing.Union[int, typing.List[int]] input_ids_seq_length: int )

Parameters

  • exponential_decay_length_penalty (tuple(int, float)) — This tuple shall consist of: (start_index, decay_factor) where start_index indicates where penalty starts and decay_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 regulation_start has been reached.

__call__

< >

( 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

< >

( bos_token_id: int )

Parameters

  • bos_token_id (int) — The id of the token to force as the first generated token.

LogitsProcessor that enforces the specified token as the first generated token.

__call__

< >

( 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

< >

( max_length: int eos_token_id: typing.Union[int, typing.List[int]] )

Parameters

  • max_length (int) — The maximum length of the sequence to be generated.
  • eos_token_id (Union[int, List[int]]) — The id of the token to force as the last generated token when max_length is reached. Optionally, use a list to set multiple end-of-sequence tokens.

LogitsProcessor that enforces the specified token as the last generated token when max_length is reached.

__call__

< >

( 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.ForceTokensLogitsProcessor

< >

( force_token_map: typing.List[typing.List[int]] )

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 inf so that they are sampled at their corresponding index.

__call__

< >

( 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

< >

( 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. Note that diversity_penalty is only effective if group beam search is enabled.
  • num_beams (int) — Number of beams used for group beam search. See this paper for more details.
  • num_beam_groups (int) — Number of groups to divide num_beams into in order to ensure diversity among different groups of beams. See 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.

__call__

< >

( 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.

class transformers.InfNanRemoveLogitsProcessor

< >

( )

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.

__call__

< >

( 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.LogitNormalization

< >

( )

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.

__call__

< >

( 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.LogitsProcessor

< >

( )

Abstract base class for all logit processors that can be applied during generation.

__call__

< >

( 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.LogitsProcessorList

< >

( iterable = () )

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__

< >

( 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.

class transformers.LogitsWarper

< >

( )

Abstract base class for all logit warpers that can be applied during generation with multinomial sampling.

__call__

< >

( 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

< >

( min_length: int eos_token_id: typing.Union[int, typing.List[int]] )

Parameters

  • min_length (int) — The minimum length below which the score of eos_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 by setting EOS probability to 0.

__call__

< >

( 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

< >

( prompt_length_to_skip: int min_new_tokens: int eos_token_id: typing.Union[int, typing.List[int]] )

Parameters

  • prompt_length_to_skip (int) — The input tokens length. Not a valid argument when used with generate as it will automatically assign the input length.
  • min_new_tokens (int) — The minimum new tokens length below which the score of eos_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. Note that for decoder-only models, such as Llama2, min_length will compute the length of prompt + newly generated tokens whereas for other models it will behave as min_new_tokens, that is, taking only into account the newly generated ones.

Examples:

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> model.config.pad_token_id = model.config.eos_token_id
>>> model.generation_config.pad_token_id = model.config.eos_token_id
>>> input_context = "Hugging Face Company is"
>>> input_ids = tokenizer.encode(input_context, return_tensors="pt")

>>> # Without `eos_token_id`, it will generate the default length, 20, ignoring `min_new_tokens`
>>> outputs = model.generate(input_ids=input_ids, min_new_tokens=30)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is a company that has been working on a new product for the past year.

>>> # If `eos_token_id` is set to ` company` it will take into account how many `min_new_tokens` have been generated
>>> # before stopping. Note that ` Company` (5834) and ` company` (1664) are not actually the same token, and even
>>> # if they were ` Company` would be ignored by `min_new_tokens` as it excludes the prompt.
>>> outputs = model.generate(input_ids=input_ids, min_new_tokens=1, eos_token_id=1664)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is a company

>>> # Increasing `min_new_tokens` will bury the first occurrence of ` company` generating a different sequence.
>>> outputs = model.generate(input_ids=input_ids, min_new_tokens=2, eos_token_id=1664)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is a new company

>>> # If no more occurrences of the `eos_token` happen after `min_new_tokens` it returns to the 20 default tokens.
>>> outputs = model.generate(input_ids=input_ids, min_new_tokens=10, eos_token_id=1664)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is a new and innovative brand of facial recognition technology that is designed to help you

__call__

< >

( 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

< >

( bad_words_ids: typing.List[typing.List[int]] eos_token_id: typing.Union[int, typing.List[int]] )

Parameters

  • bad_words_ids (List[List[int]]) — List of list of token ids that are not allowed to be generated.
  • 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 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")

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

>>> # Now let's control generation taking 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.split(" "):
...         tokenized_word = tokenizer_with_prefix_space([word], add_special_tokens=False).input_ids[0]
...         tokens_list.append(tokenized_word)
...     return tokens_list


>>> word_list = "mess"
>>> bad_words_ids = get_tokens_as_list(word_list=word_list)

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

>>> badwords_ids = model.generate(inputs["input_ids"], max_new_tokens=4, num_beams=5, bad_words_ids=bad_words_ids)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
In a word, the cake is a great way to start

__call__

< >

( 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

< >

( ngram_size: int )

Parameters

  • ngram_size (int) — All ngrams of size ngram_size can only occur once.

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. 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 GPT2Tokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
>>> inputs = tokenizer(["I enjoy watching football"], return_tensors="pt")

>>> output = model.generate(**inputs, max_length=50)
>>> print(tokenizer.decode(output[0], skip_special_tokens=True))
"I enjoy playing football on the weekends, but I'm not a big fan of the idea of playing in the middle of the night. I'm not a big fan of the idea of playing in the middle of the night. I'm not a big"

>>> # Now let's add ngram size using <no_repeat_ngram_size> in model.generate. This should stop the repetitions in the output.
>>> output = model.generate(**inputs, max_length=50, no_repeat_ngram_size=2)
>>> print(tokenizer.decode(output[0], skip_special_tokens=True))
I enjoy playing football on the weekends, but I'm not a big fan of the idea of playing in the middle of a game. I think it's a bit of an overreaction to the fact that we're playing a team that's playing"

__call__

< >

( 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

< >

( prefix_allowed_tokens_fn: typing.Callable[[int, torch.Tensor], typing.List[int]] 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 arguments inputs_ids and the batch ID batch_id. It has to return a list with the allowed tokens for the next generation step conditioned on the previously generated tokens inputs_ids and the batch ID batch_id.

LogitsProcessor that enforces constrained generation and is useful for prefix-conditioned constrained generation. See Autoregressive Entity Retrieval for more information.

__call__

< >

( 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

< >

( penalty: float )

Parameters

  • repetition_penalty (float) — The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details.

LogitsProcessor that prevents the repetition of previous tokens through an exponential penalty. This technique shares some similarities with coverage mechanisms and other aimed at reducing repetition. During the text generation process, the probability distribution for the next token is determined using a formula that incorporates token scores based on their occurrence in the generated sequence. Tokens with higher scores are less likely to be selected. The formula can be seen in the original paper. According to the paper a penalty of around 1.2 yields a good balance between truthful generation and lack of repetition.

Examples:

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

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

>>> # This shows a normal generate without any specific parameters
>>> summary_ids = model.generate(inputs["input_ids"], max_length=20)
>>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0])
I'm not going to lie, I'm not going to lie. I'm not going to lie

>>> # This generates a penalty for repeated tokens
>>> penalized_ids = model.generate(inputs["input_ids"], max_length=20, repetition_penalty=1.2)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
I'm not going to lie, I was really excited about this. It's a great game

__call__

< >

( 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

< >

( sequence_bias: typing.Dict[typing.Tuple[int], float] )

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__

< >

( 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

< >

( 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 at not sampled at the begining of the generation.

__call__

< >

( 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.SuppressTokensLogitsProcessor

< >

( suppress_tokens )

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.

__call__

< >

( 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

< >

( temperature: float )

Parameters

  • temperature (float) — Strictly positive float value used to modulate the logits distribution. A value smaller than 1 decreases randomness (and vice versa), with 0 being equivalent to shifting all probability mass to the most likely token.

LogitsWarper for temperature (exponential scaling output probability distribution), which effectively means that it can control the randomness of the predicted tokens.

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

>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> model.config.pad_token_id = model.config.eos_token_id
>>> model.generation_config.pad_token_id = model.config.eos_token_id
>>> input_context = "Hugging Face Company is"
>>> input_ids = tokenizer.encode(input_context, return_tensors="pt")

>>> torch.manual_seed(0)

>>> # With temperature=1, the default, we consistently get random outputs due to random sampling.
>>> outputs = model.generate(input_ids=input_ids, max_new_tokens=10, temperature=1, do_sample=True)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is one of these companies that is going to take a

>>> outputs = model.generate(input_ids=input_ids, max_new_tokens=10, temperature=1, do_sample=True)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is one of these companies, you can make a very

>>> # However, with temperature close to 0 , the output remains invariant.
>>> outputs = model.generate(input_ids=input_ids, max_new_tokens=10, temperature=0.0001, do_sample=True)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is a company that has been around for over 20 years

>>> # even if we set a different seed.
>>> torch.manual_seed(42)
>>> outputs = model.generate(input_ids=input_ids, max_new_tokens=10, temperature=0.0001, do_sample=True)
>>> print(tokenizer.decode(outputs[0], skip_special_tokens=True))
Hugging Face Company is a company that has been around for over 20 years

__call__

< >

( 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

< >

( 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 -float("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.

__call__

< >

( 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

< >

( 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 to top_p or higher are kept for generation.
  • filter_value (float, optional, defaults to -float("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.

Examples:

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

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

>>> text = "It is probably one of the most important things for parents to teach children about patience and acceptance. In this way, we as a society can ensure"
>>> inputs = tokenizer(text, return_tensors="pt")

>>> # Generate sequences without top_p sampling
>>> # We see that the answer tends to have a lot of repeated tokens and phrases
>>> outputs = model.generate(**inputs, max_length=55)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
'It is probably one of the most important things for parents to teach children about patience and acceptance. In this way, we as a society can ensure that our children are not taught to be impatient or to be afraid of the future.

first step is to teach them'

>>> # Generate sequences with top_p sampling: set `do_sample=True` to use top_p sampling with `top_p` arugment
>>> # We already see that the answer has less repetitive tokens and is more diverse
>>> outputs = model.generate(**inputs, max_length=55, do_sample=True, top_p=0.25)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
'It is probably one of the most important things for parents to teach children about patience and acceptance. In this way, we as a society can ensure that children learn to be more accepting of others and to be more tolerant of others.

an also teach children to be'

>>> # Generate sequences with top_p sampling with a larger top_p value
>>> # We see that as we increase the top_p value, less probable tokens also get selected during text generation, making the answer more diverse
>>> # Pro Tip: In practice, we tend to use top_p values between 0.9 and 1.0!
>>> outputs = model.generate(**inputs, max_length=55, do_sample=True, top_p=0.95)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
'It is probably one of the most important things for parents to teach children about patience and acceptance. In this way, we as a society can ensure we have the best learning environment, so that we can teach to learn and not just take advantage of the environment.

__call__

< >

( 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

< >

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

Parameters

  • mass (float) — Value of typical_p between 0 and 1 inclusive, defaults to 0.9.
  • filter_value (float, optional, defaults to -float("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. See Typical Decoding for Natural Language Generation for more information.

__call__

< >

( 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

< >

( guidance_scale: float model unconditional_ids: typing.Optional[torch.LongTensor] = None unconditional_attention_mask: typing.Optional[torch.LongTensor] = None use_cache: typing.Optional[bool] = True )

Parameters

  • guidance_scale (float) — The guidance scale for classifier free guidance (CFG). CFG is enabled by setting guidance_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.
  • 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.
  • 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.
  • smooth_factor (float, optional) — The interpolation weight for CFG Rescale. 1 means no rescaling, 0 reduces to the conditional scores without CFG. Turn it lower if the output degenerates.
  • use_cache (bool, optional) — 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]
The dragon flew over Paris, France, landing in Lyon, a city of a few million. Dragon-flying was a new form of
transport, and the dragon was the first in Europe.

>>> # 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]
The dragon flew over Paris, France, crashing into Notre Dame Cathedral in the French capital killing at least 127
people and injuring more than 350.

>>> # 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.

__call__

< >

( input_ids scores )

class transformers.WhisperTimeStampLogitsProcessor

< >

( generate_config )

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.

__call__

< >

( 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

< >

( bos_token_id: int )

Parameters

  • bos_token_id (int) — The id of the token to force as the first generated token.

TFLogitsProcessor that enforces the specified token as the first generated token.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFForcedEOSTokenLogitsProcessor

< >

( max_length: int eos_token_id: int )

Parameters

  • max_length (int) — The maximum length of the sequence to be generated.
  • eos_token_id (int) — The id of the token to force as the last generated token when max_length is reached.

TFLogitsProcessor that enforces the specified token as the last generated token when max_length is reached.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFForceTokensLogitsProcessor

< >

( force_token_map: typing.List[typing.List[int]] )

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.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFLogitsProcessor

< >

( )

Abstract base class for all logit processors that can be applied during generation.

__call__

< >

( 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.

    What are input IDs?

  • 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.

class transformers.TFLogitsProcessorList

< >

( iterable = () )

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__

< >

( 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.

    What are input IDs?

  • 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.

class transformers.TFLogitsWarper

< >

( )

Abstract base class for all logit warpers that can be applied during generation with multinomial sampling.

__call__

< >

( 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.

    What are input IDs?

  • 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

< >

( min_length: int eos_token_id: int )

Parameters

  • min_length (int) — The minimum length below which the score of eos_token_id is set to -float("Inf").
  • eos_token_id (int) — The id of the end-of-sequence token.

TFLogitsProcessor enforcing a min-length by setting EOS probability to 0.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFNoBadWordsLogitsProcessor

< >

( bad_words_ids: typing.List[typing.List[int]] 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 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.
  • eos_token_id (int) — The id of the end-of-sequence token.

TFLogitsProcessor that enforces that specified sequences will never be sampled.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFNoRepeatNGramLogitsProcessor

< >

( ngram_size: int )

Parameters

  • ngram_size (int) — All ngrams of size ngram_size can only occur once.

TFLogitsProcessor that enforces no repetition of n-grams. See Fairseq.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFRepetitionPenaltyLogitsProcessor

< >

( 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.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFSuppressTokensAtBeginLogitsProcessor

< >

( 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.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFSuppressTokensLogitsProcessor

< >

( suppress_tokens )

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.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFTemperatureLogitsWarper

< >

( temperature: float )

Parameters

  • temperature (float) — The value used to module the logits distribution.

TFLogitsWarper for temperature (exponential scaling output probability distribution).

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFTopKLogitsWarper

< >

( 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 -float("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.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFTopPLogitsWarper

< >

( 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 to top_p or higher are kept for generation.
  • filter_value (float, optional, defaults to -float("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.

__call__

< >

( input_ids: Tensor scores: Tensor cur_len: int )

FLAX

class transformers.FlaxForcedBOSTokenLogitsProcessor

< >

( bos_token_id: int )

Parameters

  • bos_token_id (int) — The id of the token to force as the first generated token.

FlaxLogitsProcessor that enforces the specified token as the first generated token.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxForcedEOSTokenLogitsProcessor

< >

( max_length: int eos_token_id: int )

Parameters

  • max_length (int) — The maximum length of the sequence to be generated.
  • eos_token_id (int) — The id of the token to force as the last generated token when max_length is reached.

FlaxLogitsProcessor that enforces the specified token as the last generated token when max_length is reached.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxForceTokensLogitsProcessor

< >

( force_token_map )

Parameters

  • force_token_map (list) — Map giving token ids and indices where they will be forced to be sampled.

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.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxLogitsProcessor

< >

( )

Abstract base class for all logit processors that can be applied during generation.

__call__

< >

( 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.

    What are input IDs?

  • 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.

class transformers.FlaxLogitsProcessorList

< >

( iterable = () )

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__

< >

( 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.

    What are input IDs?

  • 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.

class transformers.FlaxLogitsWarper

< >

( )

Abstract base class for all logit warpers that can be applied during generation with multinomial sampling.

__call__

< >

( 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.

    What are input IDs?

  • 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

< >

( min_length: int eos_token_id: int )

Parameters

  • min_length (int) — The minimum length below which the score of eos_token_id is set to -float("Inf").
  • eos_token_id (int) — The id of the end-of-sequence token.

FlaxLogitsProcessor enforcing a min-length by setting EOS probability to 0.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxSuppressTokensAtBeginLogitsProcessor

< >

( begin_suppress_tokens begin_index )

Parameters

  • begin_suppress_tokens (List[int]) — Tokens to not sample.
  • begin_index (int) — Index where the tokens are suppressed.

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.

__call__

< >

( input_ids scores cur_len: int )

class transformers.FlaxSuppressTokensLogitsProcessor

< >

( suppress_tokens: list )

Parameters

  • suppress_tokens (list) — Tokens to not sample.

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.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxTemperatureLogitsWarper

< >

( temperature: float )

Parameters

  • temperature (float) — The value used to module the logits distribution.

FlaxLogitsWarper for temperature (exponential scaling output probability distribution).

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxTopKLogitsWarper

< >

( 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 -float("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.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxTopPLogitsWarper

< >

( 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 to top_p or higher are kept for generation.
  • filter_value (float, optional, defaults to -float("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.

__call__

< >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxWhisperTimeStampLogitsProcessor

< >

( 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.

__call__

< >

( input_ids scores cur_len )

StoppingCriteria

A StoppingCriteria can be used to change when to stop generation (other than EOS token). Please note that this is exclusivelly available to our PyTorch implementations.

class transformers.StoppingCriteria

< >

( )

Abstract base class for all stopping criteria that can be applied during generation.

__call__

< >

( 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.

    What are input IDs?

  • 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.
  • kwargs (Dict[str, Any], optional) — Additional stopping criteria specific kwargs.

class transformers.StoppingCriteriaList

< >

( iterable = () )

__call__

< >

( 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.

    What are input IDs?

  • 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.
  • kwargs (Dict[str, Any], optional) — Additional stopping criteria specific kwargs.

class transformers.MaxLengthCriteria

< >

( max_length: int max_position_embeddings: typing.Optional[int] = None )

Parameters

  • max_length (int) — The maximum length that the output sequence can have in number of tokens.
  • max_position_embeddings (int, optional) — The maximum model length, as defined by the model’s config.max_position_embeddings attribute.

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__

< >

( 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.

    What are input IDs?

  • 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.
  • kwargs (Dict[str, Any], optional) — Additional stopping criteria specific kwargs.

class transformers.MaxTimeCriteria

< >

( max_time: float initial_timestamp: typing.Optional[float] = None )

Parameters

  • max_time (float) — The maximum allowed time in seconds for the generation.
  • initial_time (float, optional, defaults to time.time()) — The start of the generation allowed time.

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__

< >

( 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.

    What are input IDs?

  • 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.
  • kwargs (Dict[str, Any], optional) — Additional stopping criteria specific kwargs.

Constraints

A Constraint can be used to force the generation to include specific tokens or sequences in the output. Please note that this is exclusivelly available to our PyTorch implementations.

class transformers.Constraint

< >

( )

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

completed = False
while not completed:
    _, completed = constraint.update(constraint.advance())

will always terminate (halt).

advance

< >

( ) → 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

< >

( stateful = False ) → constraint(Constraint)

Returns

constraint(Constraint)

The same constraint as the one being called from.

Creates a new instance of this constraint.

does_advance

< >

( token_id: int )

Reads in a token and returns whether it creates progress.

remaining

< >

( )

Returns the number of remaining steps of advance() in order to complete this constraint.

reset

< >

( )

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.

test

< >

( )

Tests whether this constraint has been properly defined.

update

< >

( 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

< >

( token_ids: typing.List[int] )

Parameters

  • token_ids (List[int]) — The id of the token that must be generated by the output.

Constraint enforcing that an ordered sequence of tokens is included in the output.

class transformers.DisjunctiveConstraint

< >

( nested_token_ids: typing.List[typing.List[int]] )

Parameters

  • nested_token_ids (List[List[int]]) — a list of words, where each word is a list of ids. This constraint
  • is fulfilled by generating just one from the list of words. —

A special Constraint that is fulfilled by fulfilling just one of several constraints.

class transformers.ConstraintListState

< >

( constraints: typing.List[transformers.generation.beam_constraints.Constraint] )

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.

advance

< >

( )

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.

reset

< >

( token_ids: typing.Optional[typing.List[int]] )

token_ids: the tokens generated thus far to reset the state of the progress through constraints.

BeamSearch

class transformers.BeamScorer

< >

( )

Abstract base class for all beam scorers that are used for beam_search() and beam_sample().

process

< >

( 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.

    What are input IDs?

  • next_scores (torch.FloatTensor of shape (batch_size, 2 * num_beams)) — Current scores of the top 2 * 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 top 2 * num_beams non-finished beam hypotheses.
  • next_indices (torch.LongTensor of shape (batch_size, 2 * num_beams)) — Beam indices indicating to which beam hypothesis the next_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

< >

( 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.

    What are input IDs?

  • 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 the final_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

< >

( batch_size: int num_beams: int device: device length_penalty: typing.Optional[float] = 1.0 do_early_stopping: typing.Union[str, bool, NoneType] = False num_beam_hyps_to_keep: typing.Optional[int] = 1 num_beam_groups: typing.Optional[int] = 1 max_length: typing.Optional[int] = None )

Parameters

  • batch_size (int) — Batch Size of input_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 of BeamSearchScorer 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, while length_penalty < 0.0 encourages shorter sequences.
  • do_early_stopping (bool or str, optional, defaults to False) — 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 are num_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 ~transformer.BeamSearchScorer.finalize.
  • num_beam_groups (int) — Number of groups to divide num_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

< >

( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor pad_token_id: typing.Optional[int] = None eos_token_id: typing.Union[int, typing.List[int], NoneType] = None beam_indices: typing.Optional[torch.LongTensor] = None group_index: typing.Optional[int] = 0 )

finalize

< >

( input_ids: LongTensor final_beam_scores: FloatTensor final_beam_tokens: LongTensor final_beam_indices: LongTensor max_length: int pad_token_id: typing.Optional[int] = None eos_token_id: typing.Union[int, typing.List[int], NoneType] = None beam_indices: typing.Optional[torch.LongTensor] = None )

class transformers.ConstrainedBeamSearchScorer

< >

( batch_size: int num_beams: int constraints: typing.List[transformers.generation.beam_constraints.Constraint] device: device length_penalty: typing.Optional[float] = 1.0 do_early_stopping: typing.Union[str, bool, NoneType] = False num_beam_hyps_to_keep: typing.Optional[int] = 1 num_beam_groups: typing.Optional[int] = 1 max_length: typing.Optional[int] = None )

Parameters

  • batch_size (int) — Batch Size of input_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 as Constraint 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 of BeamSearchScorer 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, while length_penalty < 0.0 encourages shorter sequences.
  • do_early_stopping (bool or str, optional, defaults to False) — 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 are num_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 ~transformer.BeamSearchScorer.finalize.
  • num_beam_groups (int) — Number of groups to divide num_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

< >

( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor scores_for_all_vocab: FloatTensor pad_token_id: typing.Optional[int] = None eos_token_id: typing.Union[int, typing.List[int], NoneType] = None beam_indices: typing.Optional[torch.LongTensor] = None ) → 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.

    What are input IDs?

  • next_scores (torch.FloatTensor of shape (batch_size, 2 * num_beams)) — Current scores of the top 2 * 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 top 2 * num_beams non-finished beam hypotheses.
  • next_indices (torch.LongTensor of shape (batch_size, 2 * num_beams)) — Beam indices indicating to which beam hypothesis the next_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.

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

< >

( input_ids: LongTensor final_beam_scores: FloatTensor final_beam_tokens: LongTensor final_beam_indices: LongTensor max_length: int pad_token_id: typing.Optional[int] = None eos_token_id: typing.Union[int, typing.List[int], NoneType] = None beam_indices: typing.Optional[torch.LongTensor] = None )

Utilities

transformers.top_k_top_p_filtering

< >

( 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

< >

( 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

< >

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

Parameters

  • tokenizer (AutoTokenizer) — The tokenized used to decode the tokens.
  • skip_prompt (bool, optional, defaults to False) — Whether to skip the prompt to .generate() or not. Useful e.g. for chatbots.
  • decode_kwargs (dict, optional) — Additional keyword arguments to pass to the tokenizer’s decode method.

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,

end

< >

( )

Flushes any remaining cache and prints a newline to stdout.

on_finalized_text

< >

( text: str stream_end: bool = False )

Prints the new text to stdout. If the stream is ending, also prints a newline.

put

< >

( value )

Receives tokens, decodes them, and prints them to stdout as soon as they form entire words.

class transformers.TextIteratorStreamer

< >

( tokenizer: AutoTokenizer skip_prompt: bool = False timeout: typing.Optional[float] = None **decode_kwargs )

Parameters

  • tokenizer (AutoTokenizer) — The tokenized used to decode the tokens.
  • skip_prompt (bool, optional, defaults to False) — Whether to skip the prompt to .generate() or not. Useful e.g. for chatbots.
  • timeout (float, optional) — The timeout for the text queue. If None, 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’s decode 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,'

on_finalized_text

< >

( text: str stream_end: bool = False )

Put the new text in the queue. If the stream is ending, also put a stop signal in the queue.

←Utilities for Trainer Utilities for Image Processors→