Gemini API 가이드: 반복 워크로드 컨텍스트 캐싱

InYourLeague 리서치 · 2026-08-27

Answer in brief

Gemini API는 요건을 충족하는 반복 입력에 암시적 컨텍스트 캐싱을 자동으로 제공합니다. 명시적 캐시 객체를 생성하고 관리해야 한다면 generateContent API를 사용하고, 실제 재사용 여부는 usage.total_cached_tokens로 확인해야 합니다.

Key facts at a glance

Failure modes and verification

FAQ

Gemini API의 암시적 컨텍스트 캐싱은 자동으로 활성화됩니까?

그렇습니다. 공식 캐싱 가이드에 따르면 Gemini 2.5 이상 모델에서 자동으로 활성화됩니다. previous_interaction_id를 사용하는 상태 유지형 대화와 상태를 유지하지 않는 요청에서 모두 이용할 수 있습니다.

Interactions API에서 명시적 캐시를 생성하거나 관리할 수 있습니까?

아닙니다. Interactions API는 암시적 캐싱만 지원합니다. 공식 캐싱 가이드에 따르면 명시적 캐시 객체를 생성하고 관리하려면 generateContent API를 사용해야 합니다.

반복되는 프롬프트 접두사는 어떻게 구성해야 합니까?

크고 공통된 콘텐츠를 요청 앞부분에 배치하고, 요청별 콘텐츠를 그 뒤에 둔 다음, 관련 요청에서 공통 접두사를 일관되게 유지합니다. 접두사가 비슷한 요청을 짧은 시간 안에 전송하면 암시적 캐시 적중 가능성을 더 높일 수 있습니다.

최소 입력 토큰 기준을 충족하면 캐시 적중이 보장됩니까?

보장된다고 명시되어 있지 않습니다. 캐싱 문서는 암시적 캐싱을 위한 최소 기준을 제시하지만, 애플리케이션에서는 모든 대상 요청이 적중한다고 가정하지 말고 응답에서 실제 재사용 여부를 확인해야 합니다.

캐시된 토큰의 재사용 여부는 어떻게 확인합니까?

usage.total_cached_tokens를 사용하면 캐시에서 발견된 토큰 수를 확인할 수 있습니다. 0보다 큰 값은 재사용이 발생했음을 보여 주지만, 제공된 근거에는 이 값을 정확한 할인액으로 환산하는 계산식이 없습니다.

제공된 근거에서 확인할 수 있는 캐시 수명 주기 정보는 무엇입니까?

암시적 캐싱이 자동으로 적용되고 명시적 캐시 객체는 generateContent API에서 관리할 수 있다는 점까지 확인됩니다. 보존 기간, 만료, 갱신, 삭제 시점 또는 암시적 캐시 제거 방식은 제시되어 있지 않습니다.

긴 컨텍스트를 사용하려면 텍스트 또는 멀티모달 코드를 변경해야 합니까?

긴 컨텍스트 가이드는 기존 텍스트 생성 및 멀티모달 입력 코드가 변경 없이 작동한다고 설명합니다. 다만 캐싱의 최소 토큰 기준과 API별 캐싱 기능의 차이는 그대로 적용됩니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

그렇습니다. Gemini API는 요건을 충족하는 반복 입력을 암시적 컨텍스트 캐싱을 통해 자동으로 재사용할 수 있습니다. 개발자가 캐시 객체를 직접 관리해야 하는 워크로드에는 generateContent API를 통한 명시적 캐싱이 필요합니다. 이 내용은 2026-08-27에 공식 캐싱 문서와 긴 컨텍스트 문서를 기준으로 검토했습니다.

API의 캐싱 지원 범위 이해하기

암시적 캐싱은 Gemini 2.5 이상 모델에서 자동으로 활성화됩니다. previous_interaction_id를 사용하는 상태 유지형 대화와 상태를 유지하지 않는 요청에서 모두 이용할 수 있습니다. 개발자가 이 기능을 별도로 활성화하거나 캐시 객체를 생성할 필요는 없습니다. Gemini API가 암시적 캐시에서 일치하는 내용을 찾으면 Google이 해당 비용 절감분을 자동으로 반영합니다. 문서에 제시된 최소 토큰 수는 캐싱 대상이 되기 위한 조건이며, 이를 충족하더라도 캐시 적중이 보장되지는 않습니다.

