temperature와 streaming으로 Claude API 응답을 정밀 제어하기

temperature: 숫자 하나가 결과를 바꾼다

temperature는 모델의 토큰 샘플링 무작위성을 제어하는 값(0.0 ~ 1.0)입니다. 낮을수록 예측 가능하고 일관된 출력, 높을수록 다양하고 창의적인 출력이 나옵니다.

| 값 범위 | 특성 | 적합한 용도 | |---|---|---| | 0.0 ~ 0.3 | 결정론적·일관성 ↑ | SQL 생성, 분류, 데이터 추출 | | 0.4 ~ 0.7 | 균형 | 요약, Q&A, 번역 | | 0.8 ~ 1.0 | 창의성·다양성 ↑ | 브레인스토밍, 카피라이팅, 스토리 |

주의: temperature=0이어도 완전한 결정론은 보장되지 않습니다. 재현이 중요한 경우 동일 seed 개념 대신 결과를 캐싱하는 전략을 병행하세요.

streaming으로 체감 속도 혁신하기

일반 API 호출은 전체 응답이 완성될 때까지 기다립니다. 긴 응답일수록 사용자는 빈 화면을 오래 봅니다. streaming을 쓰면 첫 토큰부터 즉시 화면에 표시할 수 있습니다.

import anthropic

client = anthropic.Anthropic()

def stream_with_temperature(
    prompt: str,
    task_type: str = "balanced"
) -> str:
    """태스크 유형에 따라 temperature를 자동 선택하고 스트리밍 출력"""

    temperature_map = {
        "factual": 0.1,    # 분류, 추출
        "balanced": 0.5,   # 요약, Q&A
        "creative": 0.9,   # 브레인스토밍
    }
    temperature = temperature_map.get(task_type, 0.5)

    print(f"[설정] temperature={temperature}, task={task_type}")
    print("[응답] ", end="", flush=True)

    full_text = ""

    # stream() 컨텍스트 매니저로 스트리밍 시작
    with client.messages.stream(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        temperature=temperature,
        messages=[
            {"role": "user", "content": prompt}
        ],
    ) as stream:
        for text_chunk in stream.text_stream:
            print(text_chunk, end="", flush=True)  # 실시간 출력
            full_text += text_chunk

    print()  # 줄바꿈

    # 스트리밍 완료 후 usage 정보 확인
    final_message = stream.get_final_message()
    usage = final_message.usage
    print(f"\n[토큰] 입력={usage.input_tokens}, 출력={usage.output_tokens}")

    return full_text


# 활용 예시
if __name__ == "__main__":
    # 창의적 작업
    stream_with_temperature(
        prompt="SaaS 스타트업을 위한 슬로건 아이디어 5개를 제안해주세요.",
        task_type="creative"
    )

    print("\n" + "="*50 + "\n")

    # 사실 기반 작업
    stream_with_temperature(
        prompt="다음 텍스트의 감정을 긍정/부정/중립 중 하나로 분류하세요: '배송이 이틀이나 늦었습니다.'",
        task_type="factual"
    )

실전에서 자주 하는 실수와 해결책

실수 1 — 창의적 작업에 낮은 temperature 고정 모든 프롬프트에 temperature=0을 쓰는 개발자가 많습니다. 마케팅 카피나 아이디어 생성에서는 0.8 이상을 시도해보세요.

실수 2 — 스트리밍 중 에러 처리 누락 네트워크 단절 시 스트림이 중간에 끊깁니다. try/except로 anthropic.APIConnectionError를 잡고, 부분 응답을 저장해 재시도 로직을 구성하세요.

실수 3 — 스트리밍 응답의 usage 조회 타이밍 stream.text_stream 루프 안에서 usage를 조회하면 None이 반환됩니다. 반드시 루프 종료 후 stream.get_final_message()로 접근하세요.

claude-sonnet-4-6 vs claude-haiku-4-5 선택 기준

• 긴 문서 요약·복잡한 추론 → claude-sonnet-4-6 (품질 우선)
• 짧은 분류·실시간 챗봇 → claude-haiku-4-5 (속도·비용 우선)

✅ 체크리스트

• [ ] 작업 유형별로 temperature 값을 다르게 설정하는 로직을 구현했다
• [ ] 사용자에게 응답을 보여주는 UI에 streaming을 적용했다
• [ ] stream.get_final_message()로 최종 usage를 스트림 종료 후 수집했다
• [ ] 스트리밍 도중 네트워크 에러를 try/except로 처리했다
• [ ] 비용이 민감한 엔드포인트에는 claude-haiku-4-5로 모델을 교체했다