# 생성을 위한 유틸리티

이 페이지는 [generate()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin.generate)에서 사용되는 모든 유틸리티 함수를 나열합니다.

## 출력 생성[[transformers.generation.GenerateDecoderOnlyOutput]]

[generate()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin.generate)의 출력은 [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput)의 하위 클래스 인스턴스입니다. 이 출력은 [generate()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin.generate)가 반환하는 모든 정보를 포함하는 데이터 구조이며, 동시에 튜플이나 딕셔너리처럼 사용할 수도 있습니다.

다음은 예시입니다:

```python
from transformers import GPT2Tokenizer, GPT2LMHeadModel

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

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

`generation_output` 객체는 [GenerateDecoderOnlyOutput](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.generation.GenerateDecoderOnlyOutput)이며, 아래 해당 클래스의 문서에서 확인할 수 있듯이 다음 속성을 가집니다:

- `sequences`: 생성된 토큰 시퀀스
- `scores` (선택 사항): 각 생성 단계에 대한 언어 모델링 헤드의 예측 점수
- `hidden_states` (선택 사항): 각 생성 단계에 대한 모델의 hidden states
- `attentions` (선택 사항): 각 생성 단계별 모델의 어텐션 가중치

`output_scores=True`를 전달했기 때문에 `scores`가 있지만, `output_hidden_states=True`나 `output_attentions=True`를 전달하지 않았기 때문에 `hidden_states`와 `attentions`는 없습니다.

각 속성은 일반적인 방식으로 접근할 수 있으며, 해당 속성이 모델에 의해 반환되지 않은 경우 `None`을 반환합니다. 예를 들어 `generation_output.scores`는 언어 모델링 헤드에서 생성된 모든 예측 점수이고, `generation_output.attentions`는 `None`입니다.

`generation_output` 객체를 튜플로 사용할 때, `None` 값이 없는 속성만 유지됩니다. 예를 들어 여기서는 `loss`와 `logits` 두 개의 요소가 있으므로

```python
generation_output[:2]
```

예를 들어 `(generation_output.sequences, generation_output.scores)` 튜플을 반환합니다.

`generation_output` 객체를 사전으로 사용할 때, `None` 값이 없는 속성만 유지됩니다. 예를 들어 여기서는 `sequences`와 `scores`라는 두 개의 키가 있습니다.

여기서는 모든 출력 유형을 문서화합니다.

#### transformers.generation.GenerateDecoderOnlyOutput[[transformers.generation.GenerateDecoderOnlyOutput]]

```python
transformers.generation.GenerateDecoderOnlyOutput(sequences: LongTensor, scores: tuple[torch.Tensor] | None = None, logits: tuple[torch.Tensor] | None = None, attentions: tuple[tuple[torch.Tensor]] | None = None, hidden_states: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/utils.py#L183)

**매개변수:**

sequences (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 생성된 시퀀스입니다. 두 번째 차원(sequence_length)은 `max_length`와 같거나, `eos_token_id`로 인해 모든 배치에서 조기 종료된 경우보다 짧을 수 있습니다.

scores (`tuple(torch.Tensor)` *선택*, `output_scores=True`일 때 반환됨) : 각 생성 단계에서 언어 모델링 헤드(SoftMax 적용 전 각 어휘 토큰의 점수)의 처리된 예측 점수. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다.

logits (`tuple(torch.Tensor)` *선택*, `output_logits=True`일 때 반환됨) : 각 생성 단계에서 언어 모델링 헤드(소프트맥스 적용 전 어휘 토큰별 점수)의 처리되지 않은 예측 점수. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 형태는 `(batch_size, config.vocab_size)`입니다.

attentions (`tuple(tuple(torch.Tensor))`, *선택*, `output_attentions=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가지는 튜플로, 각 요소는 디코더의 각 레이어마다 하나의 요소를 가지는 튜플이며, 그 형태는 `(batch_size, num_heads, generated_length, sequence_length)`인 `torch.Tensor`입니다.

hidden_states (`tuple(tuple(torch.Tensor))`, *선택*, `output_hidden_states=True`일 때 반환됨) : 생성된 각 토큰에 대해 하나의 요소를 가진 튜플로, 디코더의 각 레이어에 대해 하나의 요소를 가진 `torch.Tensor` 튜플이며, 형태는 `(batch_size, generated_length, hidden_size)`입니다.

past_key_values (`Cache`, *선택*, `use_cache=True`일 때 반환됨): 디코딩 속도를 높이는 데 사용되는 모델 캐시를 반환합니다. 모델마다 캐시 형식이 다르므로 해당 모델의 문서를 확인하세요. 일반적으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다.

비빔(non-beam) 방법을 사용할 때, 디코더 전용 생성 모델의 출력입니다.

#### transformers.generation.GenerateEncoderDecoderOutput[[transformers.generation.GenerateEncoderDecoderOutput]]

```python
transformers.generation.GenerateEncoderDecoderOutput(sequences: LongTensor, scores: tuple[torch.Tensor] | None = None, logits: tuple[torch.Tensor] | None = None, encoder_attentions: tuple[torch.Tensor] | None = None, encoder_hidden_states: tuple[torch.Tensor] | None = None, decoder_attentions: tuple[tuple[torch.Tensor]] | None = None, cross_attentions: tuple[tuple[torch.Tensor]] | None = None, decoder_hidden_states: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/utils.py#L219)

**매개변수:**

sequences (`torch.LongTensor`, shape `(batch_size*num_return_sequences, sequence_length)`) : 생성된 시퀀스입니다. 두 번째 차원(sequence_length)은 `max_length`와 같거나, `eos_token_id`로 인해 모든 배치에서 조기에 종료된 경우보다 짧을 수 있습니다.

scores (`tuple(torch.Tensor)` *선택*, `output_scores=True`일 때 반환됨) : 각 생성 단계에서 언어 모델링 헤드(SoftMax 적용 전 각 어휘 토큰의 점수)의 처리된 예측 점수. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다.

logits (`tuple(torch.Tensor)` *선택*, `output_logits=True`일 때 반환됨) : 각 생성 단계에서 언어 모델링 헤드(소프트맥스 적용 전 어휘 토큰별 점수)의 처리되지 않은 예측 점수. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 형태는 `(batch_size, config.vocab_size)`입니다.

encoder_attentions (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`일 때 반환됨) : 각 디코더 레이어에 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

encoder_hidden_states (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`일 때 반환됨) : `torch.Tensor`의 튜플 (임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 `(batch_size, sequence_length, hidden_size)`입니다.

decoder_attentions (`tuple(tuple(torch.Tensor))`, *선택*, `output_attentions=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가지는 튜플로, 각 요소는 디코더의 각 레이어마다 하나의 요소를 가지는 튜플이며, 그 형태는 `(batch_size, num_heads, generated_length, sequence_length)`인 `torch.Tensor`입니다.

cross_attentions (`tuple(tuple(torch.Tensor))`, *선택*, `output_attentions=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가지는 튜플로, 각 요소는 디코더의 각 레이어마다 하나의 요소를 가지는 튜플이며, 그 형태는 `(batch_size, num_heads, generated_length, sequence_length)`인 `torch.Tensor`입니다.

decoder_hidden_states (`tuple(tuple(torch.Tensor))`, *선택*, `output_hidden_states=True`일 때 반환됨) : 생성된 각 토큰에 대해 하나의 요소를 가진 튜플로, 디코더의 각 레이어에 대해 하나의 요소를 가진 `torch.Tensor` 튜플이며, 형태는 `(batch_size, generated_length, hidden_size)`입니다.

past_key_values (`Cache`, *선택*, `use_cache=True`일 때 반환됨): 디코딩 속도를 높이는 데 사용되는 모델 캐시를 반환합니다. 모델마다 캐시 형식이 다르므로 해당 모델의 문서를 확인하세요. 일반적으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다.

비빔(non-beam) 방법을 사용할 때 인코더-디코더 생성 모델의 출력입니다.

#### transformers.generation.GenerateBeamDecoderOnlyOutput[[transformers.generation.GenerateBeamDecoderOnlyOutput]]

```python
transformers.generation.GenerateBeamDecoderOnlyOutput(sequences: LongTensor, sequences_scores: typing.Optional[torch.Tensor] = None, scores: tuple[torch.Tensor] | None = None, logits: tuple[torch.Tensor] | None = None, beam_indices: typing.Optional[torch.LongTensor] = None, attentions: tuple[tuple[torch.Tensor]] | None = None, hidden_states: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/utils.py#L267)

**매개변수:**

sequences (`torch.LongTensor`, shape `(batch_size*num_return_sequences, sequence_length)`) : 생성된 시퀀스입니다. 두 번째 차원(sequence_length)은 `max_length`와 같거나, `eos_token_id`로 인해 모든 배치에서 조기에 종료된 경우보다 짧을 수 있습니다.

sequences_scores (`torch.Tensor`, shape `(batch_size*num_return_sequences)`, *선택 사항*, `output_scores=True`일 때 반환됨) : 생성된 `sequences`의 최종 beam scores.

scores (`tuple(torch.Tensor)` *선택 사항*, `output_scores=True`일 때 반환됨) : 각 생성 단계에서 어휘의 각 토큰에 대한 Beam transition scores. 이 beam에서 이전에 생성된 토큰의 log softmax에 조건부인 토큰의 log 확률로 구성된 Beam transition scores입니다. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 shape은 `(batch_size*num_beams, config.vocab_size)`입니다.

logits (`tuple(torch.Tensor)` *선택*, `output_logits=True`일 때 반환됨) : 각 생성 단계에서 언어 모델링 헤드(소프트맥스 적용 전 어휘 토큰별 점수)의 처리되지 않은 예측 점수. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 모양은 `(batch_size*num_beams, config.vocab_size)`입니다.

beam_indices (`torch.LongTensor`, *선택*, `output_scores=True`일 때 반환됨) : 각 생성 단계에서 생성된 토큰 id의 beam 인덱스. `torch.LongTensor`이며, 형태는 `(batch_size*num_return_sequences, sequence_length)`입니다.

attentions (`tuple(tuple(torch.Tensor))`, *선택*, `output_attentions=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가진 튜플로, 디코더의 각 레이어마다 하나의 요소를 가진 튜플이며, 각 요소는 `(batch_size*num_beams, num_heads, generated_length, sequence_length)` 모양의 `torch.Tensor`입니다.

hidden_states (`tuple(tuple(torch.Tensor))`, *선택*, `output_hidden_states=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가진 튜플로, 디코더의 각 레이어마다 하나의 요소를 가진 튜플이며, 각 요소는 `(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)` 모양의 `torch.Tensor`입니다.

past_key_values (`Cache`, *선택*, `use_cache=True`일 때 반환됨): 디코딩 속도를 높이는 데 사용되는 모델 캐시를 반환합니다. 모델마다 캐시 형식이 다르므로 해당 모델의 문서를 확인하세요. 일반적으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다.

beam 방법을 사용하는 decoder-only 생성 모델의 출력입니다.

#### transformers.generation.GenerateBeamEncoderDecoderOutput[[transformers.generation.GenerateBeamEncoderDecoderOutput]]

```python
transformers.generation.GenerateBeamEncoderDecoderOutput(sequences: LongTensor, sequences_scores: typing.Optional[torch.Tensor] = None, scores: tuple[torch.Tensor] | None = None, logits: tuple[torch.Tensor] | None = None, beam_indices: typing.Optional[torch.LongTensor] = None, encoder_attentions: tuple[torch.Tensor] | None = None, encoder_hidden_states: tuple[torch.Tensor] | None = None, decoder_attentions: tuple[tuple[torch.Tensor]] | None = None, cross_attentions: tuple[tuple[torch.Tensor]] | None = None, decoder_hidden_states: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/utils.py#L311)

**매개변수:**

sequences (`torch.LongTensor`, shape `(batch_size*num_return_sequences, sequence_length)`) : 생성된 시퀀스입니다. 두 번째 차원(sequence_length)은 `max_length`와 같거나, `eos_token_id`로 인해 모든 배치에서 조기에 종료된 경우보다 짧을 수 있습니다.

sequences_scores (`torch.Tensor`, shape `(batch_size*num_return_sequences)`, *선택 사항*, `output_scores=True`일 때 반환됨) : 생성된 `sequences`의 최종 beam scores.

scores (`tuple(torch.Tensor)` *선택 사항*, `output_scores=True`일 때 반환됨) : 각 생성 단계에서 어휘의 각 토큰에 대한 Beam transition scores. 이 beam에서 이전에 생성된 토큰의 log softmax에 조건부인 토큰의 log 확률로 구성된 Beam transition scores입니다. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 shape은 `(batch_size*num_beams, config.vocab_size)`입니다.

logits (`tuple(torch.Tensor)` *선택*, `output_logits=True`일 때 반환됨) : 각 생성 단계에서 언어 모델링 헤드(소프트맥스 적용 전 어휘 토큰별 점수)의 처리되지 않은 예측 점수. `torch.Tensor`의 튜플로, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 가지며, 각 텐서의 모양은 `(batch_size*num_beams, config.vocab_size)`입니다.

beam_indices (`torch.LongTensor`, *선택*, `output_scores=True`일 때 반환됨) : 각 생성 단계에서 생성된 토큰 id의 beam 인덱스. `torch.LongTensor`이며, 형태는 `(batch_size*num_return_sequences, sequence_length)`입니다.

encoder_attentions (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`일 때 반환됨) : 각 디코더 레이어에 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

encoder_hidden_states (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`일 때 반환됨) : 임베딩 출력 1개와 각 레이어 출력 1개씩을 포함하는 `torch.Tensor` 튜플로, 모양은 `(batch_size*num_beams*num_return_sequences, sequence_length, hidden_size)`입니다.

decoder_attentions (`tuple(tuple(torch.Tensor))`, *선택*, `output_attentions=True`일 때 반환됨) : 생성된 각 토큰에 대해 하나의 요소를 가지는 튜플로, 각 요소는 디코더의 각 레이어에 대해 하나의 요소를 가지는 튜플이며, 형태가 `(batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length)`인 `torch.Tensor`입니다.

cross_attentions (`tuple(tuple(torch.Tensor))`, *선택*, `output_attentions=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가지는 튜플로, 각 요소는 디코더의 각 레이어마다 하나의 요소를 가지는 튜플이며, 그 형태는 `(batch_size, num_heads, generated_length, sequence_length)`인 `torch.Tensor`입니다.

decoder_hidden_states (`tuple(tuple(torch.Tensor))`, *선택*, `output_hidden_states=True`일 때 반환됨) : 생성된 각 토큰마다 하나의 요소를 가진 튜플로, 디코더의 각 레이어마다 하나의 요소를 가진 튜플이며, 각 요소는 `(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)` 모양의 `torch.Tensor`입니다.

past_key_values (`Cache`, *선택*, `use_cache=True`일 때 반환됨): 디코딩 속도를 높이는 데 사용되는 모델 캐시를 반환합니다. 모델마다 캐시 형식이 다르므로 해당 모델의 문서를 확인하세요. 일반적으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다.

beam 방법을 사용하는 인코더-디코더 생성 모델의 출력입니다.

## LogitsProcessor[[transformers.AlternatingCodebooksLogitsProcessor]]

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 생성을 위해 언어 모델 헤드의 예측 점수를 수정하는 데 사용할 수 있습니다.

#### transformers.AlternatingCodebooksLogitsProcessor[[transformers.AlternatingCodebooksLogitsProcessor]]

```python
transformers.AlternatingCodebooksLogitsProcessor(input_start_len: int, semantic_vocab_size: int, codebook_size: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2228)

**매개변수:**

input_start_len (`int`) : 초기 입력 시퀀스의 길이.

semantic_vocab_size (`int`) : 의미론적 부분의 어휘 크기, 즉 의미론적 어휘와 연관된 토큰의 수.

codebook_size (`int`) : 코드북에 연결된 토큰의 수.

Bark의 두 코드북 사이에서 번갈아 생성되도록 강제하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다.

이 logits processor는 [Bark](https://huggingface.co/docs/transformers/en/model_doc/bark)의 fine 서브모델과만 호환됩니다. 예제는 모델 문서를 참고하세요.

#### __call__[[transformers.AlternatingCodebooksLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2257)

#### transformers.ClassifierFreeGuidanceLogitsProcessor[[transformers.ClassifierFreeGuidanceLogitsProcessor]]

```python
transformers.ClassifierFreeGuidanceLogitsProcessor(guidance_scale)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2164)

**매개변수:**

guidance_scale (float) : classifier free guidance(CFG)의 guidance scale입니다. `guidance_scale > 1`로 설정하면 CFG가 활성화됩니다. guidance scale이 높을수록 모델은 입력 프롬프트와 더 밀접하게 연결된 샘플을 생성하도록 유도되며, 일반적으로 품질 저하를 감수해야 합니다.

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 classifier free guidance(CFG)에 사용됩니다. 점수는 배치 차원으로 나뉘며, 첫 번째 절반은 조건부 logits(입력 프롬프트에서 예측된 값)에, 두 번째 절반은 무조건부 logits(빈 프롬프트 또는 'null' 프롬프트에서 예측된 값)에 해당합니다. 이 프로세서는 `guidance_scale`로 매개변수화된 가중 평균을 조건부 logits와 무조건부 logits에 대해 계산합니다.

자세한 내용은 [논문](https://huggingface.co/papers/2306.05284)을 참고하세요.

이 logits 프로세서(로짓 프로세서)는 [MusicGen](https://huggingface.co/docs/transformers/main/en/model_doc/musicgen)과만 호환됩니다.

예:

```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)
```

#### __call__[[transformers.ClassifierFreeGuidanceLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2212)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.EncoderNoRepeatNGramLogitsProcessor[[transformers.EncoderNoRepeatNGramLogitsProcessor]]

```python
transformers.EncoderNoRepeatNGramLogitsProcessor(encoder_ngram_size: int, encoder_input_ids: LongTensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1173)

**매개변수:**

encoder_ngram_size (`int`) : `ngram_size` 크기의 모든 ngram은 인코더 입력 id 내에서만 발생할 수 있습니다.

encoder_input_ids (`int`) : decoder ids 내에서 반복되어서는 안 되는 encoder_input_ids.

[NoRepeatNGramLogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.NoRepeatNGramLogitsProcessor)와 유사하게 작동하지만, 프롬프트에 존재하는 n-gram의 반복을 방지하는 데만 적용되는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다.

이 기능은 이전 대화 라운드에 존재하는 n-gram의 생성을 방지하여 언어 모델의 대화적 성격을 촉진하도록 설계되었습니다.

예:

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

#### __call__[[transformers.EncoderNoRepeatNGramLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1222)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.EncoderRepetitionPenaltyLogitsProcessor[[transformers.EncoderRepetitionPenaltyLogitsProcessor]]

```python
transformers.EncoderRepetitionPenaltyLogitsProcessor(penalty: float, encoder_input_ids: LongTensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L440)

**매개변수:**

penalty (`float`) : 반복 페널티를 위한 매개변수입니다. 1.0은 페널티가 없음을 의미합니다. 1.0보다 큰 값은 프롬프트 토큰에 보상을 부여하고, 0.0과 1.0 사이의 값은 프롬프트 토큰에 페널티를 부과합니다.

encoder_input_ids (`torch.LongTensor`) : decoder ids 내에서 반복되어야 하는 encoder_input_ids입니다.

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 [RepetitionPenaltyLogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.RepetitionPenaltyLogitsProcessor)와 유사하게 동작하지만, 프롬프트에 포함된 토큰에 *역* 페널티를 적용합니다. 즉, 1.0보다 큰 페널티 값은 프롬프트에 이미 존재했던 토큰이 선택될 확률을 높입니다.

입력에 기반한 작업, 예를 들어 요약과 같은 작업에서 환각(hallucination)을 방지하도록 설계되었습니다. 원래 인코더-디코더 모델을 위해 의도되었지만, LLM과 같은 디코더 전용 모델에도 사용할 수 있습니다.

예:

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

#### __call__[[transformers.EncoderRepetitionPenaltyLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L486)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.EpsilonLogitsWarper[[transformers.EpsilonLogitsWarper]]

```python
transformers.EpsilonLogitsWarper(epsilon: float, filter_value: float = -inf, min_tokens_to_keep: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L897)

**매개변수:**

epsilon (`float`) : 0보다 큰 값으로 설정하면, 확률이 `epsilon` 이상인 토큰 중 가장 확률이 높은 토큰만 생성에 유지됩니다.

filter_value (`float`, *선택 사항*, 기본값 -inf) : 모든 필터링된 값이 이 float 값으로 설정됩니다.

min_tokens_to_keep (`int`, *선택 사항*, 기본값 1) : 필터링할 수 없는 최소 토큰 수입니다.

`prob >= epsilon`인 토큰으로 제한하는 epsilon-sampling을 수행하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 이 조건을 만족하는 토큰이 없으면 가장 큰 min_tokens_to_keep개의 토큰을 선택합니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://huggingface.co/papers/2210.15191)을 참조하세요.

예:
```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) ;
<BLANKLINE>
<BLANKLINE>

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

#### __call__[[transformers.EpsilonLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L952)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.EtaLogitsWarper[[transformers.EtaLogitsWarper]]

```python
transformers.EtaLogitsWarper(epsilon: float, filter_value: float = -inf, min_tokens_to_keep: int = 1, device: str = 'cpu')
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L966)

**매개변수:**

epsilon (`float`) : (0, 1) 범위의 float 값. 동적 cutoff 값인 `eta`를 계산하는 데 사용되는 하이퍼파라미터입니다. 논문에서 제안된 값은 모델 크기에 따라 3e-4에서 4e-3 범위입니다.

filter_value (`float`, *선택 사항*, 기본값 -inf) : 동적 컷오프 값 `eta`보다 낮은 것으로 판정된 모든 값은 이 float 값으로 설정됩니다. 이 매개변수는 생성 과정에서 완전히 제외해야 하는 매우 낮은 확률의 토큰에 대해 logits를 수정해야 할 때 유용합니다.

min_tokens_to_keep (`int`, *선택 사항*, 기본값 1) : 확률과 무관하게 생성에 유지해야 하는 최소 토큰 수를 지정합니다. 예를 들어, `min_tokens_to_keep`가 1로 설정되어 있으면, 모든 토큰의 확률이 임계값 `eta`보다 낮더라도 생성을 위해 항상 최소 1개의 토큰이 유지됩니다.

device (`str`, *선택 사항*, 기본값 `"cpu"`) : 텐서를 할당할 장치입니다.

동적 임계값 `eta`보다 확률이 낮은 토큰을 필터링하는 기법인 eta-sampling을 수행하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. `eta`는 하이퍼파라미터 `epsilon`과 토큰 확률의 엔트로피를 조합하여 계산되며, 즉 `eta := min(epsilon, sqrt(epsilon * e^-entropy(probabilities)))`입니다. 이 제약 조건을 만족하는 토큰이 없으면 가장 큰 min_tokens_to_keep개의 토큰을 선택합니다. 신경 언어 모델이 생성하는 긴 텍스트 샘플의 품질 저하 문제를 해결하여 더 일관되고 유창한 텍스트를 생성합니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://huggingface.co/papers/2210.15191)를 참고하세요. 참고: 이 `LogitsProcessor`가 작동하려면 `do_sample`을 `True`로 설정해야 합니다.

예:
```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) ;
<BLANKLINE>
<BLANKLINE>

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

#### __call__[[transformers.EtaLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1035)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.ExponentialDecayLengthPenalty[[transformers.ExponentialDecayLengthPenalty]]

```python
transformers.ExponentialDecayLengthPenalty(exponential_decay_length_penalty: tuple[int, float], eos_token_id: typing.Union[int, list[int], torch.Tensor], input_ids_seq_length: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1718)

**매개변수:**

exponential_decay_length_penalty (`tuple(int, float)`) : 이 튜플은 `(start_index, decay_factor)`로 구성되며, `start_index`는 페널티가 시작되는 위치를 나타내고 `decay_factor`는 지수 감쇠의 계수를 나타냅니다

eos_token_id (`Union[int, list[int], torch.Tensor]`) : *end-of-sequence* 토큰의 id입니다.

input_ids_seq_length (`int`) : 입력 시퀀스의 길이.

`start_index`에 도달한 후 `eos_token_id`의 점수를 지수적으로 증가시키는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 이를 통해 하드 컷오프 없이 더 짧은 시퀀스를 생성할 수 있으며, `eos_token`이 의미 있는 위치에서 예측되도록 합니다.

예:

```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|>
```

#### __call__[[transformers.ExponentialDecayLengthPenalty.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1804)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.ForcedBOSTokenLogitsProcessor[[transformers.ForcedBOSTokenLogitsProcessor]]

```python
transformers.ForcedBOSTokenLogitsProcessor(bos_token_id: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1596)

**매개변수:**

bos_token_id (`int`) : 첫 번째로 생성할 토큰으로 강제할 토큰의 id입니다.

지정된 토큰을 첫 번째 생성 토큰으로 강제하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor). 인코더-디코더 모델과 함께 사용됩니다.

예:

```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])
<pad> Ich liebe Kitty.</s>

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

#### __call__[[transformers.ForcedBOSTokenLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1631)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.ForcedEOSTokenLogitsProcessor[[transformers.ForcedEOSTokenLogitsProcessor]]

```python
transformers.ForcedEOSTokenLogitsProcessor(max_length: int, eos_token_id: typing.Union[int, list[int], torch.Tensor], device: str = 'cpu')
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1641)

**매개변수:**

max_length (`int`) : 생성할 시퀀스의 최대 길이입니다.

eos_token_id (`Union[int, list[int], torch.Tensor]`) : *end-of-sequence* 토큰의 id입니다.

device (`str`, *선택 사항*, 기본값 `"cpu"`) : 텐서를 할당할 장치입니다.

`max_length`에 도달했을 때 지정된 토큰을 마지막 생성 토큰으로 강제하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다.

예:

```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|>
```

#### __call__[[transformers.ForcedEOSTokenLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1687)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.InfNanRemoveLogitsProcessor[[transformers.InfNanRemoveLogitsProcessor]]

```python
transformers.InfNanRemoveLogitsProcessor()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1697)

생성 방식이 실패하지 않도록 모든 `nan` 및 `inf` 값을 제거하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. logits processor는 생성 방식을 늦출 수 있으므로 필요한 경우에만 사용해야 합니다.

이 logits processor에는 `generate` 예제가 없습니다. 이 processor를 사용할 만큼 적절한 플래그 조합이 존재할 수 없기 때문입니다.

#### __call__[[transformers.InfNanRemoveLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1706)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.LogitNormalization[[transformers.LogitNormalization]]

```python
transformers.LogitNormalization()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1820)

log-softmax를 사용하여 점수를 정규화하는 데 사용되는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. logits processor 또는 warper를 적용한 후 beam search 과정에서 점수를 정규화하는 것이 중요합니다. 이 라이브러리가 사용하는 탐색 알고리즘은 이를 수행하지 않기 때문입니다(알고리즘은 탐색 전에만 정규화를 수행하지만, 이후에 재정규화가 필요할 수 있음에도 불구하고 가설을 비교할 때 점수가 정규화되어 있다고 가정합니다).

예:

```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
```

#### __call__[[transformers.LogitNormalization.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1851)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.LogitsProcessor[[transformers.LogitsProcessor]]

```python
transformers.LogitsProcessor()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L49)

생성 과정에서 적용할 수 있는 모든 logit processor의 추상 베이스 클래스입니다.

#### __call__[[transformers.LogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L56)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.LogitsProcessorList[[transformers.LogitsProcessorList]]

```python
transformers.LogitsProcessorList(iterable = ())
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L63)

이 클래스는 `scores` 입력 텐서를 처리하기 위해 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor) 목록을 생성하는 데 사용할 수 있습니다. 이 클래스는 list를 상속하며, 각 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)를 입력에 적용하기 위한 특정 *__call__* 메서드를 추가합니다.

#### __call__[[transformers.LogitsProcessorList.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L70)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

kwargs (`dict[str, Any]`, *선택*) : logits processor에 특정한 추가 kwargs입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.MinLengthLogitsProcessor[[transformers.MinLengthLogitsProcessor]]

```python
transformers.MinLengthLogitsProcessor(min_length: int, eos_token_id: typing.Union[int, list[int], torch.Tensor], device: str = 'cpu')
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L101)

**매개변수:**

min_length (`int`) : `eos_token_id`의 점수가 `-float("Inf")`로 설정되는 최소 길이입니다.

eos_token_id (`Union[int, list[int], torch.Tensor]`) : *end-of-sequence* 토큰의 id입니다.

device (`str`, *선택 사항*, 기본값 `"cpu"`) : 텐서를 할당할 장치입니다.

EOS 확률을 0으로 설정하여 최소 길이를 강제하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 참고로, 대부분의 LLM과 같은 decoder-only 모델의 경우 길이에 프롬프트가 포함됩니다.

예:

```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
```

#### __call__[[transformers.MinLengthLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L154)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.MinNewTokensLengthLogitsProcessor[[transformers.MinNewTokensLengthLogitsProcessor]]

```python
transformers.MinNewTokensLengthLogitsProcessor(prompt_length_to_skip: int, min_new_tokens: int, eos_token_id: typing.Union[int, list[int], torch.Tensor], device: str = 'cpu')
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L164)

**매개변수:**

prompt_length_to_skip (`int`) : 입력 토큰의 길이. `generate`와 함께 사용할 때는 입력 길이가 자동으로 할당되므로 유효한 인수가 아닙니다.

min_new_tokens (`int`) : `eos_token_id`의 점수가 `-float("Inf")`로 설정되는 최소 *new* 토큰 길이입니다.

eos_token_id (`Union[int, list[int], torch.Tensor]`) : *end-of-sequence* 토큰의 id입니다.

device (`str`, *선택 사항*, 기본값 `"cpu"`) : 텐서를 할당할 장치입니다.

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor) enforcing a min-length of new tokens by setting EOS (End-Of-Sequence) token probability to 0. Contrarily to [MinLengthLogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.MinLengthLogitsProcessor), this processor ignores the prompt.

예:

```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
```

#### __call__[[transformers.MinNewTokensLengthLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L226)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.MinPLogitsWarper[[transformers.MinPLogitsWarper]]

```python
transformers.MinPLogitsWarper(min_p: float, filter_value: float = -inf, min_tokens_to_keep: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L733)

**매개변수:**

min_p (`float`) : 최소 토큰 확률입니다. 가장 가능성이 높은 토큰의 확률로 스케일링됩니다. 0과 1 사이의 값이어야 합니다. 일반적인 값은 0.01~0.2 범위로, `top_p`를 0.99~0.8 범위로 설정하는 것과 유사한 선택성을 가집니다(일반적인 `top_p` 값의 반대 개념을 사용).

filter_value (`float`, *선택 사항*, 기본값 -inf) : 모든 필터링된 값이 이 float 값으로 설정됩니다.

min_tokens_to_keep (`int`, *선택 사항*, 기본값 1) : 필터링할 수 없는 최소 토큰 수입니다.

가장 확률이 높은 토큰의 확률로 정규화된 최소 확률 이상인 모든 토큰을 유지하는 min-p를 수행하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 그 결과, 고확률 토큰이 존재할 때 필터가 더 공격적으로 작동하며, 이는 벗어나지 말아야 할 자신감 있는 출력을 나타내는 신호입니다.

[TemperatureLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TemperatureLogitsWarper)와 함께 자주 사용됩니다. [TopPLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TopPLogitsWarper)와 [TopKLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TopKLogitsWarper)의 대안으로 사용됩니다.

@menhguin과 @kalomaze(github 계정)가 작성했습니다. 코드는 [이 외부 PR](https://github.com/oobabooga/text-generation-webui/pull/4449/files)에서 가져왔습니다.

예:

```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) ;
<BLANKLINE>
<BLANKLINE>

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

#### __call__[[transformers.MinPLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L790)

#### transformers.NoBadWordsLogitsProcessor[[transformers.NoBadWordsLogitsProcessor]]

```python
transformers.NoBadWordsLogitsProcessor(bad_words_ids: list[list[int]], eos_token_id: typing.Union[int, list[int], torch.Tensor, NoneType] = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1432)

**매개변수:**

bad_words_ids (`list[list[int]]`) : 생성이 허용되지 않는 토큰 ID의 리스트로 구성된 리스트.

eos_token_id (`Union[int, list[int], torch.Tensor]`, *선택 사항*) : *end-of-sequence* 토큰의 id입니다.

지정된 시퀀스가 절대 선택되지 않도록 강제하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다.

생성된 텍스트에 나타나서는 안 되는 단어의 token id를 얻으려면, tokenizer를 초기화할 때 `add_prefix_space=True`를 설정하고 `tokenizer(bad_words, add_special_tokens=False).input_ids`를 사용해야 합니다. `add_prefix_space` 인수는 일부 slow tokenizer에서만 지원되며, fast tokenizer의 prefixing 동작은 `pre tokenizers`에서 비롯됩니다. 자세한 내용은 [여기](https://huggingface.co/docs/tokenizers/api/pre-tokenizers)를 참고하세요.

예:

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

#### __call__[[transformers.NoBadWordsLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1319)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.NoRepeatNGramLogitsProcessor[[transformers.NoRepeatNGramLogitsProcessor]]

```python
transformers.NoRepeatNGramLogitsProcessor(ngram_size: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1102)

**매개변수:**

ngram_size (`int`) : `ngram_size` 크기의 모든 ngram은 한 번만 발생할 수 있습니다.

N-gram은 텍스트 시퀀스에서 추출한 연속된 "n"개의 단어, 문자 또는 토큰의 집합입니다. "She runs fast"라는 문장의 경우, bi-gram(n=2)은 ("she", "runs")과 ("runs", "fast")입니다. 텍스트 생성에서 단어 시퀀스의 반복을 방지하면 더 다양한 출력을 얻을 수 있습니다. 이 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 금지된 토큰의 점수를 음의 무한대로 설정하여 n-gram의 반복을 방지하며, 이는 점수를 추가로 처리할 때 해당 토큰이 고려 대상에서 제외되도록 합니다. 참고로, 대부분의 LLM과 같은 decoder-only 모델의 경우 프롬프트도 n-gram을 얻기 위해 고려 대상에 포함됩니다. [Fairseq](https://github.com/pytorch/fairseq/blob/a07cb6f40480928c9e0548b737aadd36ee66ac76/fairseq/sequence_generator.py#L345).

n-gram 패널티는 신중하게 사용해야 합니다. 예를 들어, 뉴욕시에 관한 기사에서 2-그램(이원어)에 패널티를 부과하면, 도시 이름이 전체 텍스트에서 한 번만 나타나는 바람직하지 않은 결과가 발생할 수 있습니다. [참고 문헌](https://huggingface.co/blog/how-to-generate)

예:

```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
```

#### __call__[[transformers.NoRepeatNGramLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1149)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.PrefixConstrainedLogitsProcessor[[transformers.PrefixConstrainedLogitsProcessor]]

```python
transformers.PrefixConstrainedLogitsProcessor(prefix_allowed_tokens_fn: collections.abc.Callable[[int, torch.Tensor], list[int]], num_beams: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1521)

**매개변수:**

prefix_allowed_tokens_fn (`Callable[[int, torch.Tensor], list[int]]`) : 이 함수는 각 단계에서 beam search를 허용된 토큰으로만 제한합니다. 이 함수는 `inputs_ids`와 배치 ID `batch_id`라는 두 개의 인수를 받습니다. 이전에 생성된 토큰 `inputs_ids`와 배치 ID `batch_id`에 조건부인 다음 생성 단계에 허용되는 토큰의 리스트를 반환해야 합니다.

제약 생성을 강제하여 접두어 조건부 제약 생성에 유용한 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 자세한 내용은 [Autoregressive Entity Retrieval](https://huggingface.co/papers/2010.00904)을 참조하세요.

예:

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

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

#### __call__[[transformers.PrefixConstrainedLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1572)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.RepetitionPenaltyLogitsProcessor[[transformers.RepetitionPenaltyLogitsProcessor]]

```python
transformers.RepetitionPenaltyLogitsProcessor(penalty: float, prompt_ignore_length: typing.Union[int, torch.Tensor, NoneType] = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L306)

**매개변수:**

penalty (`float`) : 반복 페널티를 위한 매개변수입니다. 1.0은 페널티가 없음을 의미합니다. 1.0보다 큰 값은 이전에 생성된 토큰에 페널티를 부과합니다. 0.0과 1.0 사이의 값은 이전에 생성된 토큰에 보상을 부여합니다.

prompt_ignore_length (`int` 또는 `torch.LongTensor`, *선택 사항*) : 무시할 앞쪽 토큰의 수입니다. 배치 요소별로 지정할 수도 있습니다.

이전 토큰의 반복을 페널티를 통해 방지하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 이 페널티는 토큰당 최대 한 번만 적용됩니다. 참고로, 대부분의 LLM과 같은 decoder-only 모델의 경우 기본적으로 고려 대상 토큰에 프롬프트가 포함됩니다.

원래 [논문](https://huggingface.co/papers/1909.05858)에서는 진실한 생성과 반복 부족 사이의 균형을 잘 맞추기 위해 약 1.2 수준의 페널티 사용을 제안합니다. 반복을 페널티화하고 줄이려면 `penalty` 값을 1.0 이상으로 사용하세요. 값이 높을수록 페널티가 더 강하게 적용됩니다. 반복을 보상하고 장려하려면 `penalty` 값을 0.0과 1.0 사이로 사용하세요. 값이 낮을수록 보상이 더 강하게 적용됩니다.

예:

```py
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, RepetitionPenaltyLogitsProcessor

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

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

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

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

#### __call__[[transformers.RepetitionPenaltyLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L373)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.SequenceBiasLogitsProcessor[[transformers.SequenceBiasLogitsProcessor]]

```python
transformers.SequenceBiasLogitsProcessor(sequence_bias: list[list[list[int] | float]])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1242)

**매개변수:**

sequence_bias (`list[list[Union[list[int], float]]]`) : 토큰 시퀀스를 해당 bias term으로 매핑하는 리스트의 리스트입니다 (예: `[[[10, 45], -2.0], [[64], -7.5]]`). 양의 bias는 해당 시퀀스가 선택될 확률을 높이고, 음의 bias는 그 반대 효과를 냅니다. 시퀀스의 길이가 1인 경우, bias는 항상 적용됩니다. 그렇지 않은 경우, 해당 시퀀스가 곧 완료될 때만(이 프로세서가 적용된 후의 토큰 선택 단계에서) bias가 적용됩니다.

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 시퀀스에 가산 바이어스를 적용합니다. 다음으로 생성되는 토큰이 해당 시퀀스를 완료할 수 있을 때, 바이어스는 시퀀스의 마지막 토큰에 적용됩니다. 따라서 두 개 이상의 토큰으로 구성된 시퀀스에 대한 바이어싱 효과를 최대한 활용하려면, beam 방식(음의 바이어스가 있는 부분적으로 완료된 시퀀스를 우아하게 처리하기 위해)을 사용하고 바이어스를 해당 시퀀스의 접두사에 적용(바이어스가 더 일찍 적용되도록 보장하기 위해)하는 것을 고려해 보세요.

토큰 수준에서, 단어 자체에 편향을 적용하는 것과 앞에 공백이 있는 단어에 편향을 적용하는 것은 다릅니다. 문장 중간에 "foo"에 편향을 적용하려면, 보통은 앞에 공백을 추가하여 " foo"에 편향을 적용하는 것이 좋습니다. 그 이유는 NLP 코스의 토크나이저 섹션을 참고하세요: https://huggingface.co/learn/nlp-course/chapter2/4?fw=pt

예:

```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
```

#### __call__[[transformers.SequenceBiasLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1319)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.SuppressTokensAtBeginLogitsProcessor[[transformers.SuppressTokensAtBeginLogitsProcessor]]

```python
transformers.SuppressTokensAtBeginLogitsProcessor(begin_suppress_tokens, begin_index, device: str = 'cpu')
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1857)

[SuppressTokensAtBeginLogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.SuppressTokensAtBeginLogitsProcessor)는 `generate` 함수가 `begin_index` 토큰을 사용하여 생성을 시작하는 즉시 토큰 목록을 억제합니다. 이를 통해 `begin_suppress_tokens`으로 정의된 토큰이 시작 부분에 생성되지 않도록 보장해야 합니다. 원래 [Whisper](https://huggingface.co/docs/transformers/model_doc/whisper)용으로 작성되었습니다.

예:

```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)
```

#### __call__[[transformers.SuppressTokensAtBeginLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1899)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.SuppressTokensLogitsProcessor[[transformers.SuppressTokensLogitsProcessor]]

```python
transformers.SuppressTokensLogitsProcessor(suppress_tokens, device: str = 'cpu')
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1910)

이 프로세서는 토큰 목록을 억제하는 데 사용할 수 있습니다. 프로세서는 해당 토큰의 log probs를 `-inf`로 설정하여 생성되지 않도록 합니다. 원래 [Whisper](https://huggingface.co/docs/transformers/model_doc/whisper)를 위해 만들어졌습니다.

예:

```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)
```

#### __call__[[transformers.SuppressTokensLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1942)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.SynthIDTextWatermarkLogitsProcessor[[transformers.SynthIDTextWatermarkLogitsProcessor]]

```python
transformers.SynthIDTextWatermarkLogitsProcessor(ngram_len: int, keys: list[int], sampling_table_size: int, sampling_table_seed: int, context_history_size: int, device: device, skip_first_ngram_calls: bool = False, debug_mode: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2611)

**매개변수:**

ngram_len (`int`) : Ngram 길이.

keys (`list[int]`) : 각 깊이에 하나씩 해당하는 워터마킹 키의 시퀀스.

sampling_table_size (`int`) : 샘플링 테이블의 크기.

sampling_table_seed (`int`) : 샘플링 테이블을 생성하기 위한 랜덤 시드.

context_history_size (`int`) : 확인된 컨텍스트를 추적할 텐서의 크기.

device (`torch.device`) : 사용할 Device.

skip_first_ngram_calls (`bool`, *선택 사항*, 기본값 `False`) : 첫 번째 ngram 호출을 건너뛸지 여부.

debug_mode (`bool`, *선택 사항*, 기본값 `False`) : 워터마킹 수정이 적용되기 전에 균일한 분포로 수정된 logits를 반환합니다. 이는 구현을 테스트하기 위한 것입니다.

텍스트 생성 모델에 워터마킹 기법을 구현하는 Logits processor입니다. 이 클래스는 생성된 텍스트에 감지하기 어려운 신호를 임베드하여 합성 콘텐츠 탐지를 돕는 SynthID 텍스트 워터마킹 기법의 적용을 지원합니다. 텍스트 생성 과정에서 토큰 선택 확률을 나중에 검증 시 신뢰할 수 있게 복원할 수 있도록 미세하게 조작하는 방식으로 동작합니다.

주요 기능:
* **상태 관리:** 토큰 시퀀스를 추적하고 워터마킹 키를 생성하기 위해 내부 상태를 유지합니다
동적으로.

* **키 생성:** 토큰 시퀀스와 워터마킹 매개변수를 기반으로 해시를 계산하여 고유한 키를 생성합니다
각 위치마다

* **G-Value Sampling:** 사전 계산된 샘플링 테이블을 사용하여 워터마킹 값
생성된 키입니다.

* **점수 조정:** 생성 과정에서 토큰 확률을 수정하기 위해 계산된 g-값을 적용하며,
워터마크.

* **컨텍스트 반복 처리:** 반복되는 컨텍스트의 토큰에 워터마크를 적용하지 않도록 하는 로직을 포함합니다.
자연스러움을 유지하는

* **EOS 토큰 마스킹:** 문장 끝 토큰을 마스킹하여 워터마킹에 포함되지 않도록 지원합니다
계산

* **유틸리티 함수:** g-값을 직접 계산하고, 컨텍스트 반복을 확인하며,
EOS 토큰 마스크를 적용하고, 예상 평균 g-값을 추정합니다.

자세한 내용은 논문 URL: https://www.nature.com/articles/s41586-024-08025-4를 참고하세요.

예:
```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)
```

#### __call__[[transformers.SynthIDTextWatermarkLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2749)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.TemperatureLogitsWarper[[transformers.TemperatureLogitsWarper]]

```python
transformers.TemperatureLogitsWarper(temperature: float)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L238)

**매개변수:**

temperature (`float`) : logits 분포를 조절하는 데 사용되는 엄밀히 양의 float 값. `1`보다 작은 값은 무작위성을 감소시키고(그 반대도 성립하며), `0`은 모든 확률 질량을 가장 가능성이 높은 토큰으로 이동시키는 것과 동일합니다.

온도(지수 스케일링 출력 확률 분포)를 위한 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)로, 예측 토큰의 무작위성을 효과적으로 제어할 수 있습니다. 주로 [TopPLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TopPLogitsWarper)와 [TopKLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TopKLogitsWarper)와 함께 사용됩니다.

온도 값이 효과를 발휘하려면 `generate` 인수에 `do_sample=True`가 포함되어 있는지 확인하세요.

예:

```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']
```

#### __call__[[transformers.TemperatureLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L300)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.TopHLogitsWarper[[transformers.TopHLogitsWarper]]

```python
transformers.TopHLogitsWarper(top_h: float, filter_value: float = -inf)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L627)

**매개변수:**

top_h (`float`) : 엔트로피 기반 임계값(`tau`)의 스케일링 계수입니다. `(0, 1]` 범위에 있어야 합니다.

filter_value (`float`, *선택 사항*, 기본값 -inf) : 모든 필터링된 값이 이 float 값으로 설정됩니다.

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 엔트로피와 누적 확률 제약 조건에 따라 고확률 토큰의 부분 집합을 적응적으로 선택하는 Top-H 샘플링 디코딩 방법을 구현합니다.

이 메서드는 선택된 분포의 엔트로피 차이를 분석하여 유지할 토큰 수를 동적으로 결정함으로써 탐색(exploration)과 활용(exploitation)을 균형 있게 조절합니다. 이를 통해 생성된 텍스트가 다양성과 일관성을 모두 유지하도록 보장합니다.

참고: 자세한 내용은 *텍스트 생성에서 유계 엔트로피를 통한 창의성과 일관성 조절을 위한 Top-H 디코딩* (NeurIPS 2025): https://arxiv.org/abs/2509.02510을 참조하세요.

예:

```python
>>> from transformers import AutoTokenizer, AutoModelForCausalLM

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

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

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

#### __call__[[transformers.TopHLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L678)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 입력 토큰 ID.

scores (`torch.Tensor`, shape `(batch_size, vocab_size)`) : 모델에서 생성된 원시 logits입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, vocab_size)`

`-inf`로 마스킹된 무효 토큰을 포함한 처리된 logits입니다.

Top-H 샘플링을 사용하여 logits를 필터링합니다.

#### transformers.TopKLogitsWarper[[transformers.TopKLogitsWarper]]

```python
transformers.TopKLogitsWarper(top_k: int, filter_value: float = -inf, min_tokens_to_keep: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L571)

**매개변수:**

top_k (`int`) : top-k-filtering을 위해 유지할 최고 확률 어휘 토큰의 개수.

filter_value (`float`, *선택 사항*, 기본값 -inf) : 모든 필터링된 값이 이 float 값으로 설정됩니다.

min_tokens_to_keep (`int`, *선택 사항*, 기본값 1) : 필터링할 수 없는 최소 토큰 수입니다.

가장 높은 확률을 가진 k개 요소로 제한하는 top-k를 수행하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 주로 [TemperatureLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TemperatureLogitsWarper)와 [TopPLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TopPLogitsWarper)와 함께 사용됩니다.

예:

```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
```

#### __call__[[transformers.TopKLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L618)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.TopPLogitsWarper[[transformers.TopPLogitsWarper]]

```python
transformers.TopPLogitsWarper(top_p: float, filter_value: float = -inf, min_tokens_to_keep: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L502)

**매개변수:**

top_p (`float`) : 1 미만으로 설정하면, 확률의 합이 `top_p` 이상인 가장 확률이 높은 최소 토큰 집합만 생성에 유지됩니다.

filter_value (`float`, *선택 사항*, 기본값 -inf) : 모든 필터링된 값이 이 float 값으로 설정됩니다.

min_tokens_to_keep (`int`, *선택 사항*, 기본값 1) : 필터링할 수 없는 최소 토큰 수입니다.

prob_cut_off <= prob_cut_off를 만족하는 상위 토큰으로 제한하는 top-p를 수행하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 주로 [TemperatureLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TemperatureLogitsWarper)와 [TopKLogitsWarper](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.TopKLogitsWarper)와 함께 사용됩니다.

예:

```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) ;
<BLANKLINE>
<BLANKLINE>

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

#### __call__[[transformers.TopPLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L555)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.TypicalLogitsWarper[[transformers.TypicalLogitsWarper]]

```python
transformers.TypicalLogitsWarper(mass: float = 0.9, filter_value: float = -inf, min_tokens_to_keep: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L809)

**매개변수:**

mass (`float`, *선택 사항*, 기본값 0.9) : 0 이상 1 이하의 typical_p 값, 기본값은 0.9입니다.

filter_value (`float`, *선택 사항*, 기본값 -inf) : 모든 필터링된 값이 이 float 값으로 설정됩니다.

min_tokens_to_keep (`int`, *선택 사항*, 기본값 1) : 필터링할 수 없는 최소 토큰 수입니다.

전형적(typical) 디코딩을 수행하는 [LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)입니다. 인간의 언어 사용 방식을 참고하여, 토큰 확률 분포의 엔트로피에 가까운 로그 확률을 가진 토큰을 우선시합니다. 이는 가장 가능성이 높은 토큰이 이 과정에서 제외될 수 있음을 의미합니다.

자세한 내용은 [자연어 생성을 위한 전형적 디코딩](https://huggingface.co/papers/2202.00666)을 참조하세요.

예:

```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)
```

#### __call__[[transformers.TypicalLogitsWarper.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L873)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.UnbatchedClassifierFreeGuidanceLogitsProcessor[[transformers.UnbatchedClassifierFreeGuidanceLogitsProcessor]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2273)

**매개변수:**

guidance_scale (`float`) : classifier free guidance(CFG)의 guidance scale입니다. `guidance_scale != 1`로 설정하면 CFG가 활성화됩니다. guidance scale이 높을수록 모델은 입력 프롬프트와 더 밀접하게 연결된 샘플을 생성하도록 장려되며, 일반적으로 품질 저하를 대가로 합니다. 1보다 작은 값은 반대 효과를 내며, negative_prompt_ids로 제공된 negative prompt(있는 경우)가 positive prompt로 작용하게 만듭니다.

model (`PreTrainedModel`) : 무조건부 점수를 계산하는 모델입니다. 조건부 점수를 계산하는 모델과 동일할 것으로 예상됩니다. 두 모델 모두 동일한 tokenizer를 사용해야 합니다.

unconditional_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 무조건 분기(unconditional branch)의 입력 시퀀스 토큰 어휘 인덱스. 설정되지 않으면 프롬프트의 마지막 토큰을 기본값으로 사용합니다.

unconditional_attention_mask (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : unconditional_ids에 사용할 attention mask입니다.

use_cache (`bool`, *선택 사항*, 기본값 `True`) : negative prompt forward pass 동안 key/value를 캐시할지 여부입니다.

Classifier-Free Guidance(CFG)용 Logits processor입니다. 이 processor는 `guidance_scale`로 매개변수화되며, 프롬프트 조건부 logits와 프롬프트 무조건부(또는 negative) logits의 점수 사이에서 가중 평균을 계산합니다. 무조건부 점수는 `model`에 `unconditional_ids` 분기를 프롬프트로 전달하여 내부적으로 계산됩니다.

자세한 내용은 [논문](https://huggingface.co/papers/2306.17806)을 참고하세요.

예:

```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"
```

#### __call__[[transformers.UnbatchedClassifierFreeGuidanceLogitsProcessor.__call__]]

```python
__call__(input_ids, scores)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2379)

#### transformers.WhisperTimeStampLogitsProcessor[[transformers.WhisperTimeStampLogitsProcessor]]

```python
transformers.WhisperTimeStampLogitsProcessor(generate_config: GenerationConfig, begin_index: int, _detect_timestamp_from_logprob: bool | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L1950)

**매개변수:**

generate_config (`GenerateConfig`) : 출력을 생성하는 데 사용되는 generate config입니다. 다음 매개변수가 필요합니다. eos_token_id (`int`, *선택 사항*, 기본값 50257): *시퀀스 끝* 토큰의 id입니다. no_timestamps_token_id (`int`, *선택 사항*, 기본값 50363): `"<|notimestamps|>"` 토큰의 id입니다. max_initial_timestamp_index (`int`, *선택 사항*, 기본값 1): 초기 타임스탬프의 최대 값을 설정하는 데 사용됩니다. 모델이 너무 먼 미래의 타임스탬프를 예측하는 것을 방지하는 데 사용됩니다.

begin_index (`int`) : 모델이 생성하는 첫 번째 토큰의 인덱스.

_detect_timestamp_from_logprob (`bool`, *선택 사항*) : 모든 타임스탬프에 대한 logprobs에서 타임스탬프를 예측할 수 있는지 여부.

[LogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.LogitsProcessor)는 전사 과정에서 타임스탬프 생성을 위한 logits를 수정합니다. 입력 토큰이 특정 임계값에 도달하면, 프로세서가 점수를 음의 무한대로 설정합니다. 프로세서는 타임스탬프 토큰이 쌍으로 나타나도록, 이러한 짝짓기 패턴을 깨뜨리는 logits를 마스킹하여 보장합니다. 이는 생성된 타임스탬프의 일관성과 구조를 유지하기 위해 수행됩니다. 또한, 타임스탬프 토큰 중 하나를 샘플링할 예측 확률이 개별 비타임스탬프 토큰보다 클 경우, 해당 비타임스탬프 logits를 음의 무한대로 설정합니다. 이는 다른 잠재적 토큰보다 타임스탬프가 생성되도록 보장하기 위한 것입니다.

자세한 내용은 [논문](https://huggingface.co/papers/2212.04356)을 참고하세요.

예:
``` 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
```

#### __call__[[transformers.WhisperTimeStampLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2040)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

#### transformers.WatermarkLogitsProcessor[[transformers.WatermarkLogitsProcessor]]

```python
transformers.WatermarkLogitsProcessor(vocab_size, device, greenlist_ratio: float = 0.25, bias: float = 2.0, hashing_key: int = 15485863, seeding_scheme: str = 'lefthash', context_width: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2438)

**매개변수:**

vocab_size (`int`) : 모델 토크나이저의 vocab_size. "green" 토큰 비율을 계산하는 데 사용됩니다.

device (`str`) : 모델이 할당된 디바이스.

greenlist_ratio (`float`, optional, *optional*, 기본값 0.25) : 어휘 크기 대비 "green" 토큰의 비율입니다. 기본값은 0.25입니다.

bias (`float`, optional, *선택 사항*, 기본값 2.0) : 선택된 "green" 토큰의 logits에 추가되는 bias입니다. 텍스트 생성 품질이 저하되면 `bias` 값을 낮추는 것을 고려해 보세요. 권장 값은 [0.5, 2.0] 범위입니다. 기본값은 2.0입니다.

hashing_key (`int`, optional, *optional*, 기본값 15485863) : 해싱에 사용되는 키입니다. 이 워터마크를 배포하는 경우, 다른 개인 키를 사용하는 것을 권장합니다. 기본값은 15485863(100만 번째 소수)입니다.

seeding_scheme (`str`, optional, *optional*, 기본값 `"lefthash"`) : "green" 토큰을 선택하는 데 사용되는 시딩 스킴입니다. 허용되는 값: - "lefthash" (기본값): "green" 토큰 선택이 마지막 토큰에 따라 결정됩니다(논문 Algorithm 2). - "selfhash": "green" 토큰 선택이 현재 토큰 자체에 따라 결정됩니다(논문 Algorithm 3). 이 스킴의 단점은 모든 가능한 다음 토큰을 고려하므로 "lefthash"보다 느릴 수 있다는 것입니다. 시딩에 사용할 이전 토큰의 컨텍스트 길이입니다. 컨텍스트 길이가 길수록 워터마킹이 더 견고해집니다.

context_width (`int`, *선택 사항*, 기본값 1) : 시드 설정 시 사용할 이전 토큰의 수입니다.

생성된 텍스트에 워터마크를 적용하기 위한 Logits processor입니다. 이 프로세서는 다음 토큰을 생성하기 전에 무작위로 선택된 "green" 토큰 집합에 작은 bias를 추가하여 모델 출력 점수를 수정합니다. "green" 토큰 선택 과정은 사용된 `seeding_scheme`에 따라 달라집니다. 이 코드는 [원본 저장소](https://github.com/jwkirchenbauer/lm-watermarking/tree/main)를 기반으로 작성되었습니다.

이 `LogitsProcessor`가 생성한 텍스트는 `WatermarkDetector`를 사용하여 감지할 수 있습니다. 자세한 내용은 [__call__()](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.WatermarkDetector.__call__)를 참조하세요.

자세한 내용은 [논문](https://huggingface.co/papers/2306.04634)을 참고하세요.

예:

```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])
```

#### __call__[[transformers.WatermarkLogitsProcessor.__call__]]

```python
__call__(input_ids: LongTensor, scores: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/logits_process.py#L2560)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`torch.Tensor`, shape `(batch_size, config.vocab_size)`) : 언어 모델링 헤드의 예측 점수입니다. beam search를 사용하지 않는 경우 각 어휘에 대한 logits이며, beam search를 사용하는 경우 각 어휘 토큰에 대한 log softmax입니다.

**반환값:** `torch.Tensor`, shape `(batch_size, config.vocab_size)`

처리된 예측 점수입니다.

## StoppingCriteria[[transformers.StoppingCriteria]]

[StoppingCriteria](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.StoppingCriteria)를 사용하여 EOS 토큰을 제외하고 생성을 중단하는 시점을 변경할 수 있습니다. 이 기능은 PyTorch 구현에서만 사용할 수 있습니다.

#### transformers.StoppingCriteria[[transformers.StoppingCriteria]]

```python
transformers.StoppingCriteria()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L48)

생성 과정에서 적용할 수 있는 모든 정지 기준의 추상 베이스 클래스입니다.

중단 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하는지 확인하세요.

#### __call__[[transformers.StoppingCriteria.__call__]]

```python
__call__(input_ids: LongTensor, scores: tuple[torch.Tensor] | None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L55)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘(input sequence tokens)의 인덱스. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`tuple(torch.Tensor)`) : 언어 모델링 헤드의 예측 점수입니다. 생성 단계별로 하나의 텐서를 포함하는 튜플이며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다. 이는 SoftMax 적용 전 어휘 토큰별 점수일 수도 있고, SoftMax 적용 후 어휘 토큰별 점수일 수도 있습니다. 이 종료 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 그렇지 않으면 `None`이 전달됩니다.

kwargs (`dict[str, Any]`, *선택*) : 특정 stopping criteria에 대한 추가 kwargs.

**반환값:** `torch.BoolTensor`. (`(batch_size, 1)` 모양의 `torch.BoolTensor`)

`True`는 특정 행에 대해 생성을 중단함을 나타냅니다. `False`는 계속 진행해야 함을 나타냅니다.

#### transformers.StoppingCriteriaList[[transformers.StoppingCriteriaList]]

```python
transformers.StoppingCriteriaList(iterable = ())
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L610)

#### __call__[[transformers.StoppingCriteriaList.__call__]]

```python
__call__(input_ids: LongTensor, scores: tuple[torch.Tensor] | None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L611)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘(input sequence tokens)의 인덱스. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`tuple(torch.Tensor)`) : 언어 모델링 헤드의 예측 점수입니다. 생성 단계별로 하나의 텐서를 포함하는 튜플이며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다. 이는 SoftMax 적용 전 어휘 토큰별 점수일 수도 있고, SoftMax 적용 후 어휘 토큰별 점수일 수도 있습니다. 이 종료 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 그렇지 않으면 `None`이 전달됩니다.

kwargs (`dict[str, Any]`, *선택*) : 특정 stopping criteria에 대한 추가 kwargs.

**반환값:** `torch.BoolTensor`. (`(batch_size, 1)` 모양의 `torch.BoolTensor`)

`True`는 특정 행에 대해 생성을 중단함을 나타냅니다. `False`는 계속 진행해야 함을 나타냅니다.

#### transformers.MaxLengthCriteria[[transformers.MaxLengthCriteria]]

```python
transformers.MaxLengthCriteria(max_length: int, max_position_embeddings: int | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L60)

**매개변수:**

max_length (`int`) : 출력 시퀀스가 가질 수 있는 최대 토큰 수.

max_position_embeddings (`int`, *선택 사항*) : 모델의 `config.max_position_embeddings` 속성으로 정의된 최대 모델 길이입니다.

이 클래스는 생성된 토큰의 총 수가 `max_length`를 초과하는 시점에 생성을 중단하는 데 사용할 수 있습니다. decoder-only 유형의 Transformers의 경우, 초기 프롬프트 토큰도 포함됨을 유의하세요.

#### __call__[[transformers.MaxLengthCriteria.__call__]]

```python
__call__(input_ids: LongTensor, scores: tuple[torch.Tensor] | None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L76)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘(input sequence tokens)의 인덱스. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`tuple(torch.Tensor)`) : 언어 모델링 헤드의 예측 점수입니다. 생성 단계별로 하나의 텐서를 포함하는 튜플이며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다. 이는 SoftMax 적용 전 어휘 토큰별 점수일 수도 있고, SoftMax 적용 후 어휘 토큰별 점수일 수도 있습니다. 이 종료 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 그렇지 않으면 `None`이 전달됩니다.

kwargs (`dict[str, Any]`, *선택*) : 특정 stopping criteria에 대한 추가 kwargs.

**반환값:** `torch.BoolTensor`. (`(batch_size, 1)` 모양의 `torch.BoolTensor`)

`True`는 특정 행에 대해 생성을 중단함을 나타냅니다. `False`는 계속 진행해야 함을 나타냅니다.

#### transformers.MaxTimeCriteria[[transformers.MaxTimeCriteria]]

```python
transformers.MaxTimeCriteria(max_time: float, initial_timestamp: float | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L89)

**매개변수:**

max_time (`float`) : 생성에 허용되는 최대 시간(초).

initial_timestamp (`float`, *선택 사항*, 기본값 `time.time()`) : 생성이 허용되는 시간의 시작점입니다.

이 클래스는 전체 생성 시간이 특정 시간을 초과할 때 생성을 중단하는 데 사용할 수 있습니다. 기본적으로 이 함수를 초기화할 때부터 시간이 측정됩니다. `initial_timestamp`를 전달하여 이 동작을 재정의할 수 있습니다.

#### __call__[[transformers.MaxTimeCriteria.__call__]]

```python
__call__(input_ids: LongTensor, scores: tuple[torch.Tensor] | None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L106)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘(input sequence tokens)의 인덱스. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`tuple(torch.Tensor)`) : 언어 모델링 헤드의 예측 점수입니다. 생성 단계별로 하나의 텐서를 포함하는 튜플이며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다. 이는 SoftMax 적용 전 어휘 토큰별 점수일 수도 있고, SoftMax 적용 후 어휘 토큰별 점수일 수도 있습니다. 이 종료 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 그렇지 않으면 `None`이 전달됩니다.

kwargs (`dict[str, Any]`, *선택*) : 특정 stopping criteria에 대한 추가 kwargs.

**반환값:** `torch.BoolTensor`. (`(batch_size, 1)` 모양의 `torch.BoolTensor`)

`True`는 특정 행에 대해 생성을 중단함을 나타냅니다. `False`는 계속 진행해야 함을 나타냅니다.

#### transformers.StopStringCriteria[[transformers.StopStringCriteria]]

```python
transformers.StopStringCriteria(tokenizer: PreTrainedTokenizerBase, stop_strings: str | list[str])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L112)

**매개변수:**

tokenizer (`PreTrainedTokenizer`) : 모델에 연결된 토크나이저(어휘를 추출하고 종료 시퀀스를 토큰화하는 데 필요)

stop_strings (`Union[str, list[str]]`) : 생성을 종료해야 하는 문자열 목록입니다. 문자열 하나가 전달되면 단일 요소로 구성된 목록으로 처리됩니다.

이 클래스는 특정 문자열 시퀀스가 생성될 때마다 생성을 중단하는 데 사용할 수 있습니다. 이 클래스는 문자열을 토크나이저 어휘와 함께 전처리하여, 토큰이 stop 문자열을 유효하게 완료할 수 있는 위치를 찾습니다.

stop 문자열 중 하나를 완성하는 토큰이 생성되는 즉시 생성이 중단됩니다. 디코딩된 출력에 stop 문자열이 존재하는 모든 경우를 포착해야 하므로, 한쪽 끝 또는 양쪽 끝에 "overhang"이 있는 경우까지 포착해야 합니다. 이를 더 구체적으로 설명하면, stop 문자열인 "stop"의 경우, 다음 토큰 시퀀스 중 어느 것이든 매치를 트리거합니다:

- ["st", "op"]
- ["stop"]
- ["st", "opera"]
- ["sto", "pper"]
- ["las", "topper"]
- ["s", "to", "pped"]

stop string이 생성된 시퀀스의 끝에 위치할 때만 매치가 트리거됩니다. 즉, 다음 시퀀스들은 매치를 트리거하지 않습니다:

- ["stop", "at"]
- ["st", "op", "at"]
- ["st", "opera", "tion"]

이들이 일치하지 않는 이유는 stop 문자열이 마지막 토큰과 겹치지 않기 때문입니다. 시퀀스의 끝에서 하나 이상의 토큰을 제거해도 stop 문자열이 손상되지 않는다면, 이 기준은 해당 stop 문자열과 일치하지 않습니다. 이는 의도된 동작입니다. 이 체크는 각 토큰이 생성된 후에 실행되므로, 유효한 stop 문자열이 생성되면 이를 놓치지 않지만, 과거의 input_ids 어딘가에 stop 문자열이 존재한다는 이유만으로 생성을 중단하고 싶지 않기 때문입니다.

그렇다면 매칭은 실제로 어떻게 수행될까요? Torch 또는 XLA로 컴파일 가능한 전체 매칭 프로세스를 원하기 때문에 다소 혼란스러운 방식으로 수행합니다. 이는 표준 문자열 메서드를 사용할 수 없음을 의미합니다. 하지만 상당한 작업을 거치면 순수한 텐서 연산으로 문자열 매칭을 수행할 수 있습니다. 먼저 표준 문자열 연산을 사용하여 사용하는 알고리즘을 설명하고, 마지막에 이것이 순수한 텐서 연산으로 어떻게 변환되는지 설명하겠습니다.

이 알고리즘의 핵심은 다음과 같은 관찰에 있습니다. stop 문자열은 토큰 시퀀스의 끝과 겹쳐야 하므로, 시퀀스의 끝에서부터 거꾸로 진행할 수 있습니다. 구체적으로, 마지막 토큰의 시작 부분과 stop_string의 끝 부분이 겹치는지 확인합니다. 다시 말해, 어떤 i > 0에 대해 stop_string[-i:] == token[:i]가 성립하는지 확인하는 것입니다. 위의 긍정적 예시를 살펴보면, 모든 예시의 마지막 토큰이 이 성질을 만족하는 것을 볼 수 있습니다:

- ["st", "op"] (겹치는 부분은 "op", 겹침 길이 == 2)
- ["stop"]  (겹침은 "stop", 겹침 길이 == 4)
- ["st", "opera"] (겹치는 부분은 "op", 겹침 길이 == 2)
- ["sto", "pper"] (겹치는 문자는 "p", 겹침 길이 == 1)
- ["las", "topper"] (겹치는 부분은 "top", 겹침 길이 == 3)
- ["s", "to", "pped"] (겹치는 부분은 "p", 겹침 길이 == 1)

이 특성이 없는 매칭 시퀀스를 구성하는 것은 불가능합니다(직접 확인해 보셔도 됩니다). 그러나 최종 토큰의 시작 부분과 stop 문자열의 끝 부분 사이의 이러한 겹침은 매칭에 필수적이지만, 그것만으로는 충분하지 않습니다. 토큰 시퀀스의 나머지 부분이 stop 문자열과 일관성이 있는지 또한 확인해야 합니다.

How do we do that? Let's use ["s", "to", "pped"] as an example. We know that the final token, "pped", has an overlap of 1 with the stop string, "stop". We then go back to the previous token, "to". Since we have already matched 1 character from the stop string, the remainder to check is "sto". We check that the next token "to" matches the end of the remainder, which it does. We have now matched 3 characters from the stop string, and the remainder to match is "s". We go back to the previous token again, which is also "s". This is a match, and so we have matched the entire stop string.

그렇다면 토큰이 stop string의 시작 부분을 벗어나는 경우 어떻게 작동할까요? ["las", "topper"]의 예를 생각해 보겠습니다. 마지막 토큰인 "topper"는 stop string인 "stop"과 3개의 문자가 겹칩니다. 따라서 매칭해야 할 나머지 stop string은 "s"가 됩니다. 이전 토큰인 "las"로 돌아가 봅니다. 매칭해야 할 나머지가 길이 1인 "s"뿐이므로, 토큰의 마지막 1개 문자인 "s"만 고려합니다. 이는 stop string과 일치하므로, 전체 문자열이 매칭됩니다.

그렇다면 이러한 매칭을 텐서 연산으로 어떻게 계산할까요? 간단합니다. 모든 토큰에 대해 필요한 정보를 효율적으로 사전 계산합니다! 각 토큰에 대해 다음을 계산합니다:
- stop 문자열의 끝과 겹치는 부분(있는 경우)
- 토큰이 일치하는 stop 문자열 안의 위치들, 시작 부분에서 벗어나는 일치도 포함합니다.
- 토큰의 총 길이

예를 들어, 토큰 "pped"의 경우 끝 겹침(end overlap)은 1, 내부 일치 위치는 없으며 길이는 4로 계산됩니다. 토큰 "to"의 경우 끝 겹침은 없고, 내부 일치 위치는 1개(끝에서부터 세어 1)이며 길이는 2로 계산됩니다. 토큰 "s"의 경우 끝 겹침은 없고, 내부 일치 위치는 1개(다시 끝에서부터 세어 3)이며 길이는 1로 계산됩니다.

이 정보가 있으면 위의 알고리즘을 문자열 비교 작업 없이 실행할 수 있습니다. 다음 단계만 수행하면 됩니다:
- …
- 그동안 매칭된 stop 문자열의 길이를 추적하면서 뒤로 계속 진행합니다
- 각 단계에서 다음 토큰의 유효한 위치 중 하나가 현재 위치인지 확인합니다
- 일치 실패가 발생하거나 stop 문자열 전체가 완전히 일치할 때까지 계속합니다

Again, consider ["s", "to", "pped"] as an example. "pped" has an end overlap of 1, so we can begin a match. We have matched 1 character so far, so we check that the next token "to", has 1 as a valid position (again, counting from the end). It does, so we add the length of "to" to our position tracker. We have now matched 3 characters, so we check that the next token "s" has 3 as a valid position. It does, so we add its length to the position tracker. The position tracker is now 4, which is the length of the stop string. We have matched the entire stop string.

두 번째 경우, ["las", "topper"]에서 "topper"는 끝이 3만큼 겹치므로 매칭을 시작할 수 있습니다. 지금까지 3개의 문자를 매칭했으므로, 다음 토큰 "las"가 3을 유효한 위치로 가지는지 확인합니다. stop 문자열의 시작을 벗어나는 위치도 토큰이 매칭할 수 있도록 허용하기 때문에, 이는 유효합니다. 해당 토큰의 길이를 위치 추적기에 추가합니다. 이제 위치 추적기는 6이 되며, 이는 stop 문자열의 길이보다 큽니다. 그러나 당황하지 마세요. 이 경우에도 stop 문자열의 매칭으로 간주됩니다. stop 문자열 전체를 매칭한 것입니다.

예:

```python
>>> from transformers import AutoModelForCausalLM, AutoTokenizer

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

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

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

#### __call__[[transformers.StopStringCriteria.__call__]]

```python
__call__(input_ids: LongTensor, scores: tuple[torch.Tensor] | None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L475)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘(input sequence tokens)의 인덱스. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`tuple(torch.Tensor)`) : 언어 모델링 헤드의 예측 점수입니다. 생성 단계별로 하나의 텐서를 포함하는 튜플이며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다. 이는 SoftMax 적용 전 어휘 토큰별 점수일 수도 있고, SoftMax 적용 후 어휘 토큰별 점수일 수도 있습니다. 이 종료 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 그렇지 않으면 `None`이 전달됩니다.

kwargs (`dict[str, Any]`, *선택*) : 특정 stopping criteria에 대한 추가 kwargs.

**반환값:** `torch.BoolTensor`. (`(batch_size, 1)` 모양의 `torch.BoolTensor`)

`True`는 특정 행에 대해 생성을 중단함을 나타냅니다. `False`는 계속 진행해야 함을 나타냅니다.

#### transformers.EosTokenCriteria[[transformers.EosTokenCriteria]]

```python
transformers.EosTokenCriteria(eos_token_id: typing.Union[int, list[int], torch.Tensor])
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L537)

**매개변수:**

eos_token_id (`Union[int, list[int], torch.Tensor]`) : *end-of-sequence* 토큰의 id입니다.

이 클래스는 "end-of-sequence" 토큰이 생성될 때마다 생성을 중단하는 데 사용할 수 있습니다. 기본적으로 `model.generation_config.eos_token_id`를 사용합니다.

#### __call__[[transformers.EosTokenCriteria.__call__]]

```python
__call__(input_ids: LongTensor, scores: tuple[torch.Tensor] | None, new_token_length: int = 1, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/stopping_criteria.py#L554)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘(input sequence tokens)의 인덱스. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

scores (`tuple(torch.Tensor)`) : 언어 모델링 헤드의 예측 점수입니다. 생성 단계별로 하나의 텐서를 포함하는 튜플이며, 각 텐서의 모양은 `(batch_size, config.vocab_size)`입니다. 이는 SoftMax 적용 전 어휘 토큰별 점수일 수도 있고, SoftMax 적용 후 어휘 토큰별 점수일 수도 있습니다. 이 종료 기준이 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 그렇지 않으면 `None`이 전달됩니다.

new_token_length (`int`, *선택 사항*, 기본값 `1`) : 기준을 확인하는 토큰 수입니다. 각 배치 항목의 최신 `new_token_length`개 토큰이 확인됩니다.

kwargs (`dict[str, Any]`, *선택*) : 특정 stopping criteria에 대한 추가 kwargs.

**반환값:** `torch.BoolTensor`. (`(batch_size, 1)` 모양의 `torch.BoolTensor`)

`True`는 특정 행에 대해 생성을 중단함을 나타냅니다. `False`는 계속 진행해야 함을 나타냅니다.

## 스트리머[[transformers.TextStreamer]]

#### transformers.TextStreamer[[transformers.TextStreamer]]

```python
transformers.TextStreamer(tokenizer: PreTrainedTokenizerBase, skip_prompt: bool = False, **decode_kwargs: Any)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L41)

**매개변수:**

tokenizer (`AutoTokenizer`) : 토큰을 디코딩하는 데 사용되는 토크나이저.

skip_prompt (`bool`, *선택 사항*, 기본값 `False`) : `.generate()`에 프롬프트를 전달할지 여부를 지정합니다. 채팅봇 등에 유용합니다.

decode_kwargs (`dict`, *선택 사항*) : 토크나이저의 `decode` 메서드에 전달할 추가 키워드 인자.

Simple text streamer는 전체 단어가 형성되는 즉시 토큰을 stdout에 출력합니다.

예:

```python
>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer

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

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

#### 끝[[transformers.TextStreamer.end]]

```python
end()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L113)

