Claude Haiku 5.5 마이그레이션 가이드

이 가이드는 Claude Haiku 4.5를 호출하는 코드를 Claude Haiku 5.5로 옮기는 방법을 다룹니다. 대신 Sonnet 또는 Opus 모델로 업그레이드하려면 모델 버전 간 업그레이드를 참조하세요. Claude Haiku 4.5를 얼마나 오래 사용할 수 있는지는 모델 지원 중단을 참조하세요.

마이그레이션 체크리스트

각 항목은 Claude Haiku 4.5를 호출하는 코드에서 수행해야 할 하나의 변경 사항입니다.

1. 모델 ID를 사용 중인 플랫폼의 Claude Haiku 5.5 ID로 교체하세요. Claude Haiku 5.5 모델 ID 사용을 참조하세요.
2. 동일한 텍스트가 더 많은 토큰으로 계산되므로, 프롬프트의 토큰 수를 다시 계산하고 max_tokens 한도와 비용 추정치를 재검토하세요. 토큰 다시 계산하기를 참조하세요.
3. 요청에서 thinking: {"type": "enabled", "budget_tokens": N}을 보내는 경우, thinking을 {"type": "adaptive"}로 변경하세요. 사고 구성하기를 참조하세요.
4. 코드가 첫 번째 콘텐츠 블록을 답변으로 읽는 경우, 대신 type으로 블록을 선택하세요. 사고 구성하기를 참조하세요.
5. 요청에서 temperature, top_p, top_k를 제거하세요. 샘플링 매개변수 제거하기를 참조하세요.
6. 요청이 모델이 이어서 작성하도록 어시스턴트 턴으로 messages를 끝내는 경우, 대신 사용자 턴으로 끝내세요. 어시스턴트 프리필 대체하기를 참조하세요.
7. Claude API 또는 Google Cloud에서 컴퓨터 사용 기능을 사용하는 경우, computer_20250124에서 computer_toolset_20260801 도구 세트로 이동하세요. 컴퓨터 사용을 도구 세트로 이동하기를 참조하세요.
8. 저장된 대화를 다른 계정을 통해 재생하는 경우, 각 대화를 해당 대화를 생성한 계정을 통해 재생하세요. 사고 블록을 생성한 계정을 통해 재생하기를 참조하세요.
9. 코드가 대화 중 요청 사이에 system, tools 또는 이전 messages를 변경하고 사고 블록을 다시 보내는 경우, 대화를 추가 전용(append-only)으로 유지하세요. 이전 턴을 변경하지 않고 유지하기를 참조하세요.
10. stop_reason: "refusal"을 처리하세요. Claude Haiku 5.5는 요청을 거부할 수 있는 안전 분류기를 실행하며, 서버 측 폴백 기능이 없습니다. 안전장치 거부를 참조하세요.

조직에 Claude Haiku 4.5에 대한 Priority Tier 약정이 있는 경우, 용량을 별도로 계획하세요. Priority Tier는 Claude Haiku 5.5에서 지원되지 않습니다.

Claude Haiku 5.5 모델 ID 사용

Claude Haiku 4.5 모델 ID를 사용 중인 플랫폼의 Claude Haiku 5.5 ID로 교체하세요.

claude-haiku-5-5는 날짜 접미사가 없고 별도의 별칭도 없는 고정 모델 ID입니다.

토큰 다시 계산하기

Claude Haiku 5.5는 Claude 4.7 및 이후 모델과 동일한 새로운 "tokenizer"(토크나이저)를 사용합니다. 이 토크나이저를 사용하는 모든 모델과 마찬가지로, 동일한 입력 텍스트가 Claude Haiku 4.5보다 Claude Haiku 5.5에서 약 30% 더 많은 토큰을 생성합니다. 정확한 증가량은 콘텐츠에 따라 다릅니다. 요청, 응답 및 스트리밍 이벤트의 형태는 동일하게 유지됩니다. 달라지는 것은 토큰 단위로 측정하거나 예산을 책정하는 모든 항목입니다:

