o  h( @sddlZddlZddlmZmZmZmZmZmZddl Z ddl Z ddl m Z ddlmZddlmZeeZdZGdd d ZGd d d eZGd d d eZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZ GdddeZ!Gd d!d!eZ"d"e#d#e j$d$e#fd%d&Z%d'd(Z&d"e#d#e j$d$e#d)e#d*eee#f d+d,Z'Gd-d.d.eZ(Gd/d0d0eZ)Gd1d2d2eZ*Gd3d4d4e*Z+Gd5d6d6eZ,Gd7d8d8eZ-Gd9d:d:eZ.Gd;d<dd>eZ0Gd?d@d@eZ1GdAdBdBeZ2GdCdDdDeZ3GdEdFdFeZ4GdGdHdHeZ5GdIdJdJeZ6GdKdLdLeZ7GdMdNdNeZ8GdOdPdPeZ9GdQdRdReZ:GdSdTdTeZ;GdUdVdVZtfddt|ddDs4tdt|d|j d|||fi}q|||}q|S)a Args: input_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`): Indices of input sequence tokens in the vocabulary. [What are input IDs?](../glossary#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. Return: `torch.FloatTensor` of shape `(batch_size, config.vocab_size)`: The processed prediction scores. rc3s|]}|vVqdSNr).0argkwargsrr Qsz/LogitsProcessorList.__call__..Nz,Make sure that all the required parameters: z for z$ are passed to the logits processor.) inspect signaturer parameterslenalllistkeys ValueErrorr)rrrr% processor function_argsrr$rr>s & zLogitsProcessorList.__call__N)rrrrrrrrrrrrr 7s r c@\eZdZdZddedeeeeejfde fddZ e e dej d ejd ejfd d Zd S)MinLengthLogitsProcessora3 [`LogitsProcessor`] enforcing a min-length by setting EOS probability to 0. Note that, for decoder-only models like most LLMs, the length includes the prompt. Args: 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], torch.Tensor]`): The id(s) of the *end-of-sequence* token. device (`str`, *optional*, defaults to `"cpu"`): The device to allocate the tensors. Examples: ```python >>> from transformers import AutoModelForCausalLM, AutoTokenizer >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m") >>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m") >>> inputs = tokenizer("A number:", return_tensors="pt") >>> gen_out = model.generate(**inputs) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) A number: one >>> # setting `min_length` to a value smaller than the uncontrolled output length has no impact >>> gen_out = model.generate(**inputs, min_length=3) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) A number: one >>> # setting a larger `min_length` will force the model to generate beyond its natural ending point, which is not >>> # necessarily incorrect >>> gen_out = model.generate(**inputs, min_length=10) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) A number: one thousand, nine hundred and ninety-four ``` cpu min_length eos_token_iddevicecCsZt|tr |dkrtd|t|tjs%t|tr|g}tj||d}||_||_dS)Nrz6`min_length` has to be a non-negative integer, but is r6) isinstanceintr.rTensortensorr4r5)rr4r5r6rrr__init__s   z!MinLengthLogitsProcessor.__init__rrrcCsPtj|jd|jd}t||j}|}|jd|jkr&t|t j |}|SNr7) rarangeshaper6r r5cloner4wheremathinf)rrr vocab_tensoreos_token_maskscores_processedrrrrs  z!MinLengthLogitsProcessor.__call__Nr3rrrrr9rrrr:strr<r rrrrrrrrr2]s (& "r2c @sbeZdZdZ ddededeeeeejfde fddZ e e d ej d ejd ejfd d ZdS)!MinNewTokensLengthLogitsProcessora [`LogitsProcessor`] enforcing a min-length of new tokens by setting EOS (End-Of-Sequence) token probability to 0. Contrarily to [`MinLengthLogitsProcessor`], this processor ignores the prompt. Args: 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], torch.Tensor]`): The id(s) of the *end-of-sequence* token. device (`str`, *optional*, defaults to `"cpu"`): The device to allocate the tensors. Examples: ```python >>> from transformers import AutoModelForCausalLM, AutoTokenizer >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m") >>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m") >>> inputs = tokenizer(["A number:"], return_tensors="pt") >>> gen_out = model.generate(**inputs) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) A number: one >>> # setting `min_new_tokens` will force the model to generate beyond its natural ending point, which is not >>> # necessarily incorrect >>> gen_out = model.generate(**inputs, min_new_tokens=2) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) A number: one thousand ``` r3prompt_length_to_skipmin_new_tokensr5r6cCsd|fd|ffD]\}}t|tr|dkrtd|d|qt|tjs5t|tr.|g}tj||d}||_||_||_dS)NrLrMr`z'` has to be a positive integer, but is r7) r8r9r.rr:r;rLrMr5)rrLrMr5r6arg_name arg_valuerrrr<s    z*MinNewTokensLengthLogitsProcessor.__init__rrrcCsZ|jd|j}|}tj|jd|jd}t||j}||jkr+t |t j |}|Sr=) r@rLrArr?r6r r5rMrBrCrD)rrrnew_tokens_lengthrGrErFrrrrs  z*MinNewTokensLengthLogitsProcessor.__call__NrHrIrrrrrKs) "rKc@BeZdZdZdefddZeedej dej dej fdd Z d S) TemperatureLogitsWarperaa [`LogitsProcessor`] for temperature (exponential scaling output probability distribution), which effectively means that it can control the randomness of the predicted tokens. Often used together with [`TopPLogitsWarper`] and [`TopKLogitsWarper`]. Make sure that `do_sample=True` is included in the `generate` arguments otherwise the temperature value won't have any effect. Args: 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. Examples: ```python >>> import torch >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> set_seed(0) # for reproducibility >>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2") >>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2") >>> model.config.pad_token_id = model.config.eos_token_id >>> inputs = tokenizer(["Hugging Face Company is"], return_tensors="pt") >>> # With temperature=1.0, the default, we consistently get random outputs due to random sampling. >>> generate_kwargs = {"max_new_tokens": 10, "do_sample": True, "temperature": 1.0, "num_return_sequences": 2} >>> outputs = model.generate(**inputs, **generate_kwargs) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)) ['Hugging Face Company is one of these companies that is going to take a', "Hugging Face Company is a brand created by Brian A. O'Neil"] >>> # However, with temperature close to 0, it approximates greedy decoding strategies (invariant) >>> generate_kwargs["temperature"] = 0.0001 >>> outputs = model.generate(**inputs, **generate_kwargs) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)) ['Hugging Face Company is a company that has been around for over 20 years', 'Hugging Face Company is a company that has been around for over 20 years'] ``` temperaturecCsJt|tr |dks d|d}t|tr|dkr|d7}t|||_dS)Nrz`temperature` (=zX) has to be a strictly positive float, otherwise your next token scores will be invalid.zI If you're looking for greedy decoding strategies, set `do_sample=False`.)r8floatr.rT)rrT except_msgrrrr<s  z TemperatureLogitsWarper.__init__rrrcCs||j}|Sr!)rTrrrrGrrrrs z TemperatureLogitsWarper.__call__N rrrrrVr<r rrrrrrrrrrSs / "rSc@rR) RepetitionPenaltyLogitsProcessora? [`LogitsProcessor`] that prevents the repetition of previous tokens through a penalty. This penalty is applied at most once per token. Note that, for decoder-only models like most LLMs, the considered tokens include the prompt. In the original [paper](https://arxiv.org/pdf/1909.05858.pdf), the authors suggest the use of a penalty of around 1.2 to achieve a good balance between truthful generation and lack of repetition. To penalize and reduce repetition, use `penalty` values above 1.0, where a higher value penalizes more strongly. To reward and encourage repetition, use `penalty` values between 0.0 and 1.0, where a lower value rewards more strongly. Args: penalty (`float`): The parameter for repetition penalty. 1.0 means no penalty. Above 1.0 penalizes previously generated tokens. Between 0.0 and 1.0 rewards previously generated tokens. Examples: ```py >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> # Initializing the model and tokenizer for it >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer(["I'm not going to"], return_tensors="pt") >>> # This shows a normal generate without any specific parameters >>> summary_ids = model.generate(**inputs) >>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0]) I'm not going to be able to do that. I'm going to be able to do that >>> # This generates a penalty for repeated tokens >>> penalized_ids = model.generate(**inputs, repetition_penalty=1.1) >>> print(tokenizer.batch_decode(penalized_ids, skip_special_tokens=True)[0]) I'm not going to be able to do that. I'll just have to go out and play ``` penaltycCs*t|tr |dkstd|||_dS)Nr6`penalty` has to be a strictly positive float, but is )r8rVr.r[)rr[rrrr<Is z)RepetitionPenaltyLogitsProcessor.__init__rrrcCs>t|d|}t|dk||j||j}|d||}|SNr)rgatherrBr[scatterrrrscorerGrrrrOsz)RepetitionPenaltyLogitsProcessor.__call__NrYrrrrrZ$s $"rZc@HeZdZdZdedejfddZee dejdej dej fd d Z d S) 'EncoderRepetitionPenaltyLogitsProcessora [`LogitsProcessor`] that works similarly to [`RepetitionPenaltyLogitsProcessor`], but with an *inverse* penalty that is applied to the tokens present in the prompt. In other words, a penalty above 1.0 increases the odds of selecting tokens that were present in the prompt. It was designed to avoid hallucination in input-grounded tasks, like summarization. Although originally intended for encoder-decoder models, it can also be used with decoder-only models like LLMs. Args: penalty (`float`): The parameter for repetition penalty. 1.0 means no penalty. Above 1.0 rewards prompt tokens. Between 0.0 and 1.0 penalizes prompt tokens. encoder_input_ids (`torch.LongTensor`): The encoder_input_ids that should be repeated within the decoder ids. Examples: ```python >>> from transformers import AutoModelForCausalLM, AutoTokenizer >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m") >>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m") >>> inputs = tokenizer(["Alice and Bob. The third member's name was"], return_tensors="pt") >>> gen_out = model.generate(**inputs) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) Alice and Bob. The third member's name was not mentioned. >>> # With the `encoder_repetition_penalty` argument we can trigger this logits processor in `generate`, which can >>> # promote the use of prompt tokens ("Bob" in this example) >>> gen_out = model.generate(**inputs, encoder_repetition_penalty=1.2) >>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0]) Alice and Bob. The third member's name was Bob. The third member's name was Bob. ``` r[encoder_input_idscCs4t|tr |dkstd|d||_||_dS)Nrr\r^)r8rVr.r[re)rr[rerrrr<s  z0EncoderRepetitionPenaltyLogitsProcessor.__init__rrrcCsBt|d|j}t|dk||j||j}|d|j|}|Sr])rr_rerBr[r`rarrrrsz0EncoderRepetitionPenaltyLogitsProcessor.__call__N) rrrrrVrrr<r rrrrrrrrdZs $"rdc@VeZdZdZed dfdededefddZeed e j d e j d e j fd d Z dS)TopPLogitsWarpera [`LogitsProcessor`] that performs top-p, i.e. restricting to top tokens summing to prob_cut_off <= prob_cut_off. Often used together with [`TemperatureLogitsWarper`] and [`TopKLogitsWarper`]. Args: 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 -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. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> set_seed(1) >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt") >>> # With sampling, the output is unexpected -- sometimes too unexpected. >>> outputs = model.generate(**inputs, do_sample=True) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3 | < 4 (left-hand pointer) ; >>> # With `top_p` sampling, the output gets restricted to high-probability tokens. >>> # Pro tip: In practice, LLMs use `top_p` in the 0.9-0.95 range. >>> outputs = model.generate(**inputs, do_sample=True, top_p=0.1) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9 ``` Infr^top_p filter_valuemin_tokens_to_keepcCs\t|}|dks |dkrtd|t|tr|dkr#td|||_||_||_dS)Nr?z.`top_p` has to be a float > 0 and < 1, but is r^:`min_tokens_to_keep` has to be a positive integer, but is )rVr.r8r9rirjrk)rrirjrkrrrr< zTopPLogitsWarper.__init__rrrc Cshtj|dd\}}|jddjdd}|d|jk}d|d|j df<|d||}|||j}|S)NF descendingr>dimr^r.) rsortsoftmaxcumsumrirkr` masked_fillrj) rrr sorted_logitssorted_indicescumulative_probssorted_indices_to_removeindices_to_removerGrrrrszTopPLogitsWarper.__call__N rrrrrVr9r<r rrrrrrrrrrgs "' "rgc@sVeZdZdZed dfdededefddZeed e j d e j d e j fd d Z dS)TopKLogitsWarperu [`LogitsProcessor`] that performs top-k, i.e. restricting to the k highest probability elements. Often used together with [`TemperatureLogitsWarper`] and [`TopPLogitsWarper`]. Args: top_k (`int`): The number of highest probability vocabulary tokens to keep for top-k-filtering. filter_value (`float`, *optional*, defaults to -inf): All filtered values will be set to this float value. min_tokens_to_keep (`int`, *optional*, defaults to 1): Minimum number of tokens that cannot be filtered. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> set_seed(1) >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: A, B, C, D", return_tensors="pt") >>> # With sampling, the output is unexpected -- sometimes too unexpected. >>> outputs = model.generate(**inputs, do_sample=True) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: A, B, C, D, E — S — O, P — R >>> # With `top_k` sampling, the output gets restricted the k most likely tokens. >>> # Pro tip: In practice, LLMs use `top_k` in the 5-50 range. >>> outputs = model.generate(**inputs, do_sample=True, top_k=2) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: A, B, C, D, E, F, G, H, I ``` rhr^top_krjrkcCs6t|tr |dkrtd|t|||_||_dS)Nrz6`top_k` has to be a strictly positive integer, but is )r8r9r.maxr~rj)rr~rjrkrrrr<s  zTopKLogitsWarper.__init__rrrcCs<t|j|d}|t||ddk}|||j}|S)Nr>r.r>N)minr~sizertopkrvrj)rrrr~r{rGrrrrszTopKLogitsWarper.__call__Nr|rrrrr}s "$"r}c@sNeZdZdZed dfdededefddZd ejd ej d ej fd d Z dS)MinPLogitsWarpera [`LogitsProcessor`] that performs min-p, i.e. keeps all tokens that are above a minimum probability, scaled by the probability of the most likely token. As a result, the filter becomes more agressive in the presence of high-probability tokens, which is a sign of a confident output that we shouldn't deviate from. Often used together with [`TemperatureLogitsWarper`]. Used as an alternative to [`TopPLogitsWarper`] and [`TopKLogitsWarper`]. Created by @menhguin and @kalomaze (github handles). Code adapted from [this external PR](https://github.com/oobabooga/text-generation-webui/pull/4449/files) Args: min_p (`float`): Minimum token probability, which will be scaled by the probability of the most likely token. It must be a value between 0 and 1. Typical values are in the 0.01-0.2 range, comparably selective as setting `top_p` in the 0.99-0.8 range (use the opposite of normal `top_p` values). filter_value (`float`, *optional*, defaults to -inf): All filtered values will be set to this float value. min_tokens_to_keep (`int`, *optional*, defaults to 1): Minimum number of tokens that cannot be filtered. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> set_seed(1) >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt") >>> # With sampling, the output is unexpected -- sometimes too unexpected. >>> outputs = model.generate(**inputs, do_sample=True) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3 | < 4 (left-hand pointer) ; >>> # With `min_p` sampling, the output gets restricted to high-probability tokens. >>> # Pro tip: In practice, LLMs use `min_p` in the 0.01-0.2 range. >>> outputs = model.generate(**inputs, do_sample=True, min_p=0.1) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9 ``` rhr^min_prjrkcCsZd|kr dksntd|t|tr|dkr"td|||_||_||_dS)Nrrlz9`min_p` has to be a float in the [0, 1] interval, but is r^rm)r.r8r9rrjrk)rrrjrkrrrr<8s zMinPLogitsWarper.__init__rrrc Cstj|dd}|jddd\}}|j|}||k}tj|ddd}tj|d|d} d| dd|jf<| d || } || |j } | S) Nr>rqTrrkeepdim)rprr)rrindexF.r^) rrtrrargsortr_rkr`rvrj) rrrprobs top_probs_ scaled_min_ptokens_to_removerxrzr{rGrrrrBs zMinPLogitsWarper.__call__N rrrrrVr9r<rrrrrrrrr s". rc@sXeZdZdZded dfdededefdd Zeed e j d e j d e j fd dZ dS)TypicalLogitsWarpera [`LogitsProcessor`] that performs typical decoding. Inspired on how humans use language, it prioritizes tokens whose log probability is close to the entropy of the token probability distribution. This means that the most likely tokens may be discarded in the process. See [Typical Decoding for Natural Language Generation](https://arxiv.org/abs/2202.00666) for more information. Args: mass (`float`, *optional*, defaults to 0.9): Value of typical_p between 0 and 1 inclusive, defaults to 0.9. filter_value (`float`, *optional*, defaults to -inf): All filtered values will be set to this float value. min_tokens_to_keep (`int`, *optional*, defaults to 1): Minimum number of tokens that cannot be filtered. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m") >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m") >>> inputs = tokenizer("1, 2, 3", return_tensors="pt") >>> # We can see that greedy decoding produces a sequence of numbers >>> outputs = model.generate(**inputs) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, >>> # For this particular seed, we can see that sampling produces nearly the same low-information (= low entropy) >>> # sequence >>> set_seed(18) >>> outputs = model.generate(**inputs, do_sample=True) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) 1, 2, 3, 4, 5, 6, 7, 8, 9 and 10 >>> # With `typical_p` set, the most obvious sequence is no longer produced, which may be good for your problem >>> set_seed(18) >>> outputs = model.generate( ... **inputs, do_sample=True, typical_p=0.1, return_dict_in_generate=True, output_scores=True ... ) >>> print(tokenizer.batch_decode(outputs.sequences, skip_special_tokens=True)[0]) 1, 2, 3 and 5 >>> # We can see that the token corresponding to "4" (token 934) in the second position, the most likely token >>> # as seen with greedy decoding, was entirely blocked out >>> print(outputs.scores[1][0, 934]) tensor(-inf) ``` g?rhr^massrjrkcCs\t|}|dkr |dkstd|t|tr|dkr#td|||_||_||_dS)Nrr^z2`typical_p` has to be a float > 0 and < 1, but is rm)rVr.r8r9rjrrk)rrrjrkrrrr<rnzTypicalLogitsWarper.__init__rrrcCstjjj|dd}t|}||jddd }t| |}tj|dd\}}|d|} | j ddj dd} | |j kj dd} | j |jddd||d| ddk} d | d d|jf<| d|| } || |j}|S) Nr>rqT)rFror^)rr.)rnn functional log_softmaxexpnansumabsrsr_rtrursumclamp_r@viewrkr`rvrj)rrr normalizedpentshifted_scores sorted_scoresrxrwrylast_indrzr{rGrrrrs  zTypicalLogitsWarper.__call__Nr|rrrrrVs $4 "rc@rf)EpsilonLogitsWarperaL [`LogitsProcessor`] 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](https://arxiv.org/abs/2210.15191) for more information. Args: 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 -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. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> set_seed(1) >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt") >>> # With sampling, the output is unexpected -- sometimes too unexpected. >>> outputs = model.generate(**inputs, do_sample=True) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3 | < 4 (left-hand pointer) ; >>> # With epsilon sampling, the output gets restricted to high-probability tokens. Note that this is similar to >>> # Top P sampling, which restricts tokens based on their cumulative probability. >>> # Pro tip: The paper recomends using `epsilon_cutoff` values between 3e-4 and 9e-4 >>> outputs = model.generate(**inputs, do_sample=True, epsilon_cutoff=0.1) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9 ``` rhr^epsilonrjrkcCsZt|}|dks |dkrtd|t|}|dkr"td|||_||_||_dS)Nrr^z7`epsilon_cutoff` has to be a float > 0 and < 1, but is C`min_tokens_to_keep` has to be a strictly positive integer, but is )rVr.r9rrjrk)rrrjrkrrrr<s zEpsilonLogitsWarper.__init__rrrcCsV|jdd}||jk}t|j|d}||t||ddk@}|||j}|S)Nr>rqrr) rtrrrkrrrrvrj)rrr probabilitiesr{r~rGrrrrs  zEpsilonLogitsWarper.__call__Nr|rrrrrs "'"rc @s\eZdZdZed ddfdedededefd d Zee d e j d e j d e j fddZ dS)EtaLogitsWarpera [`LogitsProcessor`] 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](https://arxiv.org/abs/2210.15191) for more information. Note: `do_sample` must be set to `True` for this `LogitsProcessor` to work. Args: epsilon (`float`): A float value in the range (0, 1). Hyperparameter used to calculate the dynamic cutoff value, `eta`. The suggested values from the paper ranges from 3e-4 to 4e-3 depending on the size of the model. filter_value (`float`, *optional*, defaults to -inf): All values that are found to be below the dynamic cutoff value, `eta`, are set to this float value. This parameter is useful when logits need to be modified for very low probability tokens that should be excluded from generation entirely. min_tokens_to_keep (`int`, *optional*, defaults to 1): Specifies the minimum number of tokens that must be kept for generation, regardless of their probabilities. For example, 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`. device (`str`, *optional*, defaults to `"cpu"`): The device to allocate the tensors. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> set_seed(1) >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt") >>> # With sampling, the output is unexpected -- sometimes too unexpected. >>> outputs = model.generate(**inputs, do_sample=True) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3 | < 4 (left-hand pointer) ; >>> # With eta sampling, the output gets restricted to high-probability tokens. You can see it as a dynamic form of >>> # epsilon sampling that adapts its cutoff probability based on the entropy (high entropy = lower cutoff). >>> # Pro tip: The paper recomends using `eta_cutoff` values between 3e-4 to 4e-3 >>> outputs = model.generate(**inputs, do_sample=True, eta_cutoff=0.1) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9 ``` rhr^r3rrjrkr6cCsdt|}|dks |dkrtd|t|}|dkr"td|tj||d|_||_||_dS)Nrr^z3`eta_cutoff` has to be a float > 0 and < 1, but is rr7)rVr.r9rr;rrjrk)rrrjrkr6rrrr<'s zEtaLogitsWarper.__init__rrrc Cs|jdd}tjj|d}t|jt|jt| d}||k}t|j | d}||t ||ddk@}| ||j }|S)Nr>rq)logits).Nrr)rtr distributions Categoricalentropyrrsqrtrrkrrrvrj) rrrrretar{r~rGrrrr8s &zEtaLogitsWarper.__call__N)rrrrrVr9rJr<r rrrrrrrrrrs 4 "r ngram_sizeprev_input_ids num_hyposcsddt|D}t|D]1}||||}tfddt|DD]}t|dd}||g|dg||<q&q |S)ap Assume ngram_size=2 and prev_input_ids=tensor([[40, 2883, 2712, 4346]]). The output of generated ngrams look like this {(40,): [2883], (2883,): [2712], (2712,): [4346]}. Args: ngram_size (`int`): The number sequential tokens taken as a group which may only occur once before being banned. prev_input_ids (`torch.Tensor`): Generated token ids for the current hypothesis. num_hypos (`int`): The number of hypotheses for which n-grams need to be generated. Returns: generated_ngrams (`dict`): Dictionary of generated ngrams. cSsg|]}iqSrrr"rrrr Yz_get_ngrams..csg|]}|dqSr!rr"i gen_tokensrrr^sNr>)rangetolistziptupleget)rrrgenerated_ngramsidxgenerated_ngramngramprev_ngram_tuplerrr _get_ngramsGs  rcCs,|d|}t|||}||gS)a Determines the banned tokens for the current hypothesis based on previously generated n-grams. Args: banned_ngrams (`dict`): A dictionary containing previously generated n-grams for each hypothesis. prev_input_ids (`torch.Tensor`): Generated token ids for the current hypothesis. ngram_size (`int`): The number sequential tokens taken as a group which may only occur once before being banned. cur_len (`int`): The current length of the token sequences for which the n-grams are being checked. Returns: List of tokens that are banned. r^)rrr) banned_ngramsrrcur_len start_idx ngram_idxrrr_get_generated_ngramsds  rrrcsJdkrddt|DSt|fddt|D}|S)z6Copied from fairseq for no_repeat_ngram in beam_searchr^cSsg|]}gqSrrrrrrrrz-_calc_banned_ngram_tokens..cs"g|] }t||qSr)rr"hypo_idxrrrrrrrs)rr)rrrr banned_tokensrrr_calc_banned_ngram_tokens{s  rc@rR) NoRepeatNGramLogitsProcessoru N-grams are groups of "n" consecutive words, characters, or tokens taken from a sequence of text. Given the sentence: "She runs fast", the bi-grams (n=2) would be ("she", "runs") and ("runs", "fast"). In text generation, avoiding repetitions of word sequences provides a more diverse output. This [`LogitsProcessor`] enforces no repetition of n-grams by setting the scores of banned tokens to negative infinity which eliminates those tokens from consideration when further processing the scores. Note that, for decoder-only models like most LLMs, the prompt is also considered to obtain the n-grams. [Fairseq](https://github.com/pytorch/fairseq/blob/a07cb6f40480928c9e0548b737aadd36ee66ac76/fairseq/sequence_generator.py#L345). 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](https://huggingface.co/blog/how-to-generate) Args: ngram_size (`int`): All ngrams of size `ngram_size` can only occur once. Examples: ```py >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer(["Today I"], return_tensors="pt") >>> output = model.generate(**inputs) >>> print(tokenizer.decode(output[0], skip_special_tokens=True)) Today I’m not sure if I’m going to be able to do it. >>> # Now let's add ngram size using `no_repeat_ngram_size`. This stops the repetitions ("I’m") in the output. >>> output = model.generate(**inputs, no_repeat_ngram_size=2) >>> print(tokenizer.decode(output[0], skip_special_tokens=True)) Today I’m not sure if I can get a better understanding of the nature of this issue ``` rcCs*t|tr |dkrtd|||_dS)Nrz;`ngram_size` has to be a strictly positive integer, but is )r8r9r.r)rrrrrr<s z%NoRepeatNGramLogitsProcessor.__init__rrrc CsT|jd}|jd}|}t|j|||}t|D] \}}td |||f<q|S)Nrr>rD)r@rArr enumeraterV) rrrnum_batch_hypothesesrrGbanned_batch_tokensrrrrrrs  z%NoRepeatNGramLogitsProcessor.__call__N rrrrr9r<r rrrrrrrrrrs )"rc@rc) #EncoderNoRepeatNGramLogitsProcessora [`LogitsProcessor`] that works similarly to [`NoRepeatNGramLogitsProcessor`], but applied exclusively to prevent the repetition of n-grams present in the prompt. It was designed to promote chattiness in a language model, by preventing the generation of n-grams present in previous conversation rounds. Args: 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. Examples: ```py >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m") >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m") >>> inputs = tokenizer("Alice: I love cats. What do you love?\nBob:", return_tensors="pt") >>> # With greedy decoding, we see Bob repeating Alice's opinion. If Bob was a chatbot, it would be a poor one. >>> outputs = model.generate(**inputs) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) Alice: I love cats. What do you love? Bob: I love cats. What do you >>> # With this logits processor, we can prevent Bob from repeating Alice's opinion. >>> outputs = model.generate(**inputs, encoder_no_repeat_ngram_size=2) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) Alice: I love cats. What do you love? Bob: My cats are very cute. ``` encoder_ngram_sizerecCs^t|tr |dkrtd|||_t|jdkr|d}|jd|_t|||j|_ dS)NrzC`encoder_ngram_size` has to be a strictly positive integer, but is r^) r8r9r.rr*r@ unsqueeze batch_sizerr)rrrerrrr<s  z,EncoderNoRepeatNGramLogitsProcessor.__init__rrrcsj|jd}|jjd|}fddt|D}t|D] \}}td |||f<q%|S)Nrr>cs*g|]}tj||jqSr)rrrrrr num_beamsrrrrs z@EncoderNoRepeatNGramLogitsProcessor.__call__..rD)r@rrArrrV)rrrrrGrrrrrrrs   z,EncoderNoRepeatNGramLogitsProcessor.__call__N) rrrrr9rrr<r rrrrrrrrs % "rc@sveZdZdZdeeeeeeffddZe e de j de j de j fdd Zde j fd d Zd d ZddZdS)SequenceBiasLogitsProcessoraG [`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). At a token-level, biasing a word is different from biasing a word with a space before it. If you want to bias "foo" mid-sentence, you'll likely want to add a prefix space and bias " foo" instead. Check the tokenizer section of our NLP course to find out why: https://huggingface.co/learn/nlp-course/chapter2/4?fw=pt Args: sequence_bias (`List[List[Union[List[int], float]]]`): List of lists that maps a sequence of tokens to its bias term (e.g. `[[[10, 45], -2.0], [[64], -7.5]]`). 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). Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct") >>> tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct") >>> inputs = tokenizer(["The full name of Donald is Donald"], return_tensors="pt") >>> summary_ids = model.generate(inputs["input_ids"], max_new_tokens=4, do_sample=False) >>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0]) The full name of Donald is Donald John Trump Sr. >>> def get_tokens(word): ... return tokenizer([word], add_special_tokens=False).input_ids[0] >>> # IMPORTANT: Remember our tip about adding spaces before words to bias them correctly. >>> sequence_bias = [[get_tokens("Trump"), -10.0],] # will fail to apply bias >>> biased_ids = model.generate( ... inputs["input_ids"], max_new_tokens=4, do_sample=False, sequence_bias=sequence_bias ... ) >>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0]) The full name of Donald is Donald John Trump Sr. >>> sequence_bias = [[get_tokens(" Trump"), -10.0],] # will work >>> biased_ids = model.generate( ... inputs["input_ids"], max_new_tokens=4, do_sample=False, sequence_bias=sequence_bias ... ) >>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0]) The full name of Donald is Donald John Harper. He >>> # We can also add a positive bias to nudge the model towards specific tokens or continuations. This technique >>> # is also more effective when paired up with beam search. >>> sequence_bias = [[get_tokens(" Donald Duck"), 10.0],] >>> biased_ids = model.generate( ... inputs["input_ids"], max_new_tokens=4, num_beams=4, do_sample=False, sequence_bias=sequence_bias ... ) >>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0]) The full name of Donald is Donald Duck. He is ``` sequence_biascCs&||_||d|_d|_dS)NF)r_validate_arguments!_convert_list_arguments_into_dict length_1_biasprepared_bias_variablesrrrrrr<Ks  z$SequenceBiasLogitsProcessor.__init__rrrc Cs|js||t|}||j7}|jD]]\}}t|dkr"qt||jdkr,qt|d}|d}t |dd| dftj |dd|j |j dj dd}|dd|ft|tj ||j dtj d|j d7<q||} | S)Nr^r>dtyper6rqr7rU)r_prepare_bias_variablesr zeros_likerritemsr*r@eqr;rr6prodrBbool) rrrbias sequence_idsr prefix_length last_token matching_rowsrGrrrrUs0      z$SequenceBiasLogitsProcessor.__call__cCs|jd}g}|jD]}|D] }||kr||qq t|dkr+td|d|tj|ftj|jd|_ |j D]\}}t|dkrM||j |d<qrzThe model vocabulary size is z., but the following tokens were being biased: rr^T) r@rappendr*r.rzerosrVr6rrr)rrvocabulary_sizeinvalid_biasesrtoken_idrrrrrws(      z3SequenceBiasLogitsProcessor._prepare_bias_variablescs|j}t|ts t|trt|dkrtd|dt|tr3tdd|Dr3td|dt|trKtdd|DrKtd|dd d t|trgtfd d|Drgtd |dt|trtd d|Drtd|ddSdS)NrzT`sequence_bias` has to be a non-empty dictionary, or non-empty list of lists but is .cs|] }t|t VqdSr!)r8rr"rrrrr&s  zBSequenceBiasLogitsProcessor._validate_arguments..z=`sequence_bias` has to be a dict with tuples as keys, but is css.|]}tdd|Dpt|dkVqdS)cs*|]}t|ttjf p|dkVqdSrNr8r9npintegerr"rrrrr&(zLSequenceBiasLogitsProcessor._validate_arguments...rN)anyr*rrrrr&s   zUEach key in `sequence_bias` has to be a non-empty tuple of positive integers, but is cSs2t|dtotdd|dDot|dtS)Nrcss(|]}t|ttjfo|dkVqdSrrrrrrr&s&zjSequenceBiasLogitsProcessor._validate_arguments..all_token_bias_pairs_are_valid..r^)r8r,r+rV)sequencerrrall_token_bias_pairs_are_valids  zWSequenceBiasLogitsProcessor._validate_arguments..all_token_bias_pairs_are_validc3s&|]}| pt|dkVqdSr)r*r"rrrrr&s zkEach element in `sequence_bias` has to be a non-empty list of lists of positive integers and float, but is csrr!)r8rV)r"rrrrr&z?`sequence_bias` has to be a dict with floats as values, but is ) rr8dictr,r*r.rr-valuesrrrrrs:   z/SequenceBiasLogitsProcessor._validate_argumentscCs*t|jtr|j}dd|D|_dSdS)zSBC: we used to accept `dict{tuple of tokens: float}` directly, now we expect a listcSsi|] }t|d|dqS)rr^)r)r"sublistrrr szQSequenceBiasLogitsProcessor._convert_list_arguments_into_dict..N)r8rr,)r temp_sequencerrrrs z=SequenceBiasLogitsProcessor._convert_list_arguments_into_dictN)rrrrrrr9rVr<r rrrrrrrrrrrrr s"@ ! %rc sReZdZdZ d deeedeeeeeej fffdd Z ddZ Z S) NoBadWordsLogitsProcessora8 [`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](https://huggingface.co/docs/tokenizers/api/pre-tokenizers). Args: 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], torch.Tensor]`, *optional*): The id(s) of the *end-of-sequence* token. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2") >>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2") >>> inputs = tokenizer(["In a word, the cake is a"], return_tensors="pt") >>> output_ids = model.generate(inputs["input_ids"], max_new_tokens=5, pad_token_id=tokenizer.eos_token_id) >>> print(tokenizer.batch_decode(output_ids, skip_special_tokens=True)[0]) In a word, the cake is a bit of a mess. >>> # Now let's take the bad words out. Please note that the tokenizer is initialized differently >>> tokenizer_with_prefix_space = AutoTokenizer.from_pretrained("openai-community/gpt2", add_prefix_space=True) >>> def get_tokens_as_list(word_list): ... "Converts a sequence of words into a list of tokens" ... tokens_list = [] ... for word in word_list: ... tokenized_word = tokenizer_with_prefix_space([word], add_special_tokens=False).input_ids[0] ... tokens_list.append(tokenized_word) ... return tokens_list >>> bad_words_ids = get_tokens_as_list(word_list=["mess"]) >>> output_ids = model.generate( ... inputs["input_ids"], max_new_tokens=5, bad_words_ids=bad_words_ids, pad_token_id=tokenizer.eos_token_id ... ) >>> print(tokenizer.batch_decode(output_ids, skip_special_tokens=True)[0]) In a word, the cake is a bit of a surprise. ``` N bad_words_idsr5csr||_|dur)ttjsttrgtttfdd|}dd|D}t j |ddS)NcstfddDS)Nc3s|]}|gkVqdSr!rr bad_token_seqrrr&szGNoBadWordsLogitsProcessor.__init__....)r+rr5rrsz4NoBadWordsLogitsProcessor.__init__..cSsi|] }t|tdqS)z-inf)rrVrrrrrsz6NoBadWordsLogitsProcessor.__init__..)r) bad_word_idsrr8rr:r9r;r,filtersuperr<)rrr5rrrrr<s   z"NoBadWordsLogitsProcessor.__init__cCst|j}t|trt|dkrtd|dtdd|Dr'td|dtdd|Dr8td|ddS) Nrz3`bad_words_ids` has to be a non-empty list, but is rcsrr!)r8r,r"r rrrr& rz@NoBadWordsLogitsProcessor._validate_arguments..z2`bad_words_ids` has to be a list of lists, but is css"|] }tdd|DVqdS)csrrrrrrrr&rzJNoBadWordsLogitsProcessor._validate_arguments...N)rrrrrr& s  zKEach list in `bad_words_ids` has to be a list of positive integers, but is )r r8r,r*r.r)rrrrrrs z-NoBadWordsLogitsProcessor._validate_argumentsr!) rrrrrr9rrrr:r<r __classcell__rrr rrs7 rc@sXeZdZdZdeeejgeefdefddZ e e dej dej dej fd d Zd S) PrefixConstrainedLogitsProcessora [`LogitsProcessor`] that enforces constrained generation and is useful for prefix-conditioned constrained generation. See [Autoregressive Entity Retrieval](https://arxiv.org/abs/2010.00904) for more information. Args: 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`. Examples: ```py >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m") >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m") >>> inputs = tokenizer("Alice and Bob", return_tensors="pt") >>> # By default, it continues generating according to the model's logits >>> outputs = model.generate(**inputs, max_new_tokens=5) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) Alice and Bob are friends >>> # We can contrain it with `prefix_allowed_tokens_fn` to force a certain behavior based on a prefix. >>> # For instance, we can force an entire entity to be generated when its beginning is detected. >>> entity = tokenizer(" Bob Marley", return_tensors="pt").input_ids[0] # 3 tokens >>> def prefix_allowed_tokens_fn(batch_id, input_ids): ... ''' ... Attempts to generate 'Bob Marley' when 'Bob' is detected. ... In this case, `batch_id` is not used, but you can set rules for each batch member. ... ''' ... if input_ids[-1] == entity[0]: ... return [entity[1].item()] ... elif input_ids[-2] == entity[0] and input_ids[-1] == entity[1]: ... return [entity[2].item()] ... return list(range(tokenizer.vocab_size)) # If no match, allow all tokens >>> outputs = model.generate(**inputs, max_new_tokens=5, prefix_allowed_tokens_fn=prefix_allowed_tokens_fn) >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0]) Alice and Bob Marley ``` prefix_allowed_tokens_fnrcCs||_||_dSr!)_prefix_allowed_tokens_fn _num_beams)rrrrrrr<Es z)PrefixConstrainedLogitsProcessor.__init__rrrc Cst|tj }|jd|j}t|D]2}t|jD]*}|||j|}|||}t|dkr:t d|dd|||j||f<qq||} | S)Nrz?`prefix_allowed_tokens_fn` returned an empty list for batch ID zp.This means that the constraint is unsatisfiable. Please check your implementationof `prefix_allowed_tokens_fn` ) r full_likerCrDr@rrrr*r.) rrrmaskrbatch_idbeam_idsentprefix_allowed_tokensrGrrrrIs     z)PrefixConstrainedLogitsProcessor.__call__N)rrrrrr9rr:rr<r rrrrrrrrrs $."rc @sLeZdZdZdededefddZdejdej d ejd ed ej f d d Z dS)HammingDiversityLogitsProcessoraJ [`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](https://arxiv.org/pdf/1610.02424.pdf) for more details. Traditional beam search often generates very similar sequences across different beams. `HammingDiversityLogitsProcessor` addresses this by penalizing beams that generate tokens already chosen by other beams in the same time step. Args: diversity_penalty (`float`): This value is subtracted from a beam's score if it generates a token same as any beam from other group at a particular time. A higher `diversity_penalty` will enforce greater diversity among the beams. Adjusting this value can help strike a balance between diversity and natural likelihood. num_beams (`int`): Number of beams for beam search. 1 means no beam search. num_beam_groups (`int`): Number of groups to divide `num_beams` into in order to ensure diversity among different groups of beams. [this paper](https://arxiv.org/pdf/1610.02424.pdf) for more details. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM >>> import torch >>> # Initialize the model and tokenizer >>> tokenizer = AutoTokenizer.from_pretrained("google-t5/t5-base") >>> model = AutoModelForSeq2SeqLM.from_pretrained("google-t5/t5-base") >>> # A long text about the solar system >>> text = ( ... "The Solar System is a gravitationally bound system comprising the Sun and the objects that orbit it, " ... "either directly or indirectly. Of the objects that orbit the Sun directly, the largest are the eight " ... "planets, with the remainder being smaller objects, such as the five dwarf planets and small Solar System " ... "bodies. The Solar System formed 4.6 billion years ago from the gravitational collapse of a giant " ... "interstellar molecular cloud." ... ) >>> inputs = tokenizer("summarize: " + text, return_tensors="pt") >>> # Generate diverse summary >>> outputs_diverse = model.generate( ... **inputs, ... num_beam_groups=2, ... diversity_penalty=10.0, ... max_length=100, ... num_beams=4, ... num_return_sequences=2, ... ) >>> summaries_diverse = tokenizer.batch_decode(outputs_diverse, skip_special_tokens=True) >>> # Generate non-diverse summary >>> outputs_non_diverse = model.generate( ... **inputs, ... max_length=100, ... num_beams=4, ... num_return_sequences=2, ... ) >>> summary_non_diverse = tokenizer.batch_decode(outputs_non_diverse, skip_special_tokens=True) >>> # With `diversity_penalty`, the resulting beams are much more diverse >>> print(summary_non_diverse) ['the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.', 'the Solar System formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.'] >>> print(summaries_diverse) ['the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.', 'the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets. the rest of the objects are smaller objects, such as the five dwarf planets and small solar system bodies.'] ``` diversity_penaltyrnum_beam_groupscCsxt|tr |dks td||_t|tr|dkrtd||_t|tr)|dkr-td||kr5td|||_dS)NrUz=`diversity_penalty` should be a float strictly larger than 0.rz8`num_beams` should be an integer strictly larger than 1.z>`num_beam_groups` should be an integer strictly larger than 1.z8`beam_groups` has to be smaller or equal to `num_beams`.)r8rVr._diversity_penaltyr9r_num_sub_beams)rrrrrrrr<sz(HammingDiversityLogitsProcessor.__init__rrcurrent_tokensbeam_group_idxrcCs|jd|j}||j}t||j|j}||}|jd} |dkr%|S|} t|D].} || |j| |j|} tj| | d|j } | | || d||j | 8<q-| S)a Args: input_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`): Indices of input sequence tokens in the vocabulary. [What are input IDs?](../glossary#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. Return: `torch.FloatTensor` of shape `(batch_size, config.vocab_size)`: The processed prediction scores. rr>) minlengthr^) r@rrrrArrbincounttor6r)rrrrr rgroup_start_idx group_end_idx group_size vocab_sizerG batch_idxprevious_group_tokenstoken_frequencyrrrrs"   z(HammingDiversityLogitsProcessor.__call__Nrrrrrr^sI rc@rR) ForcedBOSTokenLogitsProcessora [`LogitsProcessor`] that enforces the specified token as the first generated token. Used with encoder-decoder models. Args: bos_token_id (`int`): The id of the token to force as the first generated token. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM >>> model = AutoModelForSeq2SeqLM.from_pretrained("google/flan-t5-small") >>> tokenizer = AutoTokenizer.from_pretrained("google/flan-t5-small") >>> inputs = tokenizer("Translate from English to German: I love cats.", return_tensors="pt") >>> # By default, it continues generating according to the model's logits >>> outputs = model.generate(**inputs, max_new_tokens=10) >>> print(tokenizer.batch_decode(outputs)[0]) Ich liebe Kitty. >>> # We can use `forced_bos_token_id` to force the start of generation with an encoder-decoder model >>> # (including forcing it to end straight away with an EOS token) >>> outputs = model.generate(**inputs, max_new_tokens=10, forced_bos_token_id=tokenizer.eos_token_id) >>> print(tokenizer.batch_decode(outputs)[0]) ``` bos_token_idcC ||_dSr!)r,)rr,rrrr< z&ForcedBOSTokenLogitsProcessor.__init__rrrcCs<|jd}|}|dkrt|tj }d|dd|jf<|SNr>r^r)r@rrrCrDr,rrrrrGrrrr s z&ForcedBOSTokenLogitsProcessor.__call__Nrrrrrr+s "r+c@r1)ForcedEOSTokenLogitsProcessora  [`LogitsProcessor`] that enforces the specified token as the last generated token when `max_length` is reached. Args: max_length (`int`): The maximum length of the sequence to be generated. eos_token_id (`Union[int, List[int], torch.Tensor]`): The id(s) of the *end-of-sequence* token. device (`str`, *optional*, defaults to `"cpu"`): The device to allocate the tensors. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: 1, 2, 3", return_tensors="pt") >>> # By default, it continues generating according to the model's logits >>> outputs = model.generate(**inputs, max_new_tokens=10) >>> print(tokenizer.batch_decode(outputs)[0]) A sequence: 1, 2, 3, 4, 5, 6, 7, 8 >>> # `forced_eos_token_id` ensures the generation ends with a EOS token >>> outputs = model.generate(**inputs, max_new_tokens=10, forced_eos_token_id=tokenizer.eos_token_id) >>> print(tokenizer.batch_decode(outputs)[0]) A sequence: 1, 2, 3, 4, 5, 6, 7,<|endoftext|> ``` r3 max_lengthr5r6cCs^||_t|tjst|tr|g}tj||d}||_t|s&|dkr-t d|dS)Nr7r=`eos_token_id` has to be a list of positive integers, but is ) r2r8rr:r9r;r5is_floating_pointrr.)rr2r5r6rrrr<5s  z&ForcedEOSTokenLogitsProcessor.__init__rrrcCsB|jd}|}||jdkrt|tj }d|dd|jf<|Sr/)r@r2rrrCrDr5r0rrrrAs z&ForcedEOSTokenLogitsProcessor.__call__NrHrIrrrrr1s (! "r1c@r )InfNanRemoveLogitsProcessorak [`LogitsProcessor`] that removes all `nan` and `inf` values to avoid the generation method to fail. Note that using the logits processor should only be used if necessary since it can slow down the generation method. This logits processor has no `generate` example, as there shouldn't be a correct combination of flags that warrants its use. rrrcCsXt||kd|}t|tdkt|jj|}t|td kt|jj|}|S)NrUrD)rrBrVfinforrrrXrrrrTs "z$InfNanRemoveLogitsProcessor.__call__Nrrrrrr5Ks"r5c@sbeZdZdZdeeefdeeeee j fdefddZ e e de jde jd e jfd d Zd S) ExponentialDecayLengthPenaltya [`LogitsProcessor`] that exponentially increases the score of the `eos_token_id` after `start_index` has been reached. This allows generating shorter sequences without having a hard cutoff, allowing the `eos_token` to be predicted in a meaningful position. Args: 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], torch.Tensor]`): The id(s) of the *end-of-sequence* token. input_ids_seq_length (`int`): The length of the input sequence. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed >>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2") >>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2") >>> text = "Just wanted to let you know, I" >>> inputs = tokenizer(text, return_tensors="pt") >>> # Let's consider that we want short sentences, so we limit `max_length=30`. However, we observe that the answer >>> # tends to end abruptly. >>> set_seed(1) >>> outputs = model.generate(**inputs, do_sample=True, temperature=0.9, max_length=30, pad_token_id=50256) >>> print(tokenizer.batch_decode(outputs)[0]) Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which was published in 2010. Although >>> # To promote the appearance of the EOS token at the right time, we add the `exponential_decay_length_penalty = >>> # (start_index, decay_factor)`. Instead of cutting at max_tokens, the output comes to an end before and usually >>> # with more meaning. What happens is that starting from `start_index` the EOS token score will be increased >>> # by `decay_factor` exponentially. However, if you set a high decay factor, you may also end up with abruptly >>> # ending sequences. >>> set_seed(1) >>> outputs = model.generate( ... **inputs, ... do_sample=True, ... temperature=0.9, ... max_length=30, ... pad_token_id=50256, ... exponential_decay_length_penalty=(15, 1.6), ... ) >>> print(tokenizer.batch_decode(outputs)[0]) Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which<|endoftext|> >>> # With a small decay factor, you will have a higher chance of getting a meaningful sequence. >>> set_seed(1) >>> outputs = model.generate( ... **inputs, ... do_sample=True, ... temperature=0.9, ... max_length=30, ... pad_token_id=50256, ... exponential_decay_length_penalty=(15, 1.01), ... ) >>> print(tokenizer.batch_decode(outputs)[0]) Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which was published in 2010.<|endoftext|> ``` exponential_decay_length_penaltyr5input_ids_seq_lengthcCsl|d||_|d|_t|tjst|tr|g}t|}||_t|s-|dk r4t d|dS)Nrr^r3) regulation_startregulation_factorr8rr:r9r;r5r4rr.)rr8r5r9rrrr<s    z&ExponentialDecayLengthPenalty.__init__rrrcCs|jd}|j|j|_t|}|}||jkr?||j}t|dd|jft|j |d}||dd|jf<||}|S)Nr>r^) r@r5r#r6rrr:rpowr;)rrrr penaltiesrG penalty_idxr[rrrrs    (z&ExponentialDecayLengthPenalty.__call__N)rrrrrr9rVrrrr:r<r rrrrrrrrr7`sC  "r7c@r )LogitNormalizationa [`LogitsProcessor`] for normalizing the scores using log-softmax. It's important to normalize the scores during beam search, after applying the logits processors or warpers, since the search algorithm used in this library doesn't do it (it only does it before, but they may need re-normalization) but it still supposes that the scores are normalized when comparing the hypotheses. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> import torch >>> model = AutoModelForCausalLM.from_pretrained("distilbert/distilgpt2") >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2") >>> inputs = tokenizer("A sequence: 1, 2, 3", return_tensors="pt") >>> # By default, the scores are not normalized -- the sum of their exponentials is NOT a normalized probability >>> # distribution, summing to 1 >>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True) >>> print(torch.allclose(torch.sum(torch.exp(outputs.scores[-1])), torch.Tensor((1.000,)), rtol=1e-4)) False >>> # Normalizing them may have a positive impact on beam methods, or when using the scores on your application >>> outputs = model.generate(**inputs, renormalize_logits=True, return_dict_in_generate=True, output_scores=True) >>> print(torch.allclose(torch.sum(torch.exp(outputs.scores[-1])), torch.Tensor((1.000,)), rtol=1e-4)) True ``` rrrcCs|jdd}|S)Nr>rq)rrXrrrrs zLogitNormalization.__call__Nrrrrrr?s"r?c@sLeZdZdZddefddZddZeede j d e j d e j fd d Z d S)$SuppressTokensAtBeginLogitsProcessora{ [`SuppressTokensAtBeginLogitsProcessor`] supresses a list of tokens as soon as the `generate` function starts generating using `begin_index` tokens. This should ensure that the tokens defined by `begin_suppress_tokens` are not generated at the beginning. Originally created for [Whisper](https://huggingface.co/docs/transformers/model_doc/whisper). Examples: ```python >>> from transformers import AutoProcessor, WhisperForConditionalGeneration >>> from datasets import load_dataset >>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en") >>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en") >>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") >>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt") >>> # Whisper has `begin_suppress_tokens` set by default (= `[220, 50256]`). 50256 is the EOS token, so this means >>> # it can't generate and EOS token in the first iteration, but it can in the others. >>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True) >>> print(outputs.scores[0][0, 50256]) tensor(-inf) >>> print(outputs.scores[-1][0, 50256]) # in other places we can see some probability mass for EOS tensor(29.9010) >>> # If we disable `begin_suppress_tokens`, we can generate EOS in the first iteration. >>> outputs = model.generate( ... **inputs, return_dict_in_generate=True, output_scores=True, begin_suppress_tokens=None ... ) >>> print(outputs.scores[0][0, 50256]) tensor(11.2027) ``` r3r6cCstjt||d|_||_dSNr7)rr;r,begin_suppress_tokens begin_index)rrBrCr6rrrr< s z-SuppressTokensAtBeginLogitsProcessor.__init__cCr-r!rCrrCrrrset_begin_indexr.z4SuppressTokensAtBeginLogitsProcessor.set_begin_indexrrrcCsNtj|jd|jd}t||j}|}|jd|jkr%t|td |}|SNr>r7rD) rr?r@r6r rBrCrBrV)rrrrEsuppress_token_maskrGrrrrs  z-SuppressTokensAtBeginLogitsProcessor.__call__NrH) rrrrrJr<rFr rrrrrrrrrr@s ""r@c@sDeZdZdZd defddZeedej dej dej fd d Z d S) SuppressTokensLogitsProcessora This processor can be used to suppress a list of tokens. The processor will set their log probs to `-inf` so that they are not generated. Originally created for [Whisper](https://huggingface.co/docs/transformers/model_doc/whisper). Examples: ```python >>> from transformers import AutoProcessor, WhisperForConditionalGeneration >>> from datasets import load_dataset >>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en") >>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en") >>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") >>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt") >>> # Whisper has a long list of suppressed tokens. For instance, in this case, the token 1 is suppressed by default. >>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True) >>> print(outputs.scores[1][0, 1]) # 1 (and not 0) is the first freely generated token tensor(-inf) >>> # If we disable `suppress_tokens`, we can generate it. >>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True, suppress_tokens=None) >>> print(outputs.scores[1][0, 1]) tensor(6.0678) ``` r3r6cCstjt||d|_dSrA)rr;r,suppress_tokens)rrJr6rrrr<<sz&SuppressTokensLogitsProcessor.__init__rrrcCs:tj|jd|jd}t||j}t|td |}|SrG)rr?r@r6r rJrBrV)rrrrErHrrrr?s z&SuppressTokensLogitsProcessor.__call__NrH) rrrrrJr<r rrrrrrrrrrIs "rIc@s\eZdZdZ  ddeedeefddZddZe e d e j d e j d e j fd d ZdS)WhisperTimeStampLogitsProcessora [`LogitsProcessor`] that modifies the logits for the generation of timestamps in the transcription. When the input tokens are at a specific threshold, the processor sets the scores to negative infinity. The processor makes sure that timestamp tokens appear in pairs, by masking out the logits that would break this pairing pattern. This is done to maintain the consistency and structure of generated timestamps. It also ensures that when the predicted probability of sampling any of the timestamp token is greater than any individual non-timestamp token, those non-timestamp logits are set to negative infinity. This is done to ensure the generation of timestamps over other potential tokens. See [the paper](https://arxiv.org/abs/2212.04356) for more information. Args: generate_config (`GenerateConfig`): The generate config used to generate the output. The following parameters are required: eos_token_id (`int`, *optional*, defaults to 50257): The id of the *end-of-sequence* token. no_timestamps_token_id (`int`, *optional*, defaults to 50363): The id of the `"<|notimestamps|>"` token. max_initial_timestamp_index (`int`, *optional*, defaults to 1): Used to set the maximum value of the initial timestamp. This is used to prevent the model from predicting timestamps that are too far in the future. begin_index (`Optional`, *optional*): Token index of the first token that is generated by the model. _detect_timestamp_from_logprob (`bool`, *optional*): Whether timestamps can be predicted from logprobs over all timestamps. Examples: ``` python >>> import torch >>> from transformers import AutoProcessor, WhisperForConditionalGeneration, GenerationConfig >>> from datasets import load_dataset >>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en") >>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en") >>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") >>> inputs = processor(ds[3]["audio"]["array"], return_tensors="pt") >>> input_features = inputs.input_features >>> #Displaying timestamps >>> generated_ids = model.generate(inputs=input_features, return_timestamps=True) >>> transcription = processor.batch_decode(generated_ids, decode_with_timestamps=True)[0] >>> print("Transcription:", transcription) Transcription: <|startoftranscript|><|0.00|> He has grave doubts whether Sir Frederick Layton's work is really Greek after all, and can<|6.44|><|6.44|> discover in it but little of rocky Ithaca.<|9.44|><|endoftext|> >>> #No timestamps & change EOS: >>> #This allows the user to select a specific token to terminate the sequence on, in this case it's the word "can"(460) >>> model.generation_config.eos_token_id = 460 >>> generated_ids = model.generate(inputs=input_features,return_timestamps=False) >>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0] >>> print("Transcription:", transcription) Transcription: He has grave doubts whether Sir Frederick Layton's work is really Greek after all and can ``` NrC_detect_timestamp_from_logprobcCst|j|_|jd|_|jp|j|_|dur|nt|dd|_|jdur(t|jnd}|p/|d|_t|dd|_ dS)Nr^rLTrmax_initial_timestamp_index) no_timestamps_token_idtimestamp_beginr5r,getattrrLforced_decoder_idsr*rCrM)rgenerate_configrCrLnum_forced_idsrrrr<s  z(WhisperTimeStampLogitsProcessor.__init__cCr-r!rDrErrrrFr.z/WhisperTimeStampLogitsProcessor.set_begin_indexrrrcCs|}td |dd|jf<t|jdD]q}|||jdf}t|}t|dko4|d|j k}t|dkpA|d|j k}|r_|rStd |||j df<n td ||d|j f<|| |j } | dkr|rv|sv| d} n| dd} td |||j | f<q|jd|jkrtd |ddd|j f<|j dur|j |j } td |dd| ddf<tjjj|dd} t|jdD]-}| ||j dfjdd} | |d|j f}| |kr|jrtd ||d|j f<q|S)NrDrr^r>rrq)rArVrNrr@rCr,rr*rOr5genumelrMrrrr logsumexprrL)rrrrGksampled_tokensseqlast_was_timestamppenultimate_was_timestamp timestampstimestamp_last last_allowedlogprobstimestamp_logprobmax_text_token_logprobrrrrs>      z(WhisperTimeStampLogitsProcessor.__call__)NN)rrrrrr9rr<rFr rrrrrrrrrrKGs: "rKc@speZdZdZddededefddZdd Zd d Ze d d Z ddZ e e dejdejdejfddZdS)WhisperNoSpeechDetectionzThis processor can be used to detect silence when using Whisper. It should take as input unprocessed logits to follow the original implementationFno_speech_tokenrCscores_is_logprobscCs0||_||_||_dg|_||_d|_d|_dS)NrU)rdstart_of_trans_offsetrC_no_speech_probis_scores_logprobsmodelinputs)rrdrCrerrrr<s z!WhisperNoSpeechDetection.__init__cCr-r!)ri)rrirrr set_modelr.z"WhisperNoSpeechDetection.set_modelcCs2i|jjdi|||_|jd|jd<dS)Nrjinput_featuresr)riprepare_inputs_for_generationrjpop)rrjrrr set_inputssz#WhisperNoSpeechDetection.set_inputscCs|jSr!)rg)rrrrno_speech_probsz'WhisperNoSpeechDetection.no_speech_probcCr-r!rDrErrrrFr.z(WhisperNoSpeechDetection.set_begin_indexrrrcCs|j}|jd|jkrZ|jdkr?t|jdi|jj}Wdn1s)wY|j|j}|dd|f}d}n|}|rH| }n| j dd}|dd|j f|_ |S)Nr^Fr>rqr)rhr@rCrfrno_gradrirjrrrVrtrdrg)rrrrhrno_speech_indexno_speech_scoresrrrrrs    z!WhisperNoSpeechDetection.__call__N)F)rrrrr9rr<rkropropertyrprFr rrrrrrrrrrcs "rcc@s<eZdZdZddZeedejdej dej fddZ d S) %ClassifierFreeGuidanceLogitsProcessoran [`LogitsProcessor`] for classifier free guidance (CFG). The scores are split over the batch dimension, where the first half correspond to the conditional logits (predicted from the input prompt) and the second half correspond to the unconditional logits (predicted from an empty or 'null' prompt). The processor computes a weighted average across the conditional and unconditional logits, parameterised by the `guidance_scale`. See [the paper](https://arxiv.org/abs/2306.05284) for more information. This logits processor is exclusively compatible with [MusicGen](https://huggingface.co/docs/transformers/main/en/model_doc/musicgen) Args: 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. Examples: ```python >>> from transformers import AutoProcessor, MusicgenForConditionalGeneration >>> processor = AutoProcessor.from_pretrained("facebook/musicgen-small") >>> model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small") >>> inputs = processor( ... text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"], ... padding=True, ... return_tensors="pt", ... ) >>> audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256) ``` cCs"|dkr ||_dStd|d)Nr^z\Require guidance scale >1 to use the classifier free guidance processor, got guidance scale r)guidance_scaler.)rrvrrrr</s z.ClassifierFreeGuidanceLogitsProcessor.__init__rrrcCsp|jdd|jdkrtd|jdd|jdd|jdd}|j|dd\}}||||j}|S)NrrzLogits should have twice the batch size of the input ids, the first half of batches corresponding to the conditional inputs, and the second half of batches corresponding to the unconditional inputs. Got batch size z for the logits and z for the input ids.rq)r@r.splitrv)rrr unguided_bsz cond_logits uncond_logitsrGrrrr8sz.ClassifierFreeGuidanceLogitsProcessor.__call__N) rrrrr<r rrrrrrrrrrus & "ruc@sBeZdZdZdededefddZdejdejd ejfd d Z d S) #AlternatingCodebooksLogitsProcessora [`LogitsProcessor`] enforcing alternated generation between the two codebooks of Bark. This logits processor is exclusively compatible with [Bark](https://huggingface.co/docs/transformers/en/model_doc/bark)'s fine submodel. See the model documentation for examples. Args: 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. input_start_lensemantic_vocab_size codebook_sizecCs6t|tr |dkrtd|||_||_||_dS)NrzA`input_starting_length` has to be a non-negative integer, but is )r8r9r.r|r}r~)rr|r}r~rrrr<]s  z,AlternatingCodebooksLogitsProcessor.__init__rrrcCs|jd}||jddk}|}|r5td |ddd|jf<td |dd|j|jdf<|Std |ddd|j|jf<|S)Nr>rrrD)r@r|rArVr}r~)rrrcurr_lenis_first_codebookrGrrrres ""z,AlternatingCodebooksLogitsProcessor.__call__N) rrrrr9r<rrrrrrrrr{Hs r{c @sReZdZdZ   ddedeejdeejdeefdd Z d d Z d d Z dS).UnbatchedClassifierFreeGuidanceLogitsProcessora 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](https://arxiv.org/abs/2306.17806) for more information. Args: 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. model (`PreTrainedModel`): The model computing the unconditional scores. Supposedly the same as the one computing the conditional scores. Both models must use the same tokenizer. unconditional_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`, *optional*): Indices of input sequence tokens in the vocabulary for the unconditional branch. If unset, will default to the last token of the prompt. unconditional_attention_mask (`torch.LongTensor` of shape `(batch_size, sequence_length)`, *optional*): Attention mask for unconditional_ids. use_cache (`bool`, *optional*, defaults to `True`): Whether to cache key/values during the negative prompt forward pass. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM >>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2") >>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2") >>> inputs = tokenizer(["Today, a dragon flew over Paris, France,"], return_tensors="pt") >>> out = model.generate(inputs["input_ids"], guidance_scale=1.5) >>> tokenizer.batch_decode(out, skip_special_tokens=True)[0] 'Today, a dragon flew over Paris, France, killing at least 50 people and injuring more than 100' >>> # with a negative prompt >>> neg_inputs = tokenizer(["A very happy event happened,"], return_tensors="pt") >>> out = model.generate(inputs["input_ids"], guidance_scale=2, negative_prompt_ids=neg_inputs["input_ids"]) >>> tokenizer.batch_decode(out, skip_special_tokens=True)[0] 'Today, a dragon flew over Paris, France, killing at least 130 people. French media reported that' >>> # with a positive prompt >>> neg_inputs = tokenizer(["A very happy event happened,"], return_tensors="pt") >>> out = model.generate(inputs["input_ids"], guidance_scale=0, negative_prompt_ids=neg_inputs["input_ids"]) >>> tokenizer.batch_decode(out, skip_special_tokens=True)[0] "Today, a dragon flew over Paris, France, and I'm very happy to be here. I" ``` NTrvunconditional_idsunconditional_attention_mask use_cachecCs"||_||_|||ddd|_dS)NT)rattention_maskrpast_key_values first_pass)rvriunconditional_context)rrvrirrrrrrr<s z7UnbatchedClassifierFreeGuidanceLogitsProcessor.__init__cCsB|jdr>|jddur|ddddf|jd<|jddur.tj|jdtjd|jd<|jd}|jd}d|jd<nHtj|jdtj|ddddftjdgdd}|jd srtj|jd|ddddfgdd}n |ddddf}||jd<||jd<|j|||jd |jd d }|d d|jd <|jS) Nrrr>r)rFr^rqrr)rrr)rr ones_likelongcatrirr)rrroutrrrget_unconditional_logitss:      *  zGUnbatchedClassifierFreeGuidanceLogitsProcessor.get_unconditional_logitscCs^tjjj|dd}|jdkr|S||}tjjj|dddfdd}|j|||}|S)Nr>rqr^)rrrrrvr)rrrrunconditional_logitsrGrrrrs  z7UnbatchedClassifierFreeGuidanceLogitsProcessor.__call__)NNT) rrrrrVrrrrr<rrrrrrrus 7  $rc@s\eZdZdZddeeeeejfde de fddZ e e dejd ejd ejfd d Zd S)!BarkEosPrioritizerLogitsProcessoraThis processor ensures that the EOS token is selected if its probability is greater than the `min_eos_p`. This logits processor is exclusively compatible with [Bark](https://huggingface.co/docs/transformers/en/model_doc/bark). See the model documentation for examples. Args: eos_token_id (`Union[int, List[int], torch.Tensor]`): The id(s) of the *end-of-sequence* token. min_eos_p (`float`, *optional*): Minimum end of speech threshold. r3r5 min_eos_pr6cCs|t|tjst|tr|g}tj||d}||_t|s#|dkr*td||dur9|dkr9td|||_ dS)Nr7rr3z/`min_eos_p` has to be a positive float, but is ) r8rr:r9r;r5r4rr.r)rr5rr6rrrr<s   z*BarkEosPrioritizerLogitsProcessor.__init__rrrcCs|}|jrEtjjj|dd}t|td }|dd|jf|dd|jf<|dd|jf|jk}tj|ddd}t |||}|S)Nr>rqrDr^Tr) rrrrrtrVrr5rrB)rrrrGrearly_stop_scores do_early_stoprrrr s z*BarkEosPrioritizerLogitsProcessor.__call__NrH)rrrrrr9rrr:rVrJr<r rrrrrrrrrs ("rc @seZdZdZ     ddeded ed ed ef d d Zdej fddZ dej dej fddZ dej dej dej fddZ eedej dej dej fddZdS)WatermarkLogitsProcessora Logits processor for watermarking generated text. The processor modifies model output scores by adding a small bias to randomized set of "green" tokens before generating the next token. "Green" tokens selection process depends on the `seeding_scheme` used. The code was based on the [original repo](https://github.com/jwkirchenbauer/lm-watermarking/tree/main). The text generated by this `LogitsProcessor` can be detected using `WatermarkDetector`. See [`~WatermarkDetector.__call__`] for details, See [the paper](https://arxiv.org/abs/2306.04634) for more information. Args: vocab_size (`int`): The model tokenizer's vocab_size. Used to calculate "green" tokens ratio. device (`str`): The device where model is allocated. greenlist_ratio (`float`, optional, *optional*, defaults to 0.25): The ratio of "green" tokens used to the vocabulary size. Defaults to 0.25. bias (`float`, optional, *optional*, defaults to 2.0): The bias added to the selected "green" tokens' logits. Consider lowering the `bias` if the text generation quality degrades. Recommended values are in the range of [0.5, 2.0]. Defaults to 2.0. hashing_key (`int`, optional, *optional*, defaults to 15485863): Key used for hashing. If you deploy this watermark, we advise using another private key. Defaults to 15485863 (the millionth prime). seeding_scheme (`str`, optional, *optional*, defaults to `"lefthash"`): The seeding scheme used for selecting "green" tokens. Accepts values: - "lefthash" (default): "green" tokens selection depend on the last token (Algorithm 2 from paper) - "selfhash": "green" tokens selection depends on the current token itself (Algorithm 3 from paper) The downside of this scheme is that it considers all possible next tokens and can be slower than "lefthash". The context length of previous tokens to use in seeding. Higher context length makes watermarking more robust. context_width (`int`, *optional*, defaults to 1): The number of previous tokens to use when setting the seed. Examples: ```python >>> from transformers import AutoTokenizer, AutoModelForCausalLM, WatermarkingConfig >>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2") >>> tokenizer = AutoTokenizer.from_pretrained("openai-community/gpt2") >>> inputs = tokenizer(["Alice and Bob are"], return_tensors="pt") >>> # normal generation >>> out = model.generate(inputs["input_ids"], max_length=20, do_sample=False) >>> tokenizer.batch_decode(out, skip_special_tokens=True)[0] 'Alice and Bob are both in the same room.\n\n"I\'m not sure if you\'re' >>> # watermarked generation >>> watermarking_config = WatermarkingConfig(bias=2.5, context_width=2, seeding_scheme="selfhash") >>> out = model.generate(inputs["input_ids"], watermarking_config=watermarking_config, max_length=20, do_sample=False) >>> tokenizer.batch_decode(out, skip_special_tokens=True)[0] 'Alice and Bob are both still alive and well and the story is pretty much a one-hour adventure' >>> # to detect watermarked text use the WatermarkDetector class >>> from transformers import WatermarkDetector >>> detector = WatermarkDetector(model_config=model.config, device="cpu", watermarking_config= watermarking_config) >>> detection_preds = detector(out) >>> detection_preds array([ True]) ``` ?@Klefthashr^greenlist_ratior hashing_keyseeding_scheme context_widthcCs|dvr td||dks|dkrtd|||_t|j||_||_||_tj|d|_||_ ||_ |j |d|_ tj |j |j|d|_dS) N)selfhashrzDseeding_scheme has to be one of [`selfhash`, `lefthash`], but found rlrUzLgreenlist_ratio has be in range between 0.0 and 1.0, exclusively. but found r7iCB) generatorr6)r.r'r9greenlist_sizerrr Generatorrnghash_keyr manual_seed table_sizerandperm fixed_table)rr'r6rrrrrrrrr<X s   z!WatermarkLogitsProcessor.__init__ input_seqcCs||j d}|jdkr/|j||jd}|j|d|jd}|j||}n |j|d}|j|ddS)Nrr^r>l) rrrrrritemrr)rrabseedrrrset_seedu s z!WatermarkLogitsProcessor.set_seedrcCs2||tj|j|j|jd}|d|j}|S)N)r6r)rrrr'r6rr)rrvocab_permutation greenlist_idsrrr_get_greenlist_ids s z+WatermarkLogitsProcessor._get_greenlist_idsrcCsng}|jddd\}}tdD]}|tj|||dfgdd}|||vr.|||qtj||jdS)z Generate greenlist based on current candidate next token. Reject and move on if necessary. Runs for a fixed number of steps only for efficiency, since the methods is not batched. r>T)rrrp(Nrqr7)rsrrrrrr;r6)rrrfinal_greenlistrgreedy_predictionsrrrrr_score_rejection_sampling s   z2WatermarkLogitsProcessor._score_rejection_samplingrcCs|jd|jkrtd|jd|jdd|S|}t|D]$\}}|jdkr4||||}n||}|||f|j |||f<q"|S)Nr>z"`input_ids` should have at least `z` tokens but has z7. The seeding will be skipped for this generation step!r) r@rloggerwarningrArrrrr)rrrrGb_idxrrrrrr s  z!WatermarkLogitsProcessor.__call__N)rrrrr^)rrrrrVr9rJr<rrrrrrr rrrrrrr s.A  "rc@s,eZdZdZdedededejfddZdS) SynthIDTextWatermarkStatezSynthID watermarking state.r ngram_lencontext_history_sizer6cCs>tj||dftj|d|_tj||ftj|d|_d|_dS)aInitializes the state. Args: batch_size (`int`): Batch size. ngram_len (`int`): Ngram length. context_history_size (`int`): Size of the tensor to keep track of seen contexts. device (`int`): Device to use. r^rrN)rrint64contextcontext_history num_calls)rrrrr6rrrr< s  z"SynthIDTextWatermarkState.__init__N)rrrrr9rr6r<rrrrr src@s~eZdZdZ  d9dedeededededejd ed efd d Z d efddZ dej dej dej fddZ e edejdej dej fddZ  d:dejdejdededejf ddZd ejdejfd!d"Zd#ejd$ejdeejejffd%d&Zd'ejdejfd(d)Zdejfd*d+Zdejdejfd,d-Zdejdejfd.d/Zdejd0edejfd1d2Zd;d4ed5edefd6d7Zd8S)<#SynthIDTextWatermarkLogitsProcessora Logits processor that implements watermarking techniques for text generation models. This class facilitates the application of SynthID text watermarking, a method for embedding imperceptible signals into generated text to aid in detecting synthetic content. It operates by subtly manipulating the probabilities of token selection during text generation in a manner that can be reliably recovered later for verification. Key Features: * **State Management:** Maintains internal state to track token sequences and generate watermarking keys dynamically. * **Key Generation:** Computes hashes based on token sequences and watermarking parameters to create unique keys for each position. * **G-Value Sampling:** Employs a pre-computed sampling table to sample watermarking values (g-values) based on the generated keys. * **Score Adjustment:** Applies calculated g-values to modify token probabilities during generation, embedding the watermark. * **Context Repetition Handling:** Incorporates logic to avoid watermarking tokens in repeated contexts, preserving naturalness. * **EOS Token Masking:** Supports masking end-of-sentence tokens to prevent their inclusion in watermarking calculations. * **Utility Functions:** Provides functions to compute g-values directly, check for context repetition, create EOS token masks, and estimate expected mean g-values. Refer to paper url: https://www.nature.com/articles/s41586-024-08025-4 for more details around this. Args: ngram_len (`int`): Ngram length. keys (`List[int]`): A sequence of watermarking keys, one for each depth. sampling_table_size (`int`): Size of the sampling table. sampling_table_seed (`int`): Random seed to generate the sampling table. context_history_size (`int`): Size of the tensor to keep track of seen contexts. device (`torch.device`): Device to use. skip_first_ngram_calls (`bool`, *optional*, defaults to `False`): Whether to skip first ngram calls. debug_mode (`bool`, optional, *optional*, defaults to `False`): Logits are modified to uniform one got before watermarking modification is applied. This is to test the implementation. Examples: ```python >>> from transformers import AutoModelForCausalLM, AutoTokenizer, SynthIDTextWatermarkingConfig >>> tokenizer = AutoTokenizer.from_pretrained('google/gemma-2-2b', padding_side="left") >>> model = AutoModelForCausalLM.from_pretrained('google/gemma-2-2b') >>> # SynthID Text configuration >>> watermarking_config = SynthIDTextWatermarkingConfig( ... keys=[654, 400, 836, 123, 340, 443, 597, 160, 57], ... ngram_len=5, ... ) >>> # Generation with watermarking >>> tokenized_prompts = tokenizer(["Once upon a time, "], return_tensors="pt", padding=True) >>> output_sequences = model.generate( ... **tokenized_prompts, watermarking_config=watermarking_config, do_sample=True, max_new_tokens=10 ... ) >>> watermarked_text = tokenizer.batch_decode(output_sequences, skip_special_tokens=True) ``` Frr-sampling_table_sizesampling_table_seedrr6skip_first_ngram_calls debug_modec Csb||_tj||d|_tj|d|} tjdd|f| |d|_||_||_ d|_ ||_ ||_ dS)Nr7rr)lowhighrrr6) rrr;r-rrrandintsampling_tablerr6staterr) rrr-rrrr6rrrrrrr< s  z,SynthIDTextWatermarkLogitsProcessor.__init__rcCst||j|j|jd|_dS)zInitializes the state.rrrr6N)rrrr6r)rrrrr _init_state0 s  z/SynthIDTextWatermarkLogitsProcessor._init_staterg_valuesrc Cs|j\}}}tj|dd}t|D]}|dddd|f}||jddd}|d||}qt|} tt| | t| j j } | S)aYUpdates scores using the g values. We assume that the scores are in the log space. Args: scores (`torch.FloatTensor`): Scores (batch_size, vocab_size). g_values (`torch.FloatTensor`): G valus (batch_size, vocab_size, depth). Returns: Updated scores (batch_size, vocab_size). r^rqNT)axiskeepdims) r@rrtrrlogrBisfiniter6rr) rrrrdepthrrg_values_at_depthg_mass_at_depth log_probsrrr update_scores9 s   z1SynthIDTextWatermarkLogitsProcessor.update_scoresrc sf||j\}jrt|}tfddt|D}jdur,|n#tj jj |ddddffddj_ jj ddddfj_ jdurXt djj d7_ j rljj jkrl|Sjj |\}}|}||}|dddf}jj|kjddd} tj |jjfddddddfj_tj| ||d } | S) Ncsg|] }tjjdqS)r7)rr?r6rrr'rrrZ sz@SynthIDTextWatermarkLogitsProcessor.__call__..r>r^rqzJself.state can't be None! Call `self._init_state` to initialize the state.Tr)inputother)_check_input_ids_shaper@rrrstackrrrconcatrr.rrr _compute_keyssample_g_valuesrrrrB) rrrr all_indices ngram_keyshash_result_with_just_contextrupdated_scoresis_repeated_contextupdated_watermarked_scoresrrrrQ sJ           z,SynthIDTextWatermarkLogitsProcessor.__call__-*PBr^ current_hashdata multiplier incrementcCsDt|jdD]}t||d|f}t||}t||}q|S)aG Accumulate hash of data on current hash. Method uses adapted linear congruential generator with newlib/musl parameters. This function has following property - f(x, data[T]) = f(f(x, data[:T - 1]), data[T]) This function expects current_hash.shape and data.shape[:-1] to match/broadcastable. Args: current_hash (`torch.LongTensor`): (shape,) data (`torch.LongTensor`): (shape, tensor_len) multiplier (`int`, optional, *optional*, defaults to 6364136223846793005): multiplier of linear congruential generator increment (`int`, optional, *optional*, defaults to 1): increment of linear congruential generator Returns: updated hash (shape,) r>.)rr@raddmul)rrrrrrrrraccumulate_hash s  z3SynthIDTextWatermarkLogitsProcessor.accumulate_hashngramscCst|jdkrtd|j|jd|jkr#td|jd|j|j\}}}tj||jtjd}tj|j ddd ||}|j d d d d d f}tj|j d dd ||}|S) zComputes random keys for each ngram and depth. Args: ngrams (`torch.LongTensor`): Ngrams (batch_size, num_ngrams, ngram_len). Returns: ngram keys (batch_size, num_ngrams, depth). zFNgrams should be of shape (batch_size, num_ngrams, ngram_len), but is rzRNgrams should be of shape (batch_size, num_ngrams, ngram_len), where ngram_len is z , but is r6rNr^r^in_dimsout_dimsNNr) r*r@r.rronesr6rvmaprr-)rrrr hash_resultr-rrrcompute_ngram_keys s   z6SynthIDTextWatermarkLogitsProcessor.compute_ngram_keysn_minus_1_gramsindicescCs|j\}}tj||jtjd}|||}tj|jddd||dddddf}|jdddddf}tj|jddd||}||fS)ahComputes random keys for each ngram and depth. Args: n_minus_1_grams (`torch.LongTensor`): Ngrams (batch_size, ngram_len - 1). indices (`torch.LongTensor`): indices of the continuations (batch_size, num_indices) Returns: Ngram keys (batch_size, num_indices, depth). rrr^rNrr)r@rrr6rrrr-)rrrrrrrr-rrrr s   z1SynthIDTextWatermarkLogitsProcessor._compute_keysrcCs4|jj\}|jdd|f}||}tj||ddS)a Samples g values from Bernoulli distribution. It is not possible to pass random keys in a vectorized way in torch. Instead we pre-compute a random sampling table, and use apply modulo table size to map from ngram keys (int64) to g values. Args: ngram_keys (`torch.LongTensor`): Random keys (batch_size, num_ngrams, depth). Returns: G values (batch_size, num_ngrams, depth). r^r)rrr)rr@reshapertake_along_dim)rrrrrrrr s z3SynthIDTextWatermarkLogitsProcessor.sample_g_valuescCs"t|jdkrtd|jdS)zChecks the shape of input ids.rz=Input ids should be of shape (batch_size, input_len), but is N)r*r@r.)rrrrrr sz:SynthIDTextWatermarkLogitsProcessor._check_input_ids_shapecCs0|||jd|jdd}||}||S)a" Computes g values for each ngram from the given sequence of tokens. Args: input_ids (`torch.LongTensor`): Input token ids (batch_size, input_len). Returns: G values (batch_size, input_len - (ngram_len - 1), depth). r^ dimensionrstep)runfoldrrr)rrrrrrrcompute_g_values s   z4SynthIDTextWatermarkLogitsProcessor.compute_g_valuesc Cs |||j\}}t||j|j|jd}|ddddfjd|jddd}|j\}}}g}t|D]E}|dd|ddf} tj ||jtj d} | | | dddf} |j | kj ddd} || tj| |j fdd ddddf|_ q4tj|dd }t|S) aN Computes repetition mask. 0 and 1 stand for repeated and not repeated context n-1 grams respectively. Args: input_ids (`torch.LongTensor`): Input token ids (batch_size, input_len). Returns: Repetitions mask (batch_size, input_len - (ngram_len - 1)). rNr>r^rrTrrq)rr@rrrr6rrrrrrrrrr logical_not) rrrrrcontexts num_contextsare_repeated_contextsrrr context_hashrrrrcompute_context_repetition_mask' s@      zCSynthIDTextWatermarkLogitsProcessor.compute_context_repetition_maskr5cCsn||g}||k}|D]"}t|}t|}|jddkr*d||ddd<||q tj|ddS)aq Computes repetitions mask. 1 stands for ngrams that don't contain EOS tokens and vice versa. Args: input_ids (`torch.LongTensor`): Input token ids (batch_size, input_len). eos_token_id (`int`): EOS token ID. Returns: EOS token mask (batch_size, input_len). rNrq)rrnonzerorr@rr)rrr5 noneos_masksall_eos_equated eos_equated nonzero_idx noneos_maskrrrcompute_eos_token_maskU s    z:SynthIDTextWatermarkLogitsProcessor.compute_eos_token_mask?r' coinflip_probcCs||d|dd|S)a Compute expected mean g-value after watermarking, assuming uniform LM dist. This is the theoretical expected value for single-layer watermarking. Args: vocab_size (`int`): The size of the vocabulary. coinflip_prob arg_name (`float`, *optional*, defaults to 0.5): Probability of 1 in boolean prf. Returns: The expected mean g-value for watermarked text. r^r)rr'r rrrexpected_mean_g_valueo sz9SynthIDTextWatermarkLogitsProcessor.expected_mean_g_valueN)FF)rr^)r )rrrrr9rrr6rr<rrrr rrrrrrrrrrrr rVr rrrrr shO ! B %! (.r)>r'rCtypingrrrrrrnumpyrr pytorch_utilsr utilsr utils.loggingr rrrr r,r r2rKrSrZrdrgr}rrrrr9r:rrrrrrrrrr+r1r5r7r?r@rIrKrcrur{rrrrrrrrrs|     &=HB67C5MXET  ;E2[H -8e%5( 9@-v/