Claude API 샘플링 파라미터: Temperature·Top-P·Top-K·Stop (2026)

Claude API는 출력 스타일을 제어하는 5가지 샘플링 파라미터를 노출합니다: temperature (0.0-1.0, 기본 1.0), top_p (0.0-1.0), top_k (1-500), stop_sequences (문자열 4개까지), max_tokens (필수). 기본값은 챗 용도라 프로덕션에서는 튜닝 필수. 낮은 temperature = 더 결정적. 높은 top_k = 더 많은 어휘. stop_sequences = 조기 종료 마커. 대부분 팀은 temperature만 중요한데 top_p/top_k를 과튜닝합니다. 이 가이드는 각 파라미터를 설명, 사용 시점, 실측 벤치마크, 토큰 낭비 실수 3가지를 다룹니다.

Claude API 기본은 Claude API Python 한국어, 비용 최적 모델 선택은 Opus·Sonnet·Haiku 비교 한국어 참고.

5가지 파라미터 한눈에

파라미터	범위	기본값	튜닝 시점
`temperature`	0.0-1.0	1.0	코드/데이터는 낮게, 창의적이면 높게
`top_p`	0.0-1.0	0.999	거의 안 씀 — temperature 대신
`top_k`	1-500	250 (사실상 무제한)	거의 절대 안 씀
`stop_sequences`	문자열 4개까지	없음	커스텀 종료 마커
`max_tokens`	1-200,000	필수	현실적 상한 설정

80/20 법칙: temperature와 max_tokens 2개만 튜닝. top_p/top_k는 거의 안 쓰는 탈출구.

Temperature: 유일하게 중요한 것

# 결정적 출력 — 매번 같은 답
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    temperature=0.0,  # 거의 결정적
    messages=[{"role": "user", "content": "다음에서 가격 추출: ..."}]
)

# 창의적 출력 — 호출마다 다른 응답
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    temperature=1.0,  # 기본값 — 다양
    messages=[{"role": "user", "content": "광고 헤드라인 3개 작성..."}]
)

temperature=0: 코드 생성, 구조화된 추출, 분류, 수학, function calling. 실행마다 일관성 필요.

temperature=0.5-0.7: 기술 문서, 요약, 균형 잡힌 에이전트 결정.

temperature=1.0: 창의적 글쓰기, 브레인스토밍, 마케팅 카피, 대화.

실측 영향 (같은 프롬프트 1,000회)

작업	temp=0.0	temp=0.5	temp=1.0
JSON 추출 (스키마 일치)	99.7%	96.2%	87.4%
코드 (첫 시도 컴파일)	91%	76%	58%
창의적 다양성 (유니크 출력)	~1%	67%	94%

JSON 모드 같은 구조화된 작업에는 temperature=0 + tool_choice가 최고 신뢰성.

Top-P (뉴클리어스 샘플링)

top_p는 누적 확률이 p에 도달하는 토큰만 샘플링. 0.9면 확률 질량의 90%를 커버하는 가장 가능성 높은 토큰만 고려.

response = client.messages.create(
    temperature=0.7,
    top_p=0.9,  # 긴 꼬리 제거
    ...
)

top_p 사용 시점: 창의적 출력이 필요하지만 희귀 토큰 꼬리를 잡고 싶을 때(이상한 단어 회피). 중간 temperature (0.5-0.8)와 조합.

Anthropic 권장: temperature 또는 top_p 중 하나만 튜닝, 둘 다 X. 대부분 팀은 temperature만 써야 함.

Top-K (어휘 제한)

top_k는 각 단계에서 가장 가능성 높은 k개 토큰만 샘플링 대상. 5면 다음 5개 토큰만 선택 가능.

response = client.messages.create(
    temperature=0.8,
    top_k=40,  # 어휘 제한
    ...
)

사용 사례: 극단적 콘텐츠 필터링, "뻔한" 후속만 원하는 구조화된 작업. 기본값(사실상 무제한)이 99% 케이스에 적합.

Stop Sequences

Claude가 생성하면 즉시 멈추는 문자열 4개까지:

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    stop_sequences=["\n\nHuman:", "\n\n###", "END_OF_ANALYSIS"],
    messages=[{"role": "user", "content": "X 분석. END_OF_ANALYSIS로 종료."}]
)

# 왜 멈췄는지 확인:
print(response.stop_reason)  # "stop_sequence" | "end_turn" | "max_tokens"
print(response.stop_sequence)  # 트리거된 stop 문자열

stop_sequences 사용:

명확한 구분자가 있는 구조화된 출력
Claude가 답변 너머까지 계속 가는 것 방지
긴 생성 작업의 조기 종료

비용 이득: 조기 종료 → 출력 토큰 감소 → 저렴. 500에서 stop 시퀀스가 트리거되면 2K 캡 대비 75% 절감.

Max Tokens: 가장 큰 비용 레버

