컨텍스트 윈도우

대화가 길어지면 결국 컨텍스트 윈도우 한도에 가까워지게 됩니다. 장시간 실행되는 대화와 에이전트 워크플로의 경우, 서버 측 압축(compaction)이 컨텍스트 관리의 기본 전략입니다.



컨텍스트 윈도우의 작동 방식

"Context window"(컨텍스트 윈도우)는 언어 모델이 응답을 생성할 때 참조할 수 있는 모든 텍스트를 의미하며, 응답 자체도 포함됩니다. 이는 언어 모델이 학습한 대규모 데이터 코퍼스와는 다르며, 대신 모델의 "작업 메모리"를 나타냅니다. 더 큰 컨텍스트 윈도우는 모델이 더 복잡하고 긴 프롬프트를 처리할 수 있게 하지만, 컨텍스트가 많다고 해서 자동으로 더 좋은 것은 아닙니다. 토큰 수가 증가하면 정확도와 재현율이 저하되는데, 이 현상을 *컨텍스트 부패(context rot)*라고 합니다. 따라서 컨텍스트에 무엇을 넣을지 선별하는 것이 사용 가능한 공간의 크기만큼이나 중요합니다.

다음 다이어그램은 API 요청에 대한 표준 컨텍스트 윈도우 동작을 보여줍니다¹:

¹ claude.ai와 같은 채팅 인터페이스는 "선입선출" 방식으로 컨텍스트 윈도우를 순환 관리할 수도 있습니다.

• 점진적 토큰 누적: 대화가 턴을 거듭하며 진행됨에 따라 각 사용자 메시지와 어시스턴트 응답이 컨텍스트 윈도우 내에 누적되며, 이전 턴은 완전히 보존됩니다.
• 컨텍스트 윈도우 용량: 컨텍스트 윈도우(모델에 따라 최대 1M 토큰)는 대화 기록과 Claude가 생성하는 새로운 출력을 담습니다.
• 입력-출력 흐름: 각 턴은 다음으로 구성됩니다:
  • 입력 단계: 모든 이전 대화 기록과 현재 사용자 메시지를 포함합니다
  • 출력 단계: 다음 턴의 입력의 일부가 되는 텍스트 응답을 생성합니다

요청에 포함된 모든 것이 컨텍스트 윈도우에 계산됩니다: 시스템 프롬프트, messages의 모든 메시지(도구 결과, 이미지, 문서 포함), 그리고 도구 정의입니다. Claude가 해당 턴에서 생성하는 출력도 확장 사고를 포함하여 계산됩니다. 모든 응답은 요청이 소비한 양을 usage 필드에 보고합니다. 프롬프트 캐싱을 사용하는 경우, 입력 수는 input_tokens, cache_read_input_tokens, cache_creation_input_tokens로 나뉘며, 세 가지 모두 컨텍스트 윈도우에 계산됩니다. 요청을 보내기 전에 추정하려면 토큰 계산 API를 사용하세요.



모델별 컨텍스트 윈도우 크기

Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6은 Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry에서 1M 토큰 컨텍스트 윈도우를 제공합니다. Claude Mythos Preview도 1M 토큰 컨텍스트 윈도우를 제공합니다.

Claude Fable 5와 Claude Mythos 5(claude-fable-5 및 claude-mythos-5)도 1M 토큰 컨텍스트 윈도우를 제공합니다. 1M 토큰 컨텍스트 윈도우를 가진 모든 모델에 대한 단일 요청은 최대 128k 출력 토큰(max_tokens)을 생성할 수 있습니다. Claude Sonnet 4.5를 포함한 다른 Claude 모델은 200k 토큰 컨텍스트 윈도우를 제공합니다.

1M 토큰 컨텍스트 윈도우를 가진 모든 모델에서 1M이 기본값입니다: 베타 헤더가 필요하지 않으며, 긴 컨텍스트 요청은 표준 가격으로 청구됩니다.

단일 요청에는 최대 600개의 이미지 또는 PDF 페이지(200k 토큰 컨텍스트 윈도우를 가진 모델의 경우 100개)를 포함할 수 있습니다. 많은 이미지나 대용량 문서를 보내는 경우, 토큰 한도에 도달하기 전에 요청 크기 제한에 도달할 수 있습니다.

모델별 컨텍스트 윈도우 크기 목록은 모델 비교 표를 참조하세요.



사고를 사용할 때의 컨텍스트 윈도우

사고(thinking)를 사용하면 사고 토큰을 포함한 모든 입력 및 출력 토큰이 컨텍스트 윈도우 한도에 계산되며, 다중 턴 상황에서는 몇 가지 미묘한 차이가 있습니다.

사고 토큰은 max_tokens 매개변수의 일부이며, 출력 토큰으로 청구되고, 속도 제한에 계산됩니다. 적응형 사고(adaptive thinking)를 사용하면 Claude가 사고 할당량을 동적으로 결정하므로, 사고 토큰 사용량은 요청마다 달라집니다.

이전 어시스턴트 턴의 사고 블록이 컨텍스트 윈도우에 유지되는지 여부는 모델에 따라 다릅니다. Claude Opus 4.5 및 이후 Opus 모델, Claude Sonnet 4.6 및 이후 Sonnet 모델, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview에서는 API가 기본적으로 이전 사고 블록을 유지하며, 이는 다른 입력 토큰과 마찬가지로 컨텍스트 윈도우에 계산됩니다. 이전 Opus 및 Sonnet 모델과 모든 Haiku 모델에서는 이전 사고 블록을 다시 전달할 때 API가 대화 기록에서 자동으로 제거하여 대화 콘텐츠를 위한 토큰 용량을 보존합니다. 모델별 기본값은 모델별 사고 블록 보존을 참조하세요. 어느 방향으로든 기본값을 재정의하려면 사고 블록 지우기를 사용하세요.

