Memorizzazione nella cache del contesto in Firebase AI Logic

Per la tua funzionalità di AI, potresti passare ripetutamente gli stessi token di input (contenuti) a un modello. Per questi casi d'uso, puoi invece memorizzare nella cache questi contenuti, ovvero passarli al modello una volta, archiviarli e farvi riferimento nelle richieste successive.

La memorizzazione nella cache del contesto può ridurre significativamente la latenza e i costi per le attività ripetitive che coinvolgono una grande quantità di contenuti, come grandi quantità di testo, un file audio o un file video. Alcuni casi d'uso comuni per i contenuti memorizzati nella cache includono documenti dettagliati sui profili utente, codebase o manuali.

I modelli Gemini offrono due diversi meccanismi di memorizzazione nella cache:

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

Sia per la memorizzazione nella cache implicita che per quella esplicita, il campo cachedContentTokenCount nei metadati della risposta indica il numero di token nella parte memorizzata nella cache dell'input. Per la memorizzazione nella cache esplicita, assicurati di esaminare le informazioni sui prezzi in fondo a questa pagina.

Modelli supportati

La memorizzazione nella cache è supportata quando utilizzi i seguenti modelli:

  • gemini-4-argon (solo memorizzazione nella cache implicita; la memorizzazione nella cache esplicita non è supportata)
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (e il precedente gemini-3.1-flash-lite)

I modelli Gemini 3.x Flash e Gemini 2.5 di uso generale meno recenti supportano questa funzionalità, ma non è più consigliato utilizzarli a causa delle date di arresto imminenti e/o del routing automatico ai modelli più recenti.

I modelli di generazione di contenuti multimediali (ad esempio i modelli Gemini Nano Banana come gemini-nano-banana-2.1) non supportano la memorizzazione nella cache del contesto.

Limiti di dimensione dei contenuti memorizzati nella cache

Ogni modello ha un requisito di conteggio dei token minimo per i contenuti memorizzati nella cache. Il valore massimo è dettato dalla finestra di contesto del modello.

  • Gemini 4 Argon: minimo 4096 token (Gemini Developer API) o minimo 6144 token (Agent Platform Gemini API (formerly Vertex AI))
  • Modelli Gemini Pro: minimo 4096 token
  • Modelli Gemini Flash: minimo 1024 token

Inoltre, la dimensione massima dei contenuti che puoi memorizzare nella cache utilizzando un blob o un testo è di 10 MB.


Memorizzazione nella cache implicita

La memorizzazione nella cache implicita è abilitata per impostazione predefinita e disponibile per la maggior parte dei modelli Gemini.

Google trasferisce automaticamente i risparmi sui costi se la tua richiesta raggiunge i contenuti memorizzati nella cache. Ecco alcuni modi per aumentare la probabilità che la tua richiesta utilizzi la memorizzazione nella cache implicita:

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

Il numero di token nella parte memorizzata nella cache dell'input è fornito nel campo cachedContentTokenCount nei metadati di una risposta.


Memorizzazione nella cache esplicita

La memorizzazione nella cache esplicita non è abilitata per impostazione predefinita ed è una funzionalità facoltativa dei modelli Gemini.

Tieni presente che il modello gemini-4-argon non supporta la memorizzazione nella cache esplicita.

Ecco come configurare e utilizzare le cache dei contenuti espliciti:

Tieni presente che le cache dei contenuti espliciti interagiscono con la memorizzazione nella cache implicita, il che potrebbe portare a una memorizzazione nella cache aggiuntiva oltre ai contenuti memorizzati nella cache esplicita. Puoi impedire la conservazione dei dati della cache disabilitando la memorizzazione nella cache implicita e non creando cache esplicite. Per saperne di più, consulta Abilita e disabilita la memorizzazione nella cache.


Crea e utilizza una cache esplicita

Per creare e utilizzare una cache dei contenuti esplicita, è necessario quanto segue:

  1. Crea una cache esplicita.

  2. Fai riferimento alla cache in un template di prompt del server.

  3. Fai riferimento al template di prompt del server in una richiesta di prompt dalla tua app.

Informazioni importanti sulla creazione e sull'utilizzo di una cache esplicita

