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 de votre part n'est requise 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 de 1 024 pour 2.5 Flash et de 4 096 pour 2.5 Pro.
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 du contenu 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 elle n'est pas défini, la valeur TTL par défaut est de 1 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 et d'un fichier vidéo mis en cache.
Vidéos
import os
import pathlib
import requests
import time
from google import genai
from google.genai import types
client = genai.Client()
# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
with path_to_video_file.open('wb') as wf:
response = requests.get(url, stream=True)
for chunk in response.iter_content(chunk_size=32768):
wf.write(chunk)
# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)
# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
print('Waiting for video to be processed.')
time.sleep(2)
video_file = client.files.get(name=video_file.name)
print(f'Video processing complete: {video_file.uri}')
# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'
# Create a cache with a 5 minute TTL
cache = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name='sherlock jr movie', # used to identify the cache
system_instruction=(
'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.'
),
contents=[video_file],
ttl="300s",
)
)
# Construct a GenerativeModel which uses the created cache.
response = client.models.generate_content(
model = model,
contents= (
'Introduce different characters in the movie by describing '
'their personality, looks, and names. Also list the timestamps '
'they were introduced for the first time.'),
config=types.GenerateContentConfig(cached_content=cache.name)
)
print(response.usage_metadata)
# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433
print(response.text)
from google import genai
from google.genai import types
import io
import httpx
client = genai.Client()
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)
document = client.files.upload(
file=doc_io,
config=dict(mime_type='application/pdf')
)
model_name = "gemini-2.0-flash-001"
system_instruction = "You are an expert analyzing transcripts."
# Create a cached content object
cache = client.caches.create(
model=model_name,
config=types.CreateCachedContentConfig(
system_instruction=system_instruction,
contents=[document],
)
)
# Display the cache details
print(f'{cache=}')
# Generate content using the cached prompt and document
response = client.models.generate_content(
model=model_name,
contents="Please summarize this transcript",
config=types.GenerateContentConfig(
cached_content=cache.name
))
# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')
# Print the generated text
print('\n\n', response.text)
Lister 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 du cache (name, model, display_name, usage_metadata, create_time, update_time et expire_time).
Pour lister les métadonnées de tous les caches importés, utilisez CachedContent.list() :
for cache in client.caches.list():
print(cache)
Pour extraire les métadonnées d'un objet de cache, si vous connaissez son nom, utilisez get :
client.caches.get(name=name)
Mettre à jour un cache
Vous pouvez définir un nouveau ttl ou expire_time 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 client.caches.update().
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
Pour définir le délai d'expiration, vous pouvez utiliser un objet datetime ou une chaîne de date et heure au format ISO (dt.isoformat(), comme 2025-01-27T16:02:36.473528+00:00). Votre heure doit inclure un fuseau horaire (datetime.utcnow() n'en ajoute pas, datetime.now(datetime.timezone.utc) en ajoute un).
from google import genai
from google.genai import types
import datetime
# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
expire_time=in10min
)
)
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 :
client.caches.delete(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'y a pas de limites minimales ni maximales 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 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 et de 2 048 pour 2.5 Pro. La valeur maximale est la même que celle du 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 taux ou d'utilisation spéciales pour la mise en cache du contexte. Les limites de taux standards pour
GenerateContents'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 dansGenerateContentlors de l'utilisation du cache.