샘플링 파라미터 (Parameters)
샘플링 파라미터 (Parameters)
샘플링 파라미터는 모델의 토큰 생성 과정을 조절해요. OpenRouter로 보낼 수 있는 파라미터가 있는데, 요청에서 빠뜨리면 OpenRouter가 하드코딩된 값을 넣는 대신 상위(업스트림)로 생략해서 보내, 제공자가 자기 기본값을 적용해요. 그래서 아래 각 파라미터의 "Default"는 관례적인 값이지 OpenRouter가 주입하는 값이 아니에요. 이 페이지에서는 대표적인 추론 파라미터들을 하나씩 살펴볼게요.
명시적으로 보내는 값(예: temperature: 1.0)은 여전히 전달되지만, 생략했을 때와 결과가 달라질 수 있어요(제공자 측 캐시 키에 영향을 줄 수 있음 같은). OpenRouter는 Mistral의 safe_prompt나 Hyperbolic의 raw_mode 같은 제공자별 파라미터도 지정하면 해당 제공자로 그대로 전달해요. 모델이 어떤 파라미터를 지원하는지는 모델의 제공자 섹션과 프로바이더 파라미터 관리 가이드를 확인하세요.
Temperature
- 키:
temperature - 선택, float, 0.0 ~ 2.0
- 기본: 1.0
모델 응답의 다양성에 영향을 줘요. 값이 낮을수록 예측 가능하고 전형적인 응답을, 높을수록 더 다양하고 흔치 않은 응답을 만들어요. 0이면 같은 입력에 항상 같은 응답을 돌려줘요.
Top P
- 키:
top_p - 선택, float, 0.0 ~ 1.0
- 기본: 1.0
확률이 높은 토큰들의 집합으로 모델 선택지를 제한해요 — 확률 합이 P에 이를 때까지의 상위 토큰만 골라요. 값이 낮을수록 응답이 예측 가능해지고, 기본값은 모든 토큰 선택지를 허용해요. 동적 Top-K처럼 생각하면 돼요.
Top K
- 키:
top_k - 선택, integer, 0 이상
- 기본: 0
각 단계에서 모델이 고르는 토큰을 더 작은 집합으로 제한해요. 1이면 항상 가장 가능성 높은 다음 토큰을 골라 예측 가능한 결과를 내요. 기본적으로 비활성화되어 모든 선택지를 고려해요.
Frequency Penalty
- 키:
frequency_penalty - 선택, float, -2.0 ~ 2.0
- 기본: 0.0
입력에 자주 등장한 토큰의 반복을 줄이려는 설정이에요. 입력에 많이 나온 토큰을 그 빈도에 비례해 덜 쓰려고 해요. 패널티는 등장 횟수에 비례해 커져요. 음수 값은 토큰 재사용을 부추겨요.
Presence Penalty
- 키:
presence_penalty - 선택, float, -2.0 ~ 2.0
- 기본: 0.0
입력에 이미 쓰인 특정 토큰을 모델이 얼마나 반복하는지 조절해요. 값이 높을수록 반복이 덜 일어나고, 음수는 그 반대예요. 등장 횟수에 비례해 커지지 않는다는 점이 frequency penalty와 달라요. 음수 값은 토큰 재사용을 부추겨요.
Repetition Penalty
- 키:
repetition_penalty - 선택, float, 0.0 ~ 2.0
- 기본: 1.0
입력에서 온 토큰의 반복을 줄이는 데 도움을 줘요. 값이 높을수록 토큰 반복 가능성이 낮아지지만, 너무 높으면 출력 일관성이 떨어질 수 있어요(작은 단어가 빠지는 흐트러진 문장이 자주 나와요). 패널티는 원래 토큰의 확률에 기반해 조정돼요.
Min P
- 키:
min_p - 선택, float, 0.0 ~ 1.0
- 기본: 0.0
가장 가능성 높은 토큰의 확률 대비 상대 확률이 너무 낮은 토큰은 제외하는 방식이에요. 토큰 필터링의 또 다른 한 방법으로, 상대적 임계값을 기준으로 매 단계 후보를 좁혀요.
Top A
- 키:
top_a - 선택, float, 0.0 ~ 1.0
- 기본: 0.0
가장 가능성 높은 토큰의 확률에 비추어 "충분히 높은" 확률의 토큰만 고려해요. 동적 Top-P처럼 동작해요. Top-A 값이 낮을수록 가장 높은 확률 토큰을 중심으로 더 좁은 범위에서 고르게 돼요.
Seed
- 키:
seed - 선택, integer
지정하면 동일한 seed와 파라미터로 반복 요청 시 같은 결과를 내도록 결정적으로 샘플링해요. 단, 일부 모델에서는 결정성이 보장되지 않아요.
Max Tokens
- 키:
max_tokens - 선택, integer, 1 이상
모델이 응답에서 생성할 수 있는 토큰 수의 상한이에요. 이 한도를 넘지 않아요. 최대값은 컨텍스트 길이에서 프롬프트 길이를 뺀 값이에요.
Max Completion Tokens
- 키:
max_completion_tokens - 선택, integer, 1 이상
max_tokens와 같은 역할을 하는 상한이에요. 최대값은 컨텍스트 길이에서 프롬프트 길이를 뺀 값이에요.
Logit Bias
- 키:
logit_bias - 선택, map
토크나이저의 토큰 ID로 토큰을 -100에서 100 사이의 bias 값에 매핑하는 JSON 객체를 받아요. 수학적으로 말하면, 이 bias는 샘플링 전에 모델이 생성한 logits에 더해져요.
Logprobs
- 키:
logprobs - 선택, boolean
출력 토큰의 로그 확률을 반환할지 여부예요. true면 각 출력 토큰의 로그 확률을 돌려줘요.
Top Logprobs
- 키:
top_logprobs - 선택, integer
각 토큰 위치에 반환할 가장 가능성 높은 토큰 수(0~20)를 지정하고, 각각에 로그 확률을 붙여요. 이 파라미터를 쓰려면 logprobs를 true로 설정해야 해요.
Response Format
- 키:
response_format - 선택, map
모델이 특정 출력 형식을 내도록 강제해요. { "type": "json_object" }로 두면 JSON 모드가 활성화되어 모델이 생성하는 메시지가 유효한 JSON임을 보장해요.
Structured Outputs
- 키:
structured_outputs - 선택, boolean
모델이 response_format json_schema로 구조화된 출력을 반환할 수 있는지 여부예요.
Stop
- 키:
stop - 선택, array
모델이 stop 배열에 지정된 토큰을 만나면 생성 즉시 중단해요.
Tools
- 키:
tools - 선택, array
도구 호출 파라미터로, OpenAI의 도구 호출 요청 형식을 따라요. OpenAI가 아닌 제공자에는 그에 맞게 변환돼요. 자세한 내용은 도구 호출 가이드를 참고하세요.
Tool Choice
- 키:
tool_choice - 선택, string 또는 object
모델이 어떤(있다면) 도구를 호출할지 제어해요. 'none'은 도구를 호출하지 않고 메시지를 생성해요. 'auto'는 메시지를 생성하거나 하나 이상의 도구를 호출하는 걸 모델이 고를 수 있어요. 'required'는 모델이 반드시 하나 이상의 도구를 호출해야 해요. {"type": "function", "function": {"name": "my_function"}}처럼 특정 도구를 지정하면 그 도구를 호출하도록 강제해요.
Parallel Tool Calls
- 키:
parallel_tool_calls - 선택, boolean
- 기본: true
도구 사용 중 병렬 함수 호출을 켤지 여부예요. true면 모델이 여러 함수를 동시에 호출할 수 있고, false면 순차적으로 호출해요. 도구가 제공될 때만 적용돼요.
Include Reasoning
- 키:
include_reasoning - 선택, boolean
reasoning.exclude의 지원 중단된 별칭이에요. true면 모델이 지원할 때 추론 토큰이 응답에 반환돼요.
Reasoning
- 키:
reasoning - 선택, map
thinking 토큰을 지원하는 모델의 추론 동작을 제어해요 — 추론 활성화 여부, 추론 effort, 최대 추론 토큰, 응답에서의 추론 제외 여부를 포함해요. 상세한 조절 방법은 추론 토큰 문서를 참고하세요.
Reasoning Effort
- 키:
reasoning_effort - 선택, enum (xhigh, high, medium, low, minimal, none)
OpenAI 스타일 추론 effort 설정이에요. 지원될 때 값이 높을수록 모델이 내부 추론에 더 많은 토큰을 쓸 수 있어요.
Web Search Options
- 키:
web_search_options - 선택, map
웹 연결 응답을 지원하는 모델·제공자의 네이티브 웹 검색 옵션을 구성해요.
Verbosity
- 키:
verbosity - 선택, enum (low, medium, high, xhigh, max)
- 기본: medium
모델 응답의 장황함을 제한해요. 값이 낮을수록 간결하게, 높을수록 상세하고 포괄적인 응답을 만들어요. OpenAI가 Responses API에서 도입했어요. Anthropic 모델에서는 output_config.effort로 매핑되고, xhigh는 Anthropic Claude 4.7 Opus 이후, max는 Claude 4.6 Opus 이후 모델에서 지원돼요.