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 demande 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éfinie, la valeur TTL est de 1 heure par défaut. 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.

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 :

  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 obtenir des informations à jour sur les tarifs, 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 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.