남은 캐시를 모두 비우고 stdout에 새 줄을 출력합니다.

#### on_finalized_text[[transformers.TextStreamer.on_finalized_text]]

```python
on_finalized_text(text: str, stream_end: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L127)

새 텍스트를 stdout에 출력합니다. 스트림이 종료되는 경우 줄바꿈도 출력합니다.

#### put[[transformers.TextStreamer.put]]

```python
put(value)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L79)

토큰을 수신하고 디코딩한 후, 완전한 단어가 형성되는 즉시 stdout에 출력합니다.

#### transformers.TextIteratorStreamer[[transformers.TextIteratorStreamer]]

```python
transformers.TextIteratorStreamer(tokenizer: PreTrainedTokenizerBase, skip_prompt: bool = False, timeout: float | None = None, **decode_kwargs: Any)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L156)

**매개변수:**

tokenizer (`AutoTokenizer`) : 토큰을 디코딩하는 데 사용되는 토크나이저.

skip_prompt (`bool`, *선택 사항*, 기본값 `False`) : `.generate()`에 프롬프트를 전달할지 여부를 지정합니다. 채팅봇 등에 유용합니다.

timeout (`float`, *선택 사항*) : 텍스트 큐의 타임아웃입니다. `None`인 경우 큐가 무한정 차단됩니다. 별도 스레드에서 `.generate()`를 호출할 때 예외를 처리하는 데 유용합니다.

decode_kwargs (`dict`, *선택 사항*) : 토크나이저의 `decode` 메서드에 전달할 추가 키워드 인자.

출력 가능한 텍스트를 큐에 저장하여, 하위 애플리케이션에서 반복자(iterator)로 사용할 수 있는 스트리머입니다. 이는 생성된 텍스트를 비차단(non-blocking) 방식으로 접근하는 것이 유리한 애플리케이션(예: 인터랙티브 Gradio 데모)에 유용합니다.

예:

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

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

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

#### on_finalized_text[[transformers.TextIteratorStreamer.on_finalized_text]]

```python
on_finalized_text(text: str, stream_end: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L208)