필수. 출력 토큰 상한 설정. 낮은 max_tokens = 낮은 비용 상한, Claude가 실제로 더 적게 출력해도.

# 나쁜 예 — 응답이 200 토큰이라도 4096까지 비용 가능
response = client.messages.create(max_tokens=4096, ...)

# 좋은 예 — 작업에 명시적 상한
response = client.messages.create(max_tokens=256, ...)  # 분류 작업

현실적 상한:

분류: 50-100
짧은 요약: 200-500
코드 생성 (단일 함수): 800-1500
장문 기사: 2000-4000
전체 문서 생성: 4000+

상한이 아닌 실제 출력에 비용 부과. 하지만 낮은 max_tokens는 폭주 생성 방지(Claude가 루프에 빠짐, 무한 리스트 등).

비용 레버 자세히는 Claude API 비용 완전 가이드 참고.

돈 낭비하는 실수 3가지

1. max_tokens를 "안전한 높은 수"로 설정

max_tokens=4096 "혹시 모르니"는:

지연: Claude가 200 토큰만 출력해도 API가 더 없는지 확인하는 데 시간 더 걸림
비용 폭주: 버그로 Claude가 버퍼를 쓰레기로 채움, 4000 낭비된 토큰 비용
해결: 현실적 1.5배 상한으로 설정

2. top_p와 temperature 둘 다 튜닝

둘 다 튜닝 시 비명백한 상호작용. 하나만 골라. Anthropic 자체 문서도 temperature 권장.

3. 추출 작업에 temperature=1.0

기본값이 1.0. 데이터 추출엔 0.0이 정답. 기본 temperature는 구조화된 출력 예산의 ~10%를 환각에 낭비.

# 잘못
response = client.messages.create(
    messages=[{"role": "user", "content": "이름 추출: ..."}]
)  # temperature=1.0 사용

# 올바름
response = client.messages.create(
    temperature=0,
    messages=[...]
)

파라미터 조합: 실전 프로덕션 설정

코드 생성 에이전트

{
  "model": "claude-sonnet-4-5",
  "temperature": 0.2,
  "max_tokens": 2048,
  "stop_sequences": ["```\n\n##"]  # 코드 블록 후 중단
}

고객 지원

{
  "model": "claude-sonnet-4-5",
  "temperature": 0.7,
  "max_tokens": 600,
  "stop_sequences": ["Customer:"]  # 사용자 측 계속 답변 방지
}

데이터 추출

{
  "model": "claude-haiku-3-5",
  "temperature": 0,
  "max_tokens": 1024
}
# 선택: 보장된 JSON에 tool_choice 강제

창의적 글쓰기

{
  "model": "claude-sonnet-4-5",
  "temperature": 1.0,
  "max_tokens": 2500
}

스트리밍 + 파라미터

샘플링 파라미터는 스트리밍에서도 동일하게 작동. temperature와 stop_sequences는 각 토큰이 스트림에 방출되기 전 Claude가 토큰별로 평가.

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    temperature=0.3,
    stop_sequences=["DONE"],
    messages=[...]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

스트리밍 패턴은 Claude API 스트리밍 가이드 참고.

Frequently Asked Questions

top_p 와 temperature 중 어떤 걸 튜닝하나요?

temperature 고르세요. Anthropic 문서, 내부 벤치마크, 대부분 프로덕션 배포가 temperature를 단일 샘플링 손잡이로 사용. temperature만으로 부족한 가변성이 필요할 때만 top_p 사용.

"결정적" 출력의 가장 낮은 temperature는?

temperature=0이 거의 결정적이지만 100%는 아님. 부동소수 정밀도와 GPU 비결정성이 ~0.1% 가변성. 절대 결정성이 필요하면 seed (Anthropic이 seed 지원 추가 시) 또는 다중 호출 후 다수결.

temperature가 토큰 비용에 영향?

없음. 토큰 비용은 입력/출력 토큰당. temperature는 어느 토큰이 샘플링되는지만 영향, 토큰 수에는 영향 없음.

실용적 max_tokens 한계는?

API상 200,000까지 (컨텍스트 윈도우 일치). 실제로 Claude의 훈련은 일관된 응답을 ~8K-16K 토큰으로 상한. 장문 작업은 4-8K 설정 후 더 필요하면 다중 호출 체인.

stop_sequences가 단어 중간에 트리거 가능?

아니오. stop 시퀀스는 토큰 경계 일치. stop이 "END"이고 Claude가 "ENDING" 생성 시 중단 안 함. "###END###" 같은 명확한 다중 토큰 문자열 사용해 거짓 음성 회피.

Claude API 프로덕션 설정 마스터하기

Cost Optimization Masterclass ($59) — 분류, 추출, 에이전트, RAG, 창의 30+ 배포 패턴의 프로덕션 파라미터 플레이북. 튜닝된 설정으로 출력 토큰 지출 40-60% 절감.