Effort

effort 매개변수를 사용하면 Claude가 요청에 응답할 때 토큰을 얼마나 적극적으로 사용할지 제어할 수 있습니다. 이를 통해 단일 모델로 응답의 철저함과 토큰 효율성 사이의 균형을 조절할 수 있습니다. effort 매개변수는 베타 헤더 없이 지원되는 모든 모델에서 일반적으로 사용할 수 있습니다.

effort 작동 방식

기본적으로 Claude는 높은 effort를 사용하여 우수한 결과를 위해 필요한 만큼의 토큰을 사용합니다. effort 수준을 max로 올려 절대적으로 가장 높은 성능을 얻거나, 낮춰서 토큰 사용을 더 보수적으로 하여 일부 성능 감소를 감수하면서 속도와 비용을 최적화할 수 있습니다.

effort 매개변수는 응답의 모든 토큰에 영향을 미치며, 여기에는 다음이 포함됩니다:

• 텍스트 응답 및 설명
• 도구 호출 및 함수 인수
• 확장된 사고 (활성화된 경우)

이 접근 방식에는 두 가지 주요 장점이 있습니다:

1. 사용하기 위해 사고를 활성화할 필요가 없습니다.
2. 도구 호출을 포함한 모든 토큰 사용에 영향을 줄 수 있습니다. 예를 들어, 낮은 effort는 Claude가 더 적은 도구 호출을 수행한다는 것을 의미합니다. 이를 통해 효율성에 대한 훨씬 더 큰 수준의 제어가 가능합니다.

Effort 수준

기본 사용법

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Analyze the trade-offs between microservices and monolithic architectures"
    }],
    output_config={
        "effort": "medium"
    }
)

print(response.content[0].text)

effort 매개변수를 언제 조정해야 하나요?

• 제한 없이 절대적으로 가장 높은 성능이 필요할 때—가장 철저한 추론과 가장 깊은 분석이 필요할 때 max effort를 사용하세요. Opus 4.6에서만 사용 가능하며, 다른 모델에서 max를 사용하는 요청은 오류를 반환합니다.
• Claude의 최고 수준의 작업이 필요할 때—복잡한 추론, 미묘한 분석, 어려운 코딩 문제, 또는 품질이 최우선인 모든 작업에 high effort(기본값)를 사용하세요.
• high effort의 전체 토큰 지출 없이 견고한 성능을 원할 때 균형 잡힌 옵션으로 medium effort를 사용하세요.
• 속도(Claude가 더 적은 토큰으로 응답하므로) 또는 비용을 최적화할 때 low effort를 사용하세요—예를 들어, 간단한 분류 작업, 빠른 조회, 또는 한계적인 품질 향상이 추가 지연 시간이나 비용을 정당화하지 못하는 대량 사용 사례에 적합합니다.

도구 사용과 effort

도구를 사용할 때, effort 매개변수는 도구 호출 주변의 설명과 도구 호출 자체 모두에 영향을 미칩니다. 낮은 effort 수준은 다음과 같은 경향이 있습니다:

• 여러 작업을 더 적은 도구 호출로 결합
• 더 적은 도구 호출 수행
• 서문 없이 바로 작업 진행
• 완료 후 간결한 확인 메시지 사용

높은 effort 수준은 다음과 같을 수 있습니다:

• 더 많은 도구 호출 수행
• 작업 수행 전 계획 설명
• 변경 사항에 대한 상세한 요약 제공
• 더 포괄적인 코드 주석 포함

확장된 사고와 effort

effort 매개변수는 확장된 사고와 함께 작동합니다. 동작은 모델에 따라 다릅니다:

• Claude Opus 4.6은 적응형 사고 (thinking: {type: "adaptive"})를 사용하며, effort가 사고 깊이를 제어하는 권장 방법입니다. budget_tokens는 Opus 4.6에서 여전히 허용되지만, 더 이상 사용이 권장되지 않으며 향후 릴리스에서 제거될 예정입니다. high 및 max effort에서 Claude는 거의 항상 깊이 사고합니다. 더 낮은 수준에서는 간단한 문제에 대해 사고를 건너뛸 수 있습니다.
• Claude Opus 4.5는 수동 사고 (thinking: {type: "enabled", budget_tokens: N})를 사용하며, effort가 사고 토큰 예산과 함께 작동합니다. 작업에 맞는 effort 수준을 설정한 다음, 작업 복잡도에 따라 사고 토큰 예산을 설정하세요.

effort 매개변수는 확장된 사고의 활성화 여부와 관계없이 사용할 수 있습니다. 사고 없이 사용할 때도 텍스트 응답과 도구 호출에 대한 전체 토큰 사용을 제어합니다.

모범 사례

1. high로 시작하세요: 성능과 토큰 효율성 사이의 균형을 위해 더 낮은 effort 수준을 사용하세요.
2. 속도에 민감하거나 간단한 작업에는 low를 사용하세요: 지연 시간이 중요하거나 작업이 간단할 때, low effort는 응답 시간과 비용을 크게 줄일 수 있습니다.
3. 사용 사례를 테스트하세요: effort 수준의 영향은 작업 유형에 따라 다릅니다. 배포하기 전에 특정 사용 사례에서 성능을 평가하세요.
4. 동적 effort를 고려하세요: 작업 복잡도에 따라 effort를 조정하세요. 간단한 쿼리는 low effort가 적합할 수 있고, 에이전트 코딩과 복잡한 추론은 high effort가 유리합니다.