# 생성

각 프레임워크에는 텍스트 생성을 위한 generate 메서드가 각각의 `GenerationMixin` 클래스에 구현되어 있습니다:

- PyTorch의 [generate()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin.generate)는 [GenerationMixin](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin)에 구현되어 있습니다.

generate 메서드는 [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig) 클래스 인스턴스로 매개변수화할 수 있습니다. 생성 메서드의 동작을 제어하는 생성 매개변수의 전체 목록은 해당 클래스를 참고하세요.

모델의 생성 구성을 검사하는 방법, 기본값이 무엇인지, 매개변수를 임시로 변경하는 방법, 그리고 사용자 정의 생성 구성을 생성하고 저장하는 방법에 대해서는 [텍스트 생성 전략 가이드](../generation_strategies)를 참조하세요. 이 가이드에서는 토큰 스트리밍과 같은 관련 기능 사용 방법도 설명합니다.

## GenerationConfig[[transformers.GenerationConfig]]

#### transformers.GenerationConfig[[transformers.GenerationConfig]]

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

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

**출력의 길이를 제어하는 매개변수:**

max_length (`int`, *선택 사항*) : 모델이 생성할 토큰 수를 제어하는 데는 `max_new_tokens`를 사용하는 것이 권장됩니다. `max_length`는 하위 호환성을 위해 유지됩니다.

max_new_tokens (`int`, *선택 사항*) : 프롬프트의 토큰 수를 무시하고 생성할 최대 토큰 수입니다.

min_length (`int`, *선택 사항*) : 생성할 시퀀스의 최소 길이입니다. 입력 프롬프트의 길이 + `min_new_tokens`에 해당합니다. `min_new_tokens`도 함께 설정된 경우, `min_new_tokens`의 값이 우선 적용됩니다.

min_new_tokens (`int`, *선택 사항*) : 프롬프트의 토큰 수를 무시하고 생성할 최소 토큰 수입니다.

early_stopping (`bool` 또는 `str`, *선택 사항*) : beam-search와 같은 beam 기반 방법의 종료 조건을 제어합니다. 다음 값을 허용합니다: `True`는 `num_beams`개의 완전한 후보가 있는 즉시 생성을 중단하는 경우, `False`는 휴리스틱이 적용되어 더 나은 후보를 찾을 가능성이 매우 낮을 때 생성을 중단하는 경우, `"never"`는 더 나은 후보가 있을 수 없을 때만 beam search 절차가 중단되는 경우(정규 beam search 알고리즘)입니다.

max_time (`float`, *선택 사항*) : 연산이 실행될 수 있는 최대 시간을 초 단위로 지정합니다. 할당된 시간이 경과한 후에도 generation은 현재 패스를 완료합니다.

stop_strings (`str` 또는 `list[str]`, *선택*) : 모델이 출력할 경우 생성을 종료해야 하는 문자열 또는 문자열 목록입니다.

**생성 전략을 제어하는 매개변수:**

do_sample (`bool`) : 샘플링을 사용할지 여부. 그렇지 않으면 greedy decoding을 사용합니다.

num_beams (`int`, *선택 사항*) : beam search에 사용할 beam의 수입니다. 1은 beam search를 사용하지 않음을 의미합니다.

use_mtp : (`bool`): 모델이 지원하는 경우 Multi-Token Prediction(MTP)을 사용할지 여부.

**캐시를 제어하는 매개변수:**

use_cache (`bool`) : 모델이 디코딩 속도를 높이기 위해 과거의 마지막 key/values attention을 사용할지 여부(모델에 해당 기능이 있는 경우).