새 텍스트를 큐에 넣습니다. 스트림이 종료되는 경우, 큐에 중지 신호도 넣습니다.

#### transformers.AsyncTextIteratorStreamer[[transformers.AsyncTextIteratorStreamer]]

```python
transformers.AsyncTextIteratorStreamer(tokenizer: PreTrainedTokenizerBase, skip_prompt: bool = False, timeout: float | None = None, **decode_kwargs: Any)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L225)

**매개변수:**

tokenizer (`AutoTokenizer`) : 토큰을 디코딩하는 데 사용되는 토크나이저.

skip_prompt (`bool`, *선택 사항*, 기본값 `False`) : `.generate()`에 프롬프트를 전달할지 여부를 지정합니다. 채팅봇 등에 유용합니다.

timeout (`float`, *선택 사항*) : 텍스트 큐의 타임아웃입니다. `None`인 경우 큐가 무한정 차단됩니다. 별도 스레드에서 `.generate()`를 호출할 때 예외를 처리하는 데 유용합니다.

decode_kwargs (`dict`, *선택 사항*) : 토크나이저의 `decode` 메서드에 전달할 추가 키워드 인자.

**예외:** ``TimeoutError``

- ``TimeoutError`` -- 토큰 생성 시간이 타임아웃 값을 초과한 경우.

…는 출력 가능한 텍스트를 큐에 저장하는 스트리머로, 하류 애플리케이션에서 비동기 반복자(async iterator)로 사용됩니다. 생성된 텍스트를 비동기적으로 접근하는 것이 유리한 애플리케이션(예: 인터랙티브 Gradio 데모)에 유용합니다.

예:

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

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

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

#### on_finalized_text[[transformers.AsyncTextIteratorStreamer.on_finalized_text]]

```python
on_finalized_text(text: str, stream_end: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L285)

