Mise en cache du contexte

Dans un workflow d'IA classique, vous pouvez transmettre les mêmes jetons d'entrée à plusieurs reprises à un modèle. La fonctionnalité de mise en cache contextuelle de l'API Gemini vous permet de transmettre une fois du contenu au modèle, de mettre en cache les jetons d'entrée, puis de les consulter pour les requêtes ultérieures. 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 d'existence du cache avant qu'ils soient automatiquement supprimés. Cette durée de mise en cache est appelée TTL (Time To Live). Si ce champ n'est pas défini, la valeur TTL est définie par défaut sur une heure. Le coût de la mise en cache dépend de la taille des jetons d'entrée et de leur durée de conservation.

La mise en cache du contexte est compatible avec Gemini 1.5 Pro et Gemini 1.5 Flash.

Quand utiliser la mise en cache de contexte

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 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és en fonction de la durée TTL du nombre de jetons mis en cache. Il n'existe aucune limite minimale ni maximale pour la valeur TTL.
Autres facteurs : d'autres frais s'appliquent, par exemple pour les jetons d'entrée et de sortie non mis en cache.

Pour obtenir les tarifs les plus récents, consultez la page des tarifs de l'API Gemini. Pour savoir comment compter les jetons, consultez le guide relatif aux jetons.

Utiliser la mise en cache du contexte

Cette section suppose que vous avez installé un SDK Gemini (ou que curl est installé) et que vous avez configuré une clé API, comme indiqué dans le tutoriel 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 vidéo.

import { GoogleGenerativeAI } from '@google/generative-ai';
import {
  FileState,
  GoogleAICacheManager,
  GoogleAIFileManager,
} from '@google/generative-ai/server';

// A helper function that uploads the video to be cached.
async function uploadMp4Video(filePath, displayName) {
  const fileManager = new GoogleAIFileManager(process.env.API_KEY);
  const fileResult = await fileManager.uploadFile(filePath, {
    displayName,
    mimeType: 'video/mp4',
  });

  const { name, uri } = fileResult.file;

  // Poll getFile() on a set interval (2 seconds here) to check file state.
  let file = await fileManager.getFile(name);
  while (file.state === FileState.PROCESSING) {
    console.log('Waiting for video to be processed.');
    // Sleep for 2 seconds
    await new Promise((resolve) => setTimeout(resolve, 2_000));
    file = await fileManager.getFile(name);
  }

  console.log(`Video processing complete: ${uri}`);

  return fileResult;
}

// Download video file
// curl -O https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4
const pathToVideoFile = 'Sherlock_Jr_FullMovie.mp4';

// Upload the video.
const fileResult = await uploadMp4Video(pathToVideoFile, 'Sherlock Jr. video');

// Construct a GoogleAICacheManager using your API key.
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);

// Create a cache with a 5 minute TTL.
const displayName = 'sherlock jr movie';
const model = 'models/gemini-1.5-flash-001';
const systemInstruction =
  'You are an expert video analyzer, and your job is to answer ' +
  "the user's query based on the video file you have access to.";
let ttlSeconds = 300;
const cache = await cacheManager.create({
  model,
  displayName,
  systemInstruction,
  contents: [
    {
      role: 'user',
      parts: [
        {
          fileData: {
            mimeType: fileResult.file.mimeType,
            fileUri: fileResult.file.uri,
          },
        },
      ],
    },
  ],
  ttlSeconds,
});

// Get your API key from https://aistudio.google.com/app/apikey
// Access your API key as an environment variable.
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Construct a `GenerativeModel` which uses the cache object.
const genModel = genAI.getGenerativeModelFromCachedContent(cache);

// Query the model.
const result = await genModel.generateContent({
  contents: [
    {
      role: 'user',
      parts: [
        {
          text:
            'Introduce different characters in the movie by describing ' +
            'their personality, looks, and names. Also list the ' +
            'timestamps they were introduced for the first time.',
        },
      ],
    },
  ],
});

console.log(result.response.usageMetadata);

// The output should look something like this:
//
// {
//   promptTokenCount: 696220,
//   candidatesTokenCount: 270,
//   totalTokenCount: 696490,
//   cachedContentTokenCount: 696191
// }

console.log(result.response.text());

Répertorier les 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 de cache (name, model, displayName, usageMetadata, createTime, updateTime et expireTime).

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

const listResult = await cacheManager.list();
listResult.cachedContents.forEach((cache) => {
  console.log(cache);
});

Mettre à jour un cache

Vous pouvez définir un nouveau ttl ou expireTime pour un cache. Il n'est pas possible de modifier tout autre élément du cache.

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

const ttlSeconds = 2 * 60 * 60;
const updateParams = { cachedContent: { ttlSeconds } };
const updatedCache = await cacheManager.update(cacheName, updateParams);

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 GoogleAICacheManager.delete().

await cacheManager.delete(cacheName);

Informations complémentaires

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

Le nombre minimal de jetons d'entrée pour le stockage en cache de contexte est de 32 768, et le nombre maximal est identique à celui du modèle donné. (Pour en savoir plus sur le comptage des jetons, consultez le guide des jetons.)
Le modèle ne fait aucune distinction entre les jetons mis en cache et les jetons d'entrée normaux. Le contenu mis en cache est simplement un préfixe de la requête.
Aucun taux spécial ni aucune limite d'utilisation ne s'applique à 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.