샘플링 파라미터 (Sampling Parameters)

샘플링 파라미터 (Sampling Parameters)

vLLM에서 생성할 텍스트의 성격을 결정하는 핵심 설정이 바로 샘플링 파라미터예요. 모델이 다음 토큰 하나를 고를 때 어떤 방식으로 확률 분포를 다듬고, 어디까지 계산하고, 언제 멈출지를 전부 여기서 제어하죠. 전반적으로는 OpenAI의 text completion API의 파라미터를 따라가는데, OpenAI에는 없는 빔 서치(beam search)까지 추가로 지원한다는 점이 특징이에요.

이 문서는 vLLM의 SamplingParams 객체에 담긴 파라미터들을 실제 사용 관점에서 하나씩 설명해요. 각 파라미터는 온라인 서빙(/v1/completions, /v1/chat/completions)에서는 요청 본문의 필드로, 오프라인 추론에서는 SamplingParams(...) 생성자 인자로 넘기면 돼요.

토큰 선택을 다듬는 파라미터

temperature (float, 기본값 1.0)

샘플링의 무작위성을 조절해요. 값이 낮을수록 모델이 결정적(deterministic)에 가까워지고, 높을수록 결과가 더 무작위로 나와요. 0이면 그리디(greedy) 샘플링, 즉 항상 확률이 가장 높은 토큰을 고르게 돼요. 창의적인 문장이 필요하면 높이고, 일관된 답이 필요하면 낮추면 되죠.

top_p (float, 기본값 1.0)

누적 확률로 상위 토큰들의 범위를 정해요. 값 p가 주어지면, 확률이 높은 토큰부터 누적 확률이 p에 도달할 때까지의 토큰들만 후보로 남겨요. 반드시 (0, 1] 범위에 있어야 하고, 1로 설정하면 사실상 모든 토큰을 고려해요. 이걸 nucleus sampling이라고도 불러요.

top_k (int, 기본값 0)

확률이 가장 높은 토큰 몇 개만 후보로 볼지 정해요. 0(또는 -1)로 설정하면 모든 토큰을 고려해요. top_k=50이면 확률 상위 50개 토큰만 샘플링 후보로 남긴다는 뜻이죠.

min_p (float, 기본값 0.0)

토큰이 후보로 남기 위한 최소 확률을 정하는데, 절대값이 아니라 가장 확률이 높은 토큰의 확률에 대한 상대값이에요. 예를 들어 min_p=0.1이면, 가장 가능성 높은 토큰 확률의 10% 미만인 토큰들은 모두 제외돼요. 반드시 [0, 1] 범위여야 하고, 0으로 설정하면 이 기능을 끄는 거예요. 모델의 확신 정도에 따라 기준이 유연하게 적응한다는 장점이 있어요.

seed (int | None, 기본값 None)

생성에 사용할 랜덤 시드를 지정해요. 같은 시드로 재실행하면 같은 결과를 재현할 수 있어요. None이면 매번 다른 결과가 나와요.

페널티 계열 파라미터

presence_penalty (float, 기본값 0.0)

지금까지 생성된 텍스트에 등장했는지 여부에 따라 새 토큰에 페널티를 줘요. > 0이면 모델이 새로운 토큰을 쓰도록 유도하고, < 0이면 토큰을 반복하도록 유도해요.

frequency_penalty (float, 기본값 0.0)

새 토큰이 지금까지 생성된 텍스트에서 얼마나 자주 등장했는지에 따라 페널티를 줘요. > 0이면 새로운 토큰을, < 0이면 반복을 유도한다는 점은 presence_penalty와 같지만, 등장 횟수에 비례해서 누적 적용된다는 차이가 있어요. 무엇이든 똑같은 걸 반복하는 걸 막고 싶을 때 써요.

repetition_penalty (float, 기본값 1.0)

위 두 페널티와 달리, 프롬프트와 생성된 텍스트 양쪽에 이미 등장한 토큰에 페널티를 줘요. > 1이면 새로운 토큰을 쓰도록, < 1이면 반복하도록 유도해요. (OpenAI API에는 이 파라미터가 없고, Hugging Face 계열에서 잘 알려진 값이에요.)

토큰 생성 범위와 중단 조건

max_tokens (int | None, 기본값 16)

출력 시퀀스당 생성할 최대 토큰 수예요. None이면 모델이 허용하는 최대 시퀀스 길이까지 채워서 생성해요.

min_tokens (int, 기본값 0)

EOS 토큰이나 stop_token_ids가 생성될 수 있기 전에 반드시 생성해야 하는 최소 토큰 수예요. 예를 들어 특정 길이 이상의 답변을 강제하고 싶을 때 유용해요.

stop (str | list[str] | None, 기본값 None)

생성될 때 생성을 멈추게 하는 문자열(들)이에요. 반환되는 출력에는 이 중단 문자열이 포함되지 않아요.

stop_token_ids (list[int] | None, 기본값 None)

생성될 때 생성을 멈추게 하는 토큰 ID(들)이에요. stop 문자열과 달리, 반환되는 출력에는 중단 토큰이 포함돼요. 단, 그 토큰이 special token인 경우에는 제외돼요.

ignore_eos (bool, 기본값 False)

True면 EOS 토큰을 무시하고, EOS가 생성된 뒤에도 계속 토큰을 생성해요. 특정 토큰 수까지 강제로 채우고 싶을 때 써요.

