Rihpig

Posted on Sep 2 Originally published at apidog.com

Fable 5 또는 Opus 5에서 Claude Fable 5.1로 마이그레이션: 모든 비호환 변경점

Claude Fable 5.1 마이그레이션 체크리스트: Fable 5와 Opus 5에서 전환하기

Claude Fable 5.1로의 전환은 대부분 모델 ID를 교체하는 작업입니다. API 표면, 제한, 토큰당 가격 책정, 토크나이저, 상시 적응형 사고, 거부 처리는 Fable 5와 동일합니다. 다만 Fable 5에는 없던 오류를 유발하는 세 가지 변경 사항이 있으며, 그중 기록 편집 확인은 1년 동안 정상 작동하던 에이전트 하네스를 조용히 저하시킬 수 있습니다. Opus 5에서 전환한다면 네 가지 항목이 추가됩니다.

오늘 Apidog 사용해 보기

이 가이드는 Anthropic의 마이그레이션 가이드와 Claude Fable 5.1의 새로운 기능을 바탕으로, 각 변경 사항의 정확한 오류 메시지와 해결 방법을 발생 순서대로 정리한 체크리스트입니다. 코드 조각은 Apidog에 붙여넣어 프로덕션 배포 전에 실제 엔드포인트로 실행할 수 있습니다. 모델 개요는 Claude Fable 5.1이란 무엇인가에서 확인할 수 있습니다.

0단계: 마이그레이션 필요성 확인

Anthropic은 먼저 Opus 5를 사용하고, 높은 노력 수준의 평가에서도 부족하거나 까다로운 추론 및 장기 에이전트 작업이 필요한 경우 Fable 5.1을 사용하도록 안내합니다.

Opus 5가 평가를 통과한다면 Fable 5.1로의 전환은 측정 가능한 이득 없이 토큰당 비용을 두 배로 만들 수 있습니다. Fable 5에서 전환하는 경우에는 가격이 동일하고 캐시 읽기 비용이 더 저렴하며 주장된 성능 수치도 더 좋습니다. 따라서 핵심은 하네스 수정에 필요한 작업량입니다. 다음 비교 자료를 참고하세요.

사전 확인 사항

데이터 보존: Fable 5.1은 30일 보존이 필요합니다. Anthropic의 명시적 승인이 없다면 무데이터 보존(ZDR) 환경에서 사용할 수 없습니다. ZDR 조직은 별도의 힌트 없이 모든 요청에서 400 invalid_request_error를 받습니다. Opus 5는 ZDR을 지원합니다.
우선순위 계층: Fable 5.1에서는 지원하지 않지만 Fable 5에서는 지원합니다.
요청 제한: Fable 5.1은 Fable 5와 동일한 “Fable 5.x” 풀을 공유합니다. 점진적 전환을 해도 여유 용량이 늘어나지는 않습니다.

1단계: 모델 ID 업데이트

model = "claude-fable-5"    # Before
model = "claude-opus-5"     # Or before
model = "claude-fable-5-1"  # After

Amazon Bedrock에서는 anthropic.claude-fable-5-1을 사용합니다. Google Cloud, Microsoft Foundry, AWS의 Claude Platform에서는 claude-fable-5-1을 사용합니다.

Claude Managed Agents를 사용한다면 모델 ID 변경이 유일하게 필요한 수정 사항입니다.

주요 변경 사항 1: 강제 도구 사용은 400 오류를 반환함

Fable 5는 tool_choice에 auto, none, any, tool을 허용했습니다. Fable 5.1은 Messages API, Batches API 및 토큰 계산 엔드포인트에서 any와 tool을 거부합니다.

tool_choice: type "tool" and "any" are not supported for this model.

Anthropic에 따르면 사고 기능이 항상 활성화되어 있기 때문에 강제 도구 호출은 사고 과정을 건너뛰게 됩니다. 그 결과 모델이 작업 과정을 도구 인수에 기록할 수 있습니다.

