컨텍스트 캐싱 (Context Caching)

컨텍스트 캐싱 (Context Caching)

매번 같은 시스템 프롬프트나 대화 이력을 요청에 넣으면, 그 부분을 매번 처음부터 계산하느라 토큰과 시간이 중복으로 소모돼요. 컨텍스트 캐싱은 반복되는 내용을 자동으로 기억해 뒀다가 재사용해서, 지연을 줄이고 캐시에 걸린 토큰은 더 낮은 가격으로 책정해줍니다. 이 글에서는 캐시가 어떻게 동작하는지와, 히트 여부를 확인하는 방법을 다뤄볼게요.

출처: 上下文缓存 (Context Caching) - 智谱开放平台 문서

동작 방식

캐시는 암시적(implicit) 방식이라 설정할 게 없어요. 시스템이 입력 메시지 내용을 계산해서 이전 요청과 같거나 거의 같은 부분을 찾아내면, 그 부분에 대해 앞선 계산 결과를 재사용합니다. 그래서 특별한 플래그 없이도 반복되는 시스템 프롬프트나 긴 대화 이력이 알아서 캐시에 걸려요.

캐시가 특히 효과 좋은 시나리오는 이렇습니다.

  • 시스템 프롬프트 재사용 — 다중 턴 대화에서 시스템 프롬프트가 거의 항상 같다면, 그 토큰 소비가 크게 줄어요.
  • 반복 작업 — 동일한 지시로 비슷한 내용을 여러 번 처리할 때.
  • 긴 대화 이력 — 복잡한 대화에서 과거 메시지에 중복 정보가 많을 때.

히트 여부 확인하기

캐시 히트는 응답의 usage.prompt_tokens_details.cached_tokens 필드로 투명하게 드러나요. 이 값으로 이번 요청에서 몇 토큰이 캐시에서 재사용됐는지(그리고 낮은 요금으로 청구된 부분이 얼마인지) 알 수 있습니다.

첫 번째 요청으로 캐시를 만들고, 같은 시스템 프롬프트로 두 번째 요청을 보내면 캐시가 쌓이는 예시를 cURL로 보면 이렇게 됩니다.

curl --location 'https://open.bigmodel.cn/api/paas/v4/chat/completions' \
  --header 'Authorization: Bearer ***' \
  --header 'Content-Type: application/json' \
  --data '{
      "model": "glm-5.3",
      "messages": [
          { "role": "system", "content": "너는 전문 데이터 분석가야." },
          { "role": "user", "content": "사용자 유지율을 어떻게 분석해?" }
      ]
  }'

Python SDK(zai-sdk)에서는 response.usage.prompt_tokens_details.cached_tokens로 캐시 토큰을 읽으면 됩니다. GLM-5.2·GLM-5.1·GLM-5 계열 등 주요 모델을 폭넓게 지원해요.

더 알아보기 (Learn more)