명시적 캐싱은 개발자가 캐시 객체를 직접 생성하고 관리하는 방식입니다. Interactions API는 암시적 캐싱만 지원하므로 명시적 캐시 객체를 생성하거나 관리할 수 없습니다. 따라서 이러한 객체가 필요한 워크로드는 generateContent API를 사용해야 합니다. 이는 두 API가 지원하는 캐싱 기능의 차이를 설명하는 기준이지, 모든 워크로드에서 어느 한 API를 우선 선택하라는 일반적인 권고는 아닙니다.

긴 컨텍스트 가이드는 텍스트 생성과 멀티모달 입력에 사용하던 기존 코드가 변경 없이 긴 컨텍스트에서도 작동한다고 별도로 설명합니다. 그러나 이러한 코드 호환성이 캐싱의 최소 토큰 기준이나 Interactions API와 generateContent API 사이의 캐싱 기능 차이를 바꾸지는 않습니다.

반복 프롬프트를 재사용에 유리하게 구성하기

1. 여러 호출에서 공유하는 큰 콘텐츠를 먼저 식별합니다. 시스템 지침, 참고 문서, 정책, 반복 예시 등이 여기에 해당합니다.
2. 공통 콘텐츠를 관련된 각 요청의 시작 부분에 배치합니다. 요청마다 달라지는 질문, 사용자 데이터 및 기타 가변 콘텐츠는 공통 접두사 뒤에 둡니다.
3. 관련 요청에서는 공통 접두사를 일관되게 유지합니다. 의미가 달라지지 않았다면 순서, 형식, 표현 또는 포함된 예시를 불필요하게 변경하지 않는 편이 좋습니다.
4. 워크플로가 허용한다면 접두사가 비슷한 요청을 짧은 시간 안에 전송합니다. 공식 문서는 이를 암시적 캐시 적중 가능성을 높이는 방법으로 안내하지만, 적중을 보장하지는 않습니다.
5. 선택한 모델에 적용되는 최소 입력 토큰 기준을 확인합니다. 최소 기준을 충족하면 암시적 캐싱 대상이 될 수 있지만, 실제 재사용 여부는 응답을 통해 확인해야 합니다.

절감액을 추정하지 말고 사용량 확인하기

공식 문서에 설명된 Python 및 JavaScript 응답 객체에서 usage.total_cached_tokens는 캐시에서 발견된 토큰 수를 나타냅니다. 실제 캐시 재사용을 관찰하려면 이 필드를 기록하십시오. 다만 이 값을 정확한 할인액으로 해석해서는 안 됩니다. 제공된 근거는 암시적 캐시가 적중하면 해당 비용 절감분이 반영된다고 설명하지만, 캐시된 토큰 수를 구체적인 가격 인하액으로 환산하는 계산식은 제시하지 않습니다.

제공된 발췌문은 암시적 캐싱이 자동으로 활성화되며 개발자가 별도로 조치할 필요가 없다고 설명합니다. 그러나 개발자가 제어할 수 있는 보존 설정, 제거 시점 또는 그 밖의 수명 주기 제어 기능은 다루지 않습니다. 이러한 설명이 없다는 사실은 암시적 캐시에 수명 주기가 없다는 뜻이 아니라, 제공된 근거만으로는 그 세부 사항을 확정할 수 없다는 뜻입니다.

명시적 캐싱에 대해서는 generateContent API를 통해 캐시 객체를 생성하고 관리할 수 있다는 점까지 확인됩니다. 제공된 발췌문에는 기본 만료 시점, 보존 기간, 갱신 동작, 삭제 시점 또는 그 밖의 수명 주기 세부 정보가 없습니다. 애플리케이션 로직이 이러한 동작에 의존한다면 현재 공식 문서에서 먼저 확인해야 합니다.

표에 적힌 모델 이름은 제공된 캐싱 문서 발췌문의 표시 이름입니다. 해당 발췌문에는 정확한 API 모델 식별자 문자열이 없으므로, 표의 이름을 설정에 바로 사용할 식별자로 간주해서는 안 됩니다.

구현 체크리스트

• 명시적 캐시 객체가 필요한 워크로드에는 generateContent API를 사용합니다.
• 크고 공통된 콘텐츠를 관련 요청의 시작 부분에 배치합니다.
• 관련 요청에서 공통 접두사를 일관되게 유지합니다.
• 가능하면 접두사가 비슷한 요청을 짧은 시간 안에 전송합니다.
• 모델별 최소 입력 토큰 기준을 충족하는지 확인합니다.
• 캐시 적중을 추정하지 말고 usage.total_cached_tokens를 기록합니다.
• 캐시된 토큰 수와 실제 비용 절감액을 서로 다른 측정값으로 취급합니다.
• 수명 주기 세부 사항을 애플리케이션 로직에 반영하기 전에 확인합니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.