새 텍스트를 큐에 넣습니다. 스트림이 종료되는 경우, 큐에 중지 신호도 넣습니다.

#### transformers.TextDiffusionStreamer[[transformers.TextDiffusionStreamer]]

```python
transformers.TextDiffusionStreamer(tokenizer: PreTrainedTokenizerBase, skip_prompt: bool = False, sleep_time: float | None = None, **decode_kwargs: Any)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L303)

**매개변수:**

tokenizer (`AutoTokenizer`) : 토큰을 디코딩하는 데 사용되는 토크나이저.

skip_prompt (`bool`, *선택 사항*, 기본값 `False`) : `.generate()`에 프롬프트를 전달할지 여부를 지정합니다. 채팅봇 등에 유용합니다.

sleep_time (`float`, *선택 사항*) : diffusion draft 사이에 sleep할 시간입니다. 중간 출력을 시각화하는 데 도움이 될 수 있습니다.

decode_kwargs (`dict`, *선택 사항*) : 토크나이저의 `decode` 메서드에 전달할 추가 키워드 인자.

텍스트 diffusion 출력을 출력하는 Streamer입니다. 중간 diffusion 단계(초안)는 일시적이며 후속 초안에 의해 덮어쓰이고, 확인된 텍스트가 출력되면 제거됩니다.

tmux와 같은 환경에서 실행 중인 경우, 초안 텍스트가 자기 자신을 덮어쓰지 못할 수 있습니다.

예:

```python
>>> from transformers import DiffusionGemmaForBlockDiffusion, AutoProcessor, TextDiffusionStreamer

