claude-haiku-4-5를 claude-haiku-5-5로 바꾸는 것은 이번 마이그레이션에서 가장 작은 부분입니다. Haiku 4.5에서 동작하던 요청 패턴 다섯 가지가 이제 400 오류를 반환하며, 요청이 실패하지는 않지만 결과물, 비용, 에이전트 내 모델 동작을 바꾸는 변경 사항도 여러 가지 있습니다.
Anthropic은 기존 Haiku 4.5 프롬프트를 수정하지 않아도 Haiku 5.5에서 잘 동작할 것이라고 밝혔습니다. 하지만 프롬프트를 둘러싼 요청 코드는 상황이 다릅니다. 이 글은 각 문제를 실제로 마주하게 될 형태대로 정리합니다. 즉, 무엇을 보게 되는지, 왜 발생하는지, 어떻게 고치는지를 설명하고 마지막에 체크리스트를 제공합니다. 공식 참고 자료는 Anthropic의 Haiku 5.5 마이그레이션 가이드입니다.
문제 분류: 증상으로 찾기
| 보이는 증상 | 원인 | 해결 방법 |
|---|---|---|
| thinking 예산이 포함된 요청에서 400 발생 | 수동 thinking 제거됨 | 적응형 thinking과 effort |
| temperature, top_p, top_k 사용 시 400 발생 | 샘플링 파라미터 고정됨 | 해당 파라미터 삭제 |
| messages가 assistant 턴으로 끝날 때 400 발생 | prefill 제거됨 | user 턴으로 끝내기 |
| 컴퓨터 사용 기능에서 400 발생 | 구형 컴퓨터 도구 거부됨 | 컴퓨터 툴셋으로 이전 |
| 이전 턴을 수정한 후 400 발생 | thinking이 기록에 묶임 | 기록은 추가 전용으로 유지 |
| 파서가 빈 텍스트나 잘못된 텍스트 반환 | thinking 블록이 맨 앞에 옴 | 타입으로 블록 선택 |
| 응답이 잘리거나 누락됨 | thinking이 상한에 포함됨 | max_tokens를 올리거나 effort를 낮추기 |
| 토큰 수와 비용이 약 30% 증가 | 새로운 토크나이저 | 새 모델에서 다시 계산 |
| stop reason이 refusal인 응답 | 새로운 안전 분류기 | 클라이언트에서 처리 |
앞의 다섯 가지는 명확하게 실패하지만, 나머지는 조용히 실패합니다. 그래서 원인을 찾는 데 더 많은 비용이 듭니다.
명확하게 실패하는 다섯 가지
1. 수동 thinking 예산
보이는 증상: thinking: {"type": "enabled", "budget_tokens": N}을 보내는 모든 요청에서 400 오류가 발생합니다.
이유: Haiku 4.5는 토큰 예산을 지정하는 수동 확장 thinking만 지원했습니다. Haiku 5.5는 적응형 thinking만 지원하며, 추론 깊이는 effort로 조절합니다.
해결 방법: {"type": "adaptive"}를 보내거나 thinking을 생략하고 effort 수준을 고르세요. 토큰을 아끼려고 기존 예산을 작게 잡았다면 낮은 수준을 선택하세요.
# Before: Haiku 4.5
thinking={"type": "enabled", "budget_tokens": 8000}
# After: Haiku 5.5
thinking={"type": "adaptive"},
output_config={"effort": "medium"},
2. 샘플링 파라미터
보이는 증상: 요청에 temperature, top_p, top_k가 포함되면 400 오류가 발생합니다.
이유: Haiku 5.5는 기본값만 허용합니다. temperature는 1, top_p는 0.99입니다. 다른 값을 쓰거나, top_k를 보내거나, temperature와 top_p를 함께 보내면 thinking 사용 여부와 관계없이 400이 반환됩니다. top_p를 1로 설정해도 거부됩니다.
해결 방법: 세 파라미터를 모두 삭제하세요. 가장 흔한 경우는 분류기에서 안정적인 라벨을 얻으려고 쓰는 temperature=0입니다. 이것은 구조화된 출력이나 입력이 enum인 도구로 대체하세요. 그러면 라벨 집합을 샘플링이 아니라 스키마로 강제할 수 있습니다. 또한 대신 기본 샘플링 값을 추가하는 SDK 래퍼나 게이트웨이도 확인하세요.
3. 어시스턴트 prefill
보이는 증상: thinking이 꺼져 있어도 messages의 마지막 항목이 assistant 턴이면 400 오류가 발생합니다.
이유: 현재 Claude 라인업의 다른 모델과 마찬가지로 Haiku 5.5는 prefill을 지원하지 않습니다.
해결 방법: messages를 user 턴으로 끝내고, prefill이 하던 역할을 다른 방식으로 대체하세요. 출력 형식 제어는 구조화된 출력(output_config.format)으로 바꿉니다. 미리 채운 서두는 바로 답하라는 시스템 프롬프트 지시로 바꿉니다. 중단된 응답을 이어 쓰게 하던 경우에는 user 메시지에 "이전 응답은 [텍스트]에서 끝났습니다. 거기서부터 이어서 작성하세요."와 같이 넣으세요.
4. 컴퓨터 사용
보이는 증상: Claude API나 Google Cloud에서 요청이 computer_20250124 도구를 선언하면 400 오류가 발생합니다.
이유: 이 플랫폼에서 Haiku 5.5는 더 새로운 툴셋인 computer_toolset_20260801을 통해서만 컴퓨터 사용을 지원합니다.
해결 방법: computer-use-2025-01-24 베타 헤더를 제거하고, 도구 항목을 {"type": "computer_toolset_20260801"}로 교체하세요. 그리고 에이전트 루프를 업데이트하세요. input.action이 아니라 각 tool_use 블록의 name과 toolset_name을 기준으로 분기하고, 한 턴에 있는 해당 블록을 모두 처리하고, 결과에 toolset_name을 다시 넣어 보내세요. 줌 기능은 기본적으로 켜져 있습니다. 실행 환경에서 줌을 구현하지 않는다면 툴셋 설정에서 끄세요. Amazon Bedrock을 사용한다면 버전을 고르기 전에 컴퓨터 사용 도구의 호환성 안내를 확인하세요. 같은 툴셋 계열은 브라우저 사용 기능도 제공하는데, Haiku 4.5에는 없던 기능입니다.
5. 이전 턴 수정
보이는 증상: 요청이 thinking 블록을 다시 보내는데, 그 앞에 있던 시스템 프롬프트, 도구 목록, 또는 이전 메시지가 바뀌면 400 오류가 발생합니다.
이유: Haiku 5.5의 thinking 블록은 그 앞에 보낸 모든 내용이 변경되지 않은 경우에만 유효합니다. 이 검사는 2026년 8월 31일 이후에 생성된 계정에는 기본으로 적용되며, 그보다 오래된 계정에는 요청에서 명시적으로 옵트인할 때만 적용됩니다.
해결 방법: 대화를 추가 전용(append-only)으로 유지하세요. 흔한 원인으로는 타임스탬프가 들어간 시스템 프롬프트, 플러그인이 연결될 때 늘어나는 도구 목록, 클라이언트 측 자르기, 기록에 삽입되었다가 다음 턴에 제거되는 알림 등이 있습니다. 턴마다 필요한 지시는 Haiku 5.5가 지원하는 messages 내부의 시스템 메시지로 전달하세요. 이 방식은 베타 헤더가 필요 없고, 이전 내용을 수정하지 않고 맥락을 추가할 수 있습니다.
조용한 실패
thinking 블록이 맨 앞에 옵니다. Thinking은 기본으로 켜져 있으므로, 응답이 하나 이상의 thinking 블록으로 시작할 수 있습니다. response.content[0].text를 답변으로 읽는 코드는 오류가 나거나 빈 텍스트를 반환합니다. type으로 블록을 선택하세요.
thinking 텍스트는 기본적으로 비어 있습니다. Haiku 4.5는 요약된 thinking을 반환했습니다. Haiku 5.5는 text 필드가 비어 있고 signature만 있는 thinking 블록을 반환합니다. UI에서 추론 요약을 보여줬다면 thinking: {"type": "adaptive", "display": "summarized"}로 설정하세요. 어느 쪽이든 도구 결과와 함께 thinking 블록을 변경 없이 다시 전달하세요. 빈 블록을 제거하는 직렬화기를 쓰면 이 블록이 사라집니다.
max_tokens에는 이제 thinking도 포함되어야 합니다. 짧은 답변에 맞춘 상한은 thinking에 모두 소모될 수 있으며, 그 결우 텍스트가 나오기 전에 stop_reason: "max_tokens"로 응답이 끝납니다. 상한을 올리거나 effort를 낮추세요.
같은 텍스트가 토큰을 약 30% 더 사용합니다. 새 토크나이저는 usage 필드, count_tokens 결과, 컨텍스트 예산, Haiku 4.5에 맞춰 조정한 max_tokens를 바꿉니다. 또한 Haiku 4.5 기준으로 100K 토큰이던 가격 기준선은 같은 토큰 수 기준으로 약 77K 토큰 수준으로 내려갑니다. 비용 대시보드를 믿기 전에, 모델을 claude-haiku-5-5로 설정하고 실제 프롬프트의 토큰을 다시 계산하세요.
기본 effort는 medium입니다. Haiku 4.5에는 effort 설정이 없었습니다. Haiku 5.5는 기본값이 medium이며, 단순한 라우트에는 필요 이상으로 많은 thinking일 수 있습니다. 명시적으로 설정하세요.
thinking 블록은 생성한 계정에 묶여 있습니다. 서비스가 저장된 대화를 다른 API 계정으로 재전송한다면, Haiku 5.5의 thinking 블록은 조용히 제거되고 요청은 그 추론 없이 실행됩니다. 각 대화는 생성한 계정을 통해 다시 전송하세요.
Priority Tier는 이어지지 않습니다. Haiku 5.5는 Priority Tier를 지원하지 않으므로, Haiku 4.5에서 이에 의존했다면 용량 계획을 따로 세우세요.
실제 권한을 가진 에이전트에 중요한 동작 변화
거부(refusal)는 새로 생겼고, 이를 잡아주는 장치는 없습니다. Haiku 5.5는 사이버, 생물학, 프런티어 LLM 개발, 일반 유해성의 네 가지 범주에 안전 분류기를 실행합니다. 거부는 일반적인 HTTP 200 응답으로 돌아오며, stop_reason: "refusal"과 함께 stop_details에 범주가 표시됩니다. Haiku 5.5에는 서버 측 폴백이 없습니다. 폴백 모델 목록을 보내면 400이 반환되고, 기본 폴백 모드에서는 요청이 거부된 상태로 남습니다. content를 읽기 전에 stop_reason을 확인하고, 질문을 다시 쓸지, 더 큰 모델로 넘길지, 중단할지를 직접 작성한 코드에서 결정하세요. 출시 글에 따르면 사이버 안전장치는 Sonnet 5.5보다 더 넓은 범위의 방어적 작업을 허용하지만, 침투 테스트는 차단합니다.
도구 결과 안의 사용자 텍스트는 무시될 수 있습니다. Haiku 5.5는 도구 결과를 통한 프롬프트 인젝션에 저항하도록 학습되었습니다. 하네스가 작업 도중 사용자가 입력한 메시지를 tool_result 블록 안에 넣어 전달하면, 모델은 이를 신뢰할 수 없는 입력으로 보고 무시할 수 있습니다. 턴 중간의 사용자 입력은 마지막 도구 결과 뒤의 텍스트 블록에 넣고, 하네스 알림은 별도의 시스템 메시지에 두세요.
낮은 effort에서 에이전트가 일찍 멈추거나 검사를 건너뛸 수 있습니다. 긴 코딩 에이전트 시스템 프롬프트를 low로 사용하면 Haiku 5.5가 작업을 끝내기 전에 넘겨버릴 때가 있습니다. 또한 low와 medium에서는 테스트를 실행하지 않고 코드 변경을 완료했다고 보고하기도 합니다. Anthropic의 Haiku 5.5 프롬프트 가이드에 두 경우를 위한 짧은 지침이 있습니다. 파일을 쓰거나 명령을 실행할 수 있는 에이전트라면, 검증되지 않은 "완료"가 두 문제 중 더 위험합니다.
도구 호출을 강제하면 thinking을 건너뜁니다. 강제된 tool_choice도 여전히 허용되지만, 이 경우 모델은 thinking 없이 바로 도구를 호출합니다. 부작용이 있는 도구에는 auto와 명확한 지시를 함께 쓰는 편이 좋습니다. 그러면 모델이 행동하기 전에 추론할 수 있습니다.
검색 도구에는 오늘 날짜가 필요합니다. Haiku 5.5에 검색 도구가 있다면 시스템 프롬프트나 도구 설명에 현재 날짜를 넣으세요. Anthropic의 테스트에서는 이렇게 했을 때 답변이 최신 결과에 근거했습니다.
AIHubMix를 통해 마이그레이션한 요청
JSON을 위해 temperature=0과 prefill {을 사용하던 Haiku 4.5 분류기를 AIHubMix Claude 네이티브 엔드포인트에서 Haiku 5.5용으로 다시 작성한 예시입니다:
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["AIHUBMIX_API_KEY"],
base_url="https://aihubmix.com",
)
r = client.messages.create(
model="claude-haiku-5-5",
max_tokens=2000, # room for thinking plus the JSON
output_config={
"effort": "low", # thinking is on by default; keep it light
"format": { # replaces the prefill and temperature=0
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"label": {"type": "string", "enum": ["billing", "bug", "other"]}
},
"required": ["label"],
"additionalProperties": False,
},
},
},
messages=[{"role": "user", "content": "Ticket: 'I was charged twice for October.'"}],
)
if r.stop_reason == "refusal":
raise RuntimeError(f"declined: {r.stop_details}")
text = next(b.text for b in r.content if b.type == "text")
print(text)
게이트웨이가 output_config 필드와 최신 베타 헤더를 변경 없이 전달하는지는 첫 테스트 실행에서 확인해 볼 만합니다. 마이그레이션된 경로가 평가를 통과하면, AIHubMix 모델 목록에서 Haiku에서 계속 실패하는 작업 유형에 대해 같은 코드가 Sonnet 5.5를 가리키도록 쉽게 바꿀 수 있습니다.
마이그레이션 체크리스트
- 모델 ID를 날짜 접미사 없이 claude-haiku-5-5로 바꾸세요.
- 모든 thinking 예산을 적응형 thinking과 명시적인 effort 수준으로 바꾸세요.
- temperature, top_p, top_k를 제거하고, 래퍼가 추가한 기본값도 함께 제거하세요.
- 구조화된 출력, 시스템 지시문, 또는 사용자 턴 이어쓰기로 어시스턴트 프리필을 대체하세요.
- 컴퓨터 사용 기능은 computer 툴셋으로 옮기고 에이전트 루프를 업데이트하세요.
- thinking 블록을 다시 전달할 경우, 대화 기록을 추가 전용(append-only)으로 관리하세요.
- 응답 콘텐츠는 블록 유형별로 읽고, 다시 전달할 때 빈 thinking 블록은 그대로 유지하세요.
- 짧은 답변이 필요한 경로에서는 max_tokens를 늘리거나 effort를 낮추세요.
- 콘텐츠를 읽기 전에 refusal stop reason을 처리하고, 서버 측 폴백은 설정하지 마세요.
- 새 모델에서 프롬프트 토큰을 다시 계산하고 비용 대시보드의 기준선을 재설정하세요.
- 이제 100K 토큰을 넘는 프롬프트를 확인하고, 줄이거나 나누세요.
- 사용자가 추론 요약을 보고 있었다면 display를 summarized로 설정하세요.
- 턴 도중 사용자 입력은 도구 결과 바깥으로 전달하세요.
- 검색 기능을 사용하는 에이전트에는 오늘 날짜를 알려주세요.
- 트래픽을 옮기기 전에 속도 제한(rate limit)과 Priority Tier 필요 여부를 다시 확인하세요.
자주 묻는 질문
기존 Haiku 4.5 프롬프트가 Haiku 5.5에서도 작동하나요?
Anthropic에 따르면 기존 프롬프트는 별도 수정 없이도 대体로 잘 작동해야 합니다. 문제는 프롬프트 주변의 요청 파라미터입니다. thinking 예산, 샘플링 설정, 프리필, 그리고 기존 computer use 도구는 모두 오류를 반환합니다.
temperature 0을 제거했더니 분류기가 왜 실패하나요?
실패하지는 않아야 하지만, 레이블이 더 많이 달라질 수 있습니다. 허용된 레이블을 스키마로 강제하려면 구조화된 출력이나 enum 필드를 가진 도구를 사용하세요. 이는 temperature 0보다 항상 더 신뢰할 수 있습니다.
thinking을 여전히 끌 수 있나요?
네, low, medium, high effort에서는 가능합니다. xhigh와 max에서는 thinking을 끄면 오류가 반환됩니다. Anthropic은 대신 더 낮은 effort 수준을 권장하는데, 모델이 단순한 요청에서는 스스로 thinking을 건너뛸 수 있기 때문입니다.
Haiku 5.5가 거부(refuse)하면 코드는 어떻게 해야 하나요?
콘텐츠를 읽기 전에 stop reason을 확인하세요. Haiku 5.5에는 서버 측 폴백이 없으므로, 질문을 바꿔 다시 보낼지, 더 큰 모델로 요청을 보낼지, 아니면 사용자에게 오류를 반환할지는 여러분의 코드가 결정해야 합니다.
마이그레이션 후 토큰 사용량이 왜 늘었나요?
두 가지 이유가 있습니다. 새 토크나이저는 같은 텍스트에 대해 약 30% 더 많은 토큰을 셉니다. 또한 thinking이 기본적으로 켜져 있어 출력 토큰이 추가됩니다. effort를 낮추고 새 모델에서 프롬프트를 다시 계산하세요.
프롬프트 캐싱을 위해 무언가 바꿔야 하나요?
대부분은 필요 없으며, 오히려 더 쉬워집니다. Anthropic 마이그레이션 가이드에 따르면 캐시 가능한 최소 프롬프트 길이는 4,096 토큰에서 512 토큰으로 줄었고, 이전 턴의 thinking 블록은 기본적으로 캐시된 프리픽스에 남습니다. 이전 턴을 편집하는 것은 피하세요. 이제는 캐시뿐 아니라 thinking 블록도 무효화되기 때문입니다.
대화를 Haiku 5.5에서 더 큰 모델로 옮길 수 있나요?
네, 대화 내용 자체는 그대로 넘어갑니다. 하지만 Haiku 5.5의 이전 thinking 블록도 함께 넘어갈지는 대상 모델에 따라 다르므로, 이를 신뢰하기 전에 Anthropic의 preserved thinking 문서를 확인하세요.
계속 읽기: Claude Haiku 5.5 시리즈
- 마이그레이션을 계획하기 전에 새 모델이 품질 기준을 충족하는지 아는 것이 도움이 됩니다. Haiku 4.5, GPT-6 Luna, Sonnet 5.5와의 벤치마크를 보려면 Claude Haiku 5.5 vs Haiku 4.5: What Ten Cents Now Buys를 읽어 보세요.
- 체크리스트의 2단계에서는 effort 수준을 고르라고 합니다. 각 수준이 토큰 측면에서 얼마나 비용이 드는지와 어디서 시작하면 좋은지는 Claude Haiku 5.5 Effort Levels: Medium Is the Default, Low Is Often Enough를 읽어 보세요.
- 토크나이저 변경은 가격선뿐 아니라 대시보드도 바꿉니다. 이것이 실제 청구서에 어떤 영향을 주는지 보려면 Claude Haiku 5.5 Pricing: The 100K Line Behind the 90% Cut를 읽어 보세요.
출처
- Claude Haiku 5.5 migration guide (Claude Platform Docs)
- Prompting Claude Haiku 5.5 (Claude Platform Docs)
- Introducing Claude Haiku 5.5 (Anthropic)
- Claude Haiku 5.5 on AIHubMix
- Claude Haiku 5.5 Is Out at $0.10 per Million Tokens. Read the 100K Rule Before You Migrate (Roo's Newsletter)



