컨텍스트 캐싱 (Context Caching)

같은 시스템 프롬프트를 매 요청마다 반복해서 계산하는 건 낭비예요. DeepSeek는 이런 반복 입력을 디스크 캐시에 저장해두는 Context Caching을 모든 사용자에게 기본으로 켜고 있어요. 코드를 고칠 필요 없이 자동으로 동작해요.

출처: https://api-docs.deepseek.com/guides/kv_cache

매 요청마다 하드 디스크 캐시가 만들어져요. 이후 요청이 이전 요청과 겹치는 앞부분(prefix)을 갖고 있으면, 그 겹치는 부분은 캐시에서만 가져와요. 이걸 "캐시 히트(cache hit)"라고 불러요.

캐시 히트가 되려면 해당 앞부분이 이미 디스크 캐시에 "저장(persisted)"돼 있어야 해요. 이 캐시는 Sliding Window Attention 구조 때문에 저장·매칭 방식이 조금 달라요. 각 캐시된 앞부분은 독립적이고 완전한 하나의 단위(캐시 프리픽스 단위)예요. 이후 요청이 캐시에 걸리려면 그 캐시 프리픽스 단위를 완전히 그대로 맞아야 해요.

캐시 단위가 만들어지는 경우는 세 가지예요.

요청 경계에서의 저장 — 각 요청은 사용자 입력의 끝 지점과 모델 출력의 끝 지점에 각각 캐시 프리픽스 단위 두 개를 생성해요. 이후 요청이 그걸 완전히 그대로 맞추면 히트해요.
공통 앞부분 감지 저장 — 여러 요청에서 공통 앞부분이 감지되면 그 공통 앞부분을 독립된 캐시 프리픽스 단위로 저장해요. 이후 요청이 그 단위를 완전히 그대로 재사용하면 히트해요.
고정 토큰 간격 저장 — 긴 입력이나 출력에서는, 끝 지점에 도달하지 않아 긴 앞부분이 아예 캐시되지 못하는 상황을 피하려고 고정 토큰 간격으로 캐시 프리픽스 단위를 잘라내요.

예시로 이해해 볼게요.

첫 요청이 A + B, 두 번째 요청이 A + B + C라면, 두 번째 요청은 캐시 프리픽스 단위 A + B를 완전히 그대로 맞추므로 A + B가 캐시 히트해요.
첫 요청이 A + B, 두 번째 요청이 A + C라면, A + C가 첫 요청의 단위(A + B)를 완전히 맞추지 못해 캐시되지 못해요. 다만 시스템이 두 요청의 공통 앞부분 A를 감지해 단위로 저장해요. 그러면 세 번째 요청 A + D가 그 A 단위를 완전히 맞추므로 캐시 히트해요.

실제 대화로 보면, 첫 요청과 같은 앞부분을 가진 두 번째 요청은 캐시를 재사용할 수 있어요.

첫 요청

{
  "role": "system", "content": "You are a helpful assistant",
  "role": "user", "content": "What is the capital of China?"
}

두 번째 요청 — 첫 요청의 캐시 프리픽스 단위를 완전히 그대로 재사용해 캐시 히트가 돼요.

{
  "role": "system", "content": "You are a helpful assistant",
  "role": "user", "content": "What is the capital of China?",
  "role": "assistant", "content": "The capital of China is Beijing.",
  "role": "user", "content": "What is the capital of the United States?"
}

캐시 히트 확인하기

응답의 usage 부분에 캐시 상태를 나타내는 필드 두 개가 추가돼 있어요.

prompt_cache_hit_tokens — 이 요청의 입력 중 캐시 히트가 된 토큰 수예요.
prompt_cache_miss_tokens — 이 요청의 입력 중 캐시 히트가 되지 않은 토큰 수예요.

하드 디스크 캐시는 사용자 입력의 앞부분만 매칭해요. 출력은 여전히 계산·추론으로 생성되며 temperature 같은 파라미터의 영향을 받아 랜덤성이 생겨요.

몇 가지 알아둘 점이 있어요.

캐시 시스템은 "베스트 에포트(best-effort)" 방식이라 100% 캐시 히트율을 보장하지 않아요.
캐시 구축은 수 초가 걸려요. 캐시가 더 이상 쓰이지 않으면 보통 수 시간에서 수 일 안에 자동으로 정리돼요.

더 알아보기

캐시 히트 토큰이 사용량 통계에 어떻게 집계되는지는 채팅 완성 API의 usage 설명을 봐요.
Responses API에서도 캐시 토큰이 usage에 어떻게 잡히는지 궁금하면 «Responses API 사용» 문서를 봐요.