이전: Fable 5

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "tool", "name": "record_summary"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday."}],
)

이후: Fable 5.1

tool_choice를 auto로 변경하고, 명령어에 도구 이름을 명시합니다. 인수가 스키마와 계속 일치해야 한다면 strict: true를 사용하세요. 자세한 내용은 엄격한 도구 사용을 참고하세요.

record_summary_tool["strict"] = True
record_summary_tool["input_schema"]["additionalProperties"] = False

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result."}],
)

사용 사례에 따라 다음처럼 마이그레이션하세요.

JSON 응답을 얻기 위해 도구를 강제했다면 output_config.format을 사용하는 구조화된 출력으로 대체합니다.
해당 턴에서 호출이 반드시 필요하다면 최신 사용자 턴 뒤에 도구 이름을 명시하고, 호출이 필수라고 알리는 role: "system" 메시지를 추가합니다. 이 메시지는 기록에 유지해야 합니다.
정확히 하나의 도구를 호출하려고 any를 사용했다면 auto와 함께 disable_parallel_tool_use: true를 사용합니다. 이제 최대 하나의 호출을 의미합니다.
도구가 호출되지 않았을 때의 재시도 루프는 제거하세요. Anthropic은 Fable 5.1이 명시적인 도구 지침을 안정적으로 따른다고 설명합니다.
CMEK 조직에서는 Fable 모델에서 strict: true와 구조화된 출력을 사용할 수 없습니다. 이 경우 명령어에 의존해야 합니다.

주요 변경 사항 2: 이전 모델은 Fable 5.1 사고 블록을 읽지 못함

사고 블록에는 해당 블록을 생성한 모델이 기록됩니다. Fable 5.1은 Opus 5, Fable 5, Mythos 5 및 이전 모델이 생성한 블록을 읽을 수 있으므로 기존 추론을 유지할 수 있습니다. 반대로 Mythos 5.1을 제외한 다른 모델은 Fable 5.1의 사고 블록을 읽을 수 없습니다.

다음과 같은 경로에서 Fable 5.1 대화가 이전 모델에 도달할 수 있습니다.

라우터 전환
클라이언트 측 재시도
분류기 거부에 따른 폴백

이 경우 API는 대상 모델이 읽을 수 없는 블록을 전달하기 전에 삭제합니다. 요청은 성공하지만 삭제된 토큰에는 비용이 청구되지 않습니다. 대상 모델은 추론 없이 다시 계획을 수립하므로 전환 후 첫 번째 턴의 비용과 지연 시간이 증가할 수 있습니다.

코드에서 사고 블록을 수정할 필요는 없습니다. 생성된 블록을 변경하지 말고 그대로 전달하세요. 직접 삭제하면 400 서명 오류가 발생할 수 있습니다.

가시성이 필요하다면 thinking-binding-controls-2026-08-01 베타 헤더를 전송하세요. 응답의 input_transformations 배열에서 삭제된 블록과 reason: "model_binding_mismatch"를 확인할 수 있습니다.

주요 변경 사항 3: 이전 턴을 편집하면 사고 블록이 무효화됨

Fable 5.1의 사고 블록은 바로 앞에 있는 system 프롬프트, tools 배열 및 메시지 기록에 바인딩됩니다. 이 확인이 강제되는 계정에서 해당 항목을 변경한 뒤 사고 블록을 다시 재생하면 요청이 거부됩니다. 자세한 내용은 보존된 사고를 참고하세요.

messages.5.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

강제 적용 대상

2026년 8월 31일 이후 생성된 계정에서는 이 확인이 강제 적용됩니다. 이전 계정은 불일치를 기록하지만, 요청에서 thinking.block_binding.prefix_mismatch_behavior를 설정한 경우에만 동작합니다. Anthropic은 향후 모든 계정에 이 확인을 적용할 예정입니다.