• 동일한 텍스트에 대해 usage 필드와 토큰 카운팅 결과가 더 높게 나옵니다.
• 주어진 토큰 수에 담기는 텍스트가 더 적어집니다.
• Claude Haiku 4.5에 맞춰 조정된 max_tokens 한도는 동등한 출력을 잘라낼 수 있습니다.
• Claude Haiku 4.5의 토큰 수로 산출한 비용 추정치는 Claude Haiku 5.5의 토큰 수와 가격으로 다시 계산해야 합니다.

Claude Haiku 4.5에서 측정한 토큰 수를 재사용하지 말고, model을 claude-haiku-5-5로 설정하여 프롬프트의 토큰 수를 계산하세요.

사고 구성하기

Claude Haiku 5.5는 Claude Haiku 4.5와 다른 방식으로 사고를 구성합니다. {"type": "enabled", "budget_tokens": N}의 thinking 값은 400 오류를 반환하므로, 이 값을 보내는 요청에는 새로운 thinking 값이 필요합니다.

변경 전에는 Claude Haiku 4.5에 대한 요청이 토큰 예산과 함께 thinking을 enabled로 설정했습니다:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

변경 후에는 Claude Haiku 5.5에 대한 동일한 요청이 "adaptive thinking"(적응형 사고)을 사용합니다. thinking 값이 변경되고, output_config.effort가 모델이 얼마나 사고할지를 설정합니다:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

적응형 사고는 기본적으로 켜져 있으므로, 요청에서 thinking을 설정하지 않더라도 응답이 하나 이상의 thinking 블록으로 시작할 수 있습니다. thinking을 설정하지 않거나 {"type": "adaptive"}로 설정하고, effort를 조절 수단으로 사용하세요. Claude Haiku 4.5가 사고 없이 실행되었거나 토큰을 절약하기 위해 작은 예산으로 실행되었던 경우에는 더 낮은 effort 수준을 선택하세요. 더 낮은 수준에서는 모델이 사고를 덜 하며, 더 간단한 요청에서는 사고를 완전히 건너뛸 수 있습니다. 프롬프트 작성 안내는 effort를 사용하여 사고 제어하기를 참조하세요. 콘텐츠 블록은 위치가 아닌 type 필드로 선택하고, thinking 블록은 도구 결과와 함께 수정하지 않은 상태로 다시 전달하세요.

사고 토큰은 max_tokens에 포함되므로, 작은 max_tokens를 사용하는 요청은 thinking 블록 이후 텍스트가 나오기 전에 stop_reason: "max_tokens"로 중단될 수 있습니다. Claude Haiku 4.5에 작은 max_tokens를 설정했다면, 사고를 위한 여유를 두도록 값을 높이거나 더 낮은 effort 수준을 선택하세요.

기본적으로 Claude Haiku 5.5는 각 thinking 블록을 빈 thinking 필드와 signature만 포함하여 반환하는 반면, Claude Haiku 4.5는 요약된 사고를 반환했습니다. 요약된 사고를 받으려면 thinking: {"type": "adaptive", "display": "summarized"}를 설정하세요.

Claude Haiku 5.5는 강제 tool_choice(any 또는 이름이 지정된 도구)를 허용하지만, 응답은 도구 호출로 시작하며 thinking 블록이 없습니다. 모델이 도구를 호출하기 전에 사고하도록 하려면 tool_choice: {"type": "auto"}를 사용하고 프롬프트에서 언제 도구를 사용할지 명시하세요.

샘플링 매개변수 제거하기

Claude Haiku 4.5는 temperature, top_p, top_k를 허용합니다. Claude Haiku 5.5에서는 세 가지 모두를 생략하고 대신 프롬프트를 사용하여 모델의 동작을 안내하세요. 요청에 temperature가 포함된 경우 값은 1이어야 합니다. top_p가 포함된 경우 기본값인 0.99여야 합니다. 그 외의 temperature 또는 top_p 값은 1인 top_p를 포함하여 400 오류를 반환합니다. 모든 top_k 값도 마찬가지이며, temperature와 top_p를 모두 포함하는 요청도 마찬가지입니다.

어시스턴트 프리필 대체하기

