Starting November 2, 2026, Firebase App Check enforcement will be required to use Firebase AI Logic. Learn more.

Model updates:

Gemini 4 Argon is now available to use with Firebase AI Logic! Learn more.
Gemini 2.5 models are limited to projects that actively used them in the past. For the Agent Platform Gemini API, these models will shut down for all projects in October 2026. To avoid service disruptions, update to a newer model (like gemini-4-argon, gemini-3.8-flash, or gemini-3.1-flash-image). Any stable Gemini Live API 2.5 models are not impacted. Learn more.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Memorizzazione nella cache del contesto in Firebase AI Logic

Per la tua funzionalità di AI, potresti passare gli stessi token di input (contenuti) più e più volte a un modello. Per questi casi d'uso, puoi invece memorizzare nella cache questi contenuti, ovvero passarli al modello una sola volta, memorizzarli 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, codebase o manuali dettagliati delle buyer persona.

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

Memorizzazione implicita nella cache: automaticamente abilitata sulla maggior parte dei modelli, nessun risparmio sui costi garantito
Memorizzazione esplicita nella cache: può essere attivata facoltativamente e manualmente sulla maggior parte dei modelli, di solito si traduce in un risparmio sui costi

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

Per la memorizzazione nella cache implicita ed 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-3.1-pro-preview
gemini-3.8-flash (e le versioni precedenti gemini-3.7-flash, gemini-3.6-flash e gemini-3.5-flash)
gemini-3.5-flash-lite (e il precedente gemini-3.1-flash-lite)

I modelli Gemini 2.5 di uso generale supportano questa funzionalità, ma sono tutti deprecati.

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

Modelli Gemini Pro: minimo 4096 token
Gemini Modelli Flash: minimo 1024 token

Inoltre, la dimensione massima dei contenuti che puoi memorizzare nella cache utilizzando un blob o un testo è 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 tua richiesta raggiunge i contenuti memorizzati nella cache. Ecco alcuni modi per aumentare la probabilità che la tua richiesta utilizzi la memorizzazione implicita nella cache:

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 dei metadati di una risposta.

Memorizzazione nella cache esplicita

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

Ecco come configurare e utilizzare le cache di contenuti espliciti:

Crea e utilizza una cache esplicita
Gestisci le cache esplicite, tra cui:

Tieni presente che le cache dei contenuti espliciti interagiscono con la memorizzazione nella cache implicita, il che potrebbe comportare una memorizzazione nella cache aggiuntiva oltre ai contenuti espliciti memorizzati nella cache. Puoi impedire la conservazione dei dati della cache disattivando la memorizzazione nella cache implicita e non creando cache esplicite. Per maggiori informazioni, consulta Attivare e disattivare la memorizzazione nella cache.

Creare e utilizzare una cache esplicita

La creazione e l'utilizzo di una cache di contenuti espliciti richiedono quanto segue:

Crea una cache esplicita.
Fai riferimento alla cache in un modello di prompt del server.
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 dell'app deve utilizzare lo stesso provider.
Per Firebase AI Logic, ti consigliamo vivamente di utilizzare cache di contenuti espliciti solo con Agent Platform Gemini API (formerly Vertex AI). Tutte le informazioni e gli esempi in questa pagina sono specifici per il fornitore 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 posizione quando si utilizza Agent Platform Gemini API (formerly Vertex AI).
La posizione della cache esplicita deve corrispondere alla posizione del template di prompt del server e alla posizione in cui accedi al modello nella richiesta di prompt della tua app.

Tieni inoltre presente le seguenti limitazioni e i seguenti requisiti per la memorizzazione esplicita nella cache:

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 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 o strumenti di sistema (come l'esecuzione di codice, il contesto URL, Grounding con Google Search o Grounding 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 modelli di template di prompt del server non supportano ancora la chiamata 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 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 completamente qualificata che è univoca a livello globale per la cache (tieni presente che l'ultimo segmento è l'ID cache). Utilizzerai l'intero valore di 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.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 name all'interno della proprietà cachedContent di un template di prompt del server.

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

Utilizza la risorsa completamente qualificata name della risposta quando hai creato la cache. Non si tratta del nome visualizzato facoltativo che hai specificato nella richiesta.
La posizione 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 della 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 questo provider Gemini API.
La posizione in cui accedi al modello nella richiesta di prompt della tua app deve corrispondere alla posizione del modello 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.
  'TEMPLATE_ID'
);

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',
      );

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"
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Gestisci cache esplicite

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

Gestisci 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 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

Recuperare i metadati di una cache

Non è possibile recuperare o visualizzare i contenuti memorizzati nella cache effettivi. 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, ovvero l'ultimo segmento della risorsa completamente qualificata name 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}

Aggiornare 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 in cui la cache rimane attiva dopo la creazione o dopo l'aggiornamento di 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 è 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, ovvero l'ultimo segmento della risorsa completamente qualificata name 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'"
}'

Eliminare una cache

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