The latest Gemini models, like Gemini 3.5 Flash, are available to use with Firebase AI Logic! Learn more.

All Imagen models will shut down as early as June 30, 2026. Learn about migrating your apps to use Nano Banana.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 à plusieurs reprises. 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, le stockez et 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. Voici quelques cas d'utilisation courants pour le contenu mis en cache : documents détaillés sur les personas, bases de code ou manuels.

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

Mise en cache implicite : automatiquement activée sur la plupart des modèles, aucune économie de coûts garantie
Mise en cache explicite : peut être facultativement et manuellement activée sur la plupart des modèles, ce qui permet généralement de réaliser des économies.

La mise en cache explicite est utile lorsque vous souhaitez garantir plus facilement des économies, mais cela nécessite un travail supplémentaire de la part des développeurs.

Pour la mise en cache implicite et explicite, le champ cachedContentTokenCount dans les 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.5-flash
gemini-3.1-flash-lite
gemini-2.5-pro
gemini-2.5-flash
gemini-2.5-flash-lite

Les modèles de génération de contenu multimédia (par exemple, les modèles "Nana Banana" comme gemini-3.1-flash-image) ne sont pas compatibles avec la mise en cache du contexte.

Limites de taille du contenu mis en cache

Chaque modèle a un nombre minimal de jetons requis pour le contenu mis en cache. Le maximum est déterminé par la fenêtre de contexte du modèle.

Gemini Modèles Pro : 4 096 jetons minimum
Gemini Modèles Flash : 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 modèles Gemini.

Google répercute automatiquement les économies réalisées si votre demande touche le contenu mis en cache. Voici quelques conseils pour augmenter les chances que votre requête utilise la mise en cache implicite :

Essayez de placer les contenus volumineux et courants au début de votre requête.
Essayez d'envoyer des requêtes avec un préfixe similaire en peu de temps.

Le nombre de jetons dans la partie mise en cache de votre saisie est indiqué 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. Il s'agit d'une fonctionnalité facultative des modèles Gemini.

Voici comment configurer et utiliser les caches de contenu explicite :

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

Notez que les caches de contenu explicite interagissent avec la mise en cache implicite, ce qui peut entraîner une mise en cache supplémentaire au-delà du contenu explicite mis en cache. 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 disposer des éléments suivants :

Créez un cache explicite.
Référencez le cache dans un modèle d'invite de 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 le modèle de prompt de votre serveur :

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

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

Une fois un cache explicite créé, vous ne pouvez plus rien modifier à son sujet, à l'exception du TTL ou du délai d'expiration.
Vous pouvez mettre en cache n'importe quel type MIME de fichier d'entrée compatible, voire simplement le texte fourni dans la demande de création du cache.
Si vous souhaitez inclure un fichier dans le cache, vous devez le fournir en tant qu'URI Cloud Storage. 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 demande 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 (comme l'exécution de code, le contexte d'URL, l'ancrage avec Google Search ou l'ancrage avec Google Maps), le cache lui-même doit contenir leurs configurations. Elles ne peuvent pas être configurées dans le modèle d'invite du serveur ni dans la requête d'invite de votre application. Notez que les modèles de prompts de serveur ne sont pas encore compatibles avec l'appel de fonction (ou le chat). Pour savoir comment configurer les instructions et les 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 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.5-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

Exemple de requête :

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

Exemple de réponse :

La réponse inclut une ressource name complète, qui est unique au niveau mondial pour le cache (notez que le dernier segment est l'ID du cache). Vous utiliserez l'intégralité de cette valeur name à l'étape suivante du workflow.

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

Étape 2 : Référencez le cache dans un modèle de prompt de serveur

Après avoir créé le cache, référencez-le par name dans la propriété cachedContent d'un modèle d'invite de serveur.

Veillez à respecter les exigences suivantes lorsque vous créez votre modèle de requête serveur :

Utilisez la ressource name complète 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 d'invite du serveur doit correspondre à celui du cache.
Pour utiliser des instructions ou des outils système, ils doivent être configurés dans le cache et non pas dans le modèle d'invite du serveur.

Syntaxe :

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

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

Exemple :

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

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

La valeur du paramètre name dans le modèle d'invite du serveur peut également être une variable d'entrée dynamique. 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 : Référencez le modèle de prompt du serveur dans la requête de votre application

Faites très attention aux points suivants lorsque vous rédigez votre demande :

Utilisez le Vertex AI Gemini API, car le cache a été créé avec ce fournisseur Gemini API.
L'emplacement où vous accédez au modèle dans la requête de prompt de votre application doit correspondre à l'emplacement 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 explicite, y compris comment lister tous les caches, obtenir des métadonnées sur un cache, mettre à jour 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 Vertex AI Gemini API.

Une fois le cache de contenu explicite créé, vous ne pouvez plus le modifier, à l'exception du 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 situés à 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 des métadonnées sur 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 des métadonnées sur 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 dernier segment de la ressource name complète 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 ttl ou expire_time.

ttl : valeur TTL (Time To Live) du cache, c'est-à-dire 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 (comme 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 ou maximale pour le TTL.

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

Mettre à jour 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'"
}'

Mettre à jour 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

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