Mise en cache du contexte

Dans un workflow d'IA typique, vous pouvez transmettre les mêmes jetons d'entrée à un modèle à plusieurs reprises. L'API Gemini propose deux mécanismes de mise en cache différents :

Mise en cache implicite (activée automatiquement sur les modèles Gemini 2.5, sans garantie d'économies)
Mise en cache explicite (peut être activée manuellement sur la plupart des modèles, garantie d'économies)

La mise en cache explicite est utile lorsque vous souhaitez garantir des économies, mais avec un peu de travail supplémentaire pour les développeurs.

Mise en cache implicite

La mise en cache implicite est activée par défaut pour tous les modèles Gemini 2.5. Nous répercutons automatiquement les économies de coûts si votre requête atteint les caches. Aucune action n'est requise de votre part pour activer cette fonctionnalité. Elle entrera en vigueur le 8 mai 2025. Le nombre minimal de jetons d'entrée pour la mise en cache du contexte est indiqué dans le tableau suivant pour chaque modèle :

Modèle	Limite de jetons minimale
Aperçu de Gemini 3 Pro	4096
Gemini 2.5 Pro	4096
Gemini 2.0 Flash	1024

Pour augmenter les chances d'un accès implicite au cache :

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

Vous pouvez voir le nombre de jetons qui ont été des accès au cache dans le champ usage_metadata de l'objet de réponse.

Mise en cache explicite

Grâce à la fonctionnalité de mise en cache explicite de l'API Gemini, vous pouvez transmettre certains contenus au modèle une seule fois, mettre en cache les jetons d'entrée, puis faire référence aux jetons mis en cache pour les requêtes suivantes. Pour certains volumes, l'utilisation de jetons mis en cache est moins coûteuse que la transmission répétée du même corpus de jetons.

Lorsque vous mettez en cache un ensemble de jetons, vous pouvez choisir la durée de vie du cache avant que les jetons ne soient automatiquement supprimés. Cette durée de mise en cache est appelée time to live (TTL). Si ce paramètre n'est pas défini, la valeur TTL par défaut est d'une heure. Le coût de la mise en cache dépend de la taille des jetons d'entrée et de la durée pendant laquelle vous souhaitez que les jetons soient conservés.

Cette section suppose que vous avez installé un SDK Gemini (ou curl) et que vous avez configuré une clé API, comme indiqué dans le guide de démarrage rapide.

Générer du contenu à l'aide d'un cache

L'exemple suivant montre comment générer du contenu à l'aide d'une instruction système mise en cache et d'un fichier texte.

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const doc = await ai.files.upload({
    file: "path/to/file.txt",
    config: { mimeType: "text/plain" },
  });
  console.log("Uploaded file name:", doc.name);

  const modelName = "gemini-2.0-flash-001";
  const cache = await ai.caches.create({
    model: modelName,
    config: {
      contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
      systemInstruction: "You are an expert analyzing transcripts.",
    },
  });
  console.log("Cache created:", cache);

  const response = await ai.models.generateContent({
    model: modelName,
    contents: "Please summarize this transcript",
    config: { cachedContent: cache.name },
  });
  console.log("Response text:", response.text);
}

await main();

Répertorier des caches

Il n'est pas possible de récupérer ni d'afficher le contenu mis en cache, mais vous pouvez récupérer les métadonnées du cache (name, model, displayName, usageMetadata, createTime, updateTime et expireTime).

Pour lister les métadonnées de tous les caches importés, utilisez GoogleGenAI.caches.list() :

console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
  for (const c of page) {
    console.log("    ", c.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}

Mettre à jour un cache

Vous pouvez définir un nouveau ttl ou expireTime pour un cache. Il n'est pas possible de modifier d'autres aspects du cache.

L'exemple suivant montre comment mettre à jour le ttl d'un cache à l'aide de GoogleGenAI.caches.update().

const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
  name: cache.name,
  config: { ttl },
});
console.log("After update (TTL):", updatedCache);

Supprimer un cache

Le service de mise en cache fournit une opération de suppression permettant de supprimer manuellement du contenu du cache. L'exemple suivant montre comment supprimer un cache à l'aide de GoogleGenAI.caches.delete().

await ai.caches.delete({ name: cache.name });

Mise en cache explicite à l'aide de la bibliothèque OpenAI

Si vous utilisez une bibliothèque OpenAI, vous pouvez activer la mise en cache explicite à l'aide de la propriété cached_content sur extra_body.

Quand utiliser la mise en cache explicite

La mise en cache de contexte est particulièrement adaptée aux scénarios où un contexte initial important est référencé à plusieurs reprises par des requêtes plus courtes. Envisagez d'utiliser la mise en cache de contexte pour les cas d'utilisation suivants :

Chatbots avec des instructions système détaillées
Analyse répétitive de fichiers vidéo longs
Requêtes récurrentes sur des ensembles de documents volumineux
Analyse fréquente du dépôt de code ou correction de bugs

Comment la mise en cache explicite réduit les coûts

La mise en cache de contexte est une fonctionnalité payante conçue pour réduire les coûts opérationnels globaux. La facturation dépend des facteurs suivants :

Nombre de jetons mis en cache : nombre de jetons d'entrée mis en cache, facturés à un tarif réduit lorsqu'ils sont inclus dans les requêtes suivantes.
Durée de stockage : durée pendant laquelle les jetons mis en cache sont stockés (TTL), facturée en fonction de la durée TTL du nombre de jetons mis en cache. Il n'existe aucune limite minimale ni maximale pour la durée de vie (TTL).
Autres facteurs : d'autres frais s'appliquent, par exemple pour les jetons d'entrée et de sortie non mis en cache.

Pour connaître les tarifs à jour, consultez la page des tarifs de l'API Gemini. Pour savoir comment compter les jetons, consultez le guide sur les jetons.

Informations complémentaires

Tenez compte des points suivants lorsque vous utilisez la mise en cache du contexte :

Le nombre minimal de jetons d'entrée pour la mise en cache du contexte est de 1 024 pour 2.5 Flash, 4 096 pour 2.5 Pro et 2 048 pour 3 Pro Preview. Le maximum est le même que le maximum pour le modèle donné. (Pour en savoir plus sur le comptage des jetons, consultez le guide sur les jetons.)
Le modèle ne fait aucune distinction entre les jetons mis en cache et les jetons d'entrée standards. Le contenu mis en cache est un préfixe de la requête.
Il n'existe pas de limites de débit ni d'utilisation spécifiques pour la mise en cache du contexte. Les limites de débit standards pour GenerateContent s'appliquent, et les limites de jetons incluent les jetons mis en cache.
Le nombre de jetons mis en cache est renvoyé dans usage_metadata à partir des opérations de création, d'obtention et de liste du service de cache, ainsi que dans GenerateContent lors de l'utilisation du cache.