다른 사용자가 자신의 API 키로 실행하는 도구를 출시한다면 이 필드를 설정해 테스트하세요. 새 계정 사용자는 기존 계정보다 먼저 강제 적용을 경험합니다.

Claude Code, claude.ai, Managed Agents 및 Agent SDK는 접두사를 그대로 유지합니다. Mythos 5.1은 이 확인을 실행하지 않습니다.

어떤 변경이 이후 사고 블록을 무효화하는가

무효화하는 변경

이전 턴 편집, 재정렬 또는 제거
이전 도구 결과 삭제
다음 요청에서 요청별 텍스트 삽입
요청 사이에 system 또는 tools 재구축
이후 턴에서 다른 바이트를 반환하는 이미지 URL 사용

유효성을 유지하는 변경

추가 전용 기록
가장 오래된 사고 블록부터 앞부분 제거
system, tools, messages 외부의 매개변수 변경
cache_control 마커 이동
서버 측 압축 또는 컨텍스트 편집

안전한 폴백

베타 헤더를 전송하고 prefix_mismatch_behavior를 "drop_block"으로 설정할 수 있습니다.

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    thinking={"type": "adaptive", "block_binding": {"prefix_mismatch_behavior": "drop_block"}},
    betas=["thinking-binding-controls-2026-08-01"],
    messages=history,
)
for t in response.input_transformations or []:
    print(t.path, t.reason)   # prefix_binding_mismatch or model_binding_mismatch

API는 첫 번째 불일치 블록과 그 이후의 모든 사고 블록을 삭제한 뒤 요청을 계속 처리하고, 각각의 삭제를 보고합니다. 이 설정은 해당 요청에만 적용되므로 모든 요청에 계속 전송해야 합니다.

CI에서는 "error"를 명시적으로 설정해 기록 편집 시 실행이 실패하도록 하세요. 보존된 사고 가이드는 3단계 감사와 실패하는 압축 형태를 설명합니다.

기존 작업	대신 수행할 작업
세션 중간에 `system` 편집	세션 시작 시 고정하고, 변경 사항에는 `role: "system"` 메시지 추가
세션 중간에 `tools` 편집	전체 도구 세트를 미리 선언하고, 시스템 메시지에 `tool_addition` 또는 `tool_removal` 블록 전송. 베타 `mid-conversation-tool-changes-2026-07-01` 필요
턴별 알림을 삽입한 뒤 삭제	`clear_at: "next_user_message"`가 포함된 턴 범위 시스템 메시지 사용. 베타 `mid-conversation-system-clear-at-2026-08-21` 필요
클라이언트 측에서 이전 도구 결과 삭제	서버 측 컨텍스트 편집 사용
최근 턴을 그대로 유지하는 클라이언트 측 압축	서버 측 압축 사용. 또는 하나의 요약 메시지와 새로운 사용자 턴만 재생
여러 턴에 걸쳐 URL로 이미지 참조	Files API에 한 번 업로드한 뒤 `file_id` 전송

Opus 5에서 전환할 때 추가되는 네 가지 변경 사항

1. 어떤 노력 수준에서도 사고를 비활성화할 수 없음

Opus 5는 high 이하의 노력 수준에서 다음 설정을 허용했습니다.

{"type": "disabled"}

Fable 5.1은 어떤 노력 수준에서도 thinking: {"type": "disabled"}에 대해 400 오류를 반환합니다.

해당 필드를 제거하고, 낮은 노력 수준으로 비용을 제어하세요. 사고 없이 실행되던 경로의 max_tokens도 다시 검토해야 합니다.

2. 도구 간 설명이 사고 블록으로 이동함

Opus 5에서는 도구 호출 사이의 텍스트가 text 블록으로 반환되었습니다. Fable 5.1에서는 기본 display: "omitted" 상태에서 비어 있는 진행 상황 업데이트 thinking 블록으로 반환됩니다.

UI에서 설명을 렌더링해야 한다면 다음 헤더와 설정을 사용하세요.