>>> model = DiffusionGemmaForBlockDiffusion.from_pretrained(
...     "google/diffusiongemma-26B-A4B-it", device_map="auto",
... )
>>> processor = AutoProcessor.from_pretrained("google/diffusiongemma-26B-A4B-it")

>>> chat = [{"role": "user", "content": "Why is the sky blue?"},]
>>> input_ids = processor.apply_chat_template(
...     chat, tokenize=True, return_tensors="pt", add_generation_prompt=True
... )
>>> streamer = TextDiffusionStreamer(tokenizer=processor.tokenizer)
>>> model.generate(input_ids.to(model.device), max_new_tokens=512, streamer=streamer)
```

#### 끝[[transformers.TextDiffusionStreamer.end]]

```python
end()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L392)

남은 캐시를 모두 비우고 새 줄을 출력합니다.

#### put[[transformers.TextDiffusionStreamer.put]]

```python
put(value)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L387)

확인된 토큰을 수신하고, 초안을 지운 후, 이를 영구적으로 출력합니다.

#### put_draft[[transformers.TextDiffusionStreamer.put_draft]]

```python
put_draft(value, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/streamers.py#L365)

전체 draft 토큰 시퀀스를 받아 디코딩한 후 노란색으로 출력합니다. 이전 draft를 덮어씁니다.

## 캐시[[transformers.CacheLayerMixin]]

#### transformers.CacheLayerMixin[[transformers.CacheLayerMixin]]

```python
transformers.CacheLayerMixin(**kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L23)

단일 레이어의 캐시를 위한 기본 추상 클래스입니다.

#### 업데이트[[transformers.CacheLayerMixin.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L52)

#### get_seq_length[[transformers.CacheLayerMixin.get_seq_length]]

```python
get_seq_length()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L60)

