mise en cache du contexte

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

  • Mise en cache implicite (automatisée, sans garantie d'économies)
  • Mise en cache explicite (manuelle, garantie d'économies)

La mise en cache implicite est activée par défaut sur les modèles Gemini 2.5. Si une requête contient du contenu qui correspond à un cache, nous vous remboursons automatiquement les économies réalisées.

La mise en cache explicite est utile lorsque vous souhaitez garantir des économies de coûts, mais avec un travail supplémentaire pour le développeur.

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 des caches. Aucune action de votre part n'est requise pour l'activer. Il est en vigueur depuis le 8 mai 2025. Le nombre minimal de jetons d'entrée pour le stockage en cache de contexte est de 1 024 pour Flash 2.5 et de 2 048 pour Pro 2.5.

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

  • 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 résultats de 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 du contenu au modèle une seule fois, mettre en cache les jetons d'entrée, puis vous reporter aux jetons mis en cache pour les requêtes suivantes. À certains volumes, l'utilisation de jetons mis en cache est moins coûteuse que de transmettre le même corpus de jetons à plusieurs reprises.

Lorsque vous mettez en cache un ensemble de jetons, vous pouvez choisir la durée d'existence du cache avant que les jetons ne soient supprimés automatiquement. 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 du jeton d'entrée et de la durée de conservation des jetons.

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 créer un cache, puis l'utiliser pour générer du contenu.

VidéosPDF 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
TTL="300s"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"

# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"

# Create the cached content request
echo '{
  "model": "'$MODEL'",
  "contents":[
    {
      "parts":[
        {"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}
      ],
    "role": "user"
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "'$SYSTEM_INSTRUCTION'"
      }
    ],
    "role": "system"
  },
  "ttl": "'$TTL'"
}' > request.json

# Send the cached content request
curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
echo "CACHE_NAME: ${CACHE_NAME}"
# Send the generateContent request using the cached content
curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "'$PROMPT'"
          }],
          "role": "user"
        }
      ],
      "cachedContent": "'$CACHE_NAME'"
    }' > response.json

cat response.json

echo jq ".candidates[].content.parts[].text" response.json

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

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

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.

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

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.

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

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

Si vous utilisez une bibliothèque OpenAI, vous pouvez activer le stockage 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 le 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 :

  1. 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.
  2. 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 valeur TTL.
  3. Autres facteurs : d'autres frais s'appliquent, par exemple pour les jetons d'entrée et de sortie non mis en cache.

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

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 1 024 pour Flash 2.5 et de 2 048 pour Pro 2.5. La valeur maximum est identique à celle 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 un préfixe de la requête.
  • Aucune limite de débit ou d'utilisation spéciale ne s'applique au stockage en cache de contexte. Les limites de débit standards pour GenerateContent s'appliquent, et les limites de jeton 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.