베타 헤더: thinking-display-updates-2026-08-18
설정: thinking: {"type": "adaptive", "display": "updates"}

3. 분류기 범위가 넓어짐

Opus 5는 사이버 전용 분류기를 실행합니다. Fable 5.1은 다음 분류기를 포함합니다.

cyber
bio
frontier_llm
reasoning_extraction
general_harms

content를 읽기 전에 stop_reason: "refusal"을 먼저 처리하세요. 서버 측 폴백을 사용하려면 server-side-fallback-2026-07-01 헤더와 함께 fallbacks: "default"를 선택합니다.

허용되는 폴백 대상은 Opus 4.8과 Opus 5입니다. 따라서 거부된 요청은 마이그레이션 이전 모델로 폴백될 수 있습니다.

4. 가격과 데이터 보존이 변경됨

캐시 읽기 비용: $0.50 → $0.25
기존 $5, $25 대신 $10, $50
ZDR 지원 안 함

자세한 내용은 Claude Fable 5.1 가격 분석을 참고하세요.

Opus 4.8 또는 이전 버전에서 전환한다면 먼저 Opus 4.8에서 Opus 5로의 마이그레이션을 적용한 뒤 이 가이드를 따르세요.

Opus 4.8용 통합은 이전 턴을 잘라내거나 요청마다 시스템 프롬프트를 재구축하는 경우가 많았지만, Opus 4.8은 이를 문제 삼지 않았습니다.

테스트해야 할 동작 변경

다음 변경 사항은 오류를 반환하지 않지만, 프롬프트와 하네스 동작에 영향을 줄 수 있습니다. Claude Fable 5.1 프롬프트 가이드의 한 줄 수정도 함께 확인하세요.

긴 루프에서 Fable 5.1은 Fable 5처럼 여러 도구 호출을 일괄 처리하는 대신 턴당 하나의 도구 호출만 발행할 수 있습니다. 다중 호출 턴의 비율을 측정하고, 감소했다면 배칭을 유도하는 문구를 추가하세요.
진행 메시지가 줄어들 수 있습니다. UI에 진행 상황이 필요하면 display: "updates"를 사용하세요.
발견 사항을 보류하도록 지시하는 프롬프트 줄은 제거하세요.
low 노력 수준에서는 검색 도구 호출 빈도가 낮아질 수 있습니다. 최신 데이터가 필요한 턴에는 더 높은 노력 수준을 사용하세요.

권장 변경 사항

메시지별 노력 수준: 베타 mid-conversation-output-config-2026-07-01을 사용하세요. 캐시를 재설정하는 최상위 값을 변경하는 대신, output_config를 포함한 빈 role: "system" 메시지로 노력 수준을 변경합니다.
높은 수준부터 테스트: high에서 시작해 전체를 다시 테스트하세요. Fable 5.1의 이점은 xhigh와 max에서 가장 크게 나타납니다. Anthropic은 medium이 더 낮은 비용으로 Fable 5와 거의 일치한다고 설명합니다. 노력 수준 이름은 모델마다 동일하게 동작하지 않습니다.
서버에서 컨텍스트 정리: 서버 측 압축 베타 compact-2026-01-12와 컨텍스트 편집을 사용하세요. 이 작업은 기록 편집으로 간주되지 않습니다.

마이그레이션 체크리스트