#### get_mask_sizes[[transformers.CacheLayerMixin.get_mask_sizes]]

```python
get_mask_sizes(query_length: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L57)

#### get_max_length[[transformers.CacheLayerMixin.get_max_length]]

```python
get_max_length()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L63)

레이어가 보유할 수 있는 최대 시퀀스 길이를 반환합니다. `-1` 값은 최대치가 없거나 최대치가 정의되지 않음을 의미하며, 예를 들어 무한정 확장되는 동적 어텐션 레이어나 시퀀스 길이 차원이 없는 선형 어텐션 레이어가 해당됩니다.

#### 초기화[[transformers.CacheLayerMixin.reset]]

```python
reset()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L84)

cache 값을 초기화하되, 객체는 유지합니다

#### reorder_cache[[transformers.CacheLayerMixin.reorder_cache]]

```python
reorder_cache(beam_idx: LongTensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L97)

beam search를 위해 이 레이어의 캐시를 재배열합니다.

#### lazy_initialization[[transformers.CacheLayerMixin.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L49)

#### transformers.DynamicLayer[[transformers.DynamicLayer]]

```python
transformers.DynamicLayer(**kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L104)

생성되는 토큰이 증가함에 따라 동적으로 확장되는 캐시 레이어입니다. 이는 생성형 모델의 기본 방식입니다. 키와 값 상태를 `[batch_size, num_heads, seq_len, head_dim]` 형태의 텐서로 저장합니다.

#### 업데이트[[transformers.DynamicLayer.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L119)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

**반환값:** tuple[`torch.Tensor`, `torch.Tensor`]

키와 값 상태입니다.

key와 value 캐시를 인플레이스로 업데이트하고, 필요한 key 및 value 상태를 반환합니다.

#### lazy_initialization[[transformers.DynamicLayer.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L113)

#### crop[[transformers.DynamicLayer.crop]]

```python
crop(tokens_to_remove: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L164)

현재 캐시 레이어에서 `tokens_to_remove` 토큰을 제거합니다.

#### batch_repeat_interleave[[transformers.DynamicLayer.batch_repeat_interleave]]

```python
batch_repeat_interleave(repeats: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L183)

`repeats`만큼 배치 차원 방향으로 캐시를 반복합니다.

#### batch_select_indices[[transformers.DynamicLayer.batch_select_indices]]

```python
batch_select_indices(indices: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L189)

캐시의 배치 차원에는 `indices`만 유지합니다.

#### transformers.StaticLayer[[transformers.StaticLayer]]

```python
transformers.StaticLayer(max_cache_len: int, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L403)

**매개변수:**

max_cache_len (`int`) : 저장할 수 있는 최대 토큰 수. 텐서 사전 할당에 사용됩니다.

`[batch_size, num_heads, max_cache_len, head_dim]` 형태의 정적 텐서로 key와 value 상태를 저장하는 정적 캐시 레이어입니다. 전체 백킹 텐서를 지연 배정(lazy allocation)한 후, 이를 인플레이스(in-place)로 변경합니다. `torch.compile` 지원을 위해 설계되었습니다.

#### 업데이트[[transformers.StaticLayer.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L461)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

**반환값:** tuple[`torch.Tensor`, `torch.Tensor`]

키와 값 상태입니다.

key와 value 캐시를 인플레이스로 업데이트하고, 필요한 key 및 value 상태를 반환합니다.

#### lazy_initialization[[transformers.StaticLayer.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L423)

키와 값 텐서의 지연 초기화. 이를 통해 런타임에 dtype, device, TP의 경우 num_heads 등 모든 속성을 직접 가져올 수 있으며, 이는 각 `update` 시점에 device, dtype 등을 다시 이동할 필요가 없어 매우 실용적입니다(이 과정은 정적 dynamo 주소도 깨뜨릴 수 있습니다).

이것이 원치 않는 동작이라면, Cache에 직접 `early_initialization(...)`을 호출하여 이 함수를 사전에 호출할 수 있습니다(예를 들어 `torch.export`의 경우 필수입니다). 또한 prefill 자체가 컴파일 영역에 포함되는 경우(예: chunked prefill)에도 필요합니다.

#### transformers.StaticSlidingWindowLayer[[transformers.StaticSlidingWindowLayer]]

```python
transformers.StaticSlidingWindowLayer(max_cache_len: int, sliding_window: int, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L510)

**매개변수:**

max_cache_len (`int`) : 저장할 수 있는 최대 토큰 수. 텐서 사전 할당에 사용됩니다.

sliding_window (`int`) : 슬라이딩 윈도우의 크기.

