작성자 주: claude-haiku-5-5는 기본적으로 사고(thinking)를 수행하는데, 끄려고 하면 오류가 난다고요? 대부분 effort가 high보다 높기 때문이에요. 이 글에서는 규칙과 3단계 해결 방법, 그리고 파라미터 경계를 명확히 설명해요.
claude-haiku-5-5가 사고를 덜 하고 출력 할당량을 본문에 쓰게 만드는 것은 배치 처리나 구조화 작업을 돌릴 때 아주 흔한 요구사항이에요. 이미 thinking을 disabled로 설정했는데 API가 오류를 반환했다면? 분명히 사고를 끄려던 건데 왜 막힌 걸까요? 이 글에서는 effort와 disabled의 조합 규칙을 소개하고, claude-haiku-5-5에서 사고를 끄는 올바른 방법을 빠르게 익힐 수 있게 도와드려요.
이건 신비한 문제도, 모델이 이상해진 것도 아니에요. 문서에 아주 명확히 적혀 있어요: claude-haiku-5-5는 thinking을 전달하지 않으면 적응형 사고(adaptive thinking)가 기본으로 켜지고, 사고를 끄려면 thinking의 type: disabled를 쓰면 되는데, 이 표기는 effort가 high보다 높지 않을 때만 허용돼요. 이 글의 파라미터는 2026-11-08(UTC+8) 기준 Anthropic 공식 문서를 따르며, 확인 날짜는 2026-11-13이에요.
핵심 가치: 이 글을 읽고 나면 오류의 실제 원인, 3단계 해결 방법, 그리고 max_tokens와 사고 토큰의 관계를 확실히 이해하게 되어, 이후 어떤 환경에서 호출하든 이 규칙에 발목 잡히지 않을 거예요.
claude-haiku-5-5 핵심 요점
먼저 결론부터 정리할게요. 시간이 없는 분은 이 섹션만 보셔도 충분해요:
| 요점 | 문서 기재 | 영향 |
|---|---|---|
| 기본 사고 활성화 | thinking을 전달하지 않으면 적응형 사고가 기본 활성화 |
할당량을 아끼려면 명시적으로 꺼야 함 |
| 끄는 방법 | thinking을 type: disabled로 설정 |
유일한 비활성화 방법 |
| effort 조건 | effort가 high 이하일 때만 disabled 허용 |
xhigh 또는 max와 함께 쓰면 오류 발생 |
| effort 기본값 | 기본값 medium, claude-opus-5-5와 동일 |
직접 올리지만 않으면 문제 없음 |
| 할당량 경계 | 최대 출력 128000, 사고 토큰은 max_tokens에 포함 |
사고가 본문 공간을 잡아먹음 |
claude-haiku-5-5 주요 내용 자세히 보기
첫째, 기본적으로 사고해요. claude-haiku-5-5는 기본적으로 사고 기능을 켜고 실행되는 모델이에요. 요청에 thinking 필드가 없으면 적응형 사고로 동작해요. 문서가 적응형 모드의 구체적인 판단 세부 사항을 자세히 설명하지는 않지만, 기본 상태에서 사고가 켜져 있다는 점은 확실해요.
짧은 Q&A, 대량 라벨링, 형식 변환처럼 깊은 추론이 크게 필요 없는 작업이라면 사고 토큰은 순전히 비용이에요. 문서에는 또한 사고 토큰이 max_tokens에 포함되며 최대 출력이 128000이라고 되어 있어요. 사고가 많을수록 본문에 남는 할당량은 줄어들어요. 바로 여기서 “사고를 끄고 할당량을 본문에 쓰고 싶다”는 요구가 나온 거예요.
둘째, 끄는 데 조건이 있어요. 사고를 끄는 유일한 방법은 thinking을 type: disabled로 설정하는 거예요. 하지만 문서에는 이 설정이 effort가 high 이하일 때만 허용된다고 나와 있어요. effort가 medium 또는 high이면 문제없지만, xhigh나 max로 설정하면 요청이 오류를 내요. 공식 문서가 제시하는 해결 방법도 아주 명확해요. effort를 high 이하로 낮추면 돼요. APIYI apiyi.com을 통해 claude-haiku-5-5를 호출한다면, 이런 오류를 점검할 때도 먼저 이 두 파라미터 조합부터 확인하세요.
셋째, 오히려 기본값이 안전해요. claude-haiku-5-5의 effort 기본값은 medium으로 claude-opus-5-5와 같고, 나머지 대부분 모델의 기본값은 high예요. 문제가 생기기 쉬운 흐름은 보통 이래요. 다른 모델에서 코드를 옮기면서 습관적으로 effort를 xhigh나 max로 올려 품질을 높이려 하고, 동시에 비용을 조절하려고 disabled를 덧붙이면 두 의도가 충돌해 오류가 나요.
반대로 effort를 위로 올리지만 않으면 기본 medium이 “high 이하” 조건을 자연스럽게 만족해서 disabled가 정상 동작해요. 여러 모델을 오가며 비교해야 할 때 APIYI apiyi.com에서 하나의 API 키로 여러 모델을 호출하면 접속 설정을 반복해서 바꾸지 않아도 돼요.
위 그림이 바로 표준 점검 경로예요. 가장 흔한 경우는 가운데 판단 상자에서 막히는데, 바로 effort가 범위를 벗어난 경우예요. 수정한 뒤에는 먼저 작은 할당량으로 APIYI apiyi.com에서 한 번 실행해 검증하고, 반환값이 정상인지 확인한 다음 프로덕션 트래픽에 넣는 걸 권장해요.
claude-haiku-5-5 빠른 시작: 세 단계로 오류 해결
긴 문서를 뒤질 필요 없이, 아래 세 단계만 따르면 이런 오류는 대부분 해결할 수 있어요:
- 모델 ID 확인: 요청의
model은claude-haiku-5-5여야 해요. 먼저 모델명 오타로 생긴 문제인지부터 확인해 보세요. effort낮추기:high또는 그보다 낮게 설정하세요.medium이 기본값이라 아예 전달하지 않아도 되고, 핵심은xhigh나max를 전달하지 않는 거예요.- 그다음 사고 기능 끄기:
thinking을{"type": "disabled"}로 설정하세요. 이때effort가high이하라면 요청이 정상적으로 허용돼요.
claude-haiku-5-5 요청 파라미터 빠른 확인
| 파라미터 | 권장 값 | 설명 |
|---|---|---|
model |
claude-haiku-5-5 |
이 글에서 다루는 모델이에요. 다른 버전으로 쓰지 않도록 주의하세요 |
thinking |
{"type": "disabled"} |
사고 기능을 끄는 유일한 설정이에요 |
effort |
medium(기본값) 또는 high |
high 이하여야 해요. 그렇지 않으면 disabled와 충돌해요 |
effort 비허용 값 |
xhigh, max |
disabled와 조합하면 오류가 발생해요 |
max_tokens |
최대 128000 | 사고 토큰도 이 값에 포함돼요. 사고를 끄면 이 값을 전부 본문에 쓸 수 있어요 |
연동 정보도 복잡하지 않아요. APIYI를 예로 들면:
- 연동 주소:
https://api.apiyi.com/v1 - 인증 방식: API 키 하나면 충분해요
- 인터페이스 스타일: OpenAI 호환 인터페이스
- 과금 방식: 사용량 기반 과금, 합리적인 가격, 신규 사용자에게 무료 테스트 크레딧이 있어요
- 지원 범위: OpenAI, Claude, Gemini 등 주요 모델
🚀 빠르게 시작하기: 이번 검증은 APIYI apiyi.com에서 진행하는 걸 추천해요. 가입한 뒤 무료 테스트 크레딧으로 수정한 요청을 한 번 실행해 보고,
disabled가 정상적으로 적용되고 오류가 사라지는지 확인한 다음 실제 업무에 연결하세요. 몇 분이면 마무리할 수 있어요.
claude-haiku-5-5의 effort 호환성
아래 표는 글 전체에서 가장 기억할 만한 내용이에요. 팀 노트에 바로 저장해 두길 권해요.
effort 값 |
disabled와 조합 |
결과 |
|---|---|---|
medium(기본값) |
호환 | 정상적으로 사고 비활성화 |
high |
호환 | 정상적으로 사고 비활성화 |
xhigh |
충돌 | 요청 오류 |
max |
충돌 | 요청 오류 |
이 표를 옆에 두고 자신의 요청을 다시 들여다보면 방향이 명확해져요. 오류가 disabled를 함께 전달한 요청에서 나타났다면, 첫 반응은 effort가 high라는 선을 넘었는지 확인하는 거예요. 문서에 적힌 수정 방법은 딱 한 문장이에요. effort를 high 이하로 낮추라는 것, 그 외의 우회 방법은 없어요.
claude-haiku-5-5와 다른 모델의 기본 effort 대조
| 모델 | 기본 effort |
사고 끄기와의 관계 |
|---|---|---|
| claude-haiku-5-5 | medium |
기본값이 “high 이하”를 만족하므로 disabled가 바로 적용됨 |
| claude-opus-5-5 | medium |
기본값이 haiku와 같으며, 이 모델의 사고 스위치 규칙은 이 글에서 다루지 않음 |
| 나머지 대부분 모델 | high |
기본값 역시 기준 안에 있으므로, 직접 올려야만 경계를 넘음 |
이 표는 “왜 하필 내 요청만 오류가 날까”를 설명해 줘요. 모델마다 기본 effort가 다르기 때문에 코드를 옮길 때 예전 파라미터 습관을 그대로 가져오면 effort를 슬쩍 xhigh나 max로 명시해 두기 쉬워요. 이전 전에 기본값을 한 번 대조해 보는 것이 가장 저렴한 예방 조치예요.
claude-haiku-5-5 오류 진단 및 자가 점검 체크리스트
| 증상 | 가장 가능성 높은 원인 | 처리 방법 |
|---|---|---|
disabled를 전달했는데도 오류가 남 |
effort가 xhigh 또는 max |
effort를 high 이하로 낮추기 |
effort 값을 모르겠음 |
전달하지 않으면 기본값이 medium |
기본값이 기준을 충족하므로 별도 처리 불필요 |
| 본문이 짧아지거나 잘림 | 사고 토큰이 max_tokens에 포함됨 |
사고 기능을 끄거나, 128000 상한 내에서 max_tokens를 늘리기 |
| 더 깊은 추론 품질을 원함 | 사고 기능을 끄면 사고 과정이 사라짐 | disabled를 제거하고 기본 적응형 사고로 되돌리기 |
수정한 뒤에는 요청을 보내기 전에 이 자가 점검 체크리스트를 한 번 훑어보세요:
model이 정확히claude-haiku-5-5로 작성됨effort가 생략되었거나, 명시적으로medium,high로 설정됨thinking이{"type": "disabled"}로 설정됨max_tokens가 128000을 초과하지 않음
네 가지 조건을 모두 충족하면 이런 유형의 오류는 다시 찾아오지 않아요. 최종 파라미터 조합을 요청 템플릿으로 고정해두면 나중에 실수로 바꾸는 일도 막을 수 있어요.
claude-haiku-5-5 자주 묻는 질문(FAQ)
Q1: claude-haiku-5-5는 기본적으로 사고하나요?
네. 문서에 따르면 `thinking`을 전달하지 않으면 claude-haiku-5-5는 적응형 사고(adaptive thinking)로 동작하며, 기본적으로 켜져 있어요. 출력 예산을 전부 본문에 쓰고 싶다면 `disabled`를 명시적으로 전달해 꺼야 해요.
Q2: `disabled`를 전달했는데도 왜 오류가 나나요?
가장 흔한 원인은 `effort`가 `high`보다 높은 경우예요. 문서에는 `disabled`가 `effort`가 `high` 이하일 때만 허용된다고 나와 있어요. `xhigh`나 `max`와 함께 쓰면 오류가 나고, 해결 방법은 `effort`를 `high` 이하로 낮추는 거예요.
Q3: `effort`를 전달하지 않으면 어떻게 되나요?
기본값은 `medium`이에요. claude-haiku-5-5와 claude-opus-5-5의 기본값은 모두 `medium`으로 같고, 나머지 대부분 모델은 기본값이 `high`예요. 기본값 자체가 “high 이하” 조건을 만족하므로 `disabled`와 바로 조합할 수 있어요.
Q4: 사고를 끄면 출력 길이에 어떤 변화가 있나요?
문서에 따르면 사고 토큰은 `max_tokens`에 포함되며 최대 출력은 128000이에요. 사고를 끄면 같은 `max_tokens` 예산을 전부 본문에 쓸 수 있어 잘릴 위험도 줄어들어요.
Q5: 일시적으로 더 깊은 추론이 필요하면 어떻게 하나요?
`disabled`를 빼면 claude-haiku-5-5가 기본 적응형 사고로 돌아가요. 동시에 `effort`를 올리려면 “`xhigh` 또는 `max` + `disabled`” 조합에 머물지 않도록 주의해야 해요.
Q6: 수정 사항이 제대로 적용됐는지 빠르게 확인하려면 어떻게 하나요?
APIYI apiyi.com에서 가입한 뒤 무료 테스트 크레딧을 받고, 접속 주소는 `https://api.apiyi.com/v1`을 사용해 수정한 파라미터로 한 번 실행해 보세요. 요청이 더 이상 오류를 내지 않고 본문이 정상 반환되면 `disabled`가 제대로 적용된 거예요. 플랫폼은 사용량 기반 과금이라 소액으로 검증하는 비용이 매우 낮아요.
Q7: 오류가 반드시 `effort` 때문인가요?
반드시 그렇다고 할 수는 없지만, 문서에 명확히 기록된 유형 중 하나예요. 먼저 `model`이 `claude-haiku-5-5`로 정확히 쓰였는지 확인하고, 그다음 `thinking`과 `effort` 조합이 범위를 벗어나지 않았는지 점검한 뒤, 둘 다 배제하고 나서 다른 원인을 살펴보세요. APIYI를 통해 호출할 때 오류가 나도 마찬가지로 이 파라미터 조합부터 확인하면 돼요.
Q8: 이 파라미터 기준은 어떤 버전을 따르나요?
이 글은 2026-11-08(UTC+8) 기준 Anthropic 공식 문서를 따르며, 확인 날짜는 2026-11-13이에요. 이후 공식 문서에서 `effort`와 `disabled` 규칙을 조정한다면 최신 문서를 기준으로 하세요.
요약
claude-haiku-5-5에서 사고(thinking)를 끄는 요령은 결국 네 가지로 정리돼요.
- 기본값이 사고:
thinking을 전달하지 않으면 적응형 사고가 적용되고 기본으로 켜져 있어요. 할당량을 아끼려면 반드시 명시적으로 꺼야 해요. - 끄는 데도 조건이 있어요:
thinking을disabled로 설정할 때effort는high를 넘지 않아야 하고,xhigh나max를 함께 쓰면 오류가 나요. - 기본값만으로도 안전해요:
effort의 기본값은medium으로 claude-opus-5-5와 같아요. 굳이 올리지 않으면 충돌이 생기지 않아요. - 할당량 경계: 최대 출력은 128000이고, 사고 토큰도
max_tokens에 포함돼요. 사고를 끄면 할당량 전부를 본문에 쓸 수 있어요.
다음에 “사고를 끄려는데 오류가 난다”는 상황을 만나면 먼저 effort가 high라는 선을 넘었는지 확인해 보세요. 파라미터 조합만 정리하면 문제는 거의 해결돼요. APIYI apiyi.com에서 무료 테스트 할당량으로 빠르게 검증해 보시길 권해요. API 키 하나면 claude-haiku-5-5를 포함한 여러 주류 모델을 호출할 수 있고, OpenAI 호환 인터페이스 덕분에 모델 전환도 한결 편해요.
📚 참고 자료
- APIYI 문서: Claude effort 및 thinking 파라미터 설명
- 링크:
docs.apiyi.com/api-capabilities/claude-effort-thinking.md -
설명: effort 값, disabled 허용 조건과 오류 메시지 기준
-
APIYI 문서: Claude 사고 가이드 업데이트 (2026-11)
- 링크:
docs.apiyi.com/live/2026-11/claude-thinking-guide-refresh.md -
설명: 사고 관련 가이드의 업데이트 기록과 배경
-
Anthropic 공식 문서
- 링크:
docs.anthropic.com - 설명: 이 글의 파라미터는 2026-11-08(UTC+8) 버전 공식 기준을 따릅니다
작성자: APIYI 기술팀
기술 교류: APIYI 웹사이트 홈페이지에서 문의해 주세요. 더 많은 자료는 문서 센터에서 확인할 수 있어요