"Prefill"(프리필)은 모델이 이어서 작성하는 messages의 마지막 어시스턴트 턴입니다. Claude Haiku 4.5는 사고가 꺼져 있을 때 이를 허용합니다. Claude Haiku 5.5는 사고가 꺼져 있더라도 400 오류와 함께 이를 거부합니다. messages를 사용자 턴으로 끝내고, 각 프리필을 그 용도에 따라 대체하세요:

• 출력 형식: 구조화된 출력을 사용하거나, 분류에는 enum 필드가 있는 도구를 사용하세요. 구조화된 출력을 지원하지 않는 Claude in Amazon Bedrock에서는 도구를 사용하세요.
• 서두: 시스템 프롬프트에서 직접적인 답변을 요청하세요.
• 이어쓰기: 이를 사용자 메시지로 옮기세요. 예: "이전 응답이 중단되었으며 [previous_response]로 끝났습니다. 중단된 부분부터 계속하세요."
• 컨텍스트 알림: 사용자 턴에 넣으세요.

컴퓨터 사용을 도구 세트로 이동하기

Claude Haiku 4.5는 computer-use-2025-01-24 베타 헤더와 함께 computer_20250124 도구를 통해 컴퓨터 사용을 지원합니다. Claude API와 Google Cloud에서 Claude Haiku 5.5는 computer_toolset_20260801 도구 세트를 통해서만 컴퓨터 사용을 지원하며, computer_20250124를 선언하는 요청은 400 오류를 반환합니다.

통합을 이전하려면 computer-use-2025-01-24 베타 헤더를 제거하고 tools 항목을 {"type": "computer_toolset_20260801"}로 교체하세요. 그런 다음 computer_20251124에서 마이그레이션에 설명된 나머지 요청 및 에이전트 루프 변경 사항을 적용하세요. input.action이 아닌 각 멤버 tool_use 블록의 name과 toolset_name을 기준으로 분기하고, 한 턴의 모든 해당 블록을 처리하며, 결과에 toolset_name을 그대로 반영하세요. 도구 세트에서는 확대/축소(zoom)가 기본적으로 켜져 있습니다. 환경에서 이를 구현하지 않는 경우 "configs": {"zoom": {"enabled": false}}를 추가하세요. fine-grained-tool-streaming-2025-05-14 베타 헤더를 보내는 경우 제거하세요. 도구 세트 항목과 함께 사용하면 400 오류를 반환합니다. 다른 플랫폼의 경우 컴퓨터 사용 도구의 호환성 섹션을 참조하세요.

Claude API와 Google Cloud에서 Claude Haiku 5.5는 웹페이지 내 작업을 위한 브라우저 사용 도구(browser_toolset_20260801)도 지원합니다. Claude Haiku 4.5는 이를 지원하지 않습니다.

사고 블록을 생성한 계정을 통해 재생하기

Claude Haiku 5.5의 사고 블록은 해당 블록을 생성한 계정 또는 그 계정에 연결된 계정에서만 작동합니다. 다른 계정이 이러한 블록 중 하나를 보내면, API는 모델이 보기 전에 해당 블록을 삭제하고 요청은 그 추론 없이 성공합니다. 이는 대화를 저장하고 다른 계정을 통해 재생하는 코드에 영향을 미칩니다. 예를 들어 하나의 대화 저장소에서 여러 고객에게 서비스를 제공하는 서비스가 이에 해당합니다. 각 대화를 해당 대화를 생성한 계정을 통해 재생하세요. 사고 블록은 생성한 계정에 귀속됩니다를 참조하세요.

이전 턴을 변경하지 않고 유지하기

Claude Haiku 5.5 사고 블록은 그 이전에 전송된 모든 내용이 변경되지 않은 동안에만 유효합니다. system, tools 또는 이전 messages를 변경한 후 사고 블록을 다시 보내는 요청은 400 오류를 반환합니다. Claude Haiku 4.5는 이 검사를 실행하지 않습니다. 대화를 추가 전용으로 유지하세요. 2026년 8월 31일 00:00 UTC 이전에 생성된 계정에서는 thinking.block_binding.prefix_mismatch_behavior를 설정한 요청에서만 오류가 발생합니다. 오류를 유발하는 변경 사항과 대신 수행해야 할 작업은 변경이 필요한 대상을 참조하세요.