Le cache en pratique

Les règles sont posées ; place au code. Cette leçon ajoute la mise en cache à la fonction chat du cours, pour les définitions d’outils et le prompt système, puis montre comment lire dans la réponse ce qui a été écrit ou relu.

Le plus simple : la mise en cache automatique

Un seul paramètre suffit : l’API place le point d’arrêt sur le dernier bloc qui peut être mis en cache.

response = client.messages.create(
    model=model,
    max_tokens=4096,
    cache_control={"type": "ephemeral"},
    system=system_prompt,
    messages=messages,
)

C’est le bon point de départ pour une conversation qui s’allonge : à chaque tour, tout l’historique déjà vu est relu depuis le cache.

Des points d’arrêt sur les outils et le prompt système

Pour mettre en cache séparément les outils et le prompt système, on pose deux points d’arrêt explicites. Pour les outils, on marque la dernière définition de la liste, sans modifier les définitions d’origine :

def chat(messages, system=None, tools=None):
    params = {"model": model, "max_tokens": 4096, "messages": messages}
    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
    if system:
        params["system"] = [
            {"type": "text", "text": system, "cache_control": {"type": "ephemeral"}}
        ]
    return client.messages.create(**params)

Les copies évitent d’ajouter cache_control aux définitions partagées par le reste du programme : si vous réordonnez ensuite la liste des outils, aucun point d’arrêt ne traîne au mauvais endroit. Le prompt système, lui, passe de la chaîne simple à la forme longue, la seule qui accepte le champ.

Lire ce qui s’est passé

Trois champs de response.usage racontent l’histoire :

Le scénario typique, avec des outils et un prompt système assez longs :

1. Première requête : cache_creation_input_tokens compte les outils et le prompt système, écrits dans le cache.
2. Requêtes suivantes, dans les 5 minutes : cache_read_input_tokens affiche le même nombre, relu au lieu d’être recalculé.
3. Prompt système modifié : les outils, placés avant lui, sont encore relus, et le nouveau prompt système est écrit. Cette lecture partielle n’a lieu que si les outils atteignent seuls le seuil minimal du modèle.

u = response.usage
print(f"écrits : {u.cache_creation_input_tokens}, relus : {u.cache_read_input_tokens}, hors cache : {u.input_tokens}")

Un cache d’une heure

Pour une application consultée moins souvent que toutes les 5 minutes, on demande une durée d’une heure, avec une écriture facturée deux fois le prix d’entrée :

{"type": "text", "text": system, "cache_control": {"type": "ephemeral", "ttl": "1h"}}

Quand le cache rapporte le plus

• des définitions d’outils stables d’une requête à l’autre ;
• un prompt système long et stable, sans date ni identifiant de requête dedans ;
• des applications qui envoient de nombreuses requêtes au même contexte, dans la durée de vie du cache.

À vous de jouer

Mesurer le cache. Reprenez l’assistant de rappels de la section 5, avec ses trois outils et un prompt système d’au moins 600 jetons. Envoyez trois questions de suite et affichez les trois compteurs à chaque fois. Modifiez ensuite une phrase du prompt système et vérifiez que seuls les outils sont relus, à condition qu’ils atteignent seuls le seuil de 512 jetons ; sinon, tout est réécrit.

Sources officielles : Prompt caching in action (Claude Academy) · Prompt caching (documentation Claude : mise en cache automatique, champs d’usage, durée d’une heure)

Points clés à retenir

• cache_control au niveau de la requête : la mise en cache automatique, idéale pour une conversation.
• Pour les outils, un point d’arrêt sur la dernière définition, posé sur une copie.
• Pour le prompt système, la forme longue avec cache_control.
• cache_creation_input_tokens et cache_read_input_tokens montrent ce qui a été écrit et relu.
• "ttl": "1h" prolonge le cache à une heure, pour un prix d’écriture double.