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 è elencato nella tabella seguente per ciascun modello:

Modello Limite minimo di token
Anteprima di Gemini 3 Pro 4096
Gemini 2.5 Pro 4096
Gemini 2.5 Flash 1024

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

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

Puoi vedere il numero di token che sono stati riscontrati nella 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.

Generare contenuti utilizzando una cache

L'esempio seguente mostra come generare contenuti utilizzando un'istruzione di sistema memorizzata nella cache e un file di testo.

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const doc = await ai.files.upload({
    file: "path/to/file.txt",
    config: { mimeType: "text/plain" },
  });
  console.log("Uploaded file name:", doc.name);

  const modelName = "gemini-2.0-flash-001";
  const cache = await ai.caches.create({
    model: modelName,
    config: {
      contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
      systemInstruction: "You are an expert analyzing transcripts.",
    },
  });
  console.log("Cache created:", cache);

  const response = await ai.models.generateContent({
    model: modelName,
    contents: "Please summarize this transcript",
    config: { cachedContent: cache.name },
  });
  console.log("Response text:", response.text);
}

await main();

Elenca cache

Non è possibile recuperare o visualizzare i contenuti memorizzati nella cache, ma puoi recuperare i metadati della cache (name, model, displayName, usageMetadata, createTime, updateTime e expireTime).

Per elencare i metadati di tutte le cache caricate, utilizza GoogleGenAI.caches.list():

console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
  for (const c of page) {
    console.log("    ", c.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}

Aggiornare una cache

Puoi impostare un nuovo ttl o expireTime per una cache. La modifica di qualsiasi altro aspetto della cache non è supportata.

L'esempio seguente mostra come aggiornare ttl di una cache utilizzando GoogleGenAI.caches.update().

const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
  name: cache.name,
  config: { ttl },
});
console.log("After update (TTL):", updatedCache);

Eliminare una cache

Il servizio di memorizzazione nella cache fornisce un'operazione di eliminazione per rimuovere manualmente i contenuti dalla cache. L'esempio seguente mostra come eliminare una cache utilizzando GoogleGenAI.caches.delete().

await ai.caches.delete({ name: cache.name });

Memorizzazione nella cache esplicita 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. Numero di token della 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 sui prezzi aggiornati, 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 quanto segue:

  • Il conteggio dei token di input minimo per la memorizzazione nella cache del contesto è 1024 per 2.5 Flash, 4096 per 2.5 Pro e 2048 per 3 Pro Preview. Il massimo è uguale al massimo per il modello specificato. Per saperne di più sul conteggio dei token, consulta la guida ai token.
  • Il modello non fa distinzione tra i token memorizzati nella cache e i 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.