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 utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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. Pour 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 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, bases de code 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, 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 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.8-flash (et les anciennes versions gemini-3.7-flash, gemini-3.6-flash et gemini-3.5-flash)
gemini-3.5-flash-lite (et l'ancienne version gemini-3.1-flash-lite)

Les modèles Gemini 2.5 à usage général sont compatibles avec cette fonctionnalité, mais ils sont tous obsolètes.

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 cache de 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 atteint 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 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.

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 mises en 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.
Faites référence au cache dans un modèle de prompt serveur.
Faites référence au modèle de prompt côté serveur dans une requête de prompt provenant 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 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 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 d'invite 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 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, ou même 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. 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 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 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 entièrement qualifiée, qui est unique au cache à l'échelle mondiale (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.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érencez le cache dans un modèle de prompt de serveur

Après avoir créé le cache, faites-y référence 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 demande.
L'emplacement du modèle de prompt 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 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 prudent concernant les points suivants lorsque vous rédigez votre demande :

Utilisez le Agent Platform Gemini API (formerly Vertex AI) depuis la création du cache 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.
  '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}");
}

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 Agent Platform Gemini API (formerly Vertex AI).

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 renverra 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 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 (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 TTL par défaut est d'une heure. Il n'y a pas de limites minimales ni maximales pour le TTL.

Pour les caches explicites existants, vous pouvez ajouter ou modifier ttl ou expire_time. Vous devez fournir le CACHE_ID, qui correspond au dernier segment du name de ressource complet 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.