`[batch_size, num_heads, min(max_cache_len, sliding_window), head_dim]` 형태의 정적 텐서로 key와 value 상태를 저장하는 정적 캐시 레이어입니다. 전체 백킹 텐서를 지연 배분한 후, 이를 인플레이스(in-place)로 수정합니다. `torch.compile` 지원을 위해 설계되었습니다.

#### 업데이트[[transformers.StaticSlidingWindowLayer.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L531)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

**반환값:** tuple[`torch.Tensor`, `torch.Tensor`]

키와 값 상태입니다.

key와 value 캐시를 인플레이스로 업데이트하고, 필요한 key 및 value 상태를 반환합니다.

#### lazy_initialization[[transformers.StaticSlidingWindowLayer.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L423)

키와 값 텐서의 지연 초기화. 이를 통해 런타임에 dtype, device, TP의 경우 num_heads 등 모든 속성을 직접 가져올 수 있으며, 이는 각 `update` 시점에 device, dtype 등을 다시 이동할 필요가 없어 매우 실용적입니다(이 과정은 정적 dynamo 주소도 깨뜨릴 수 있습니다).

이것이 원치 않는 동작이라면, Cache에 직접 `early_initialization(...)`을 호출하여 이 함수를 사전에 호출할 수 있습니다(예를 들어 `torch.export`의 경우 필수입니다). 또한 prefill 자체가 컴파일 영역에 포함되는 경우(예: chunked prefill)에도 필요합니다.

#### transformers.QuantoQuantizedLayer[[transformers.QuantoQuantizedLayer]]

```python
transformers.QuantoQuantizedLayer(nbits: int = 4, axis_key: int = 0, axis_value: int = 0, q_group_size: int = 64, residual_length: int = 128)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L854)

#### 업데이트[[transformers.QuantoQuantizedLayer.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L781)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

**반환값:** tuple[`torch.Tensor`, `torch.Tensor`]

키와 값 상태입니다.

key와 value 캐시를 인플레이스로 업데이트하고, 필요한 key 및 value 상태를 반환합니다.

#### lazy_initialization[[transformers.QuantoQuantizedLayer.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L113)

#### transformers.HQQQuantizedLayer[[transformers.HQQQuantizedLayer]]

```python
transformers.HQQQuantizedLayer(nbits: int = 4, axis_key: int = 0, axis_value: int = 0, q_group_size: int = 64, residual_length: int = 128)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L909)

#### 업데이트[[transformers.HQQQuantizedLayer.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L781)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

**반환값:** tuple[`torch.Tensor`, `torch.Tensor`]

키와 값 상태입니다.

key와 value 캐시를 인플레이스로 업데이트하고, 필요한 key 및 value 상태를 반환합니다.

#### lazy_initialization[[transformers.HQQQuantizedLayer.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L113)

#### transformers.Fp8QuantizedLayer[[transformers.Fp8QuantizedLayer]]

```python
transformers.Fp8QuantizedLayer()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L966)

8-bit 부동소수점으로 key와 value 상태를 저장하는 양자화 레이어입니다. 첫 번째 `update` 이후에 per-tensor scale이 고정되므로, 새로운 상태는 그대로 추가됩니다: 잔여 캐시도, 재양자화도 없습니다.

더 세밀한 변형은 `QuantizedLayer` 아래가 아니라 여기에 속합니다. head 차원을 기준으로 그룹을 나누면 상태를 appendable 상태로 유지할 수 있고, 저장된 scale만 tensor로 변환되기 때문입니다.

#### 업데이트[[transformers.Fp8QuantizedLayer.update]]

```python
update(key_states: Tensor, value_states: Tensor, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L994)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

**반환값:** tuple[`torch.Tensor`, `torch.Tensor`]

키와 값 상태입니다.

key와 value 캐시를 인플레이스로 업데이트하고, 필요한 key 및 value 상태를 반환합니다.

#### lazy_initialization[[transformers.Fp8QuantizedLayer.lazy_initialization]]

```python
lazy_initialization(key_states: Tensor, value_states: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L978)

#### transformers.Cache[[transformers.Cache]]

```python
transformers.Cache(layers: list[transformers.cache_utils.CacheLayerMixin | transformers.cache_utils.LinearAttentionCacheLayerMixin | transformers.cache_utils.DummyLayer] | None = None, layer_class_to_replicate: type[transformers.cache_utils.CacheLayerMixin | transformers.cache_utils.LinearAttentionCacheLayerMixin] | None = None, offloading: bool = False, offload_only_non_sliding: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1453)

**매개변수:**

layers (`Optional`, *선택 사항*) : 미리 생성된 `CacheLayerMixin` 또는 `LinearAttentionCacheLayerMixin`의 목록입니다. 생략(`None`)된 경우 `layer_class_to_replicate`가 사용됩니다.

layer_class_to_replicate (`type[CacheLayerMixin | LinearAttentionCacheLayerMixin]`, *선택*) : `layers`가 생략된 경우(`None`)에만 사용되며, 이 경우 각 레이어의 베이스 클래스로 사용되고, `layer_idx`가 현재 레이어 목록보다 큰 값으로 `update`가 호출되는 시점에 레이어가 지연 추가됩니다.

offloading (`bool`, *선택 사항*, 기본값 `False`) : GPU 메모리를 절약하기 위해 레이어를 `cpu`로 오프로딩할지 여부.

offload_only_non_sliding (`bool`, *선택 사항*, 기본값 `True`) : `offloading`이 `True`인 경우, 슬라이딩 레이어가 아닌 레이어만 오프로딩할지 여부를 추가로 결정합니다. (보통 슬라이딩 레이어의 크기가 작아 오프로딩할 필요가 없으며, 건너뛰는 것이 더 빠릅니다.)

`Cache`는 기본적으로 모델 레이어마다 하나씩 배치된 `CacheLayerMixin` 객체의 목록입니다. 각 레이어의 Cache를 담는 컨테이너 역할을 합니다.

#### 업데이트[[transformers.Cache.update]]

```python
update(key_states: Tensor, value_states: Tensor, layer_idx: int, *args, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1540)

**매개변수:**

key_states (`torch.Tensor`) : 캐시에 저장할 새로운 키 상태.

value_states (`torch.Tensor`) : 캐시에 저장할 새로운 값 상태.

layer_idx (`int`) : 상태를 캐시할 레이어의 인덱스입니다.

**반환값:**

업데이트된 key와 value 상태를 포함하는 tuple입니다.

`layer_idx` 레이어에 대해 캐시를 새로운 `key_states`와 `value_states`로 업데이트합니다.

#### early_initialization[[transformers.Cache.early_initialization]]

```python
early_initialization(batch_size: int, num_heads: int | list[int], head_dim: int | list[int], dtype: dtype, device: device)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1669)

모든 레이어를 사전에 초기화합니다(그렇지 않으면 첫 번째 `update` 호출 시 지연 초기화됩니다). `export` 레시피에 유용하며, `export`는 모든 것이 사전에 준비되어야 하기 때문입니다.

#### get_seq_length[[transformers.Cache.get_seq_length]]

```python
get_seq_length(layer_idx: int = 0)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1706)

…

#### get_mask_sizes[[transformers.Cache.get_mask_sizes]]

```python
get_mask_sizes(query_length: int, layer_idx: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1776)

`layer_idx`의 해당 레이어에 대해 반환될 길이와 오프셋에 해당하는 튜플 (kv_length, kv_offset)을 반환합니다. 이후 각 레이어의 주어진 길이(kv_length, kv_offset)와 패턴에 따라 마스크가 준비됩니다.

#### get_max_length[[transformers.Cache.get_max_length]]

```python
get_max_length(layer_idx: int | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1730)

캐시의 최대 길이를 반환합니다. `layer_idx`가 제공되지 않은 경우(기본값)에는 모든 레이어에 걸친 최대 값을 반환합니다. 그렇지 않은 경우, 해당 레이어에 대해 지원되는 최대 값을 반환합니다. `-1` 값은 최대치가 없거나 최대치가 정의되지 않음을 의미하며, 예를 들어 무한정 확장될 수 있는 동적 attention 레이어나 시퀀스 길이 차원이 없는 선형 attention 레이어에 해당합니다.

#### 초기화[[transformers.Cache.reset]]

```python
reset()
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1813)

모든 레이어 텐서를 재귀적으로 초기화

#### reorder_cache[[transformers.Cache.reorder_cache]]

```python
reorder_cache(beam_idx: LongTensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1818)

beam search를 위한 캐시 재배치

#### crop[[transformers.Cache.crop]]

```python
crop(tokens_to_remove: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1823)

현재 Cache에서 `tokens_to_remove` 토큰을 제거합니다. 메모리에 모든 과거 상태를 유지할 필요가 없는 레이어(슬라이딩 윈도우 레이어나 선형 어텐션 레이어 등)의 경우, 캐시된 상태의 크기를 최소 작업 크기로 다시 제한합니다. 따라서 `crop(0)`이 항상 no-op인 것은 아니며, 다음 `forward`에 필요하지 않은 상태(즉, 불필요한 상태)를 Cache에서 제거할 수 있습니다.

#### batch_repeat_interleave[[transformers.Cache.batch_repeat_interleave]]

```python
batch_repeat_interleave(repeats: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1833)

캐시를 반복하고 교차 삽입

#### batch_select_indices[[transformers.Cache.batch_select_indices]]

```python
batch_select_indices(indices: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1838)

캐시에서 인덱스 선택

#### transformers.DynamicCache[[transformers.DynamicCache]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L1960)

**매개변수:**

ddp_cache_data (`Iterable[tuple[torch.Tensor, torch.Tensor]]`, *선택*) : 원래 `torch.distributed`(DDP)와의 호환성을 위해 추가되었습니다. 간단히 말하면 `map(gather_map, zip(*caches))`이며, 즉 이터러블의 각 항목에는 torch.distributed를 통해 리플리카 전체에서 수집된 레이어의 키와 값 상태가 포함됩니다(shape=[global batch size, num_heads, seq_len, head_dim]). 참고: 올바르게 작동하려면 1번째 인수로 전달되어야 합니다

config (`PreTrainedConfig`, *선택*) : 이 Cache가 사용될 모델의 config입니다. 전달된 경우, 슬라이딩 또는 하이브리드 레이어 구조를 확인하는 데 사용되어 캐시된 텐서의 메모리 요구량을 `[batch_size, num_heads, min(seq_len, sliding_window), head_dim]`으로 크게 줄일 수 있습니다.

offloading (`bool`, *선택 사항*, 기본값 `False`) : GPU 메모리를 절약하기 위해 레이어를 `cpu`로 오프로딩할지 여부.

offload_only_non_sliding (`bool`, *선택 사항*, 기본값 `False`) : `offloading`이 `True`인 경우, 슬라이딩하지 않는 레이어만 오프로딩할지 여부를 추가로 결정합니다. (일반적으로 슬라이딩 레이어의 크기가 작아 오프로딩할 필요가 없으며, 이를 건너뛰는 것이 더 빠릅니다.)

생성되는 토큰이 증가함에 따라 동적으로 확장되는 캐시입니다. 이는 생성형 모델의 기본값입니다. 각 레이어에 하나씩, `CacheLayer`의 리스트 형태로 key와 value 상태를 저장합니다. `CacheLayer`의 각 텐서에 대한 예상 shape는 `[batch_size, num_heads, seq_len, head_dim]`입니다. config가 전달되면 sliding 또는 hybrid 캐시 구조를 추가로 확인하여, 캐시된 텐서의 메모리 요구량을 `[batch_size, num_heads, min(seq_len, sliding_window), head_dim]`으로 크게 줄입니다.

모든 캐시 클래스에서 구현되는 공통 메서드에 대한 자세한 내용은 `Cache`를 참조하세요.

예:

```python
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, DynamicCache

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

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

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

#### transformers.StaticCache[[transformers.StaticCache]]

```python
transformers.StaticCache(config: PreTrainedConfig, max_cache_len: int, offloading: bool = False, offload_only_non_sliding: bool = True, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2056)

**매개변수:**

config (`PreTrainedConfig`) : 이 Cache가 사용될 모델의 config입니다. 슬라이딩 또는 하이브리드 레이어 구조를 확인하고 각 레이어를 그에 맞게 초기화하는 데 사용됩니다.

max_cache_len (`int`) : 이 Cache가 보유해야 할 최대 토큰 수입니다.

offloading (`bool`, *선택 사항*, 기본값 `False`) : GPU 메모리를 절약하기 위해 레이어를 `cpu`로 오프로딩할지 여부.

offload_only_non_sliding (`bool`, *선택 사항*, 기본값 `True`) : `offloading`이 `True`인 경우, 슬라이딩 레이어가 아닌 레이어만 오프로딩할지 여부를 추가로 결정합니다. (보통 슬라이딩 레이어의 크기가 작아 오프로딩할 필요가 없으며, 건너뛰는 것이 더 빠릅니다.)

`torch.compile(model)` 및 `torch.export()`와 함께 사용할 Static Cache 클래스입니다. `config`에서 잠재적인 하이브리드 캐시 구조를 확인하고, 각 레이어를 그에 맞게 초기화합니다.

모든 캐시 클래스에서 구현되는 공통 메서드에 대한 자세한 내용은 `Cache`를 참조하세요.

예:

```python
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, StaticCache

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

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

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

#### transformers.QuantizedCache[[transformers.QuantizedCache]]

```python
transformers.QuantizedCache(backend: str, config: PreTrainedConfig, nbits: int | None = None, axis_key: int | None = None, axis_value: int | None = None, q_group_size: int | None = None, residual_length: int | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2113)

**매개변수:**

backend (`str`) : 사용할 양자화 백엔드입니다. `("quanto", "hqq", "fp8")` 중 하나입니다.

config (`PreTrainedConfig`) : 이 Cache가 사용될 모델의 config입니다.

nbits (`int`, *선택 사항*, 기본값 4) : 양자화에 사용할 비트 수입니다.

axis_key (`int`, *선택 사항*, 기본값 0) : 키를 양자화할 축.

axis_value (`int`, *선택 사항*, 기본값 0) : 값을 양자화할 축.

q_group_size (`int`, *선택 사항*, 기본값 64) : 양자화는 키와 값 모두에 대해 설정된 `q_group_size`에 따라 채널별로 수행됩니다.

residual_length (`int`, *선택 사항*, 기본값 128) : 원본 정밀도 캐시의 최대 용량입니다.

