The latest Gemini models, like Gemini 3.1 Flash Image (Nano Banana 2), are available to use with Firebase AI Logic! Learn more.

Gemini 2.0 Flash and Flash-Lite models will shut down on June 1, 2026. To avoid service disruption, update to a newer model like gemini-2.5-flash-lite. Learn more.

All Imagen models will shut down on June 24, 2026. Learn about migrating your apps to use Nano Banana.

Mise en cache du contexte dans Firebase AI Logic

Pour votre fonctionnalité d'IA, vous pouvez transmettre les mêmes jetons d'entrée (contenu) à un modèle de manière répétée. Dans ces cas d'utilisation, vous pouvez plutôt mettre en cache ce contenu, ce qui signifie que vous le transmettez au modèle une seule fois, que vous le stockez et que vous y faites référence dans les requêtes suivantes.

La mise en cache du contexte peut réduire considérablement la latence et les coûts pour les tâches répétitives impliquant une grande quantité de contenu, comme de grandes quantités de texte, un fichier audio ou un fichier vidéo. Parmi les cas d'utilisation courants du contenu mis en cache, on trouve les documents de persona détaillés, les bases de code ou les manuels.

Gemini modèles proposent deux mécanismes de mise en cache différents :

Mise en cache implicite : activée automatiquement sur la plupart des modèles, aucune économie de coûts garantie
Mise en cache explicite : peut être activée manuellement et facultativement sur la plupart des modèles, entraîne généralement des économies de coûts

La mise en cache explicite est utile lorsque vous souhaitez garantir plus facilement des économies de coûts, mais avec un travail de développement supplémentaire.

Pour la mise en cache implicite et explicite, le champ cachedContentTokenCount des métadonnées de votre réponse indique le nombre de jetons dans la partie mise en cache de votre entrée. Pour la mise en cache explicite, veillez à consulter les informations sur les tarifs en bas de cette page.

Modèles compatibles

La mise en cache est compatible avec les modèles suivants :

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

Les modèles de génération de médias (par exemple, les modèles Nana Banana tels que gemini-3.1-flash-image-preview) ne sont pas compatibles avec la mise en cache du contexte.

Limites de taille du contenu mis en cache

Chaque modèle est soumis à une exigence de nombre de jetons minimal pour le contenu mis en cache. Le maximum est dicté par la fenêtre de contexte du modèle.

Gemini Modèles Pro : 4 096 jetons minimum
Modèles Flash Gemini : 1 024 jetons minimum

De plus, la taille maximale du contenu que vous pouvez mettre en cache à l'aide d'un blob ou d'un texte est de 10 Mo.

Mise en cache implicite

La mise en cache implicite est activée par défaut et disponible pour la plupart des Gemini modèles.

Google répercute automatiquement les économies de coûts si votre requête atteint le contenu mis en cache. Voici quelques façons d'augmenter les chances que votre requête utilise la mise en cache implicite :

Essayez de placer du contenu volumineux et courant au début de votre prompt.
Essayez d'envoyer des requêtes avec un préfixe similaire dans un court laps de temps.

Le nombre de jetons dans la partie mise en cache de votre entrée est fourni dans le champ cachedContentTokenCount des métadonnées d'une réponse.

Mise en cache explicite

La mise en cache explicite n'est pas activée par défaut et constitue une fonctionnalité facultative des modèles Gemini.

Voici comment configurer et utiliser des caches de contenu explicites :

Créer et utiliser un cache explicite
Gérer les caches explicites, y compris :

Notez que les caches de contenu explicites interagissent avec la mise en cache implicite, ce qui peut entraîner une mise en cache supplémentaire au-delà du contenu mis en cache explicite. Vous pouvez empêcher la conservation des données de cache en désactivant la mise en cache implicite et en ne créant pas de caches explicites. Pour en savoir plus, consultez Activer et désactiver la mise en cache.

Créer et utiliser un cache explicite

Pour créer et utiliser un cache de contenu explicite, vous devez procéder comme suit :

Créez un cache explicite.
Faites référence au cache dans un modèle de prompt côté serveur.
Faites référence au modèle de prompt côté serveur dans une requête de prompt depuis votre application.

Informations importantes sur la création et l'utilisation d'un cache explicite

Votre cache doit être aligné sur les requêtes de prompt de votre application et sur votre modèle de prompt côté serveur :

Le cache est spécifique à un Gemini API fournisseur. La requête de prompt de votre application doit utiliser le même fournisseur.
Pour Firebase AI Logic, nous vous recommandons vivement d'utiliser des caches de contenu explicites uniquement avec Vertex AI Gemini API. Toutes les informations et exemples de cette page sont spécifiques à ce fournisseur Gemini API.
Le cache est spécifique à un Gemini modèle. La requête de prompt de votre application doit utiliser le même modèle.
Le cache est spécifique à un emplacement lorsque vous utilisez le Vertex AI Gemini API.
L'emplacement du cache explicite doit correspondre à celui du modèle de prompt côté serveur et à celui où vous accédez au modèle dans la requête de prompt de votre application.

Tenez également compte des limites et exigences suivantes pour la mise en cache explicite :

