Gemini API 콘텍스트 캐싱 — 토큰 비용 90% 줄이는 가성비 설정

Haram

@haram

Gemini API 콘텍스트 캐싱 — 토큰 비용 90% 줄이는 가성비 설정

Gemini API 콘텍스트 캐싱 — 토큰 비용 90% 줄이는 가성비 설정

AI로 긴 문서나 전체 소스 코드를 분석하다 보면, 순식간에 늘어나는 API 비용 때문에 부담스러울 때가 많습니다. 질문을 던질 때마다 수만 토큰에 달하는 배경 데이터를 매번 처음부터 다시 전송해야 하기 때문인데요. 제미나이 API가 제공하는 '콘텍스트 캐싱'을 활용하면 이 낭비되는 입력 토큰 비용을 최대 90%까지 줄이고 답변 속도도 훨씬 빠르게 끌어올릴 수 있습니다.

콘텍스트 캐싱, 어떤 원리로 동작할까요?

콘텍스트 캐싱은 쉽게 말해 '두꺼운 참고서를 책상 위에 미리 펼쳐두는 것'과 같습니다. 원래대로라면 AI에게 질문할 때마다 수백 페이지짜리 설명서나 전체 소스 코드를 통째로 넘겨주어야 했습니다. 질문을 한 마디 바꿀 때마다 똑같은 데이터를 매번 처음부터 다시 전송하느라 돈과 시간이 낭비되던 구조였습니다.

구글의 콘텍스트 캐싱은 이 무거운 참고서를 구글 서버에 딱 한 번만 펼쳐두고, 필요할 때마다 그 내용을 즉시 참고해 답변하는 기술입니다. 덕분에 똑같은 데이터를 매번 전송할 필요가 없어서 속도가 획기적으로 빨라집니다.

이 캐싱 기술은 크게 두 가지 방식으로 나뉩니다. 제미나이 2.5 이상 모델에서 알아서 똑똑하게 작동하는 '암묵적 캐싱'과, 개발자가 코드로 직접 생성하고 기간을 제어하는 '명시적 캐싱'입니다. 이 글에서는 확실한 토큰 할인 혜택이 보장되어 지갑을 확실히 지켜주는 명시적 캐싱을 중점적으로 살펴보겠습니다.

토큰 몇 개부터 적용될까? 내 지갑을 지켜줄 새로운 비용 계산법

과거 제미나이 1.5 시절에는 최소 3만 2,768토큰 이상을 입력해야 캐싱을 쓸 수 있었습니다. 소규모 토이 프로젝트나 개인 개발자에게는 사실상 그림의 떡이나 다름없었죠. 하지만 최신 모델이 나오면서 이 문턱이 획기적으로 낮아졌습니다.

이제 제미나이 2.5 제품군은 최소 2,048토큰, 제미나이 3 및 3.5 제품군은 최소 4,096토큰만 넘으면 콘텍스트 캐싱을 즉시 적용할 수 있습니다. 웬만한 긴 기사나 소스 코드 파일 한두 개 수준만 되어도 가성비 혜택을 볼 수 있는 길이 열린 셈입니다.

비용 구조 역시 무척 합리적입니다. 캐시로 지정한 영역에서 데이터를 다시 읽어올 때는 입력 토큰 비용이 무려 90% 할인되어 원래 가격의 10% 수준만 지불하면 됩니다. 대신 캐시 데이터를 서버에 유지하는 동안 아주 소액의 시간당 보관 비용만 부담하는 방식입니다.

보관 비용은 모델의 체급에 따라 나뉩니다. 가볍고 빠른 플래시(Flash) 모델들은 100만 토큰당 1시간에 1.00달러가 청구되며, 고성능 프로(Pro) 모델들은 100만 토큰당 1시간에 4.50달러가 부과됩니다. 몇 시간 동안 켜두는 고객 응대 챗봇이나 코드 분석 툴이라면 보관료 몇 달러를 내고 수십, 수백 달러에 달하는 중복 입력 비용을 아낄 수 있습니다.

실제 코드로 1분 만에 캐싱 적용하기

명시적 캐싱을 적용하는 방법은 의외로 정말 간단합니다. 구글의 최신 공식 SDK인 @google/genai를 활용하면 몇 줄의 코드만으로 대용량 데이터를 구글 서버에 캐싱해두고 필요할 때마다 재사용할 수 있습니다.

먼저 구글 서버에 한 번 펼쳐둘 배경 지식이나 대형 문서를 지정하고 ai.caches.create()를 호출합니다. 이때 캐시가 유지될 생존 시간(TTL)을 지정할 수 있으며, 따로 적지 않으면 기본값인 1시간으로 설정됩니다. 캐시 등록이 완료되면 고유한 캐시 식별자인 cache.name을 받게 됩니다.

이후 질문을 보낼 때는 새로 발급받은 식별자를 cachedContent 설정에 담아 전달하기만 하면 끝납니다.

javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

// 1. 대용량 문서나 배경 데이터를 캐시로 등록합니다.
const cache = await ai.caches.create({
  model: 'gemini-2.5-flash',
  config: {
    displayName: 'large-doc-cache',
    ttl: '3600s', // 캐시 생존 시간 (기본값 1시간)
  },
  contents: [
    {
      role: 'user',
      parts: [{ text: '여기에 분석할 수만 글자의 대용량 소스 코드나 매뉴얼을 넣습니다.' }]
    }
  ]
});

// 2. 등록한 캐시를 지정하여 빠르게 질문을 보냅니다.
const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '위 소스 코드에서 개선할 점을 세 가지만 찾아줘.',
  config: {
    // 생성된 캐시 이름을 지정해 재사용합니다.
    cachedContent: cache.name,
  }
});

console.log(response.text);

여기서 실전에서 자주 실수하는 주의점이 하나 있습니다. 캐싱을 적용한 질문을 보낼 때는 시스템 지침(systemInstruction)이나 도구 설정(tools)을 요청 본문에 다시 중복해서 작성하면 안 됩니다.

이러한 설정들은 캐시를 처음 생성할 때 함께 저장되어 자동으로 상속됩니다. 질문을 보낼 때는 이 부분들을 비워두고 순수 질문만 넘겨야 오류 없이 깔끔하게 작동합니다.

내 프로젝트에 바로 도입해야 할까?

동일한 대형 문서나 장문의 소스 코드, 혹은 무거운 프롬프트를 붙잡고 유저와 여러 번 대화를 주고받는 서비스를 만들고 계시나요? 그렇다면 제미나이의 콘텍스트 캐싱은 그야말로 지갑을 지켜줄 든든한 아군이 될 것입니다. 단 몇 줄의 코드만 추가해도 매번 나가던 아까운 입력 토큰 비용을 최대 10분의 1 수준으로 아낄 수 있으니까요.

물론 가끔 한두 번 가벼운 질문을 던지는 단순한 챗봇이라면 캐싱을 굳이 설정할 필요가 없습니다. 오히려 저장 비용이 더 나갈 수도 있죠. 하지만 서비스 성격에 맞게 기준점인 2,048토큰 혹은 4,096토큰을 넘기는 작업이 많다면, 지금 바로 이 구글의 가성비 옵션을 켜고 똑똑하게 지갑을 지켜보세요!

아직 댓글이 없습니다.