[ ] 30일 데이터 보존을 확인하고 우선순위 계층 의존성이 없는지 확인
[ ] 모델 ID를 claude-fable-5-1로 변경
[ ] any 또는 tool인 모든 tool_choice를 auto와 명령어, strict: true 또는 구조화된 출력으로 교체
[ ] Opus 5에서 전환한다면 thinking: {"type": "disabled"} 제거
[ ] 사고 없이 실행되던 경로의 max_tokens 재검토
[ ] 빈 사고 블록을 포함해 모든 턴의 사고 블록을 변경 없이 재전달
[ ] 메시지를 직접 구성한다면 prefix_mismatch_behavior: "drop_block"으로 실행하고 input_transformations 기록
[ ] 모든 prefix_binding_mismatch 원인 수정
[ ] 세션 시작 시 system과 tools 고정
[ ] 턴별 알림을 삭제하지 않는 턴 범위 시스템 메시지로 이동
[ ] 프로덕션에서 prefix_mismatch_behavior를 선택하고 모니터링
[ ] stop_reason: "refusal" 처리
[ ] fallbacks: "default" 추가
[ ] UI에서 도구 간 텍스트를 렌더링한다면 display: "updates" 설정
[ ] high부터 노력 수준 테스트를 다시 실행하고 비용 기준 재설정
[ ] 토큰 수는 Fable 5와 동일하고, 캐시 읽기 비용은 4분의 1로 줄어든다는 점을 비용 모델에 반영

Apidog에서 체크리스트 실행

주요 변경 사항마다 하나의 요청을 컬렉션에 추가하세요.

강제 tool_choice 호출 — 400 오류 예상
thinking: disabled 호출 — 400 오류 예상
사고 바인딩 헤더를 설정한 상태에서 턴 사이에 시스템 프롬프트를 편집하는 두 요청 시퀀스 — prefix_binding_mismatch 예상
통과 버전 — stop_reason을 어설션하고 input_transformations가 빈 배열인지 확인

모든 하네스 변경 사항은 Apidog CLI를 통해 CI에서 실행하세요. 테스트를 구축하려면 Apidog 다운로드를 사용하고, 요청 본문은 Claude Fable 5.1 API 워크스루에서 확인하세요.

자주 묻는 질문

Fable 5에서 Fable 5.1로의 마이그레이션은 드롭인 변경입니까?

대부분 그렇습니다. 다만 강제 tool_choice는 400 오류를 반환하고, 이전 모델은 Fable 5.1 사고 블록을 읽을 수 없으며, 강제 적용 계정에서 이전 턴을 편집하면 이후 사고 블록이 무효화됩니다. 그 외의 동작은 유지됩니다.

“다른 대화에 바인딩됨”은 무엇을 의미합니까?

Fable 5.1 사고 블록 앞에 있는 항목을 변경한 뒤 해당 블록을 다시 재생했다는 의미입니다. 기록 편집을 중단하거나 thinking-binding-controls-2026-08-01 헤더와 함께 prefix_mismatch_behavior: "drop_block"을 전송하세요.

내 계정에 기록 편집 확인이 강제 적용됩니까?

2026년 8월 31일 또는 그 이후에 생성된 계정이라면 그렇습니다. 이전 계정은 prefix_mismatch_behavior를 설정한 경우에만 강제 적용됩니다.

Fable 5 프롬프트를 계속 사용할 수 있습니까?

네. Anthropic은 변경 없이도 정상 작동해야 한다고 설명합니다. 다만 노력 수준 테스트를 다시 실행하고, 긴 루프에서 병렬 도구 호출이 줄어들 수 있다는 점을 반영하세요.

Opus 5에서 마이그레이션할 때 무엇이 문제입니까?

Fable 5 마이그레이션 항목에 더해, 어떤 노력 수준에서도 thinking: disabled가 400 오류를 반환합니다. 도구 간 설명은 사고 블록으로 이동하고, 분류기 범위가 넓어지며, 가격은 두 배가 되고 ZDR은 지원되지 않습니다.

Bedrock과 Google Cloud에도 동일한 주요 변경 사항이 적용됩니까?

모델 변경 사항은 동일합니다. 사고 바인딩 제어 기능은 출시 시 Claude API와 AWS의 Claude Platform에서 제공되었으며, Bedrock과 Google Cloud에는 모델별로 적용될 예정입니다. 해당 제어 기능이 없다면 사고 블록을 제거하고 한 번 재시도하는 것이 복구 방법입니다.

DEV Community