[KIVI: A Tuning-Free Asymmetric 2bit Quantization for KV Cache](https://huggingface.co/papers/2402.02750) 논문에서 설명한 것과 유사한 양자화 캐시입니다. 양자화를 적용하여 키와 값에 과도한 메모리를 할당하지 않으면서도 모델이 더 긴 시퀀스 길이를 생성할 수 있도록 합니다. 이 캐시는 원본 정밀도와 양자화된 캐시를 위한 두 가지 유형의 저장소를 가집니다. `residual length`는 원본 정밀도 캐시의 최대 용량으로 설정됩니다. 길이가 최대 용량을 초과하면 원본 정밀도 캐시는 폐기되고 양자화된 캐시로 이동합니다. 논문에서 설명한 것과 달리, 양자화는 키와 값 모두에 대해 채널별로 설정된 `q_group_size`를 사용하여 수행됩니다.

모든 캐시 클래스에서 구현되는 공통 메서드에 대한 자세한 내용은 `Cache`를 참조하세요.

마지막 다섯 개의 인수는 그룹 단위 정수 백엔드를 구성합니다. `fp8` 백엔드는 텐서별 양자화를 수행하며, 이 인수를 거부합니다.

#### transformers.EncoderDecoderCache[[transformers.EncoderDecoderCache]]

```python
transformers.EncoderDecoderCache(*caches)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2199)

**매개변수:**

caches (`Iterable`) : 보통 길이가 2인 반복 가능 객체로, 2개의 `Cache` 객체를 포함합니다. 첫 번째는 self-attention을 위해, 두 번째는 cross-attention을 위해 사용됩니다. 선택적으로, `tuple[tuple[torch.Tensor]]`를 포함하는 길이가 1인 반복 가능 객체일 수도 있습니다(보통 torch dp 및 ddp와의 호환성을 위해 사용).

모든 encoder-decoder cache의 기본 추상 클래스입니다. self-attention cache와 cross-attention cache의 조합을 보유하는 데 사용할 수 있습니다.

모든 캐시 클래스에서 구현되는 공통 메서드에 대한 자세한 내용은 `Cache`를 참조하세요.

예:

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

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

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

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

#### batch_repeat_interleave[[transformers.EncoderDecoderCache.batch_repeat_interleave]]

```python
batch_repeat_interleave(repeats: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2316)

`repeats`만큼 배치 차원 방향으로 캐시를 반복합니다. 대조적 검색(허브에서)에 사용됩니다.

#### batch_select_indices[[transformers.EncoderDecoderCache.batch_select_indices]]

```python
batch_select_indices(indices: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2322)

캐시의 배치 차원 `indices`만 유지합니다. 대조적 검색(Hub에서)에 사용됩니다.

#### crop[[transformers.EncoderDecoderCache.crop]]

```python
crop(tokens_to_remove: int)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2309)

현재 캐시 레이어에서 `tokens_to_remove` 토큰을 제거합니다.

#### get_max_length[[transformers.EncoderDecoderCache.get_max_length]]

```python
get_max_length(layer_idx: int | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2284)

캐시 객체의 최대 시퀀스 길이(즉, 최대 용량)를 반환합니다

#### get_seq_length[[transformers.EncoderDecoderCache.get_seq_length]]

```python
get_seq_length(layer_idx: int = 0)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2280)

캐시된 상태의 시퀀스 길이를 반환합니다. 레이어 인덱스를 선택적으로 전달할 수 있습니다.

#### reorder_cache[[transformers.EncoderDecoderCache.reorder_cache]]

```python
reorder_cache(beam_idx: LongTensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/cache_utils.py#L2294)

선택된 빔 인덱스가 주어지면 빔 검색을 위해 캐시를 다시 정렬합니다.

## 워터마크 유틸[[transformers.WatermarkingConfig]]

#### transformers.WatermarkingConfig[[transformers.WatermarkingConfig]]

```python
transformers.WatermarkingConfig(greenlist_ratio: float = 0.25, bias: float = 2.0, hashing_key: int = 15485863, seeding_scheme: str = 'lefthash', context_width: int = 1)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/configuration_utils.py#L1460)

워터마크 생성에 필요한 인수를 포함하는 클래스로, `generate` 시에 `GenerationConfig`에 전달해야 합니다. 인자에 대한 자세한 내용은 [이 논문](https://huggingface.co/papers/2306.04634)을 참고하세요.

다음 키를 받습니다:
- greenlist_ratio (`float`): 워터마킹에 사용됩니다. 어휘 크기 대비 "green" 토큰 사용 비율입니다. 기본값은 0.25입니다.
- bias (`float`): 워터마킹과 함께 사용됩니다. 선택된 "green" 토큰의 logits에 추가되는 bias입니다. 기본값은 2.0입니다.
- hashing_key (`int`): 워터마킹에 사용되는 해싱 키입니다. 기본값은 15485863(100만 번째 소수)입니다.
- seeding_scheme (`str`): 워터마킹에 사용할 알고리즘. 허용되는 값:
  - "lefthash" (기본값): "green" 토큰 선택은 마지막 토큰에 따라 결정됩니다(논문 Algorithm 2).
  - "selfhash"의 "green" 토큰 선택은 현재 토큰 자체에 따라 결정됩니다(논문 Algorithm 3). 이 방식의 단점은 모든 가능한 다음 토큰을 고려해야 하므로 "lefthash"보다 느릴 수 있다는 것입니다.
- context_width(`int`): 시딩에 사용할 이전 토큰의 컨텍스트 길이입니다. 컨텍스트 길이가 길수록 워터마킹이 더 강건해집니다.

#### __call__[[transformers.WatermarkingConfig.__call__]]

```python
__call__(*args, **kwargs)
```

self를 함수로 호출합니다.

#### transformers.WatermarkDetector[[transformers.WatermarkDetector]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L71)

**매개변수:**

model_config (`PreTrainedConfig`) : 생성 시 모델별 인수를 가져오는 데 사용되는 모델 설정입니다.

device (`str`) : 워터마크 텍스트 생성 시 사용된 장치입니다.

watermarking_config (Union[`WatermarkingConfig`, `Dict`]) : 텍스트 생성 시 사용된 것과 동일한 워터마킹 설정 및 인자입니다.

ignore_repeated_ngrams (`bool`, *선택 사항*, 기본값 `False`) : 각 고유 ngram을 한 번만 카운트할지 여부.

max_cache_size (`int`, *선택 사항*, 기본값 128) : 모든 토큰에 대해 호출되는 시딩/샘플링 알고리즘의 LRU 캐싱에 사용할 최대 크기입니다.

워터마크가 생성된 텍스트를 감지하는 Detector입니다. Detector는 텍스트 생성 시 사용된 설정과 정확히 동일한 설정을 제공받아 워터마크 greenlist 생성을 재현하고, 이를 통해 워터마크를 감지해야 합니다. 여기에는 텍스트 생성 시 사용된 올바른 device, 올바른 워터마크링 인자, 올바른 tokenizer vocab size가 포함됩니다. 해당 코드는 [original repo](https://github.com/jwkirchenbauer/lm-watermarking/tree/main)를 기반으로 작성되었습니다.

자세한 내용은 [논문](https://huggingface.co/papers/2306.04634)을 참고하세요.

예:

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

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

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

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

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

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

#### __call__[[transformers.WatermarkDetector.__call__]]

```python
__call__(input_ids: LongTensor, z_threshold: float = 3.0, return_dict: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L193)

**매개변수:**

input_ids (`torch.LongTensor`) : 워터마크가 생성된 텍스트입니다. 감지에 영향을 줄 수 있으므로 프롬프트를 제거하는 것이 좋습니다.

z_threshold (`Dict`, *선택 사항*, 기본값 `3.0`) : 이 임계값을 변경하면 탐지기의 민감도가 변경됩니다. z 임계값이 높을수록 민감도가 낮아지고, z 임계값이 낮을수록 민감도가 높아집니다.

return_dict (`bool`, *선택 사항*, 기본값 `False`) : `~generation.WatermarkDetectorOutput`를 반환할지 여부입니다. 반환하지 않으면 boolean 예측 값을 반환합니다.

**반환값:** `WatermarkDetectorOutput` 또는 `np.ndarray`

`return_dict=True`인 경우 `WatermarkDetectorOutput`, 그렇지 않으면 `np.ndarray`를 반환합니다.

ma

#### transformers.BayesianDetectorConfig[[transformers.BayesianDetectorConfig]]

```python
transformers.BayesianDetectorConfig(watermarking_depth: int | None = None, base_rate: float = 0.5, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L252)

**매개변수:**

watermarking_depth (`int`, *선택 사항*) : 토너먼트 레이어의 수입니다.

base_rate (`float`, *선택*, 기본값 0.5) : 텍스트가 워터마크 처리되었을 때의 사전 확률 P(w).

이것은 [BayesianDetectorModel](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.BayesianDetectorModel)의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Bayesian Detector 모델을 인스턴스화하는 데 사용됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

#### transformers.BayesianDetectorModel[[transformers.BayesianDetectorModel]]

```python
transformers.BayesianDetectorModel(config)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L359)

**매개변수:**

config ([BayesianDetectorConfig](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.BayesianDetectorConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

워터마크 감지를 위한 베이지안 분류기.

이 detektor는 Bayes' rule을 사용하여 워터마킹 점수를 계산합니다. 이 점수는 사후 확률 P(watermarked|g_values)과 P(unwatermarked|g_values)의 비율의 로그에 대한 sigmoid 값입니다. 자세한 내용은 해당 논문의 BayesianScore 섹션을 참고하세요. 논문 URL: https://www.nature.com/articles/s41586-024-08025-4

이 검출기는 Bernoulli(0.5) g-value 분포를 사용하는 비왜곡 Tournament 기반 워터마킹에서만 작동한다는 점에 유의하세요.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.BayesianDetectorModel.forward]]

```python
forward(g_values: Tensor, mask: Tensor, labels: typing.Optional[torch.Tensor] = None, loss_batch_weight = 1, return_dict = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L448)

**매개변수:**

g_values (`torch.Tensor`, shape `(batch_size, seq_len, watermarking_depth, ...)`) : g-values (값이 0 또는 1)

mask : 어떤 g-value를 사용할지 나타내는 이진 배열로, shape은 [batch_size, seq_len]입니다. mask 값이 0인 g-value는 폐기됩니다.

**반환값:**

p(watermarked | g_values), shape [batch_size].

워터마크가 적용된 사후 확률 P(watermarked|g_values)을 계산합니다.

#### transformers.SynthIDTextWatermarkingConfig[[transformers.SynthIDTextWatermarkingConfig]]

```python
transformers.SynthIDTextWatermarkingConfig(ngram_len: int, keys: list[int], context_history_size: int = 1024, sampling_table_seed: int = 0, sampling_table_size: int = 65536, skip_first_ngram_calls: bool = False, debug_mode: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/configuration_utils.py#L1540)

**매개변수:**

ngram_len (`int`) : Ngram 길이.

keys (`list[int]`) : 각 깊이에 하나씩 해당하는 워터마킹 키의 시퀀스.

context_history_size (`int`, *선택 사항*, 기본값 1024) : 확인된 컨텍스트를 추적하기 위해 유지할 텐서의 크기.

sampling_table_seed (`int`, *선택 사항*, 기본값 0) : 샘플링 테이블을 생성할 때 사용할 무작위 시드입니다.

sampling_table_size (`int`, *선택 사항*, 기본값 65536) : 샘플링 테이블의 크기.

skip_first_ngram_calls (`bool`, *선택 사항*, 기본값 `False`) : 첫 번째 ngram 호출을 건너뛸지 여부.

debug_mode (`bool`, *선택 사항*, 기본값 `False`) : 워터마킹 수정이 적용되기 전에 균일한 분포로 수정된 logits를 반환합니다. 이는 구현을 테스트하기 위한 것입니다.

워터마크 생성에 필요한 인수를 포함하는 클래스로, `generate` 시에 `GenerationConfig`에 전달해야 합니다. 인자에 대한 자세한 내용은 [이 논문](https://www.nature.com/articles/s41586-024-08025-4)을 참고하세요.

예:
```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)
```

#### transformers.SynthIDTextWatermarkDetector[[transformers.SynthIDTextWatermarkDetector]]

```python
transformers.SynthIDTextWatermarkDetector(detector_module: BayesianDetectorModel, logits_processor: SynthIDTextWatermarkLogitsProcessor, tokenizer: Any)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L492)

**매개변수:**

detector_module ([BayesianDetectorModel](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.BayesianDetectorModel)) : 매개변수로 초기화된 Bayesian detector 모듈 객체입니다. 사용법은 https://github.com/huggingface/transformers-research-projects/tree/main/synthid_text 를 확인하세요.

logits_processor (`SynthIDTextWatermarkLogitsProcessor`) : 워터마킹에 사용되는 logits 프로세서입니다.

tokenizer (`Any`) : 모델에 사용되는 토크나이저.

SynthID 텍스트 워터마크 감지 클래스.

이 클래스는 학습된 bayesian detector 모듈로 초기화되어야 합니다. 예를 들어 examples/synthid_text/detector_training.py 스크립트를 참고하여 이 detector 모듈을 학습/저장/로드하는 방법을 확인하세요. 해당 폴더에는 이 detector의 사용 예시도 포함되어 있습니다.

예:
```python
>>> from transformers import (
...     AutoTokenizer, BayesianDetectorModel, SynthIDTextWatermarkLogitsProcessor, SynthIDTextWatermarkDetector
... )

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

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

#### __call__[[transformers.SynthIDTextWatermarkDetector.__call__]]

```python
__call__(tokenized_outputs: Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/watermarking.py#L539)

## 컴파일 유틸[[transformers.CompileConfig]]

#### transformers.CompileConfig[[transformers.CompileConfig]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/configuration_utils.py#L1632)

**매개변수:**

fullgraph (`bool`, *선택 사항*, 기본값 `False`) : False(기본값)인 경우, 최적화될 컴파일 가능 영역을 탐색하려고 합니다. True인 경우, 전체 함수가 단일 그래프로 캡처될 수 있어야 합니다. 이것이 불가능한 경우(즉, 그래프 브레이크가 있는 경우) 오류가 발생합니다.

dynamic (`bool` 또는 `None`, *선택 사항*) : 동적 shape graph를 사용하려고 할지 여부.

backend (`str` 또는 `Callable`, *선택 사항*, 기본값은 `"inductor"`) : 사용할 Backend입니다.

mode (`str`, *선택 사항*, 기본값 `"reduce-overhead"`) : 성능과 오버헤드 사이의 균형을 제어합니다.

options (`dict`, *선택 사항*) : 백엔드에 전달할 옵션의 사전입니다.

`generate`에서 자동 컴파일을 사용할 때 `torch.compile` 동작과 관련된 인수를 포함하는 클래스입니다. 인수에 대한 자세한 내용은 [`torch.compile`](https://pytorch.org/docs/stable/generated/torch.compile.html)을 참조하세요.

예:
```python
>>> from transformers import AutoModelForCausalLM, AutoTokenizer, CompileConfig

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

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

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

#### __call__[[transformers.CompileConfig.__call__]]

```python
__call__(*args, **kwargs)
```

self를 함수로 호출합니다.