La cache deve essere allineata alle richieste di prompt dell'app e al template di prompt del server:

  • La cache è specifica per un provider Gemini API. La richiesta di prompt della tua app deve utilizzare lo stesso provider.
    Per Firebase AI Logic, consigliamo vivamente di utilizzare cache dei contenuti esplicite solo con Agent Platform Gemini API (formerly Vertex AI). Tutte le informazioni e gli esempi riportati in questa pagina sono specifici per il provider Gemini API.

  • La cache è specifica per un modello Gemini. La richiesta di prompt dell'app deve utilizzare lo stesso modello.

  • La cache è specifica per una località quando utilizzi Agent Platform Gemini API (formerly Vertex AI).
    La località della cache esplicita deve corrispondere alla località del template di prompt del server e alla località da cui accedi al modello nella richiesta di prompt della tua app.

Inoltre, tieni presente le seguenti limitazioni e i seguenti requisiti per la memorizzazione nella cache esplicita:

  • Una volta creata una cache esplicita, non puoi modificarla, ad eccezione del TTL o della scadenza.

  • Puoi memorizzare nella cache qualsiasi tipo MIME di file di input supportato o anche solo il testo fornito nella richiesta di creazione della cache.

  • Se vuoi includere un file nella cache, devi fornirlo come URI Cloud Storage. Non può essere un URL del browser o di YouTube.

    Inoltre, le limitazioni di accesso al file vengono controllate al momento della creazione della cache e non vengono controllate di nuovo al momento della richiesta dell'utente. Per questo motivo, assicurati che tutti i dati inclusi nella cache esplicita siano adatti a qualsiasi utente che effettua una richiesta che include la cache.

  • Se vuoi utilizzare istruzioni di sistema o strumenti (come l'esecuzione di codice, il contesto dell'URL, la base con Google Search o la base con Google Maps), la cache stessa deve contenere le relative configurazioni. Non possono essere configurati nel template di prompt del server o nella richiesta di prompt dell'app. Tieni presente che i template di prompt del server non supportano ancora la chiamata di funzione (o la chat). Per informazioni dettagliate su come configurare le istruzioni di sistema e gli strumenti nella cache, consulta l'API REST di Agent Platform Gemini API (formerly Vertex AI).

Passaggio 1: crea la cache

Crea la cache utilizzando direttamente l'API REST di Agent Platform Gemini API (formerly Vertex AI).

Di seguito è riportato un esempio che crea una cache esplicita di un file PDF come contenuto.

Sintassi:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3.8-flash
LOCATION="LOCATION"  # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI"  # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME"  # optional
TTL="CACHE_TIME_TO_LIVE"  # optional (if not specified, defaults to 3600s)

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Esempio di richiesta:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.8-flash"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Esempio di risposta:

La risposta include una risorsa name con nome completo, che è univoca a livello globale per la cache (tieni presente che l'ultimo segmento è l'ID cache). Utilizzerai l'intero valore name nel passaggio successivo del workflow.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.8-flash",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Passaggio 2: fai riferimento alla cache in un template di prompt del server

Dopo aver creato la cache, fai riferimento a questa tramite name all'interno della proprietà cachedContent di un template di prompt del server.

Assicurati di seguire questi requisiti quando crei il tuo template di prompt del server:

  • Utilizza la risorsa con nome completo name dalla risposta quando hai creato la cache. Questo non è il nome visualizzato facoltativo specificato nella richiesta.

  • La località del template di prompt del server deve corrispondere a quella della cache.

  • Per utilizzare le istruzioni o gli strumenti di sistema, questi devono essere configurati come parte della cache e non come parte del template di prompt del server.

Sintassi:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

Esempio:

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

In alternativa, il valore del parametro name nel template di prompt del server può essere una variabile di input dinamica. Ad esempio, {{cachedContent name=someVariable}} ti consente di includere name della cache come input per la richiesta dalla tua app.

Passaggio 3: fai riferimento al template di prompt del server nella richiesta dalla tua app

Quando scrivi la richiesta, presta molta attenzione a quanto segue:

  • Utilizza Agent Platform Gemini API (formerly Vertex AI), poiché la cache è stata creata con quel provider Gemini API.

  • La località da cui accedi al modello nella richiesta di prompt della tua app deve corrispondere alla località del template di prompt del server e della cache.

Swift 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION"))
                                  .templateGenerativeModel()

