Memorizzazione nella cache del contesto in Firebase AI Logic

Per la tua funzionalità di AI, potresti passare gli stessi token di input (contenuti) più volte a un modello. Per questi casi d'uso, puoi invece memorizzare nella cache questi contenuti, il che significa che li passi al modello una sola volta, li memorizzi e fai riferimento a essi 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 di persona dettagliati, codebase o manuali.

Gemini modelli offrono due meccanismi di memorizzazione nella cache diversi:

La memorizzazione nella cache esplicita è utile nei casi in cui vuoi garantire più probabilmente un risparmio sui costi, ma con un po' di lavoro di sviluppo aggiuntivo.

Sia per la memorizzazione nella cache implicita sia 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 nella parte inferiore di questa pagina.

Modelli supportati

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

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite-preview
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

I modelli di generazione di contenuti multimediali (ad esempio i modelli Nana Banana come gemini-3.1-flash-image-preview) 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 è determinato dalla finestra contestuale del modello.

  • Gemini Modelli 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 ed è disponibile per la maggior parte dei modelli Gemini.

Google trasferisce automaticamente i risparmi sui costi se la richiesta raggiunge i contenuti memorizzati nella cache. Ecco alcuni modi per aumentare la probabilità che la 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.

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 disattivando la memorizzazione nella cache implicita e non creando cache esplicite. Per ulteriori informazioni, vedi Attivare e disattivare la memorizzazione nella cache.


Crea e utilizza una cache esplicita

Per creare e utilizzare una cache dei contenuti esplicita, devi:

  1. Crea una cache esplicita.

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

  3. Fai riferimento al modello 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 modello di prompt del server:

  • La cache è specifica per un Gemini API provider. La richiesta di prompt dell'app deve utilizzare lo stesso provider.
    Per Firebase AI Logic, ti consigliamo vivamente di utilizzare le cache dei contenuti espliciti solo con Vertex AI Gemini API. Tutte le informazioni e gli esempi in questa pagina sono specifici per questo Gemini API provider.

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

  • La cache è specifica per una località quando si utilizza la Vertex AI Gemini API.
    La località della cache esplicita deve corrispondere alla località del modello di prompt del server e alla località in cui accedi al modello nella richiesta di prompt dell'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 modificare nulla della cache, tranne il TTL o l'ora di 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 un Cloud Storage URI. Non può essere un URL del browser o un URL di YouTube.

    Inoltre, le limitazioni di accesso al file vengono controllate al momento della creazione della cache e le limitazioni di accesso 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 o strumenti di sistema (come l'esecuzione di codice, il contesto URL o il grounding con la Ricerca Google), la cache stessa deve contenere le relative configurazioni. Non possono essere configurati nel modello di prompt del server o nella richiesta di prompt dell'app. Tieni presente che i modelli di prompt del server non supportano ancora le chiamate di funzioni (o la chat). Per informazioni dettagliate su come configurare le istruzioni e gli strumenti di sistema nella cache, consulta l' API REST di Vertex AI Gemini API.

Passaggio 1: crea la cache

Crea la cache utilizzando direttamente l' API REST del Vertex AI Gemini API.

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

Sintassi:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
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

Richiesta di esempio:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3-flash-preview"
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

Risposta di esempio:

La risposta include un name della risorsa completo, univoco a livello globale per la cache (tieni presente che l'ultimo segmento è l'ID cache). Utilizzerai l'intero valore name nel passaggio successivo del flusso di lavoro.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3-flash-preview",
  "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 modello di prompt del server

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

Assicurati di soddisfare questi requisiti quando crei il modello di prompt del server:

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

  • La località del modello di prompt del server deve corrispondere alla località della cache.

  • Per utilizzare istruzioni o strumenti di sistema, devono essere configurati come parte della cache e non come parte del modello 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 name parametro nel modello di prompt del server può essere una variabile di input dinamica. Ad esempio, {{cachedContent name=someVariable}} ti consente di includere il name della cache come input per la richiesta da tua app.

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

Fai molta attenzione a quanto segue quando scrivi la richiesta:

  • Utilizza il Vertex AI Gemini API, poiché la cache è stata creata con quel Gemini API provider.

  • La località in cui accedi al modello nella richiesta di prompt dell'app deve corrispondere alla località del modello di prompt del server e della cache.

Swift 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(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 Vertex AI Gemini API backend service
// 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.vertexAI(location = "LOCATION"))
                        .templateGenerativeModel()

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

val text = response.text
println(text)

Java 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().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 Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('LOCATION') });

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

const result = await model.generateContent(
  // Specify your template ID
  'TEMPLATE_ID'
);

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

Dart 

// ...

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

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

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

Unity 

// ...

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

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

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID
      "TEMPLATE_ID"
  );
  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 dei contenuti espliciti, inclusi come elencare tutte le cache, recuperare i metadati di una cache, aggiornare il TTL o l'ora di scadenza di una cache, e eliminare una cache.

Gestisci le cache esplicite utilizzando l' API REST del Vertex AI Gemini API.

Una volta creata una cache dei contenuti esplicita, non puoi modificare nulla della cache, tranne il TTL o l'ora 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 memorizzati nella cache. Tuttavia, puoi recuperare i metadati di una cache esplicita, inclusi name, model, display_name, usage_metadata, create_time, update_time, e expire_time.

Devi fornire CACHE_ID, che è l'ultimo segmento del name della risorsa completo della cache.

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 l'ora di scadenza di una cache

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

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

  • expire_time: un Timestamp (ad esempio 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 è l'ultimo segmento del name della risorsa completo della cache.

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 non hai più bisogno di una cache esplicita, puoi eliminarla.

Devi fornire CACHE_ID, che è l'ultimo segmento del name della risorsa completo della cache.

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 sia 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 nella cache esplicita, sono previsti anche costi di archiviazione in base alla durata di archiviazione delle cache. Non sono previsti costi di archiviazione per la memorizzazione nella cache implicita. Per ulteriori informazioni, consulta i prezzi per Vertex AI Gemini API.

  • Utilizzo dei contenuti memorizzati nella cache: la memorizzazione nella cache esplicita garantisce uno sconto quando si fa riferimento alle cache esplicite, il che significa che ottieni 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.