Atelier

Lesson 6 — Contexte long, cache et RAG

La mise en cache du contexte

5 min read

This content is not translated yet. Showing the original version.

La mise en cache du contexte

L'idée

Quand vous envoyez le même long document à chaque question, le modèle refait à chaque fois le même travail de lecture. La mise en cache du contexte (context caching) garde ce travail côté serveur : les tokens servis depuis le cache sont facturés à un tarif réduit (voir la page de tarifs) et peuvent répondre plus vite.

Cache impliciteCache explicite
Activationautomatique (modèles Gemini 2.5 et plus récents, d'après la documentation)vous créez un objet CachedContent avec une durée de vie (TTL)
Conditionun préfixe identique envoyé à peu d'intervalle, au-dessus d'un minimum de tokens (4 096 pour les modèles Gemini 3.x listés, 2 048 pour Gemini 2.5 Flash)le contenu dépasse le minimum du modèle
Garantieaucune : c'est une optimisation « au mieux »les appels qui citent le cache l'utilisent
Coût en plusaucunstockage facturé à la durée tant que le cache existe
À fairemettre le contenu stable en têtesupprimer le cache quand on a fini
sequenceDiagram
  participant App as "Votre code"
  participant API as "API Gemini"
  App->>API: "caches.create(document, ttl=300s)"
  API-->>App: "cachedContents/abc (8164 tokens)"
  App->>API: "question 1 + cached_content=abc"
  API-->>App: "réponse (8164 tokens lus depuis le cache)"
  App->>API: "question 2 + cached_content=abc"
  API-->>App: "réponse (8164 tokens lus depuis le cache)"
  App->>API: "caches.delete(abc)"

Le code

files/demo_contexte.py
cache = c.caches.create(model=MODEL, config=types.CreateCachedContentConfig(
    display_name="lab-context-engineering", contents=[doc], ttl="300s",
    system_instruction="Tu réponds uniquement à partir du catalogue fourni, en une phrase."))
try:
    for q in [QUESTION, "Quelle est la garantie de la référence AT-1050 ?"]:
        show("explicite", ask(c, q, cached_content=cache.name))
finally:
    c.caches.delete(name=cache.name)   # même en cas d'erreur

Le cache contient le document et l'instruction système : les appels qui l'utilisent n'envoient plus que la question. Le try/finally garantit la suppression même si une question échoue.

Vous voulez profiter du cache implicite. Où placez-vous le long document dans la requête ?

Résultat obtenu

Exécution réelle de python demo_contexte.py le 2026-10-15 (gemini-3.5-flash, document de 8 149 tokens) :

implicite, appel 1      1.42 s | entrée  8161 (dont cache     0) | sortie   27 | 'Le prix du produit **AT-1050** (Chaise rotin terracotta) est de **93 euros TTC**.'
implicite, appel 2      1.44 s | entrée  8161 (dont cache  6119) | sortie   26 | 'Le prix de la référence AT-1050 (Chaise rotin terracotta) est de **93 euros TTC**.'

cache créé : 8164 tokens, expire 15:01:08 UTC
explicite               2.92 s | entrée  8197 (dont cache  8164) | sortie   54 | "La référence AT-1137 coûte 821 euros TTC, est expédiée depuis l'entrepôt de Nantes, et ne bénéficie pas de la livraison "
explicite               2.29 s | entrée  8179 (dont cache  8164) | sortie   17 | 'La garantie pour la référence AT-1050 est de 1 an.'
cache supprimé ; caches restants du lab : []

Ce qu'on lit :

  • Le cache implicite a servi 6 119 tokens sur 8 161 au deuxième appel, sans aucune configuration. Pas 100 % : le cache travaille par blocs, la fin du préfixe n'est pas toujours couverte.
  • Le cache explicite a servi la totalité du document (8 164 tokens) aux deux questions.
  • La latence n'a pas baissé de façon visible sur ces essais isolés : l'intérêt principal mesuré ici est le coût des tokens d'entrée.
  • Un test équivalent sur Vertex AI (gemini-2.5-flash, europe-west1, même document) a donné prompt 8157, cached 8149, puis le cache a été supprimé et la liste des caches était vide.

Au 2e appel implicite, cached_content_token_count vaut 6119 sur 8161 tokens d'entrée. Qu'est-ce que cela signifie ?

Exercice : rentable ou pas ?

Un cache explicite coûte un stockage horaire. Vous interrogez un manuel de 50 000 tokens. Quelles informations vous faut-il pour décider s'il est rentable, et quelle est la règle ?

Voir la solution

Il faut : le nombre de questions par heure nn, le tarif normal des tokens d'entrée pp, le tarif des tokens en cache pcp_c et le tarif de stockage par token et par heure ss (tous sur la page de tarifs de votre modèle).

Économie par heure : n×50 000×(p−pc)n \times 50\,000 \times (p - p_c). Coût du stockage par heure : 50 000×s50\,000 \times s. Le cache est rentable si n×(p−pc)>sn \times (p - p_c) > s.

En pratique : quelques questions par heure sur le même gros document suffisent souvent, une question par jour jamais. Et si vos questions arrivent en rafale, le cache implicite gratuit peut suffire : mesurez cached_content_token_count avant de payer un cache explicite.

Je sais faire

  • Distinguer cache implicite et cache explicite
  • Structurer une requête pour favoriser le cache implicite
  • Créer, utiliser et supprimer un cache explicite, avec un TTL court
  • Lire cached_content_token_count et raisonner sur la rentabilité
Next