Le cache de contexte de Gemini 4 Neon : fonctionnement, structure des prompts et économies
Le cache de contexte de Gemini 4 Neon est uniquement implicite. Vous ne créez pas de cache : Google met en cache de lui-même les préfixes de prompt répétés d'au moins 4 096 tokens et les facture au tarif d'entrée en cache de 0,15 $ par million au lieu de 3 $, soit une réduction de 95 %. Vous en profitez en plaçant la partie stable de chaque requête au début, à l'identique octet par octet, puis en vérifiant les correspondances dans usage.total_cached_tokens.
Essayez Apidog dès aujourd'hui
Ci-dessous : la disposition du prompt pour obtenir des correspondances en cache, la règle des boucles d'agent, la lecture du compteur de tokens en cache et un test que votre agent de code exécute pour vous.
Comment fonctionne le cache de contexte de Gemini 4 Neon ?
Le cache de contexte de Gemini 4 Neon est un cache de préfixe automatique. Quand une nouvelle requête commence par les mêmes tokens qu'une requête récente, et que ce préfixe partagé fait au moins 4 096 tokens, Google sert la partie répétée depuis le cache et la facture au tarif en cache. Rien à activer, aucun objet cache, aucun TTL ni frais de stockage à gérer.
Google a publié Neon le 18 novembre 2026 (identifiant de modèle gemini-4-neon, voir l'annonce de lancement). Ses caractéristiques de cache tiennent en un tableau :
| Élément | Gemini 4 Neon |
|---|---|
| Mode de cache | Implicite uniquement, activé par défaut |
Cache explicite (cachedContents, caches.create) |
Non pris en charge |
| Préfixe minimal pour une correspondance en cache | 4 096 tokens |
| Entrée standard | 3,00 $ par million de tokens |
| Entrée en cache (Standard) | 0,15 $ par million de tokens |
| Entrée en cache (Batch et Flex) | 0,075 $ par million de tokens |
| Entrée en cache (Priority) | 0,27 $ par million de tokens |
| Où voir les correspondances | usage.total_cached_tokens |
| Offre gratuite | Aucune, offre payante uniquement |
La réduction est de 95 % sur tous les paliers : 0,15 $ représente 5 % de 3 $, 0,075 $ représente 5 % de 1,50 $, et 0,27 $ représente 5 % de 5,40 $. Les tokens de sortie, y compris les tokens de réflexion, restent à 15 $ par million sur le palier Standard. Le cache ne concerne que l'entrée.
Cache implicite ou cache explicite avec Gemini 4 Neon
Si vous utilisiez le cache explicite sur Gemini 2.5 ou 3, c'est le changement qui va casser votre code. Les notes de migration de Google pour Neon le disent clairement : Gemini 4 Neon « ne prend pas en charge le cache explicite (cachedContents et caches.create) », et vous devez « retirer les champs cached_content des requêtes ».
La documentation du cache précise que l'API Interactions ne prend en charge que le cache implicite, et que le cache explicite n'est disponible pour aucun modèle Gemini 4. Les caches explicites continuent de fonctionner sur les modèles Gemini 3 et 2.5 pris en charge via generateContent.
Cela signifie, pour une migration :
- Supprimer le code qui appelle
caches.createet stocke un nom de cache. - Retirer
cached_contentde chaque corps de requête. - Cesser de payer pour le stockage de cache dont vous ne vous servez plus.
- Restructurer vos prompts pour que le contenu que vous mettiez explicitement en cache se trouve tout au début de chaque requête.
Vous ne pouvez pas épingler un document ni choisir un TTL, et une correspondance n'est pas garantie. Mais vous pouvez nettement augmenter vos chances.
Comment structurer vos prompts pour atteindre le cache de Gemini 4 Neon ?
Une correspondance en cache exige un préfixe long et identique renvoyé rapidement. La documentation de Google donne deux conseils : placer les contenus volumineux et communs au début de votre prompt, et envoyer des requêtes avec un préfixe similaire dans un laps de temps court.
Ordonnez chaque requête ainsi :
- L'instruction système. Texte fixe, sans horodatages, sans noms d'utilisateurs, sans identifiants de requête.
- Les déclarations d'outils et de fonctions. Même liste, même ordre, mêmes descriptions à chaque fois.
- Les documents partagés. La base de code, le contrat, la spécification API, le long fichier de règles.
- La partie qui change. La question de l'utilisateur, le dernier résultat d'outil, la date du jour.
La façon la plus courante de rater le cache est une petite valeur dynamique placée près du début. Une ligne comme Current time: 2026-11-19T09:14:02Z dans l'instruction système modifie le préfixe à chaque appel, si bien que rien après elle ne peut correspondre. Déplacez-la à la fin, après les documents.
Autres casseurs de préfixe : des listes d'outils construites dans un ordre aléatoire, des documents resérialisés avec des espacements différents, et des fragments récupérés renvoyés dans un ordre différent.
Maintenez le préfixe au-dessus de 4 096 tokens. Un prompt système de 2 000 tokens à lui seul ne suffira pas. Si vous y ajoutez un long document partagé, le préfixe combiné le sera.
Avec l'API Interactions, passez l'instruction stable dans system_instruction et placez les documents au début de input :
from google import genai
client = genai.Client() # reads GEMINI_API_KEY
SYSTEM = open("review_rules.md").read() # fixed text
CODEBASE = open("repo_snapshot.txt").read() # ~200K tokens, unchanged
def ask(question: str):
interaction = client.interactions.create(
model="gemini-4-neon",
system_instruction=SYSTEM,
input=CODEBASE + "\n\nQuestion: " + question,
)
print("cached tokens:", interaction.usage.total_cached_tokens)
return interaction
ask("Where do we validate JWT expiry?")
ask("Which handlers skip input validation?")
Le premier appel remplit le cache. Si le second affiche 0 token en cache, quelque chose dans le préfixe a changé.
Le cache implicite fonctionne dans les deux modes de conversation. Les appels sans état comme celui ci-dessus sont éligibles, tout comme les sessions avec état chaînées via previous_interaction_id. Pour la forme complète des requêtes, consultez notre guide de l'API Gemini 4 Neon.
Fonctionnement du cache dans les boucles d'agent : la règle des 2 050 tokens
Les boucles d'agent sont l'endroit où le cache rapporte le plus, car chaque tour renvoie tout l'historique. Les modèles Gemini 4 ajoutent une règle à connaître. D'après la documentation de Google sur le cache : « Gemini ne met en cache la requête précédente complète que si la nouvelle requête ajoute au moins 2 050 tokens. » La sortie du modèle, les réflexions et les résultats de fonctions comptent tous dans ce total.
Si un tour ajoute moins de 2 050 tokens, Gemini retraite les 2 050 derniers tokens de la requête précédente au tarif d'entrée standard. La partie antérieure du préfixe peut toujours correspondre, mais cette fin est facturée 3 $ par million.
Google précise que la plupart des tours d'agent dépassent ce seuil. Le problème se pose dans les boucles bavardes à petites étapes, comme une vérification d'état renvoyant {"ok": true}. Le coût est faible par tour (2 050 tokens à 3 $ par million, soit environ 0,006 $), mais cela s'accumule sur des milliers de tours courts. Si votre boucle effectue de nombreux micro-appels, regroupez les petits résultats d'outils en un seul tour lorsque votre logique le permet.
Quelles économies apporte le cache de contexte de Gemini 4 Neon ?
Prenons un assistant de revue de code qui répond à 20 questions sur une base de code de 200 000 tokens. Chaque question ajoute 3 000 tokens et obtient une réponse de 1 000 tokens, sur le palier Standard.
Sans correspondance en cache, chaque appel coûte :
- Entrée : 203 000 × 3 $ / 1M = 0,609 $
- Sortie : 1 000 × 15 $ / 1M = 0,015 $
- Par appel : 0,624 $, soit 12,48 $ pour 20 appels
Avec correspondances en cache après le premier appel, les appels 2 à 20 coûtent :
- Préfixe en cache : 200 000 × 0,15 $ / 1M = 0,030 $
- Nouvelle entrée : 3 000 × 3 $ / 1M = 0,009 $
- Sortie : 0,015 $
- Par appel : 0,054 $
En ajoutant le premier appel, non mis en cache, à 0,624 $, la session coûte 1,65 $, soit environ 87 % de moins.
L'économie est inférieure à 95 % car la sortie et la nouvelle entrée ne bénéficient jamais de la réduction. Plus le préfixe partagé est important par rapport au reste, plus vous vous approchez de 95 % sur l'entrée. Exécutez le même travail via Batch et le tarif en cache est encore divisé par deux, à 0,075 $. Pour la grille tarifaire complète et les coûts par niveau de réflexion, consultez les tarifs de Gemini 4 Neon.
Comment vérifier les tokens en cache de Gemini 4 Neon dans la réponse ?
Lisez usage.total_cached_tokens sur chaque réponse. Google la documente comme le champ indiquant combien de tokens ont été des correspondances en cache, dans les SDK Python et JavaScript.
Avec curl et jq :
curl -s "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | jq '.usage'
Pour facturer un appel, comptez les tokens en cache à 0,15 $ par million, le reste de votre entrée à 3 $, et la sortie plus la réflexion à 15 $. Enregistrez le compteur en cache à côté de votre identifiant de requête. Une chute soudaine à 0 sur tout le trafic signifie généralement qu'un déploiement a modifié le préfixe : un nouvel outil, une règle reformulée, ou un horodatage qui s'est glissé dans l'instruction système.
Laissez votre agent de code tester les correspondances en cache avec Apidog CLI
Les préfixes se cassent lors de refactorings ordinaires, et personne ne s'en aperçoit avant la facture. Transformez la vérification du cache en test API que votre agent de code maintient et que la CI exécute.
Apidog CLI permet à Claude Code, Codex, Cursor ou OpenCode de créer et d'exécuter des tests API depuis le terminal. Configurez-le une fois :
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Donnez ensuite un seul prompt à votre agent :
In Apidog project <id>, create an environment for the Gemini API with a
GEMINI_API_KEY variable. Build a test scenario called "Neon cache hit" with two
steps that POST to /v1beta/interactions with model gemini-4-neon, using our
production system_instruction and the docs/context.md file as the start of
input, then two different questions. Assert HTTP 200 on both, and assert that
usage.total_cached_tokens on step 2 is greater than 4096. Run it and tell me
the cached token count.
L'agent crée l'environnement et le scénario, vérifie son payload par rapport au schéma de la CLI, et l'exécute :
apidog environment create gemini-api --project <id> --base-url https://generativelanguage.googleapis.com
apidog test-scenario create --project <id> --name "Neon cache hit"
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file scenario.json
apidog test-scenario update <scenarioId> --project <id> --file scenario.json
apidog run -t <scenarioId> --project <id> -e <envId> -r cli,json
Si quelqu'un ajoute un horodatage au prompt système le mois prochain, l'assertion de l'étape 2 échouera avant la mise en production. Ajoutez apidog run -t <scenarioId> --project <id> -e <envId> -r junit à votre pipeline avec le guide CI/CD d'Apidog CLI, ou commencez avec Apidog CLI dans Claude Code. Chaque exécution effectue deux vrais appels à Neon, donc elle coûte quelques centimes au tarif indiqué ci-dessus. Le plan Gratuit d'Apidog couvre jusqu'à 4 utilisateurs.
Pour comprendre le fonctionnement du cache de préfixe chez les différents fournisseurs, consultez qu'est-ce que le cache de prompt.
FAQ
Gemini 4 Neon prend-il en charge le cache de contexte explicite ? Non. Le guide Neon de Google indique qu'il ne prend pas en charge cachedContents ni caches.create, et que vous devez retirer cached_content des requêtes. Neon utilise uniquement le cache implicite, activé par défaut.
Quelle est la taille minimale du prompt pour une correspondance en cache avec Gemini 4 Neon ? 4 096 tokens de préfixe partagé. C'est le même minimum que pour Gemini 4 Hydrogen, Argon et Carbon. Gemini 2.5 Flash et Pro exigent 2 048.
Quelle est la réduction du cache avec Gemini 4 Neon ? 95 % sur l'entrée en cache. Le palier Standard passe de 3 $ à 0,15 $ par million de tokens, Batch et Flex de 1,50 $ à 0,075 $, et Priority de 5,40 $ à 0,27 $. Les tokens de sortie et de réflexion ne sont pas réduits.
Puis-je forcer Gemini 4 Neon à mettre un prompt en cache ? Non. Le cache implicite n'offre aucun réglage à activer, aucun TTL à choisir, et aucune correspondance garantie. Vous augmentez vos chances en maintenant un préfixe long et identique au début de chaque requête, et en envoyant des requêtes similaires à intervalles rapprochés.
Comment savoir si ma requête a atteint le cache ? Vérifiez usage.total_cached_tokens dans la réponse. Une valeur supérieure à zéro signifie que autant de tokens d'entrée ont été facturés au tarif en cache.
Le cache fonctionne-t-il avec previous_interaction_id ? Oui. La documentation de Google précise que le cache implicite fonctionne aussi bien dans les conversations avec état chaînées via previous_interaction_id que dans les appels sans état où vous envoyez vous-même tout l'historique.


Top comments (0)