일반적인 AI 워크플로에서는 동일한 입력 토큰을 모델에 반복해서 전달할 수 있습니다. Gemini API는 다음과 같은 두 가지 캐싱 메커니즘을 제공합니다.
- 암시적 캐싱 (Gemini 2.5 모델에서 자동으로 사용 설정되며 비용 절감 보장 없음)
- 명시적 캐싱 (대부분의 모델에서 수동으로 사용 설정 가능, 비용 절감 보장)
명시적 캐싱은 비용 절감을 보장하되 개발자 작업을 추가하려는 경우에 유용합니다.
암시적 캐싱
암시적 캐싱은 모든 Gemini 2.5 모델에 기본적으로 사용 설정됩니다. 요청이 캐시에 도달하면 비용 절감이 자동으로 전달됩니다. 이 기능을 사용 설정하기 위해 사용자가 수행해야 하는 작업은 없습니다. 이 정책은 2025년 5월 8일부터 시행됩니다. 컨텍스트 캐싱의 최소 입력 토큰 수는 2.5 Flash의 경우 1,024개, 2.5 Pro의 경우 4,096개입니다.
암시적 캐시 적중 가능성을 높이려면 다음을 따르세요.
- 크고 일반적인 콘텐츠를 프롬프트의 시작 부분에 배치해 보세요.
- 짧은 시간 내에 유사한 접두사가 있는 요청을 전송하려고 시도
응답 객체의 usage_metadata 필드에서 캐시 적중된 토큰 수를 확인할 수 있습니다.
명시적 캐싱
Gemini API 명시적 캐싱 기능을 사용하면 콘텐츠를 모델에 한 번 전달하고 입력 토큰을 캐시한 다음 후속 요청에서 캐시된 토큰을 참조할 수 있습니다. 특정 볼륨에서는 캐시된 토큰을 사용하는 것이 동일한 코퍼스 토큰을 반복적으로 전달하는 것보다 비용이 저렴합니다.
토큰 집합을 캐시할 때 토큰이 자동으로 삭제되기 전에 캐시가 유지될 기간을 선택할 수 있습니다. 이 캐싱 기간을 TTL (수명)이라고 합니다. 설정하지 않으면 TTL은 기본적으로 1시간입니다. 캐싱 비용은 입력 토큰 크기와 토큰을 유지하려는 기간에 따라 달라집니다.
이 섹션에서는 빠른 시작에 표시된 대로 Gemini SDK를 설치했거나 curl이 설치되어 있고 API 키를 구성했다고 가정합니다.
OpenAI 라이브러리를 사용한 명시적 캐싱
OpenAI 라이브러리를 사용하는 경우 extra_body에서 cached_content 속성을 사용하여 명시적 캐싱을 사용 설정할 수 있습니다.
명시적 캐싱을 사용해야 하는 경우
컨텍스트 캐싱은 짧은 요청에서 상당한 양의 초기 컨텍스트를 반복적으로 참조하는 시나리오에 특히 적합합니다. 다음과 같은 사용 사례에 컨텍스트 캐싱을 사용하는 것이 좋습니다.
- 다양한 시스템 안내를 제공하는 챗봇
- 긴 동영상 파일 반복 분석
- 대규모 문서 세트에 대해 반복 쿼리
- 빈번한 코드 저장소 분석 또는 버그 수정
명시적 캐싱으로 비용을 절감하는 방법
컨텍스트 캐싱은 전반적인 운영 비용을 줄이기 위해 설계된 유료 기능입니다. 다음 요소를 기준으로 결제가 청구됩니다.
- 캐시 토큰 수: 캐시된 입력 토큰 수로, 후속 프롬프트에 포함될 경우 할인된 요율로 청구됩니다.
- 스토리지 기간: 캐시된 토큰이 저장되는 시간 (TTL)으로, 캐시된 토큰 수의 TTL 기간을 기준으로 청구됩니다. TTL에는 최소 또는 최대 경계가 없습니다.
- 기타 요인: 캐시되지 않은 입력 토큰 및 출력 토큰과 같은 기타 요인에 다른 요금이 청구됩니다.
최신 가격 책정 세부정보는 Gemini API 가격 책정 페이지를 참고하세요. 토큰 수를 계산하는 방법을 알아보려면 토큰 가이드를 참고하세요.
추가 고려사항
컨텍스트 캐싱을 사용할 때는 다음 사항을 고려하세요.
- 컨텍스트 캐싱의 최소 입력 토큰 수는 2.5 Flash의 경우 1,024개, 2.5 Pro의 경우 2,048개입니다. 최댓값은 지정된 모델의 최댓값과 동일합니다. 토큰 수에 대한 자세한 내용은 토큰 가이드를 참고하세요.
- 모델은 캐시된 토큰과 일반 입력 토큰을 구분하지 않습니다. 캐시된 콘텐츠는 프롬프트의 접두사입니다.
- 컨텍스트 캐싱에는 특별한 비율 또는 사용량 제한이 없습니다.
GenerateContent의 표준 비율 제한이 적용되며 토큰 제한에는 캐시된 토큰이 포함됩니다. - 캐시된 토큰 수는 캐시 서비스의 생성, 가져오기, 목록 작업의
usage_metadata에 반환되며, 캐시를 사용할 때GenerateContent에도 반환됩니다.