SamplingParams·구조화된 출력 레퍼런스 (vllm.sampling_params)

생성 결과를 어떻게 뽑을지는 SamplingParams가 정해요. OpenAI 텍스트 완성 API의 샘플링 파라미터를 거의 그대로 따르면서, OpenAI에는 없는 **빔 서치(beam search)**까지 지원하는 게 vLLM의 특징이에요. 그리고 StructuredOutputsParams를 함께 쓰면 출력을 JSON 스키마·정규식·문법에 맞게 강제할 수 있어요.

출처: vllm.sampling_params — Inference Parameters

SamplingParams 주요 필드

temperature = 1.0 — 샘플링의 무작위성을 조절해요. 값이 낮을수록 결정적이고, 높을수록 무작위예요. 0이면 그리디 샘플링이 돼요.
top_k = 0 — 상위 k개 토큰만 후보로 뽑는 방식. 0(또는 -1)은 비활성화를 뜻해요.
top_p = 1.0 — 누적 확률이 p에 도달할 때까지 상위 토큰만 후보로 남기는 nucleus 샘플링. 범위는 (0, 1]이에요.
min_p = 0.0 — top 토큰 확률 대비 일정 비율 미만인 토큰을 제외하는 방식.
max_tokens = 16 — 생성할 최대 토큰 수.
min_tokens = 0 — 생성할 최소 토큰 수.
n = 1 — 프롬프트당 생성할 출력 시퀀스 수.
stop — 만나면 생성을 멈출 문자열 또는 토큰 id 목록.
seed — 재현 가능한 생성을 위한 난수 시드.
presence_penalty = 0.0 — 이미 등장한 토큰에 페널티를 줘 새로운 주제로 유도.
repetition_penalty = 1.0 — 반복 생성을 억제하는 페널티.
logprobs / prompt_logprobs — 출력/프롬프트 토큰별 로그 확률 반환 요청.
logit_bias — 주어지면 엔진이 해당 토큰에 편향을 적용하는 로짓 프로세서를 만들어요.
allowed_token_ids — 생성에 허용할 토큰 id 목록.
thinking_token_budget — thinking 연산에 허용할 최대 토큰 수.
structured_outputs — 구조화된 출력을 설정하는 StructuredOutputsParams.
detokenize = True — 출력 텍스트를 다시 디토크나이즈할지 여부.
extra_args — 추가 확장 인자.

참고: 검증 규칙

temperature는 0 이상이어야 하고, top_p는 (0, 1], top_k는 0(비활성) 또는 양수여야 해요. 범위를 벗어나면 VLLMValidationError가 나요.
max_tokens는 0보다 커야 하고, min_tokens는 0 이상이어야 해요.
logprob_token_ids는 모델의 vocab 크기를 넘는 토큰 id를 담을 수 없어요.
logprobs와 logprob_token_ids를 같이 쓸 땐 개수가 일치해야 해요.

BeamSearchParams

빔 서치용 파라미터예요. beam_width(빔 폭), max_tokens, ignore_eos, temperature, length_penalty, include_stop_str_in_output 등을 담아요. OpenAI에는 없는 vLLM 전용 기능이에요.

RepetitionDetectionParams

출력 토큰에서 반복되는 N-gram 패턴을 감지하는 파라미터예요. 패턴이 감지되면 생성을 일찍 끝낼 수 있어요.

max_pattern_size = 0 — 반복 감지할 N-gram 패턴의 최대 크기. 0이면 비활성화.
min_count = 0 — 반복으로 간주할 최소 등장 횟수.

StructuredOutputsParams (구조화된 출력)

SamplingParams 안에 structured_outputs로 넣는 구조화된 출력 설정이에요. 주요 옵션:

json — JSON 스키마에 맞춰 출력을 생성.
regex — 정규식 패턴을 따르도록 생성.
choice — 주어진 선택지 중 정확히 하나를 출력.
grammar — 컨텍스트 프리 문법(EBNF)을 따르도록 생성.
structural_tag — 생성 텍스트 안의 지정된 태그 내에서 JSON 스키마를 따르도록.

주의: 옛 API 필드

v0.12.0에서 제거된 옛 필드들(guided_json, guided_regex, guided_choice, guided_grammar, guided_whitespace_pattern, structural_tag, guided_decoding_backend)은 더 이상 쓰지 말고, 다음과 같이 structured_outputs로 옮겨야 해요.

guided_json → {"structured_outputs": {"json": ...}} 또는 StructuredOutputsParams(json=...)
guided_regex → StructuredOutputsParams(regex=...)
guided_choice → StructuredOutputsParams(choice=...)
guided_grammar → StructuredOutputsParams(grammar=...)

핵심 포인트

온도·top-p·top-k 같은 디코딩 파라미터는 OpenAI 스타일과 호환되지만, 빔 서치와 구조화된 출력이 vLLM의 강점이에요.
구조화된 출력은 백엔드(xgrammar·guidance·outlines 등)에 따라 정규식 문법이 달라질 수 있어요.
옛 guided_* 필드는 전부 제거됐으니 새 코드는 StructuredOutputsParams를 쓰세요.