Prompt caching en pratique : implémentation pas à pas

Maintenant que vous connaissez la théorie, voyons comment implémenter concrètement le prompt caching dans vos applications. L’objectif : rendre vos requêtes API plus rapides et moins coûteuses quand vous envoyez repetivement le même contenu.

Rappel du fonctionnement

Quand vous activez le caching :

1. La première requête écrit le contenu dans un cache dont la durée de vie par défaut est de 5 minutes, réinitialisée à chaque lecture
2. Les requêtes suivantes lisent depuis ce cache au lieu de tout retraiter

C’est particulièrement rentable quand vous envoyez :

• Un prompt système long (par exemple 6000 tokens pour un assistant de code)
• Des schémas d’outils complexes (environ 1700 tokens pour plusieurs outils)
• Du contenu de messages répété

Mettre en cache les schémas d’outils

Pour cacher vos schémas d’outils, ajoutez le champ cache_control au dernier outil de votre liste. Voici la bonne façon de le faire sans modifier vos définitions originales :

if tools:
    # Créer des copies pour ne pas modifier les originaux
    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

Pourquoi faire des copies ? Si vous modifiez directement tools[-1]["cache_control"], vous risquez des problèmes en cas de réordonnancement ultérieur de vos outils. La copie est une précaution simple et efficace.

Mettre en cache le prompt système

Pour le prompt système, il faut le transformer en bloc structuré avec le champ cache_control :

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

On passe d’une simple chaîne de caractères à un format structuré qui supporte le caching.

Comprendre le comportement du cache

Quand vous exécutez des requêtes avec le caching activé, les métriques d’utilisation dans la réponse vous indiquent ce qui se passe :

Le cache est extrêmement sensible : changer ne serait-ce qu’un seul caractère invalide tout ce qui suit le point de modification. La conséquence pratique dicte l’ordre de votre prompt — placez ce qui est stable au début (instructions, schémas d’outils, documents de référence) et ce qui varie à la fin. Un horodatage glissé en tête de prompt système suffit à ne jamais rien mettre en cache, et le symptôme est discret : tout fonctionne, seule la facture ne baisse pas. Changer un seul caractère dans vos outils ou votre prompt système invalide donc tout le cache pour ce composant.

Ordre du cache et breakpoints multiples

Vous pouvez définir plusieurs breakpoints dans une même requête. L’ordre de traitement est important :

1. Outils (si fournis)
2. Prompt système (si fourni)
3. Messages

Conséquence pratique : si vous changez votre prompt système mais gardez les mêmes outils, vous verrez une lecture partielle du cache (pour les outils) et une écriture (pour le nouveau prompt système). Ce caching granulaire signifie que vous ne payez le retraitement que pour les parties qui ont réellement change.

Considérations pratiques

Le prompt caching est le plus efficace quand vous avez :

• Des schémas d’outils stables entre les requêtes
• Des prompts système constants
• Des applications qui font de nombreuses requêtes avec un contexte similaire

N’oubliez pas la durée de vie : 5 minutes par défaut, remises à zéro à chaque fois que le cache est lu. Un service sollicité en continu garde donc son cache chaud indéfiniment, tandis qu’un usage espacé le laisse expirer entre deux requêtes et repaie l’écriture à chaque fois. Une option de cache étendu à une heure existe pour les cas où les requêtes sont trop espacées. Dans tous les cas, c’est conçu pour des applications avec une utilisation API relativement fréquente, pas pour du stockage à long terme.

Exercice : implémenter le caching

Prenez une de vos applications existantes qui utilise l’API Claude et :

1. Identifiez les parties du prompt qui restent identiques entre les requêtes (prompt système, outils)
2. Ajoutez les cache_control breakpoints aux endroits stratégiques
3. Comparez les métriques cache_creation_input_tokens vs cache_read_input_tokens dans les réponses successives
4. Mesurez l’amélioration du temps de réponse et du coût