do {
    let response = try await model.generateContent(
        // Specify your template ID.
        templateID: "TEMPLATE_ID"
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID.
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
      .templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

Future<GenerateContentResponse> response = model.generateContent(
    // Specify your template ID.
    "TEMPLATE_ID"
);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

Web 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent({
  // Specify your template ID.
  templateId: 'TEMPLATE_ID',
  templateVariables: {},
});

const response = result.response;
const text = response.text();

Dart 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
var _model = FirebaseAI.agentPlatform(location: 'LOCATION').templateGenerativeModel();

var response = await _model.generateContent(
        // Specify your template ID.
        'TEMPLATE_ID',
        inputs: {},
      );

var text = response?.text;
print(text);

Unity 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID.
      "TEMPLATE_ID",
      new Dictionary<string, object>()
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}


Gestisci le cache esplicite

Questa sezione descrive la gestione delle cache di contenuti espliciti, tra cui come elencare tutte le cache, recuperare i metadati relativi a una cache, aggiornare il TTL o la data/ora di scadenza di una cache e eliminare una cache.

Puoi gestire le cache esplicite utilizzando l'API REST di Agent Platform Gemini API (formerly Vertex AI).

Una volta creata una cache di contenuti espliciti, non puoi modificarne nulla, ad eccezione del TTL o della data di scadenza.

Elenca tutte le cache

Puoi elencare tutte le cache esplicite disponibili per il tuo progetto. Questo comando restituirà solo le cache nella località specificata.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

Recupera i metadati di una cache

Non è possibile recuperare o visualizzare i contenuti effettivi memorizzati nella cache. Tuttavia, puoi recuperare i metadati relativi a una cache esplicita, tra cui name, model, display_name, usage_metadata, create_time, update_time e expire_time.

Devi fornire CACHE_ID, ovvero il segmento finale della risorsa name della cache con nome completo.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}

Aggiorna il TTL o la data di scadenza di una cache

Quando crei una cache esplicita, puoi facoltativamente impostare ttl o expire_time.

  • ttl: il TTL (durata) della cache, in particolare il numero di secondi e nanosecondi di durata della cache dopo la sua creazione o dopo l'aggiornamento di ttl prima della scadenza. Quando imposti ttl, expireTime della cache viene aggiornato automaticamente.

  • expire_time: un Timestamp (come 2024-06-30T09:00:00.000000Z) che specifica la data e l'ora assolute di scadenza della cache.

Se non imposti nessuno di questi valori, il TTL predefinito è di 1 ora. Non esistono limiti minimi o massimi per il TTL.

Per le cache esplicite esistenti, puoi aggiungere o aggiornare ttl o expire_time. Devi fornire CACHE_ID, che è il segmento finale della risorsa name della cache con nome completo.

Aggiorna ttl

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "ttl": "'$TTL'"
}'

Aggiorna expire_time

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "expire_time": "'$EXPIRE_TIME'"
}'

Elimina una cache

Quando una cache esplicita non è più necessaria, puoi eliminarla.

Devi fornire CACHE_ID, ovvero il segmento finale della risorsa name della cache con nome completo.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}


Prezzi per la memorizzazione nella cache esplicita

La memorizzazione nella cache esplicita è una funzionalità a pagamento progettata per ridurre i costi. I prezzi si basano sui seguenti fattori:

  • Token di input per la creazione della cache: sia per la memorizzazione nella cache implicita che per quella esplicita, ti vengono addebitati i token di input utilizzati per creare la cache al prezzo standard dei token di input.

  • Archiviazione della cache: per la memorizzazione esplicita nella cache, sono previsti anche costi di archiviazione in base alla durata della memorizzazione nella cache. Non sono previsti costi di archiviazione per la memorizzazione nella cache implicita. Per saperne di più, consulta i prezzi per Agent Platform Gemini API (formerly Vertex AI).

  • Utilizzo dei contenuti memorizzati nella cache: la memorizzazione esplicita nella cache garantisce uno sconto quando si fa riferimento alle cache esplicite, il che significa che ricevi uno sconto sui token di input quando fanno riferimento a una cache esistente. Per i modelli Gemini 2.5 e successivi, questo sconto è del 90%.

Il numero di token nella parte memorizzata nella cache dell'input è fornito nel campo cachedContentTokenCount nei metadati di una risposta.