로그확률(logprob) 관련 파라미터

logprobs (int | None, 기본값 None)

출력 토큰 하나마다 반환할 로그확률의 개수를 정해요. None이면 아무 확률도 반환하지 않아요. 값을 지정하면, 지정한 개수의 가장 가능성 높은 토큰들의 로그확률이 선택된 토큰과 함께 반환돼요. 구현이 OpenAI API를 따르는데, 샘플링된 토큰의 로그확률은 항상 포함되므로 응답에는 최대 logprobs + 1개의 요소가 올 수 있어요. -1로 설정하면 전체 vocab_size개의 로그확률을 반환해요.

prompt_logprobs (int | None, 기본값 None)

프롬프트 토큰 하나마다 반환할 로그확률의 개수를 정해요. -1로 설정하면 전체 vocab_size개의 로그확률을 반환해요.

logprob_token_ids (list[int] | None, 기본값 None)

로그확률을 얻고 싶은 특정 토큰 ID 목록이에요. 작은 토큰 집합의 확률만 필요할 때 logprobs=-1보다 훨씬 효율적이에요. 설정하면 이 토큰 ID들의 로그확률이 샘플링된 토큰과 함께 정확히 반환되죠. 특정 레이블 토큰의 확률을 비교하는 점수 매기기(scoring) 작업에서 유용해요.

flat_logprobs (bool, 기본값 False)

True면 로그확률을 평탄화된 FlatLogprob 형식으로 반환해 성능을 올려요. FlatLogprobs의 GC 비용이 list[dict[int, Logprob]]보다 훨씬 작아요. 활성화하면 PromptLogprobs와 SampleLogprobs가 FlatLogprobs로 채워져요.

출력 처리 관련 파라미터

n (int, 기본값 1)

주어진 프롬프트 요청에 대해 반환할 출력 개수예요. 최대 허용값은 VLLM_MAX_N_SEQUENCES 환경 변수로 제어되는데, 기본값은 16384예요. AsyncLLM은 기본적으로 출력을 스트리밍하므로, n > 1이면 모든 n개 출력이 요청당 누적되어 생성·스트리밍돼요. 완료 시점에 모든 n개 출력을 한 번에 보려면 SamplingParams에서 output_kind=RequestOutputKind.FINAL_ONLY를 쓰면 돼요.

detokenize (bool, 기본값 True)

출력을 디토크나이즈할지 여부예요.

skip_special_tokens (bool, 기본값 True)

출력에서 special token을 제외할지 여부예요.

spaces_between_special_tokens (bool, 기본값 True)

출력에서 special token 사이에 공백을 넣을지 여부예요.

include_stop_str_in_output (bool, 기본값 False)

중단 문자열을 출력 텍스트에 포함할지 여부예요.

stream_interval (int | None, 기본값 None)

각각 스트리밍되는 RequestOutput에 묶어서 보낼 새로 생성된 토큰 수예요. 엔진 레벨의 --stream-interval보다 값이 낮으면 해당 엔진 설정까지 끌어올려지고, 그보다 낮게 내려갈 수는 없어요. 첫 출력과 마지막 출력은 항상 즉시 내보내져요.

bad_words (list[str] | None, 기본값 None)

생성되면 안 되는 단어(들)이에요. 보다 정확히는, 다음 생성 토큰이 해당 단어 시퀀스를 완성할 수 있을 때 그 시퀀스의 마지막 토큰만 허용하지 않아요.

logit_bias (dict[int, float] | None, 기본값 None)

제공하면 엔진이 이 로짓 바이어스를 적용하는 logits processor를 만들어요. 특정 토큰 ID의 확률을 직접 올리거나 낮추고 싶을 때 써요.

allowed_token_ids (list[int] | None, 기본값 None)

제공하면 엔진이 주어진 토큰 ID들의 점수만 남기는 logits processor를 만들어요. 생성 토큰을 특정 집합으로 제한할 때 써요.

extra_args (dict[str, Any] | None, 기본값 None)

커스텀 샘플링 구현이나 플러그인 등이 사용할 수 있는 임의의 추가 인자예요. vLLM 내부에 포함된 샘플링 구현에서는 사용되지 않아요.

thinking_token_budget (int | None, 기본값 None)

think(사고) 작업에 허용되는 최대 토큰 수예요.

structured_outputs (StructuredOutputsParams | None, 기본값 None)

구조화된 출력을 구성하기 위한 파라미터예요. JSON 스키마, 정규식, choice, grammar 등을 지정해서 출력 형식을 강제할 수 있어요.

repetition_detection (RepetitionDetectionParams | None, 기본값 None)

출력 토큰에서 반복적인 N-gram 패턴을 감지하기 위한 파라미터예요. 이런 반복이 감지되면 생성을 일찍 끝내요. LLM은 가끔 abcdabcdabcd...나 😀 😀 😀 ...처럼 무의미하게 반복하며 최대 출력 길이까지 이어지기도 하는데, 이 기능이 그런 동작을 감지해서 일찍 끝내 시간과 토큰을 아껴줘요.

빔 서치 관련 파라미터

use_beam_search가 활성화된 경우 쓰이는 파라미터예요. (현재 SamplingParams에서는 별도 필드로 노출되지 않지만, 빔 서치 자체는 OpenAI가 지원하지 않는 vLLM만의 기능이에요.)

함께 살펴보면 좋은 자료