다음 다이어그램은 이전 사고 블록을 제거하는 모델에서 사고가 활성화되었을 때 토큰이 관리되는 방식을 보여줍니다:

• 사고 블록 제거: 이전 사고 블록을 제거하는 모델에서는 사고 블록(진한 회색으로 표시)이 각 턴의 출력 단계에서 생성되지만 이후 턴의 입력 토큰으로 전달되지 않습니다. 사고 블록을 직접 제거할 필요는 없습니다: 다시 전달하면 Claude API가 자동으로 제거합니다.
• 청구: 사고 토큰은 생성될 때 한 번 출력 토큰으로 청구됩니다. 이전 사고 블록을 유지하는 모델에서는 유지된 블록이 이후 요청의 입력의 일부가 되어 나머지 대화 기록과 마찬가지로 입력 토큰으로 청구됩니다.



사고와 도구 사용을 함께 사용할 때의 컨텍스트 윈도우

다음 다이어그램은 이전 사고 블록을 제거하는 모델에서 사고와 도구 사용을 결합할 때 토큰이 관리되는 방식을 보여줍니다:

• 사고와 함께 도구 사용 시 고려 사항:
  • 도구 결과를 게시할 때, 해당 도구 요청에 수반되는 수정되지 않은 전체 사고 블록을 서명을 포함하여 포함해야 합니다.
  • API는 암호화 서명을 사용하여 사고 블록의 진위를 확인합니다. 사고 블록을 수정하면 API가 오류를 반환합니다.

도구 정의 자체가 소비하는 컨텍스트를 줄이려면 도구 컨텍스트 관리를 참조하거나, 도구 검색 도구로 도구 정의를 지연시키세요.



컨텍스트 인식

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5는 컨텍스트 인식(context awareness) 기능을 갖추고 있습니다: 이 모델들은 대화 전반에 걸쳐 남은 컨텍스트 윈도우(즉, "토큰 예산")를 추적합니다. 이를 통해 모델은 남은 토큰 수를 추측하는 대신 남은 공간에 맞춰 장시간 실행되는 작업을 관리할 수 있습니다. 컨텍스트 인식은 자동입니다: 활성화할 것이 없으며, 이 섹션에 표시된 태그를 직접 보낼 필요도 없습니다. API가 이를 주입합니다.



작동 방식

모든 요청의 시스템 프롬프트에서 API는 Claude에게 전체 컨텍스트 윈도우를 알려줍니다:

<budget:token_budget>200000</budget:token_budget>

예산은 요청에 사용 가능한 컨텍스트 윈도우와 일치합니다: Claude Sonnet 5와 Claude Sonnet 4.6의 경우 1M 토큰, Claude Sonnet 4.5와 Claude Haiku 4.5의 경우 200k 토큰입니다. 이 섹션의 예시는 200k 토큰 컨텍스트 윈도우를 가진 모델을 보여줍니다.

각 도구 호출 후, API는 Claude에게 남은 용량에 대한 업데이트를 제공합니다:

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

이미지 토큰도 이러한 예산에 포함됩니다.

Claude Opus 4.7 및 이후 Opus 모델, Claude Fable 5, Claude Mythos 5는 이러한 주입된 태그를 받지 않습니다. Claude Opus 4.7 및 이후 Opus 모델, Claude Fable 5, Claude Mythos 5에서는 베타 상태인 작업 예산을 통해 모델에 명시적인 예산을 제공할 수 있습니다.

컨텍스트 인식 사용에 대한 프롬프팅 지침은 프롬프팅 모범 사례를 참조하세요.



압축으로 컨텍스트 관리

대화가 정기적으로 컨텍스트 윈도우 한도에 가까워진다면 서버 측 압축을 사용하세요. 압축은 서버에서 대화의 이전 부분을 자동으로 요약하여 대화가 컨텍스트 윈도우 한도를 넘어 계속될 수 있게 합니다. Claude 4.6 및 이후 모델과 Claude Mythos Preview에서 베타로 제공됩니다.

보다 특수한 요구 사항의 경우, 컨텍스트 편집이 추가 전략을 제공합니다:

• 도구 결과 지우기: 에이전트 워크플로에서 오래된 도구 결과를 지웁니다
• 사고 블록 지우기: 확장 사고를 사용할 때 사고 블록을 관리합니다

캐시된 프롬프트 접두사는 여전히 컨텍스트 윈도우를 차지합니다: 프롬프트 캐싱은 해당 토큰에 대해 지불하는 비용을 변경할 뿐, 계산 여부를 변경하지는 않습니다.



컨텍스트 윈도우 초과 동작

입력만으로 이미 모델의 컨텍스트 윈도우를 초과하는 경우, API는 모든 모델에서 400 invalid_request_error("prompt is too long")를 반환합니다.

Claude 4.5 모델 및 이후 모델에서는 입력 토큰과 max_tokens의 합이 컨텍스트 윈도우 크기를 초과하더라도 API가 요청을 수락합니다. 생성이 컨텍스트 윈도우 한도에 도달하면 stop_reason: "model_context_window_exceeded"로 중지됩니다. 이전 모델에서는 API가 대신 유효성 검사 오류를 반환합니다. 해당 모델에서 model_context_window_exceeded 동작을 사용하려면 model-context-window-exceeded-2025-08-26 베타 헤더를 사용하세요. 자세한 내용은 중지 이유 및 폴백을 참조하세요.

컨텍스트 윈도우 한도 내에서 유지하려면 토큰 계산 API를 사용하여 Claude에 메시지를 보내기 전에 토큰 사용량을 추정하세요.



다음 단계