Les règles du cache

Le prompt caching ne se déclenche jamais tout seul : rien n’est mis en cache tant que vous ne le demandez pas explicitement. Le mécanisme de contrôle s’appelle le point d’arrêt de cache (cache breakpoint) — un marqueur que vous posez dans la requête et qui signifie : « tout ce qui précède ce point mérite d’être conservé ». Savoir où poser ces marqueurs, et ce que l’API accepte de mettre en cache, fait toute la différence entre un cache qui divise vos coûts et un cache qui ne sert jamais.

Points d’arrêt de cache

La règle fondamentale : tout ce qui précède un point d’arrêt est mis en cache, et le cache n’est réutilisé que si le contenu jusqu’au point d’arrêt est strictement identique d’une requête à l’autre. Un caractère de différence — un espace, une date qui change, un identifiant de session glissé dans le prompt système — et c’est un cache miss : l’API refacture le traitement complet. Cette exactitude au caractère près est la contrainte de conception numéro un : elle impose de séparer rigoureusement le contenu stable du contenu variable.

Techniquement, le marqueur se pose via le champ cache_control, ce qui oblige à utiliser la forme longue des blocs de texte :

user_message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "votre texte",
            "cache_control": {
                "type": "ephemeral"
            }
        }
    ]
}

La forme courte — "content": "votre texte" — ne peut pas porter de métadonnées ; dès qu’on cache, on écrit ses messages comme des listes de blocs typés.

Emplacements des points d’arrêt

Vous pouvez placer des points d’arrêt sur :

• Les définitions d’outils (cas le plus courant)
• Les prompts système
• Les messages

# Outils avec cache
tools[-1]["cache_control"] = {"type": "ephemeral"}

# Prompt systeme avec cache
system = [{
    "type": "text",
    "text": "Vous êtes un ingénieur senior...",
    "cache_control": {"type": "ephemeral"}
}]

La première ligne condense une subtilité importante : le marqueur se pose sur le dernier outil de la liste (tools[-1]), et comme un breakpoint couvre tout ce qui le précède, c’est l’intégralité du bloc d’outils qui est mise en cache d’un coup. Inutile de marquer chaque schéma individuellement. Même logique pour un prompt système : un seul marqueur sur son dernier bloc suffit à couvrir l’ensemble.

Ordre du cache

Pour raisonner juste, il faut connaître l’ordre d’assemblage interne : l’API joint toujours les outils, puis le prompt système, puis les messages — dans cet ordre, quel que soit l’ordre de vos paramètres. Conséquence directe : une modification en amont invalide tout ce qui suit. Changez un schéma d’outil, et le cache du prompt système et des messages tombe avec lui ; changez le prompt système, et les outils restent cachés mais les messages sont recalculés. D’où la règle d’organisation : le plus stable en tête de requête, le plus volatil en queue. Jusqu’à quatre points d’arrêt sont autorisés par requête, ce qui permet des paliers — outils, système, historique long, dernier échange.

Taille minimum et durée de vie

Deux contraintes chiffrées complètent le tableau. D’abord, un segment doit atteindre au moins 1 024 tokens pour être mis en cache (le seuil monte à 2 048 sur les modèles Haiku) : en dessous, le marqueur est simplement ignoré — cacher trois lignes n’aurait aucun intérêt économique. Ensuite, le cache est éphémère, comme son type l’indique : sa durée de vie de base est de cinq minutes, rafraîchie à chaque réutilisation. Un assistant en conversation active garde donc son cache chaud en permanence, tandis qu’un utilisateur qui revient après dix minutes d’absence repart de zéro.

Côté facturation, le modèle économique du cache tient en deux chiffres à retenir : l’écriture initiale coûte environ 25 % de plus qu’un traitement normal, la lecture coûte environ 90 % de moins. Le cache devient donc rentable dès la deuxième utilisation — et c’est bien pour cela que la clé d’un cache efficace est d’identifier les parties de vos requêtes qui restent stables, généralement les schémas d’outils et le prompt système, et d’y placer les breakpoints stratégiquement.

Points clés à retenir

• Rien n’est caché sans marqueur explicite cache_control: {"type": "ephemeral"} — posé sur des blocs en forme longue
• Le cache exige une identité stricte jusqu’au breakpoint : un caractère variable = cache miss
• Un breakpoint sur tools[-1] couvre tous les outils ; ordre interne immuable : outils → système → messages
• Toute modification en amont invalide l’aval — placez le stable en tête, le volatil en queue ; quatre breakpoints maximum
• Minimum 1 024 tokens (2 048 sur Haiku) ; durée de vie 5 minutes rafraîchie à chaque hit ; écriture +25 %, lecture −90 %