cache_implementation (`str`, *선택 사항*) : `generate`에서 더 빠른 디코딩을 위해 인스턴스화될 캐시 클래스의 이름입니다. 가능한 값은 다음과 같습니다:  - `"dynamic"`: [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache) - `"static"`: [StaticCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.StaticCache) - `"offloaded"`: `DynamicCache(offloaded=True)` - `"offloaded_static"`: `StaticCache(offloaded=True)` - `"quantized"`: [QuantizedCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.QuantizedCache)  지정되지 않으면 모델의 기본 캐시(대부분 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)입니다)를 사용합니다. 자세한 내용은 [캐시 문서](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

cache_config (`dict`, *선택 사항*, 기본값 `None`) : key-value cache 클래스에서 사용되는 인수는 `cache_config`를 통해 전달할 수 있습니다.

max_cache_len (`int`, *선택 사항*) : 정적 캐시(`cache_implementation`가 `"static"` 또는 `"offloaded_static"`로 설정된 경우)에서만 사용됩니다. 현재 호출의 `max_length` 대신 캐시를 이 길이로 미리 할당합니다. 예상되는 최대 호출 크기로 한 번만 설정하면, 더 긴 프롬프트나 더 큰 `max_new_tokens`(이 상한선까지)을 가진 반복적인 `generate()` 호출이 재할당과 `torch.compile` 재컴파일을 트리거하는 대신 동일한 캐시를 재사용합니다.

**모델 출력 logits를 조작하기 위한 매개변수:**

temperature (`float`, *선택*) : 다음 토큰의 확률을 모듈레이션하는 데 사용되는 값입니다. 이 값은 모델의 `generation_config.json` 파일에서 설정됩니다. 설정되지 않은 경우 기본값은 1.0입니다.

top_k (`int`, *선택 사항*) : top-k-filtering을 위해 유지할 최고 확률 어휘 토큰의 수입니다. 이 값은 모델의 `generation_config.json` 파일에서 설정됩니다. 설정되지 않은 경우 기본값은 50입니다.

top_p (`float`, *선택*) : float < 1로 설정하면, 확률의 합이 `top_p` 이상인 가장 확률이 높은 토큰의 최소 집합만 생성에 유지됩니다. 이 값은 모델의 `generation_config.json` 파일에 설정됩니다. 설정되지 않은 경우 기본값은 1.0입니다.

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

top_h (`float`, *선택 사항*) : 엔트로피 예산 스케일링 계수로, 샘플링 시 분포의 엔트로피 중 얼마나 보존되는지를 제어합니다. 0과 1 사이의 값이어야 합니다. 각 단계에서 토큰은 확률 순으로 정렬되며, 전체 분포의 엔트로피의 `top_h` 배 이하인 *재정규화* 엔트로피를 가지는 가장 작은 토큰 접두사가 유지됩니다. 값이 작을수록(예: 0.2–0.5) 더 집중적이고 결정론적인 출력이 생성되며, 1.0에 가까울수록 더 많은 무작위성과 다양성이 허용됩니다. 일반적인 값은 0.3–0.6 범위입니다.

typical_p (`float`, *선택 사항*) : Local typicality는 이미 생성된 부분 텍스트를 조건으로 할 때, 다음 토큰으로 타겟 토큰을 예측하는 조건부 확률이 다음 토큰으로 무작위 토큰을 예측하는 기대 조건부 확률과 얼마나 유사한지를 측정합니다. float < 1로 설정하면, 확률의 합이 `typical_p` 이상인 가장 로컬적으로 전형적인 토큰의 최소 집합만 생성에 유지됩니다. 자세한 내용은 [이 논문](https://huggingface.co/papers/2202.00666)을 참고하세요.

epsilon_cutoff (`float`, *선택 사항*) : 0과 1 사이의 float 값으로 설정하면, `epsilon_cutoff`보다 큰 조건부 확률을 가진 토큰만 샘플링됩니다. 해당 논문에서는 모델 크기에 따라 권장 값이 3e-4에서 9e-4 범위로 제시됩니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://huggingface.co/papers/2210.15191)을 참고하세요.

eta_cutoff (`float`, *선택*) : Eta 샘플링은 로컬 전형 샘플링과 epsilon 샘플링의 하이브리드입니다. 0과 1 사이의 float 값으로 설정하면, 토큰이 `eta_cutoff` 또는 `sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits)))`보다 큰 경우에만 고려됩니다. 후자의 항은 직관적으로 `sqrt(eta_cutoff)`로 스케일링된 다음 토큰의 기대 확률입니다. 논문에서는 모델 크기에 따라 권장 값이 3e-4에서 2e-3 범위로 제시됩니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://huggingface.co/papers/2210.15191)을 참고하세요.

repetition_penalty (`float`, *선택 사항*) : 반복 페널티를 위한 매개변수입니다. 1.0은 페널티가 없음을 의미합니다. 자세한 내용은 [이 논문](https://huggingface.co/papers/1909.05858)을 참조하세요.

encoder_repetition_penalty (`float`, *선택 사항*) : encoder_repetition_penalty의 매개변수입니다. 원래 입력에 없는 시퀀스에 대해 지수형 패널티를 적용합니다. 1.0은 패널티가 없음을 의미합니다.

length_penalty (`float`, *선택*) : beam 기반 생성에서 길이에 적용되는 지수형 페널티입니다. 시퀀스 길이에 지수로 적용된 후, 해당 값으로 시퀀스 점수를 나눕니다. 점수는 시퀀스의 로그 가능도(즉, 음수)이므로, `length_penalty` > 0.0이면 더 긴 시퀀스를 선호하고, `length_penalty` < 0.0이면 더 짧은 시퀀스를 선호합니다.

no_repeat_ngram_size (`int`, *선택 사항*) : 0보다 큰 int 값으로 설정하면, 해당 크기의 모든 ngram은 한 번만 발생할 수 있습니다.

bad_words_ids (`list[list[int]]`, *선택 사항*) : 생성이 허용되지 않는 토큰 ID의 리스트로 구성된 리스트입니다. 추가 문서 및 예제는 [NoBadWordsLogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.NoBadWordsLogitsProcessor)를 참조하세요.

renormalize_logits (`bool`) : 모든 logits 프로세서(사용자 정의 프로세서 포함)를 적용한 후 logits를 재정규화할지 여부입니다. 탐색 알고리즘은 점수 logits가 정규화되어 있다고 가정하지만 일부 logit 프로세서는 정규화를 깨뜨릴 수 있으므로, 이 플래그를 `True`로 설정하는 것이 강력히 권장됩니다.

forced_bos_token_id (`int`, *선택 사항*, 기본값은 `model.config.forced_bos_token_id`) : `decoder_start_token_id` 이후에 첫 번째로 생성되는 토큰으로 강제할 토큰의 id입니다. [mBART](../model_doc/mbart)와 같은 다국어 모델에서는 첫 번째로 생성되는 토큰이 대상 언어 토큰이어야 하므로 유용합니다.

forced_eos_token_id (`int` or list[int]`, *optional*, defaults to `model.config.forced_eos_token_id`) : The id of the token to force as the last generated token when `max_length` is reached. Optionally, use a list to set multiple *end-of-sequence* tokens.

remove_invalid_values (`bool`) : 모델의 *nan* 및 *inf* 출력을 제거하여 생성 메서드가 충돌하는 것을 방지할지 여부입니다. `remove_invalid_values`를 사용하면 생성 속도가 느려질 수 있습니다.

exponential_decay_length_penalty (`tuple(int, float)`, *선택*) : 이 Tuple은 특정 수의 토큰이 생성된 후 지수적으로 증가하는 길이 페널티를 추가합니다. 이 Tuple은 `(start_index, decay_factor)`로 구성되며, 여기서 `start_index`는 페널티가 시작되는 위치를 나타내고 `decay_factor`는 지수 감쇠의 계수를 나타냅니다.

suppress_tokens (`list[int]`, *선택 사항*) : 생성 시 억제될 토큰 목록입니다. `SuppressTokens` logit 프로세서가 해당 토큰의 log prob을 `-inf`로 설정하여 샘플링되지 않도록 합니다.

begin_suppress_tokens  (`list[int]`, *선택 사항*) : 생성의 시작 부분에 억제될 토큰 목록입니다. `SuppressBeginTokens` logit processor는 해당 토큰의 log prob을 `-inf`로 설정하여 샘플링되지 않도록 합니다.

sequence_bias (`dict[tuple[int], float]`, *선택 사항*) : 토큰 시퀀스를 해당 바이어스 항으로 매핑하는 사전입니다. 양의 바이어스는 해당 시퀀스가 선택될 확률을 높이고, 음의 바이어스는 그 반대 효과를 냅니다. 추가 문서와 예제는 [SequenceBiasLogitsProcessor](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.SequenceBiasLogitsProcessor)를 참고하세요.

token_healing (`bool`) : 프롬프트의 꼬리 토큰을 적절한 확장으로 대체하여 복구합니다. 이는 greedy tokenization bias의 영향을 받는 프롬프트의 완성 품질을 향상시킵니다.

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

watermarking_config (`BaseWatermarkingConfig` 또는 `dict`, *선택*) : 무작위로 선택된 "green" 토큰 집합에 작은 bias를 추가하여 모델 출력에 워터마크를 적용하는 데 사용되는 인자입니다. 자세한 내용은 [SynthIDTextWatermarkingConfig](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.SynthIDTextWatermarkingConfig) 및 [WatermarkingConfig](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.WatermarkingConfig)의 문서를 참조하세요. `Dict`로 전달되면 내부적으로 `WatermarkingConfig`로 변환됩니다.

**generate의 출력 변수를 정의하는 매개변수:**

num_return_sequences (`int`, *선택 사항*) : 배치의 각 요소에 대해 독립적으로 계산되어 반환되는 시퀀스의 수입니다.

output_attentions (`bool`) : 모든 attention 레이어의 attentions 텐서를 반환할지 여부. 자세한 내용은 반환 텐서에서 `attentions` 항목을 참조하세요.

output_hidden_states (`bool`) : 모든 레이어의 hidden states를 반환할지 여부. 자세한 내용은 반환되는 텐서에서 `hidden_states` 항목을 참조하세요.

output_scores (`bool`) : 예측 점수를 반환할지 여부. 자세한 내용은 반환되는 텐서에서 `scores` 항목을 참조하세요.

output_logits (`bool`) : 처리되지 않은 예측 logit 점수를 반환할지 여부. 자세한 내용은 반환되는 텐서에서 `logits` 항목을 참조하세요.

return_dict_in_generate (`bool`) : 생성된 시퀀스만 반환하는 대신 [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput)을 반환할지 여부. 생성 캐시를 반환하려면(`use_cache`가 `True`인 경우) 또는 선택적 출력을 반환하려면(`output_`로 시작하는 플래그 참조) 이 플래그를 `True`로 설정해야 합니다.

**생성 시 사용할 수 있는 특수 토큰:**

pad_token_id (`int`, *선택 사항*) : *padding* 토큰의 id입니다.

bos_token_id (`int`, *선택 사항*) : *시퀀스 시작* 토큰의 id입니다.

eos_token_id (`Union[int, list[int]]`, *선택*) : *시퀀스 종료* 토큰의 id입니다. *시퀀스 종료* 토큰을 여러 개 설정하려면 리스트를 사용할 수 있습니다.

**인코더-디코더 모델에만 적용되는 생성 매개변수:**

encoder_no_repeat_ngram_size (`int`, *선택 사항*) : 0보다 큰 int 값으로 설정하면, `encoder_input_ids`에 나타나는 해당 크기의 모든 ngram은 `decoder_input_ids`에 나타날 수 없습니다.

decoder_start_token_id (`int` 또는 `list[int]`, *선택 사항*) : 인코더-디코더 모델이 *bos*와 다른 토큰으로 디코딩을 시작하는 경우, 해당 토큰의 id 또는 `batch_size` 길이의 리스트입니다. 리스트를 지정하면 배치의 각 요소에 대해 서로 다른 시작 id를 사용할 수 있습니다(예: 하나의 배치에 서로 다른 대상 언어를 가진 다국어 모델).

**어시스턴트 생성에 전용인 생성 매개변수:**

is_assistant (`bool`) : 모델이 어시스턴트(드래프트) 모델인지 여부.

num_assistant_tokens (`int`, *선택 사항*) : 각 반복에서 타깃 모델이 검사하기 전에 어시스턴트 모델이 생성할 _추측 토큰_의 수를 정의합니다. `num_assistant_tokens`의 값이 높을수록 생성이 더 _추측적_이 됩니다. 어시스턴트 모델의 성능이 좋으면 더 큰 속도 향상을 얻을 수 있지만, 어시스턴트 모델에 대한 교정이 많이 필요하면 속도 향상은 낮아집니다.

num_assistant_tokens_schedule (`str`, *선택 사항*) : 추론 중에 max assistant tokens가 변경될 스케줄을 정의합니다. - `"heuristic"`: 모든 speculative tokens가 정확할 경우 `num_assistant_tokens`를 2 증가시키고, 그렇지 않으면 1 감소시킵니다. `num_assistant_tokens` 값은 동일한 assistant model을 사용하는 여러 generation 호출에 걸쳐 유지됩니다. - `"heuristic_transient"`: `"heuristic"`와 동일하지만, 각 generation 호출 후 `num_assistant_tokens`가 초기 값으로 재설정됩니다. - `"constant"`: generation 동안 `num_assistant_tokens`가 변경되지 않습니다

assistant_confidence_threshold (`float`, *선택 사항*) : 어시스턴트 모델의 신뢰도 임계값입니다. 어시스턴트 모델이 현재 토큰에 대한 예측에 대한 신뢰도가 이 임계값보다 낮으면, _추측 토큰_의 수(`num_assistant_tokens`로 정의됨)가 아직 도달하지 않았더라도 어시스턴트 모델은 현재 토큰 생성 반복을 중단합니다. 어시스턴트의 신뢰도 임계값은 불필요한 드래프트 및 타깃 포워드 패스의 횟수를 줄이기 위해 추측 반복 과정에서 조정되며, 오탐(false negative)을 피하는 방향으로 편향됩니다. `assistant_confidence_threshold` 값은 동일한 어시스턴트 모델로 여러 생성 호출에 걸쳐 유지됩니다. 이는 Dynamic Speculation Lookahead Accelerates Speculative Decoding of Large Language Models의 동적 추측 선망(dynamic speculation lookahead)의 비지도 버전입니다.

prompt_lookup_num_tokens (`int`, *선택 사항*) : 후보 토큰으로 출력할 토큰의 개수입니다.

max_matching_ngram_size (`int`, *선택 사항*) : 프롬프트에서 매칭을 고려할 최대 ngram 크기입니다. 제공되지 않으면 기본값은 2입니다.

`int`, *optional* : 양의 정수로 설정하면, 모델의 early exit를 어시스턴트로 사용합니다. early exit를 지원하는 모델(즉, 중간 레이어의 logits를 LM head로 해석할 수 있는 모델)에서만 사용할 수 있습니다.

assistant_lookbehind(`int`, *선택 사항*) : 양의 정수로 설정하면, 재인코딩 과정에서 토큰을 올바르게 정렬하기 위해 마지막 `assistant_lookbehind`개의 어시스턴트 토큰도 함께 고려합니다. 추측적 디코딩 시 서로 다른 토크나이저를 사용하는 경우에만 사용할 수 있습니다. 자세한 내용은 이 [블로그](https://huggingface.co/blog/universal_assisted_generation)를 참고하세요.

target_lookbehind(`int`, *optional*) : 양의 정수로 설정하면, 재인코딩 과정에서 토큰을 올바르게 정렬하기 위해 마지막 `target_lookbehind`개의 target 토큰도 함께 고려합니다. speculative decoding에서 서로 다른 tokenizer를 사용할 때만 사용할 수 있습니다. 자세한 내용은 이 [블로그](https://huggingface.co/blog/universal_assisted_generation)를 참고하세요.

assistant_ensemble_weight (`float`, *선택 사항*) : speculative decoding에서 정적 ensemble 검증을 활성화합니다. `(0.0, 1.0)` 범위의 값으로 설정하면, 검증기가 `p_target` 대신 혼합 분포 `w * p_target + (1 - w) * q_draft`에 대해 토큰을 수락하여, 제어된 분포 편향으로 더 높은 수락률을 얻는 트레이드오프를 수행합니다. 기본값은 `None`이며, 이 경우 decoding이 손실 없이 유지됩니다. assistant model이 logits를 반환해야 하므로 prompt lookup decoding과 호환되지 않습니다.

speculation_type (`str`, *선택 사항*) : 요청한 추측 유형. 허용되는 값은 `dflash`입니다.

**성능 및 컴파일 관련 매개변수:**

compile_config (CompileConfig, *선택 사항*) : 컴파일 가능한 캐시를 사용하는 경우, `generate`가 추론 속도를 높이기 위해 포워드 패스를 `compile`하는 방식을 제어합니다.

disable_compile (`bool`) : forward pass의 자동 컴파일을 비활성화할지 여부. compilable cache를 사용하는 등 특정 조건이 충족되면 자동 컴파일이 수행됩니다. 이 플래그를 사용할 필요가 있는 경우 이슈를 등록해 주세요.

생성 작업에 대한 설정을 보유하는 클래스입니다. `generate` 호출은 텍스트 디코더, 텍스트-대-텍스트, 음성-대-텍스트, 비전-대-텍스트 모델에 대해 다음 생성 방법을 지원합니다:

- `num_beams=1`이고 `do_sample=False`인 경우 *greedy decoding*
- `num_beams=1`이고 `do_sample=True`인 경우 *다항 샘플링*
- `num_beams>1`이고 `do_sample=False`인 경우 *beam-search decoding*
- `num_beams>1`이고 `do_sample=True`인 경우 *beam-search multinomial sampling*
- `.generate()`에 `assistant_model` 또는 `prompt_lookup_num_tokens`가 전달되면 *assisted decoding*

디코딩 전략에 대해 자세히 알아보려면 [텍스트 생성 전략 가이드](../generation_strategies)를 참고하세요.

이러한 플래그 중 상당수는 생성의 logits 또는 중단 기준을 제어합니다. 가능한 조작에 대한 전체 설명과 사용 예시를 확인하려면 [generate 관련 클래스](https://huggingface.co/docs/transformers/internal/generation_utils)를 참고하세요.

참고: 아직 `None`인 설정 필드는 생성 루프 동안 `GenerationConfig._get_default_generation_params()`에 의해 덮어쓰기됩니다. 이러한 필드에 다른 값을 사용하려면 generation config에서 해당 값을 명시적으로 설정해야 합니다.

#### from_pretrained[[transformers.GenerationConfig.from_pretrained]]

```python
from_pretrained(pretrained_model_name: str | os.PathLike, config_file_name: str | os.PathLike | None = None, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', **kwargs)
```

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

**매개변수:**

pretrained_model_name (`str` 또는 `os.PathLike`) : 다음 중 하나일 수 있습니다. - huggingface.co의 모델 저장소에 호스팅된 사전 학습된 모델 구성의 *model id*인 문자열. - [save_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig.save_pretrained) 메서드를 사용하여 저장된 구성 파일이 포함된 *디렉터리*의 경로, 예: `./my_model_directory/`.

config_file_name (`str` 또는 `os.PathLike`, *선택 사항*, 기본값 `"generation_config.json"`) : `pretrained_model_name`에서 로드할 generation configuration JSON 파일의 이름.

cache_dir (`str` 또는 `os.PathLike`, *선택 사항*) : 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습된 모델 구성을 캐시할 디렉터리의 경로입니다.

force_download (`bool`, *선택 사항*, 기본값 `False`) : 캐시된 버전이 존재하더라도 설정 파일을 (재)다운로드하도록 강제할지 여부.

proxies (`dict[str, str]`, *선택*) : 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예: `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}.` 각 요청에 프록시가 사용됩니다.

token (`str` 또는 `bool`, *선택*) : 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. `True`이거나 지정되지 않은 경우, `hf auth login` 실행 시 생성된 토큰(`~/.huggingface`에 저장됨)을 사용합니다.

revision (`str`, *선택 사항*, 기본값 `"main"`) : 사용할 특정 모델 버전입니다. huggingface.co에서 모델 및 기타 아티팩트를 저장하기 위해 git 기반 시스템을 사용하므로, `revision`은 git에서 허용하는 모든 식별자, 즉 브랜치 이름, 태그 이름 또는 커밋 id가 될 수 있습니다. Hub에서 만든 pull request를 테스트하려면 `revision="refs/pr/<pr_number>"`를 전달할 수 있습니다.

return_unused_kwargs (`bool`, *선택 사항*, 기본값 `False`) : `False`인 경우, 이 함수는 최종 구성 객체만 반환합니다. `True`인 경우, 이 함수는 `Tuple(config, unused_kwargs)`를 반환하며, 여기서 *unused_kwargs*는 키가 구성 속성이 아닌 키/값 쌍으로 구성된 사전입니다. 즉, `kwargs` 중 `config`를 업데이트하는 데 사용되지 않고 무시되는 부분입니다.

subfolder (`str`, *선택 사항*, 기본값 `""`) : 관련 파일이 huggingface.co의 모델 저장소 내 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.

kwargs (`dict[str, Any]`, *선택*) : kwargs의 값 중 설정 속성에 해당하는 키는 로드된 값을 덮어쓰는 데 사용됩니다. 키가 설정 속성이 *아닌* 키/값 쌍에 대한 동작은 `return_unused_kwargs` 키워드 매개변수로 제어됩니다.

**반환값:** [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)

이 사전 학습된 모델에서 인스턴스화된 구성 객체.

생성 구성 파일에서 [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)를 인스턴스화합니다.

예:

```python
>>> from transformers import GenerationConfig

>>> # Download configuration from huggingface.co and cache.
>>> generation_config = GenerationConfig.from_pretrained("openai-community/gpt2")

>>> # E.g. config was saved using *save_pretrained('./test/saved_model/')*
>>> generation_config.save_pretrained("./test/saved_model/")
>>> generation_config = GenerationConfig.from_pretrained("./test/saved_model/")

>>> # You can also specify configuration names to your generation configuration file
>>> generation_config.save_pretrained("./test/saved_model/", config_file_name="my_configuration.json")
>>> generation_config = GenerationConfig.from_pretrained("./test/saved_model/", "my_configuration.json")

>>> # If you'd like to try a minor variation to an existing configuration, you can also pass generation
>>> # arguments to `.from_pretrained()`. Be mindful that typos and unused arguments will be ignored
>>> generation_config, unused_kwargs = GenerationConfig.from_pretrained(
...     "openai-community/gpt2", top_k=1, foo=False, do_sample=True, return_unused_kwargs=True
... )
>>> generation_config.top_k
1

>>> unused_kwargs
{'foo': False}
```

#### from_model_config[[transformers.GenerationConfig.from_model_config]]

```python
from_model_config(model_config: typing.Union[ForwardRef('PreTrainedConfig'), dict])
```

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

**매개변수:**

model_config (`PreTrainedConfig | dict`) : generation config를 인스턴스화할 때 사용할 모델 config입니다.

**반환값:** [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)

해당 파라미터에서 인스턴스화된 구성 객체.

[PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)에서 [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)를 초기화합니다. 이 함수는 생성 매개변수를 포함할 수 있는 레거시 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig) 객체를 독립적인 [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)로 변환하는 데 유용합니다.

#### save_pretrained[[transformers.GenerationConfig.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, config_file_name: str | os.PathLike | None = None, push_to_hub: bool = False, **kwargs)
```

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

**매개변수:**

save_directory (`str` 또는 `os.PathLike`) : 설정 JSON 파일을 저장할 디렉터리(존재하지 않으면 생성됩니다).

config_file_name (`str` 또는 `os.PathLike`, *선택 사항*, 기본값 `"generation_config.json"`) : `save_directory`에 저장할 generation configuration JSON 파일의 이름입니다.

push_to_hub (`bool`, *선택 사항*, 기본값 `False`) : 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다. `repo_id`를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내 `save_directory`의 이름이 기본값으로 사용됩니다.

kwargs (`dict[str, Any]`, *선택*) : [push_to_hub()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 메서드에 함께 전달되는 추가 키워드 인자입니다.

생성 설정 객체를 `save_directory` 디렉토리에 저장하여 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig.from_pretrained) 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.

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

```python
update(defaults_only = False, allow_custom_entries = False, **kwargs)
```

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

**매개변수:**

defaults_only (`bool`, *선택 사항*, 기본값 `False`) : `kwargs`로 config의 모든 키를 업데이트할지, 아니면 `None`(즉, 기본값)으로 설정된 키만 업데이트할지를 결정합니다.

allow_custom_entries (`bool`, *선택*, 기본값 `False`) : 현재 config에 없는 경우 `kwargs`로 custom entries를 업데이트하는 것을 허용할지 여부.

kwargs (`dict[str, Any]`) : 이 클래스를 잠정적으로 업데이트할 속성들의 사전.

**반환값:** `dict[str, Any]`

인스턴스를 업데이트하는 데 사용되지 않은 모든 키-값 쌍을 포함하는 사전(Dictionary)입니다.

`kwargs`의 속성이 기존 속성과 일치하는 경우, 이 클래스 인스턴스의 속성을 `kwargs`의 속성으로 업데이트하고 사용하지 않은 모든 `kwargs`를 반환합니다.

#### validate[[transformers.GenerationConfig.validate]]

```python
validate(strict = False, user_set_attributes: set[str] | None = None)
```

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

**매개변수:**

strict (bool) : True인 경우, 발견된 모든 문제에 대해 예외를 발생시킵니다. False인 경우, 문제만 로깅합니다.

user_set_attributes (set[str], *optional*) : 호출자가 명시적으로 제공한 속성의 이름입니다. 이 값이 제공되면, 충돌하는 플래그 조합에 대한 "경미한 문제" 경고(예: `do_sample=False` 상태에서도 샘플링 전용 플래그가 설정된 경우)는 해당 충돌 플래그가 이 집합에 포함된 경우에만 발생하여, 모델의 기본 `generation_config.json`에서 상속된 값에 대해 불필요한 경고가 발생하는 것을 방지합니다. `None`인 경우, 설정된 모든 속성이 사용자 설정으로 간주됩니다(직접 `validate()`를 호출하는 경우를 위한 하위 호환 동작).

[GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig) 인스턴스의 속성 값을 검증합니다. 구성 인스턴스만으로 잘못된 것으로 판별할 수 있는 파라미터화가 존재하는 경우 예외를 발생시킵니다.

여기서 검증되지 않는 일부 파라미터는 다른 입력 및/또는 모델에 따라 달라질 수 있으므로(예: 생성 길이와 관련된 파라미터) generate 실행 시점에 검증하는 것이 가장 좋습니다.

#### get_generation_mode[[transformers.GenerationConfig.get_generation_mode]]

```python
get_generation_mode(assistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = None)
```

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

**매개변수:**

assistant_model (`PreTrainedModel`, *선택 사항*) : assisted generation에 사용할 assistant model입니다. 설정된 경우, generation mode가 assisted generation으로 설정됩니다.

**반환값:** `GenerationMode`

인스턴스에 의해 트리거되는 생성 모드입니다.

[GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig) 인스턴스에 의해 트리거된 생성 모드를 반환합니다.

## GenerationMixin[[transformers.GenerationMixin]]

#### transformers.GenerationMixin[[transformers.GenerationMixin]]

```python
transformers.GenerationMixin()
```

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

모든 자동 회귀 텍스트 생성 함수를 포함하는 클래스로, 모델 클래스에서 믹스인(mixin)으로 사용됩니다. 이 클래스를 상속하면 모델에 `GenerationConfig`를 초기화 시점에 로드하거나 `transformers` CI에서 `generate` 관련 테스트가 실행되도록 보장하는 등 생성과 관련된 특별한 동작이 부여됩니다.

모델 클래스는 `GenerationMixin`을 상속해야 `generate`와 같은 메서드를 호출할 수 있습니다. 또는 `GenerationMixin`에 직접 또는 간접적으로 의존하는 커스텀 `generate` 메서드를 정의한 경우에도 마찬가지입니다. 이 경우 `generate`와 같은 공개 메서드와 대략 동일한 인터페이스를 공유합니다. 세 가지 예시:
- `LlamaForCausalLM`은 `GenerationMixin`을 상속해야 `generate`와 기타 mixin의 공개 메서드를 호출할 수 있습니다.
- `BlipForQuestionAnswering`에는 `GenerationMixin.generate`와 거의 동일한 인터페이스를 공유하는 사용자 정의 `generate` 메서드가 있습니다(추가 인수가 몇 개 있고, 출력은 동일합니다). 해당 함수는 내부 모델을 통해 `GenerationMixin.generate`를 간접적으로 호출합니다. 따라서 `BlipForQuestionAnswering`는 코드베이스의 모든 생성 관련 자동화 기능을 활용하기 위해 `GenerationMixin`을 상속해야 합니다.
- `BarkModel`에는 사용자 정의 `generate` 메서드가 있으며, 내부 모델 중 하나가 `GenerationMixin.generate`를 호출합니다. 그러나 `generate`는 `GenerationMixin.generate`와 동일한 인터페이스를 공유하지 않습니다. 이 경우 `BarkModel`은 `GenerationMixin`을 상속해서는 안 되며, 그렇게 하면 `generate` 인터페이스가 깨지기 때문입니다.

이 클래스는 [generate()](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationMixin.generate)를 노출하며, 이를 다음 용도로 사용할 수 있습니다:
- `num_beams=1`이고 `do_sample=False`인 경우 *greedy decoding*
- `num_beams=1`이고 `do_sample=True`인 경우 *다항 샘플링*
- `num_beams>1`이고 `do_sample=False`인 경우 *beam-search decoding*
- `num_beams>1`이고 `do_sample=True`인 경우 *beam-search multinomial sampling*
- `.generate()`에 `assistant_model` 또는 `prompt_lookup_num_tokens`가 전달되면 *assisted decoding*

디코딩 전략에 대해 자세히 알아보려면 [텍스트 생성 전략 가이드](../generation_strategies)를 참고하세요.

#### generate[[transformers.GenerationMixin.generate]]

```python
generate(inputs: typing.Optional[torch.Tensor] = None, generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, logits_processor: transformers.generation.logits_process.LogitsProcessorList | None = None, stopping_criteria: transformers.generation.stopping_criteria.StoppingCriteriaList | None = None, prefix_allowed_tokens_fn: collections.abc.Callable[[int, torch.Tensor], list[int]] | None = None, synced_gpus: bool | None = None, assistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = None, streamer: typing.Optional[ForwardRef('BaseStreamer')] = None, negative_prompt_ids: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, custom_generate: str | collections.abc.Callable | None = None, **kwargs)
```

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

**매개변수:**

inputs (`torch.Tensor`, 모달리티에 따라 형태가 다양하며, *선택 사항*) : 생성을 위한 프롬프트로 사용되거나 인코더의 모델 입력으로 사용되는 시퀀스입니다. `None`인 경우 `bos_token_id`와 배치 크기 1로 초기화됩니다. 디코더 전용 모델의 경우 `inputs`는 `input_ids` 형식이어야 합니다. 인코더-디코더 모델의 경우 *inputs*는 `input_ids`, `input_values`, `input_features`, `pixel_values` 중 어느 하나를 나타낼 수 있습니다.

generation_config ([GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig), *선택*) : 생성 호출의 기본 파라미터화로 사용할 생성 구성입니다. `**kwargs`로 전달되며 `generation_config`의 속성과 일치하는 값은 해당 속성을 덮어씁니다. `generation_config`가 제공되지 않으면 기본값이 사용되며, 이때 로딩 우선순위는 다음과 같습니다: 1) `generation_config.json` 모델 파일이 존재하는 경우 해당 파일에서; 2) 모델 구성에서. 명시되지 않은 파라미터는 [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)의 기본값을 상속받으므로, 생성을 파라미터화하려면 해당 문서에서 기본값을 확인해야 합니다.

logits_processor (`LogitsProcessorList`, *선택*) : 인자와 generation config에서 생성된 기본 logits processor를 보완하는 사용자 정의 logits processor입니다. 인자 또는 generation config로 이미 생성된 logit processor가 전달되면 오류가 발생합니다. 이 기능은 고급 사용자를 위한 것입니다.

stopping_criteria (`StoppingCriteriaList`, *선택*) : 인자와 generation config에서 기본으로 생성되는 stopping criteria를 보완하는 사용자 정의 stopping criteria입니다. 인자 또는 generation config로 이미 생성된 stopping criteria를 전달하면 오류가 발생합니다. stopping criteria가 `scores` 입력에 의존하는 경우, `generate`에 `return_dict_in_generate=True, output_scores=True`를 전달하도록 하십시오. 이 기능은 고급 사용자를 위한 것입니다.

prefix_allowed_tokens_fn (`Callable[[int, torch.Tensor], list[int]]`, *선택*) : 지정된 경우, 이 함수는 각 단계에서 beam search를 허용된 토큰으로만 제한합니다. 지정되지 않으면 제약이 적용되지 않습니다. 이 함수는 2개의 인수를 받습니다: 배치 ID `batch_id`와 `input_ids`. 배치 ID `batch_id`와 이전에 생성된 토큰 `inputs_ids`에 조건부인 다음 생성 단계에 허용되는 토큰의 리스트를 반환해야 합니다. 이 인수는 [Autoregressive Entity Retrieval](https://huggingface.co/papers/2010.00904)에 설명된 바와 같이 접두사에 조건부인 제약 생성에 유용합니다.

synced_gpus (`bool`, *선택 사항*) : max_length까지 while 루프를 계속 실행할지 여부. `FullyShardedDataParallel` 또는 DeepSpeed ZeRO Stage 3을 여러 GPU로 사용하는 경우, 한 GPU가 다른 GPU보다 먼저 생성을 완료할 때 데드락을 방지하기 위해 이 플래그가 `True`로 설정됩니다. 이 경우를 제외하면 기본값은 `False`입니다.

assistant_model (`PreTrainedModel`, *선택 사항*) : 생성을 가속화하는 데 사용할 수 있는 어시스턴트 모델입니다. 어시스턴트 모델은 정확히 동일한 토크나이저를 가져야 합니다. 어시스턴트 모델로 후보 토큰을 예측하는 것이 generate를 호출하는 모델로 생성을 실행하는 것보다 훨씬 빠를 때 가속화가 이루어집니다. 따라서 어시스턴트 모델은 훨씬 작아야 합니다.

streamer (`BaseStreamer`, *선택 사항*) : 생성된 시퀀스를 스트리밍하는 데 사용되는 Streamer 객체입니다. 생성된 토큰은 `streamer.put(token_ids)`를 통해 전달되며, 스트리머는 추가 처리를 담당합니다.

negative_prompt_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택*) : CFG와 같은 일부 프로세서에 필요한 negative prompt입니다. 배치 크기는 입력 배치 크기와 일치해야 합니다. 이는 실험적 기능이며, 향후 버전에서 API가 변경될 수 있습니다.

negative_prompt_attention_mask (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : `negative_prompt_ids`에 대한 Attention_mask입니다.

custom_generate (`str` 또는 `Callable`, *선택 사항*) : 다음 중 하나입니다: - `str` (Hugging Face Hub 저장소 이름): 표준 `generate` 메서드 대신 해당 저장소의 `custom_generate/generate.py`에 정의된 사용자 정의 `generate` 함수를 실행합니다. 이 저장소는 생성 로직을 완전히 대체하며, 반환 타입이 다를 수 있습니다. - `str` (로컬 저장소 경로): 위와 동일하지만 로컬 경로에서 실행합니다. 로컬 `custom_generate/generate.py`가 실행되므로 로컬 디렉터리도 `trust_remote_code=True`가 필요합니다. - `Callable`: `generate`는 일반적인 입력 준비 단계를 수행한 후, 제공된 callable을 호출하여 디코딩 루프를 실행합니다. 자세한 내용은 [문서](../../generation_strategies#custom-generation-methods)를 참조하세요.

kwargs (`dict[str, Any]`, *선택*) : `generation_config`의 즉석 파라미터화 및/또는 모델의 `forward` 함수로 전달될 추가적인 모델 전용 kwargs입니다. 모델이 encoder-decoder 모델인 경우, encoder 전용 kwargs에는 접두사를 붙이지 않고 decoder 전용 kwargs에는 *decoder_* 접두사를 붙여야 합니다.

**반환값:** [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput) 또는 `torch.LongTensor`

`return_dict_in_generate=True`인 경우 또는 `config.return_dict_in_generate=True`인 경우 [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput), 아니면 `torch.LongTensor`.

모델이 인코더-디코더 모델이 *아니면* (`model.config.is_encoder_decoder=False`), 가능한 [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput) 유형은 다음과 같습니다:

- [GenerateDecoderOnlyOutput](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.generation.GenerateDecoderOnlyOutput),
- [GenerateBeamDecoderOnlyOutput](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.generation.GenerateBeamDecoderOnlyOutput)

모델이 인코더-디코더 모델(`model.config.is_encoder_decoder=True`)인 경우, 가능한 [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput) 유형은 다음과 같습니다:

- [GenerateEncoderDecoderOutput](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.generation.GenerateEncoderDecoderOutput),
- [GenerateBeamEncoderDecoderOutput](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.generation.GenerateBeamEncoderDecoderOutput)

language modeling 헤드가 있는 모델에 대해 토큰 ID 시퀀스를 생성합니다.

대부분의 생성 제어 매개변수는 `generation_config`에 설정되며, 전달되지 않으면 모델의 기본 생성 구성으로 설정됩니다. `generation_config`의 항목은 generate()에 해당 매개변수를 전달하여 오버라이드할 수 있습니다. 예를 들어 `.generate(inputs, num_beams=4, do_sample=True)`와 같이 사용할 수 있습니다.

생성 전략 개요와 코드 예제는 [다음 가이드](../generation_strategies)를 참고하세요.

#### compute_transition_scores[[transformers.GenerationMixin.compute_transition_scores]]

```python
compute_transition_scores(sequences: Tensor, scores: tuple[torch.Tensor], beam_indices: typing.Optional[torch.Tensor] = None, normalize_logits: bool = False)
```

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

**매개변수:**

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

scores (`tuple(torch.Tensor)`) : 각 생성 단계에서 어휘의 각 토큰에 대한 전환 점수(transition score). 이 빔 내에서 이전에 생성된 토큰의 log softmax에 조건부인 토큰의 로그 확률로 구성된 빔 전환 점수입니다. `torch.Tensor`의 튜플이며, 최대 `max_new_tokens`개의 요소(생성된 각 토큰당 1개 요소)를 포함합니다. 각 텐서의 shape은 `(batch_size*num_beams, config.vocab_size)`입니다.

beam_indices (`torch.LongTensor`, *선택 사항*) : 각 생성 단계에서 생성된 토큰 id의 beam 인덱스. `torch.LongTensor`이며, 형태는 `(batch_size*num_return_sequences, sequence_length)`입니다. generate 시점에 `num_beams>1`인 경우에만 필요합니다.

normalize_logits (`bool`, *선택 사항*, 기본값 `False`) : logits를 정규화할지 여부입니다(레거시 이유로 인해 정규화되지 않은 상태일 수 있음).

**반환값:** `torch.Tensor`

전이 점수(logits)를 포함하는 `(batch_size*num_return_sequences, sequence_length)` 모양의 `torch.Tensor`

생성 점수(beam search를 사용한 경우 beam 인덱스 포함)를 기반으로 시퀀스의 전이 점수를 계산합니다. 이는 생성 시점에 선택된 토큰의 점수를 빠르게 가져오기 위한 편리한 메서드입니다.

예:

```python
>>> from transformers import GPT2Tokenizer, AutoModelForCausalLM
>>> import numpy as np

>>> tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("openai-community/gpt2")
>>> tokenizer.pad_token_id = tokenizer.eos_token_id
>>> inputs = tokenizer(["Today is"], return_tensors="pt")

>>> # Example 1: Print the scores for each token generated with Greedy Search
>>> outputs = model.generate(**inputs, max_new_tokens=5, return_dict_in_generate=True, output_scores=True)
>>> transition_scores = model.compute_transition_scores(
...     outputs.sequences, outputs.scores, normalize_logits=True
... )
>>> # input_length is the length of the input prompt for decoder-only models, like the GPT family, and 1 for
>>> # encoder-decoder models, like BART or T5.
>>> input_length = 1 if model.config.is_encoder_decoder else inputs.input_ids.shape[1]
>>> generated_tokens = outputs.sequences[:, input_length:]
>>> for tok, score in zip(generated_tokens[0], transition_scores[0]):
...     # | token | token string | log probability | probability
...     print(f"| {tok:5d} | {tokenizer.decode(tok):8s} | {score.numpy():.3f} | {np.exp(score.numpy()):.2%}")
|   262 |  the     | -1.414 | 24.33%
|  1110 |  day     | -2.609 | 7.36%
|   618 |  when    | -2.010 | 13.40%
|   356 |  we      | -1.859 | 15.58%
|   460 |  can     | -2.508 | 8.14%

>>> # Example 2: Reconstruct the sequence scores from Beam Search
>>> outputs = model.generate(
...     **inputs,
...     max_new_tokens=5,
...     num_beams=4,
...     num_return_sequences=4,
...     return_dict_in_generate=True,
...     output_scores=True,
... )
>>> transition_scores = model.compute_transition_scores(
...     outputs.sequences, outputs.scores, outputs.beam_indices, normalize_logits=False
... )
>>> # If you sum the generated tokens' scores and apply the length penalty, you'll get the sequence scores.
>>> # Tip 1: recomputing the scores is only guaranteed to match with `normalize_logits=False`. Depending on the
>>> # use case, you might want to recompute it with `normalize_logits=True`.
>>> # Tip 2: the output length does NOT include the input length
>>> output_length = np.sum(transition_scores.numpy() < 0, axis=1)
>>> length_penalty = model.generation_config.length_penalty
>>> reconstructed_scores = transition_scores.sum(axis=1) / (output_length**length_penalty)
>>> print(np.allclose(outputs.sequences_scores, reconstructed_scores))
True
```

## ContinuousMixin[[transformers.ContinuousMixin]]

#### transformers.ContinuousMixin[[transformers.ContinuousMixin]]

```python
transformers.ContinuousMixin()
```

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

모델에 연속 배치(continuous batching) 기능을 추가하기 위한 Mixin 클래스입니다. 연속 배치에는 세 가지 진입점이 있습니다:
- 실제 continuous batching의 진입점인 `init_continuous_batching`
- `continuous_batching_context_manager`은 `init_continuous_batching`을 감싸는 래퍼입니다.
- 실제로 `continuous_batching_context_manager`을 감싸는 래퍼인 `generate_batch`

이들은 이 순서로 정의됩니다. 이 세 개의 진입점 중 하나에 변경 사항이 있으면 나머지 두 곳에도 반영되어야 합니다.

#### continuous_batching_context_manager[[transformers.ContinuousMixin.continuous_batching_context_manager]]

```python
continuous_batching_context_manager(generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, block: bool = True, timeout: float | None = None, continuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = None, persistent_manager: bool = False, warmup: bool = True, workload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None)
```

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

연속 배치 관리자를 안전하게 사용하기 위한 컨텍스트 매니저입니다. 인수는 `init_continuous_batching`의 인수와 유사하지만, 다음을 제외합니다:
- block: 매니저를 중지할 때 스레드를 차단할지 여부. 기본값은 True입니다.
- timeout: 스레드가 중지될 때까지 대기할 최대 시간. 기본값은 None(타임아웃 없음)입니다.
- warmup: 실행 전에 가장 큰 크기로 CUDA graphs를 사전 캡처할지 여부. 기본값은 True입니다.

#### destroy_cached_continuous_batching_manager[[transformers.ContinuousMixin.destroy_cached_continuous_batching_manager]]

```python
destroy_cached_continuous_batching_manager()
```

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

캐시된 continuous batching manager를 제거하고 GPU 리소스를 해제합니다.

#### generate_batch[[transformers.ContinuousMixin.generate_batch]]

```python
generate_batch(inputs: list[list[int]], generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, continuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = None, record_timestamps: bool = False, progress_bar: bool = False, persistent_manager: bool = False, warmup: bool = True, **kwargs)
```

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

**매개변수:**

inputs : 입력 토큰 시퀀스(프롬프트) 목록

generation_config : 선택적 생성 구성

continuous_batching_config : 선택 사항인 연속 배치 처리 구성

record_timestamps : true로 설정하면, 생성된 각 토큰에 대해 타임스탬프가 포함됩니다

progress_bar : true로 설정하면 진행률 표시줄이 표시됩니다

persistent_manager : 생성이 완료된 후 매니저를 유지할지 여부. 기본값은 False입니다.

warmup : 요청을 처리하기 전에 CUDA 그래프를 사전에 캡처할지 여부. 기본값은 True입니다.

**반환값:** `dict[str, GenerationOutput]`

요청 ID를 GenerationOutput 객체로 매핑한 사전

연속 배치(continuous batching)를 사용하여 프롬프트 배치에 대해 시퀀스를 생성합니다.

#### init_continuous_batching[[transformers.ContinuousMixin.init_continuous_batching]]

```python
init_continuous_batching(generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, continuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = None, workload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None)
```

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

**매개변수:**

generation_config : 선택 사항인 생성 구성으로, CompileConfig 객체를 포함할 수 있습니다

continuous_batching_config : 선택 사항인 연속 배치 처리 구성

workload_hints : 기본값에 대한 더 나은 결정을 내릴 수 있도록 연속 배치 관리자를 돕는 선택적 WorkloadHints

**반환값:** `ContinuousBatchingManager`

요청을 추가하고 결과를 가져오기 위한 매니저 인스턴스.

연속 배치 추론을 위한 매니저를 초기화합니다.

## ContinuousBatchingManager[[transformers.ContinuousBatchingManager]]

#### transformers.ContinuousBatchingManager[[transformers.ContinuousBatchingManager]]

```python
transformers.ContinuousBatchingManager(model: ProtoPretrainedModel, generation_config: GenerationConfig, continuous_batching_config: ContinuousBatchingConfig, workload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None)
```

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

생성 요청의 연속 배치 처리를 관리하는 매니저입니다. 생성 요청 제출, 결과 조회, 백그라운드 생성 스레드 관리를 위한 사용자 인터페이스를 제공합니다. 이 클래스는 직접 생성하지 말고, 다음 진입점(`ContinuousMixin` 믹신의 모든 메서드) 중 하나를 통해 생성해야 합니다:
- `init_continuous_batching`
- `continuous_batching_context_manager`
- `generate_batch`

#### add_request[[transformers.ContinuousBatchingManager.add_request]]

```python
add_request(input_ids: list[int], request_id: str | None = None, max_new_tokens: int | None = None, streaming: bool = False, record_timestamps: bool = False, eos_token_id: int | list[int] | None = None, **logit_processor_kwargs: Any)
```

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

**매개변수:**

input_ids : 프롬프트로 사용할 입력 토큰 ID

request_id : 선택 사항. 사용자 지정 요청 ID (None인 경우 자동 생성)

max_new_tokens : 생성할 새 토큰의 최대 개수

streaming 토큰이 생성되는 대로 스트리밍할지 여부

record_timestamps : 생성된 각 토큰에 대해 타임스탬프를 기록할지 여부

eos_token_id : 시퀀스 종료 토큰 ID

logit_processor_kwargs : logits 프로세서에 대한 키워드 인자.

**반환값:** `str | None`

프로세스가 TP 드라이버인 경우 요청 ID, 그렇지 않으면 None.

새로운 생성 요청을 큐에 추가합니다. 프로세스가 TP 드라이버가 아닌 경우, 이 작업은 아무것도 하지 않습니다(no-op).

#### add_requests[[transformers.ContinuousBatchingManager.add_requests]]

```python
add_requests(inputs: list[list[int]], max_new_tokens: int | None = None, streaming: bool = False, record_timestamps: bool = False, **logit_processor_kwargs: Any)
```

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

`add_request`를 배치로 처리하고 해당 ID를 반환하는 유틸리티 함수입니다. 자세한 내용은 해당 문서에서 확인하세요.

#### cancel_request[[transformers.ContinuousBatchingManager.cancel_request]]

```python
cancel_request(request_id: str)
```

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

ID를 사용하여 요청을 취소합니다. 이 함수가 TP 드라이버가 아닌 프로세스에서 호출된 경우 아무 동작도 수행하지 않습니다. 관리자와의 상호작용은 TP 드라이버 프로세스에서만 이루어집니다.

#### destroy[[transformers.ContinuousBatchingManager.destroy]]

```python
destroy()
```

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

manager를 종료하고 분산 리소스를 해제합니다. 여러 번 호출해도 안전합니다. 이 메서드를 호출한 후에는 manager를 다시 시작할 수 없습니다.

#### get_result[[transformers.ContinuousBatchingManager.get_result]]

```python
get_result(request_id: str | None = None, timeout: float | None = None)
```

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

출력 큐에서 결과를 하나 가져옵니다. ID가 제공되면 첫 번째 일치하는 요청을 반환합니다. 타임아웃이 제공되면 타임아웃(초 단위) 이후에 None을 반환합니다.

#### is_running[[transformers.ContinuousBatchingManager.is_running]]

```python
is_running()
```

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

배경 생성 스레드가 시작되어 아직 실행 중인지 확인하여 True를 반환합니다.

#### join[[transformers.ContinuousBatchingManager.join]]

```python
join(stop_trigger_time: float, timeout: float | None = None)
```

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

백그라운드 스레드가 완료될 때까지 기다립니다. timeout 인자(초 단위)를 사용하여 대기 시간을 제한할 수 있습니다.

#### 일시 정지[[transformers.ContinuousBatchingManager.pause]]

```python
pause()
```

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

… 생성 루프를 일시 중지하는 컨텍스트 매니저입니다. 이를 통해 호출 스레드가 모델을 사용할 수 있으며, 일반적으로 모델을 인플레이스(in-place)로 업데이트하는 데 사용됩니다. 루프가 일시 중지된 후에만 해당 스레드가 이 컨텍스트에 진입하며, 컨텍스트를 벗어나면 루프가 재개됩니다. 이때 캐시와 진행 중인 요청은 그대로 유지되며, 아무것도 비워지지 않고 요청이 유실되지도 않습니다. 여러 스레드가 동시에 일시 중지를 보유할 수 있으며, 마지막 스레드가 컨텍스트를 벗어날 때 루프가 재개됩니다. TP가 활성화된 경우, 모든 랭크가 이 컨텍스트에 진입해야 하며, 그렇지 않으면 다른 랭크가 영원히 대기 상태에 머물게 됩니다.

#### register_result_handler[[transformers.ContinuousBatchingManager.register_result_handler]]

```python
register_result_handler(request_id: str, callback: Callable)
```

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

**매개변수:**

request_id (*str*) : 출력을 받을 요청 ID입니다.

callback (*callable*) : 각 결과에 대해 `GenerationOutput`와 함께 호출됩니다.

결과 전달(스트리밍 또는 비스트리밍)을 위한 콜백을 등록합니다.

이 콜백은 이 요청에 대한 결과가 생성될 때마다 이벤트 루프를 통해 `call_soon_threadsafe`로 호출됩니다. 스트리밍 요청의 경우 모든 토큰마다, 비스트리밍 요청의 경우 완료 시에만 호출됩니다. 요청이 완료되면 핸들러는 자동으로 정리됩니다.

#### request_id_iter[[transformers.ContinuousBatchingManager.request_id_iter]]

```python
request_id_iter(request_id: str)
```

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

request id가 일치하는 결과를 반복합니다(블로킹).

재큐잉(requeue)을 사용하는 공유 출력 큐를 사용합니다. 높은 동시성 서빙의 경우, 대신 `register_result_handler`를 사용하세요.

#### 시작[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

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

배경 생성 스레드를 시작합니다.

#### stop[[transformers.ContinuousBatchingManager.stop]]

```python
stop(block: bool = True, timeout: float | None = None, keep_for_next_session: bool = False, hard_stop: bool = False)
```

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

백그라운드 생성 스레드를 중지합니다. `block` 플래그가 True로 설정된 경우, 이 메서드는 스레드가 중지될 때까지 최대 `timeout`초 동안 대기합니다(None은 타임아웃 없음). `keep_for_next_session` 플래그가 True로 설정된 경우, 매니저는 향후 사용을 위해 모델에 캐시됩니다. `hard_stop` 플래그가 설정된 경우, 백그라운드 생성 스레드가 즉시 중지되고 대기 중인 요청은 실패 처리됩니다.

#### switch_to_cb_friendly_attn[[transformers.ContinuousBatchingManager.switch_to_cb_friendly_attn]]

```python
switch_to_cb_friendly_attn(model: ProtoPretrainedModel, auto_switch_to_flash: bool = True)
```

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

attn 구현을 CB와 호환되는 방식으로 전환합니다. auto_switch_to_flash이 True이고 attn 구현이 SDPA 또는 eager인 경우, flash가 지원되고 사용 가능한 경우에도 flash로 전환합니다.

#### warmup[[transformers.ContinuousBatchingManager.warmup]]

```python
warmup()
```

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

더미 배치 실행을 통해 varlen 및 decode 경로에 대한 CUDA graphs를 사전에 캡처합니다. 아직 초기화되지 않은 경우 배치 프로세서를 초기화합니다.

## 스케줄러[[transformers.generation.Scheduler]]

#### transformers.generation.Scheduler[[transformers.generation.Scheduler]]

```python
transformers.generation.Scheduler(cache: PagedAttentionCache, safety_margin: float, max_requests_per_batch: int)
```

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

연속 배치 프로세서에서 요청을 스케줄링하기 위한 추상 베이스 클래스입니다. 스케줄러는 요청이 대기 큐에 추가된 시점부터 처리를 위해 스케줄링되는 시점까지의 요청 수명 주기를 관리합니다. 서로 다른 스케줄러는 요청을 우선순위화하고 배치하는 데 서로 다른 전략을 구현합니다.

#### add_waiting_request[[transformers.generation.Scheduler.add_waiting_request]]

```python
add_waiting_request(state: RequestState)
```

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

대기 목록에 요청을 추가합니다.

#### clear_cancelled_requests[[transformers.generation.Scheduler.clear_cancelled_requests]]

```python
clear_cancelled_requests()
```

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

취소된 모든 요청을 활성 대기열과 대기 대기열에서 제거합니다.

#### finish_request[[transformers.generation.Scheduler.finish_request]]

```python
finish_request(request_id: str)
```

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

요청의 처리를 완료하고 할당된 캐시 블록을 해제합니다. 이 메서드는 요청이 생성을 완료했거나 오류가 발생한 경우 호출됩니다.

#### get_active_request_static_outputs[[transformers.generation.Scheduler.get_active_request_static_outputs]]

```python
get_active_request_static_outputs(request_id: str)
```

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

활성 요청에 대해 생성된 토큰을 가져옵니다.

#### has_pending_requests[[transformers.generation.Scheduler.has_pending_requests]]

```python
has_pending_requests()
```

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

처리할 준비가 된 요청이 있는지 확인합니다.

#### request_is_cancelled[[transformers.generation.Scheduler.request_is_cancelled]]

```python
request_is_cancelled(request_id: str)
```

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

요청이 취소되었거나 제거되었는지 확인합니다.

#### 초기화[[transformers.generation.Scheduler.reset]]

```python
reset()
```

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

새로운 생성 루프를 위해 스케줄러 상태를 초기화합니다.

#### schedule_batch[[transformers.generation.Scheduler.schedule_batch]]

```python
schedule_batch(token_budget: int, cache_budget: int)
```

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

사용 가능한 토큰 및 캐시 예산에 기반하여 다음 배치의 요청을 스케줄링합니다. 이 메서드는 예산과 스케줄러의 우선순위 규칙을 고려하여 현재 배치에서 처리할 요청을 선택합니다. token_budget은 배치에서 처리할 수 있는 최대 토큰 수를, cache_budget은 배치에서 읽을 수 있는 최대 KV 캐시 엔트리 수를 나타냅니다. 스케줄링된 요청 목록을 "FutureRequestState" 형태로 반환하며, decode fast path를 사용할 수 있는지 여부를 나타내는 불리언 값, 쿼리 토큰의 총 개수, 읽은 kv 토큰의 최대 개수를 함께 반환합니다.

#### set_request_cancellation[[transformers.generation.Scheduler.set_request_cancellation]]

```python
set_request_cancellation(request_id: str)
```

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

취소 요청을 표시합니다.

## FIFOScheduler[[transformers.generation.FIFOScheduler]]

#### transformers.generation.FIFOScheduler[[transformers.generation.FIFOScheduler]]

```python
transformers.generation.FIFOScheduler(cache: PagedAttentionCache, safety_margin: float | None, max_requests_per_batch: int)
```

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

이 스케줄러는 요청이 도착한 순서대로 처리하므로, 디코딩 요청이 프리필링 요청보다 우선합니다.

## PrefillFirstScheduler[[transformers.generation.PrefillFirstScheduler]]

#### transformers.generation.PrefillFirstScheduler[[transformers.generation.PrefillFirstScheduler]]

```python
transformers.generation.PrefillFirstScheduler(cache: PagedAttentionCache, safety_margin: float | None, max_requests_per_batch: int)
```

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

split prefill 요청을 decoding 요청보다 우선 처리하는 Scheduler입니다. 이 Scheduler는 split prefill 요청(부분적으로 처리된 프롬프트의 연속)이 처리되기 전에 새로운 decoding 요청을 처리하지 않도록 보장합니다.