Une fois qu'un cache explicite est créé, vous ne pouvez rien modifier à son sujet, à l'exception de la valeur TTL ou du délai d'expiration.
Vous pouvez mettre en cache n'importe quel type MIME de fichier d'entrée compatible ou même simplement le texte fourni dans la requête de création du cache.
Si vous souhaitez inclure un fichier dans le cache, vous devez le fournir en tant qu' Cloud Storage URI. Il ne peut pas s'agir d'une URL de navigateur ni d'une URL YouTube.

De plus, les restrictions d'accès au fichier sont vérifiées au moment de la création du cache, et les restrictions d'accès ne sont pas vérifiées à nouveau au moment de la requête de l'utilisateur. Pour cette raison, assurez-vous que toutes les données incluses dans le cache explicite conviennent à tout utilisateur effectuant une requête incluant ce cache.
Si vous souhaitez utiliser des instructions ou des outils système (tels que l'exécution de code, le contexte d'URL ou l'ancrage avec la recherche Google), le cache lui-même doit contenir leurs configurations. Ils ne peuvent pas être configurés dans le modèle de prompt côté serveur ni dans la requête de prompt de votre application. Notez que les modèles de prompts côté serveur ne sont pas encore compatibles avec l'appel de fonction (ni le chat). Pour savoir comment configurer des instructions et des outils système dans votre cache, consultez l'API REST de Vertex AI Gemini API.

Étape 1 : Créez le cache

Créez le cache en utilisant directement l' API REST de l'Vertex AI Gemini API.

L'exemple suivant crée un cache explicite d'un fichier PDF en tant que contenu.

Syntaxe :

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

Exemple de requête :

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

Exemple de réponse :

La réponse inclut un name de ressource complet qui est globalement unique au cache (notez que le dernier segment est l'ID du cache). Vous utiliserez cette valeur name complète à l'étape suivante du workflow.

{
  "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"
}

Étape 2 : Faites référence au cache dans un modèle de prompt côté serveur

Après avoir créé le cache, faites-y référence par name dans la cachedContent propriété d'un modèle de prompt côté serveur.

Assurez-vous de respecter les exigences suivantes lorsque vous créez votre modèle de prompt côté serveur :

Utilisez le name de ressource complet de la réponse lorsque vous avez créé le cache. Il ne s'agit pas du nom à afficher facultatif que vous avez spécifié dans la requête.
L' emplacement du modèle de prompt côté serveur doit correspondre à celui du cache.
Pour utiliser des instructions ou des outils système, ils doivent être configurés comme partie du cache et non comme partie du modèle de prompt côté serveur.

Syntaxe :

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

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

Exemple :

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

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

Vous pouvez également utiliser une variable d'entrée dynamique comme valeur du paramètre name dans le modèle de prompt côté serveur. Par exemple, {{cachedContent name=someVariable}} vous permet d'inclure le name du cache en tant qu'entrée pour la requête de votre application.

Étape 3 : Faites référence au modèle de prompt côté serveur dans la requête de votre application

Soyez très attentif aux points suivants lorsque vous rédigez votre requête :

Utilisez le Vertex AI Gemini API, car le cache a été créé avec ce Gemini API fournisseur.
L' emplacement où vous accédez au modèle dans la requête de prompt de votre application doit correspondre à celui du modèle de prompt côté serveur et du 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}");
}

Gérer les caches explicites

Cette section décrit la gestion des caches de contenu explicites, y compris comment lister tous les caches, obtenir les métadonnées d'un cache, modifier la valeur TTL ou le délai d'expiration d'un cache, et supprimer un cache.

Vous gérez les caches explicites à l'aide de l' API REST de l'Vertex AI Gemini API.

Une fois qu'un cache de contenu explicite est créé, vous ne pouvez rien modifier à son sujet, à l'exception de la valeur TTL ou du délai d'expiration.

Lister tous les caches

Vous pouvez lister tous les caches explicites disponibles pour votre projet. Cette commande ne renvoie que les caches de l'emplacement spécifié.

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

Obtenir les métadonnées d'un cache

Il n'est pas possible de récupérer ni d'afficher le contenu mis en cache. Toutefois, vous pouvez récupérer les métadonnées d'un cache explicite, y compris name, model, display_name, usage_metadata, create_time, update_time, et expire_time.

Vous devez fournir le CACHE_ID, qui correspond au segment final du name de ressource complet du 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}

Modifier la valeur TTL ou le délai d'expiration d'un cache

Lorsque vous créez un cache explicite, vous pouvez éventuellement définir le ttl ou le expire_time.

ttl: valeur TTL (Time To Live) du cache, plus précisément le nombre de secondes et de nanosecondes pendant lequel le cache est actif après sa création ou après la mise à jour de ttl avant son expiration. Lorsque vous définissez ttl, le expireTime du cache est automatiquement mis à jour.
expire_time: Timestamp (tel que 2024-06-30T09:00:00.000000Z) qui spécifie la date et l'heure absolues d'expiration du cache.

Si vous ne définissez aucune de ces valeurs, la valeur TTL par défaut est de 1 heure. Il n'existe aucune limite minimale ni maximale pour la valeur TTL.

Pour les caches explicites existants, vous pouvez ajouter ou modifier le ttl ou le expire_time. Vous devez fournir le CACHE_ID, qui correspond au segment final du name de ressource complet du cache.

Modifier 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'"
}'

Modifier 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'"
}'

Supprimer un cache

Si vous n'avez plus besoin d'un cache explicite, vous pouvez le supprimer.