Context Caching di Gemini — Riduci i Costi delle API con Documenti Lunghi e Ripetuti

Stai pagando per inviare lo stesso documento di 100 pagine a ogni chiamata API Gemini? È come commissionare una traduzione integrale ogni volta che fai una domanda. Il Context Caching di Gemini è la soluzione che taglia i costi di input token fino al 90% nelle applicazioni con contesti stabili e ripetuti. No, di Meteora Web, lo abbiamo implementato su progetti reali per clienti che analizzavano manuali tecnici, contratti legali e documentazione di prodotto. Vediamo come funziona e come metterlo in produzione subito.

Che cos’è il Context Caching di Gemini e perché ti fa risparmiare?

Il Context Caching è una funzionalità di Gemini API (modelli come Gemini 1.5 Pro e Flash) che permette di memorizzare un contesto – un documento, una conversazione lunga, un set di istruzioni – e riutilizzarlo su più richieste, pagando solo per la differenza (ogni nuovo token inviato) invece che per l’intero contesto ogni volta.

Il risparmio è diretto: se hai un documento di 200.000 token che invii ad ogni query, con il caching paghi una volta lo storage (costo fisso orario) e poi solo i token di domanda e risposta. Per 100 query al giorno, il costo scende drasticamente. Noi abbiamo visto un cliente passare da 0,50 € a 0,05 € per richiesta su documenti tecnici di prodotto.

Questa tecnologia è ideale per: chatbot con knowledge base personalizzata, analisi ricorrenti di contratti, documenti legali, manualistica, assistenti che lavorano su un set di documenti statici per sessioni lunghe.

Come funziona il Context Caching di Gemini?

Il meccanismo è semplice: carichi un contenuto una volta (un file, un testo, una lista di messaggi) e ottieni un identificatore univoco (cachedContent). Poi, nelle chiamate successive, passi quell’identificatore invece del contenuto originale. Gemini recupera il contesto dalla cache e processa solo i nuovi token (domande dell’utente, eventuali aggiornamenti).

Cosa si può mettere in cache? Qualsiasi cosa che andrebbe nel parametro contents di una richiesta: array di messaggi (chat), file PDF/immagini convertiti in token (con il supporto multimodale), testi lunghi. L’unico limite è la finestra di contesto del modello (fino a 1 milione di token per Gemini 1.5 Pro).

TTL (Time-To-Live) configurabile: puoi impostare per quanto tempo la cache rimane attiva (da pochi minuti a 30 giorni). Scaduto, paghi solo per la ricarica. Ideale per sessioni giornaliere o settimanali.

I costi: lo storage si paga a ore (es. 0,10 €/ora per 200K token su Gemini 1.5 Flash – verifica sempre su ai.google.dev/pricing). Il risparmio è enorme quando invii molte richieste con lo stesso contesto.

Come implementare il Context Caching con Gemini API in Python?

Vediamo il codice. Usiamo la libreria ufficiale google-generativeai (versione ≥0.7.0).

Passo 1: Installazione e configurazione

pip install google-generativeai

import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")

Passo 2: Creare una cache da un testo lungo

# Esempio: documento di 100 pagine in una stringa
long_text = open("manuale.pdf", "r", encoding="utf-8").read()  # meglio tokenizzarlo

# Crea il modello
model = genai.GenerativeModel("models/gemini-1.5-flash")

# Crea il contenuto da cache (usa un singolo messaggio di sistema o utente)
cached_content = genai.caching.CachedContent.create(
    model="models/gemini-1.5-flash",
    contents=[
        {
            "role": "user",
            "parts": [long_text]
        }
    ],
    ttl=3600  # 1 ora
)
cached_content.name  # es. 'cachedContents/abc123'

Passo 3: Usare la cache nelle richieste

# Recupera la cache per id
cache = genai.caching.CachedContent.get("cachedContents/abc123")

# Crea un modello che punti alla cache
model_cached = genai.GenerativeModel(
    "models/gemini-1.5-flash",
    cached_content=cache
)

# Ora fai domande
response = model_cached.generate_content("Qual è il capitolo sulla manutenzione?")
print(response.text)

Nota: puoi anche passare il nome della cache direttamente al parametro cached_content in generate_content, ma il metodo sopra è più pulito.

Passo 4: Aggiornare il TTL e cancellare

# Estendi la cache di altre 2 ore
cache.update(ttl=7200)

# Cancella quando non serve più
cache.delete()

Quali sono i limiti e le best practice del Context Caching?

Limiti:

• La cache è una risorsa condivisa e ha un costo di storage orario. Se fai poche richieste, conviene non usarla.
• Non puoi modificare il contesto interno senza ricreare la cache. Se il documento cambia spesso, devi invalidare e ricaricare.
• Funziona solo con modelli Gemini 1.5 Pro e Flash (non con modelli precedenti).

Best practice da Meteora Web:

• Calcola il break-even: per file <10.000 token e meno di 10 richieste al giorno, conviene pagare l’input normale. Oltre, il caching è vincente.
• Imposta TTL in base alla sessione: per assistenti giornalieri usa 24 ore; per documenti fissi, 7-30 giorni.
• Monitora i costi: usa la console Google Cloud per vedere lo storage, e i log delle API per tracciare le richieste.
• Ottimizza il contenuto: prima di cache, riduci il testo a ciò che serve (rimuovi boilerplate, indici). Minori token = minori costi di storage.

Cosa fare adesso

1. Identifica nel tuo progetto i pattern di ripetizione: stesso documento inviato a più chiamate? Lista dei prodotti? Contratto legale?
2. Integra il codice sopra nel tuo backend (Python, Node.js, Go – SDK supportano tutti).
3. Testa con un documento di 50.000 token e misura il risparmio sui costi dopo 10-20 richieste.
4. Leggi la documentazione ufficiale per approfondire: Google AI – Context Caching.
5. Se vuoi un supporto personalizzato per la tua architettura AI, torna alla nostra guida pillar su Gemini API.

Noi di Meteora Web usiamo il Context Caching da quando è uscito. Sui progetti che lo meritano, il risparmio è netto e immediato. Provalo.