Memorizzazione nella cache del contesto

In un tipico workflow di AI, potresti passare gli stessi token di input più e più volte a un modello. L'API Gemini offre due diversi meccanismi di memorizzazione nella cache:

  • Memorizzazione implicita nella cache (attivata automaticamente sui modelli Gemini 2.5, senza garanzia di risparmio sui costi)
  • Memorizzazione nella cache esplicita (può essere attivata manualmente sulla maggior parte dei modelli, garanzia di risparmio sui costi)

La memorizzazione nella cache esplicita è utile nei casi in cui vuoi garantire un risparmio sui costi, ma con un po' di lavoro aggiuntivo per gli sviluppatori.

Memorizzazione nella cache implicita

La memorizzazione nella cache implicita è abilitata per impostazione predefinita per tutti i modelli Gemini 2.5. Trasmettiamo automaticamente i risparmi sui costi se la tua richiesta raggiunge le cache. Non devi fare nulla per abilitare questa funzionalità. È in vigore dall'8 maggio 2025. Il numero minimo di token di input per la memorizzazione nella cache del contesto è 1024 per 2.5 Flash e 4096 per 2.5 Pro.

Per aumentare la probabilità di un successo implicito della cache:

  • Prova a inserire contenuti grandi e comuni all'inizio del prompt.
  • Prova a inviare richieste con un prefisso simile in un breve periodo di tempo

Puoi visualizzare il numero di token che sono stati hit della cache nel campo usage_metadata dell'oggetto risposta.

Memorizzazione nella cache esplicita

Utilizzando la funzionalità di memorizzazione nella cache esplicita dell'API Gemini, puoi passare alcuni contenuti al modello una sola volta, memorizzare nella cache i token di input e poi fare riferimento ai token memorizzati nella cache per le richieste successive. A determinati volumi, l'utilizzo di token memorizzati nella cache è meno costoso rispetto al passaggio ripetuto dello stesso corpus di token.

Quando memorizzi nella cache un insieme di token, puoi scegliere per quanto tempo vuoi che la cache esista prima che i token vengano eliminati automaticamente. Questa durata della memorizzazione nella cache è chiamata durata (TTL). Se non viene impostato, il TTL è impostato su 1 ora per impostazione predefinita. Il costo della memorizzazione nella cache dipende dalle dimensioni dei token di input e dalla durata di permanenza dei token.

Questa sezione presuppone che tu abbia installato un SDK Gemini (o che tu abbia installato curl) e che tu abbia configurato una chiave API, come mostrato nella guida rapida.

Memorizzazione esplicita nella cache utilizzando la libreria OpenAI

Se utilizzi una libreria OpenAI, puoi attivare la memorizzazione nella cache esplicita utilizzando la proprietà cached_content su extra_body.

Quando utilizzare la memorizzazione esplicita nella cache

La memorizzazione nella cache del contesto è particolarmente adatta agli scenari in cui un contesto iniziale sostanziale viene referenziato ripetutamente da richieste più brevi. Valuta la possibilità di utilizzare la memorizzazione nella cache del contesto per casi d'uso come:

  • Chatbot con istruzioni di sistema dettagliate
  • Analisi ripetitiva di file video di grandi dimensioni
  • Query ricorrenti su grandi set di documenti
  • Analisi frequente del repository di codici o correzione di bug

In che modo la memorizzazione esplicita nella cache riduce i costi

La memorizzazione nella cache del contesto è una funzionalità a pagamento progettata per ridurre i costi operativi complessivi. La fatturazione si basa sui seguenti fattori:

  1. Conteggio token cache:il numero di token di input memorizzati nella cache, fatturati a una tariffa ridotta se inclusi nei prompt successivi.
  2. Durata dell'archiviazione: il periodo di tempo in cui i token memorizzati nella cache vengono archiviati (TTL), fatturato in base alla durata TTL del conteggio dei token memorizzati nella cache. Non esistono limiti minimi o massimi per il TTL.
  3. Altri fattori: si applicano altri addebiti, ad esempio per i token di input non memorizzati nella cache e per i token di output.

Per i dettagli aggiornati sui prezzi, consulta la pagina dei prezzi dell'API Gemini. Per scoprire come conteggiare i token, consulta la guida ai token.

Considerazioni aggiuntive

Quando utilizzi la memorizzazione nella cache del contesto, tieni presente le seguenti considerazioni:

  • Il conteggio dei token di input minimo per la memorizzazione nella cache del contesto è 1024 per 2.5 Flash e 2048 per 2.5 Pro. Il massimo è lo stesso del massimo per il modello specificato. Per saperne di più sul conteggio dei token, consulta la guida ai token.
  • Il modello non fa distinzione tra token memorizzati nella cache e token di input normali. I contenuti memorizzati nella cache sono un prefisso del prompt.
  • Non sono previsti limiti di utilizzo o tariffe speciali per la memorizzazione nella cache del contesto; si applicano i limiti di frequenza standard per GenerateContent e i limiti di token includono i token memorizzati nella cache.
  • Il numero di token memorizzati nella cache viene restituito in usage_metadata dalle operazioni di creazione, recupero ed elenco del servizio di cache e anche in GenerateContent quando si utilizza la cache.