Le cache en pratique

Les règles du cache sont posées ; il reste à les câbler dans notre code. L’objectif de cette leçon : modifier notre fonction chat pour qu’elle pose automatiquement les points d’arrêt aux deux endroits qui rapportent le plus — les schémas d’outils et le prompt système — puis apprendre à lire les compteurs qui prouvent que le cache fonctionne réellement.

Cacher les schémas d’outils

Premier emplacement, et le plus rentable : les outils. On ajoute le cache_control sur le dernier outil de la liste — souvenez-vous, un breakpoint couvre tout ce qui le précède — mais sans modifier les définitions originales :

if tools:
    tools_clone = tools.copy()
    last_tool = tools_clone[-1].copy()
    last_tool["cache_control"] = {"type": "ephemeral"}
    tools_clone[-1] = last_tool
    params["tools"] = tools_clone

La double copie n’est pas de la paranoïa : tools appartient au code appelant, et les schémas d’outils sont typiquement des dictionnaires partagés par toute l’application. Modifier l’original en place y laisserait un cache_control fantôme, qui persisterait d’un appel à l’autre et resurgirait dans des contextes où on ne l’attend pas — le genre de bug d’état partagé qui coûte une soirée de débogage. En copiant la liste puis le dernier outil, la fonction chat pose son marqueur sur sa version locale et laisse le monde extérieur intact.

Cacher le prompt système

Deuxième emplacement : le prompt système, converti au passage en forme longue puisque le marqueur ne se pose que sur un bloc typé :

if system:
    params["system"] = [{
        "type": "text",
        "text": system,
        "cache_control": {"type": "ephemeral"}
    }]

L’appelant continue de passer une simple chaîne, comme avant ; c’est chat qui l’enveloppe dans la structure attendue. Nos deux breakpoints couvrent ainsi, ensemble, tout le contenu stable de la requête — outils puis système, dans l’ordre d’assemblage interne de l’API.

Comprendre le comportement du cache

Comment savoir si le cache fonctionne ? La réponse est dans le champ usage de chaque réponse, qui distingue les tokens selon leur traitement :

• Première requête : vous verrez cache_creation_input_tokens dans le champ usage
• Requêtes suivantes : vous verrez cache_read_input_tokens
• Contenu mixte : si vous gardez les mêmes outils mais changez le prompt système, vous lirez les outils depuis le cache tout en écrivant le nouveau prompt en cache

Prenez l’habitude de vérifier ces compteurs après toute mise en place de cache : c’est la seule preuve tangible. Un cache_creation_input_tokens qui réapparaît à chaque requête signale un cache qui ne se réutilise jamais — contenu sous le seuil de taille, ou variation involontaire d’une requête à l’autre. Le cas mixte montre au passage la finesse du mécanisme : chaque segment vit sa propre vie de cache, un préfixe stable peut être lu pendant qu’un segment aval est réécrit.

Invalidation du cache

Dernier rappel, car c’est la cause numéro un des caches inopérants : le cache est extrêmement sensible aux changements. Modifier un seul caractère dans le schéma d’outil ou le prompt système invalide le cache — le contenu sera traité comme neuf, et refacturé en création. Les coupables classiques sont les valeurs dynamiques glissées par mégarde dans le contenu « stable » : un horodatage dans le prompt système, un identifiant de session, une date du jour. Mettez en cache ce qui est réellement stable — schémas d’outils et prompts système invariants entre les requêtes — et gardez le contenu dynamique en aval des breakpoints, dans les messages, où il ne casse rien.

Points clés à retenir

• Deux branchements dans chat : cache_control sur le dernier outil, et prompt système en forme longue marquée
• Copiez liste et dernier outil avant de marquer — ne jamais muter les schémas partagés de l’application
• Preuve par usage : cache_creation_input_tokens à l’écriture, cache_read_input_tokens à la réutilisation
• Une création qui se répète à chaque requête = cache jamais réutilisé — cherchez la variation involontaire
• Un caractère modifié invalide tout : gardez horodatages et valeurs dynamiques hors des segments cachés