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. Pour ces cas d'utilisation, vous pouvez mettre en cache ce contenu, ce qui signifie que vous le transmettez une seule fois au modèle, que vous le stockez et que vous y faites référence dans les requêtes ultérieures.

La mise en cache de contexte peut réduire considérablement la latence et le coût des 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 du contenu mis en cache : documents détaillés sur les personas, codebases ou manuels.

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

  • Mise en cache implicite : activée automatiquement sur la plupart des modèles, sans garantie d'économies.

  • Mise en cache explicite : peut être activée facultativement et manuellement sur la plupart des modèles, ce qui permet généralement de réduire les coûts.

La mise en cache explicite est utile lorsque vous souhaitez garantir des économies, mais elle nécessite un travail de développement supplémentaire.

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 de tarification au bas de cette page.

Modèles compatibles

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

  • gemini-4-argon (mise en cache implicite uniquement ; la mise en cache explicite n'est pas acceptée)
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (et l'ancien gemini-3.1-flash-lite)

Les anciens modèles Gemini 3.x Flash à usage général sont compatibles avec cette fonctionnalité, mais leur utilisation n'est plus recommandée en raison des dates d'arrêt à venir et/ou du routage automatique vers des modèles plus récents.

Les modèles de génération de contenus multimédias (par exemple, les modèles Gemini Nano Banana comme gemini-nano-banana-2.1) ne sont pas compatibles avec la mise en cache de contexte.

Limites de taille du contenu mis en cache

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

  • Gemini 4 Argon : 4 096 jetons minimum (Gemini Developer API) ou 6 144 jetons minimum (Agent Platform Gemini API (formerly Vertex AI))
  • Modèles Gemini Pro : 4 096 jetons minimum
  • Modèles Gemini 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 requête atteint le contenu mis en cache. Voici quelques moyens d'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 dans un court laps de temps.

Le nombre de jetons dans la partie mise en cache de votre entrée 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.

Notez que le modèle gemini-4-argon n'est pas compatible avec la mise en cache explicite.

Voici comment configurer et utiliser des caches de contenu explicites :

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 de manière explicite. Vous pouvez empêcher la conservation des données du 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 :

  1. Créer un cache explicite

  2. Référencez le cache dans un modèle de prompt côté serveur.

  3. Référencez le modèle de prompt côté serveur dans une requête de prompt de 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 fournisseur Gemini API. La requête 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 explicites uniquement avec Agent Platform Gemini API (formerly Vertex AI). 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 de prompt de votre application doit utiliser le même modèle.

  • Le cache est spécifique à un emplacement lorsque vous utilisez Agent Platform Gemini API (formerly Vertex AI).
    L'emplacement du cache explicite doit correspondre à l'emplacement du modèle de prompt du serveur et à l'emplacement où vous accédez au modèle dans la requête de prompt de votre application.

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

  • Une fois qu'un cache explicite est créé, vous ne pouvez rien modifier, à 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 du texte fourni dans la requête de création de 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 requête de l'utilisateur. Pour cette raison, assurez-vous que toutes les données incluses dans le cache explicite sont adaptées à 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. 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 prompt de serveur ne sont pas encore compatibles avec l'appel de fonction (ou le chat). Pour savoir comment configurer les instructions système et les outils dans votre cache, consultez l'API REST de Agent Platform Gemini API (formerly Vertex AI).

Étape 1 : Créez le cache

Créez le cache en utilisant directement l'API REST de Agent Platform Gemini API (formerly Vertex AI).

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

Exemple de requête :

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

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.8-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érencer 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 de prompt de serveur.

Veillez à respecter les exigences suivantes lorsque vous créez votre modèle de prompt de 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 de prompt du serveur doit correspondre à l'emplacement du cache.

  • Pour utiliser des instructions ou des outils système, ils doivent être configurés dans le cache et non dans le modèle de prompt 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 de prompt 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

Soyez très attentif aux points suivants lorsque vous rédigez votre demande :

  • Utilisez Agent Platform Gemini API (formerly Vertex AI), 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 du serveur et du 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}");
}


Gérer les caches explicites

Cette section explique comment gérer les caches de contenu explicites, y compris comment lister tous les caches, obtenir les métadonnées d'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 Agent Platform Gemini API (formerly Vertex AI).

Une fois qu'un cache de contenu explicite est créé, vous ne pouvez plus rien modifier, à 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 est le dernier segment de la name de ressource 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}

Mettre à jour 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, 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 paramètre 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 d'une heure. Il n'y a pas de limites minimale ou maximale pour la valeur TTL.

Pour les caches explicites existants, vous pouvez ajouter ou mettre à jour ttl ou expire_time. Vous devez fournir le CACHE_ID, qui est le dernier segment de la name de ressource 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.

Vous devez fournir le CACHE_ID, qui est le dernier segment de la name de ressource 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 DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}


Tarifs de la mise en cache explicite

La mise en cache explicite est une fonctionnalité payante conçue pour réduire les coûts. La tarification est basée sur les facteurs suivants :

  • Jetons d'entrée pour la création du cache : pour la mise en cache implicite et explicite, les jetons d'entrée utilisés pour créer le cache vous sont facturés au prix standard des jetons d'entrée.

  • Stockage du cache : pour la mise en cache explicite, des coûts de stockage sont également facturés en fonction de la durée de stockage des caches. La mise en cache implicite n'entraîne aucuns frais de stockage. Pour en savoir plus, consultez les tarifs de Agent Platform Gemini API (formerly Vertex AI).

  • Utilisation du contenu mis en cache : la mise en cache explicite garantit une remise lorsque des caches explicites sont référencés, ce qui signifie que vous bénéficiez d'une remise sur les jetons d'entrée lorsqu'ils référencent un cache existant. Pour les modèles Gemini 2.5 et ultérieurs, cette remise est de 90 %.

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