Prompt Caching : Economisez 90% sur vos requetes API Claude

Vous envoyez le meme contexte de 50 000 tokens a chaque requete ? Vous payez pour retraiter encore et encore la meme documentation ? Le prompt caching est votre meilleur allie. Je vais vous montrer comment j’ai reduit mes couts API de 90% sur un projet reel.

Comment ca marche : les bases techniques

Le prompt caching permet a Claude de mettre en cache certaines parties de votre prompt. Au lieu de retraiter tout le contexte a chaque requete, Claude reutilise ce qui est deja en memoire.

Les chiffres qui changent tout :

Ecriture en cache : 25% plus cher que le tarif normal
Lecture depuis le cache : 90% moins cher que le tarif normal
Duree de vie : 5 minutes d’inactivite avant expiration

Si vous faites plusieurs requetes dans les 5 minutes avec le meme contexte, vous payez une seule fois l’ecriture, puis 90% de reduction sur toutes les lectures suivantes. Le ROI est immediat des la 2e requete.

Implementation pratique avec le SDK Python

Voici comment activer le caching. Le secret : ajouter des cache_control breakpoints dans votre prompt.

import anthropic

client = anthropic.Anthropic(api_key="votre-cle")

# Exemple : assistant qui connait votre codebase
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Tu es un assistant qui connait notre codebase Python."
        },
        {
            "type": "text",
            "text": "Voici le contenu de notre fichier utils.py:\n\n" + open("utils.py").read(),
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Comment utiliser la fonction parse_config ?"}
    ]
)

print(response.content)

Le cache_control marque la fin d’un bloc a mettre en cache. Tout ce qui precede ce marqueur sera cache. Vous pouvez mettre plusieurs breakpoints dans votre prompt.

Les 3 cas d’usage qui rentabilisent vraiment

1. Documentation volumineuse

Vous construisez un chatbot qui connait votre doc produit de 100 pages ? Mettez toute la doc en system prompt avec un cache breakpoint. Chaque question utilisateur reutilise le meme contexte cache.

system_prompt = [
    {"type": "text", "text": "Tu es le support client de ProductX."},
    {
        "type": "text",
        "text": load_documentation(),  # 50k tokens de doc
        "cache_control": {"type": "ephemeral"}
    }
]

# Chaque conversation client reutilise le cache
for question in user_questions:
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=512,
        system=system_prompt,
        messages=[{"role": "user", "content": question}]
    )

2. Conversations longues avec contexte

Vous gerez une conversation multi-tours ? Cachez tout l’historique sauf le dernier message.

messages = [
    {"role": "user", "content": "Explique-moi les decorators Python"},
    {"role": "assistant", "content": "Les decorators sont..."},
    {"role": "user", "content": "Donne un exemple avec @property"},
    {"role": "assistant", "content": "Voici un exemple..."},
    # ... 10 tours de conversation
]

# Cachez tout l'historique
messages[-2]["cache_control"] = {"type": "ephemeral"}

# Nouvelle question
messages.append({"role": "user", "content": "Et avec @staticmethod ?"})

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=messages
)

3. Code review automatise

Vous analysez plusieurs fichiers d’une PR ? Cachez le contexte du repo et les guidelines.

system = [
    {"type": "text", "text": "Tu fais des code reviews selon nos standards."},
    {"type": "text", "text": load_coding_guidelines(), "cache_control": {"type": "ephemeral"}},
    {"type": "text", "text": load_repo_structure(), "cache_control": {"type": "ephemeral"}}
]

# Reviewez chaque fichier modifie sans repayer le contexte
for file in modified_files:
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=2048,
        system=system,
        messages=[{"role": "user", "content": f"Review ce fichier:\n{file.content}"}]
    )

Les pieges a eviter

Piege 1 : Cache trop petit Le cache doit faire minimum 1024 tokens. Si votre bloc est plus petit, il ne sera pas cache. Regroupez vos contextes.

Piege 2 : Oublier les 5 minutes Si vous espacez vos requetes de plus de 5 minutes, le cache expire. Pour un traitement batch, parallelisez ou accelerez votre pipeline.

Piege 3 : Cache au mauvais endroit Cachez ce qui ne change pas, pas ce qui varie. La question de l’utilisateur ne doit jamais etre cachee, seulement le contexte stable.

Piege 4 : Trop de breakpoints Chaque cache_control cree un point de cache. Plus vous en avez, plus c’est complexe a gerer. En general, 1 a 3 breakpoints suffisent.

Monitoring et optimisation

La reponse API vous indique exactement ce qui s’est passe :

response = client.messages.create(...)

print(f"Tokens caches ecrits: {response.usage.cache_creation_input_tokens}")
print(f"Tokens caches lus: {response.usage.cache_read_input_tokens}")
print(f"Tokens normaux: {response.usage.input_tokens}")

Vous pouvez calculer vos economies reelles :

def calculate_savings(usage, price_per_mtok_input=3.0):
    # Prix pour Claude 3.5 Sonnet (ajustez selon votre modele)
    normal_cost = usage.input_tokens * price_per_mtok_input / 1_000_000
    cache_write_cost = usage.cache_creation_input_tokens * price_per_mtok_input * 1.25 / 1_000_000
    cache_read_cost = usage.cache_read_input_tokens * price_per_mtok_input * 0.1 / 1_000_000
    
    total_cost = normal_cost + cache_write_cost + cache_read_cost
    saved = usage.cache_read_input_tokens * price_per_mtok_input * 0.9 / 1_000_000
    
    return total_cost, saved

Avec TypeScript aussi

Le SDK TypeScript supporte exactement la meme syntaxe :

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'Tu es un assistant technique.',
    },
    {
      type: 'text',
      text: largeDocumentation,
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [
    { role: 'user', content: 'Ma question' },
  ],
});

Conclusion : quand l’activer ?

Activez le prompt caching si :

Vous avez un contexte de plus de 1024 tokens qui se repete
Vous faites plusieurs requetes dans un intervalle de 5 minutes
Vous voulez reduire la latence (le cache accelere aussi le traitement)

Ne l’activez pas si :

Votre contexte change a chaque requete
Vous faites une seule requete isolee
Votre contexte fait moins de 1024 tokens

Dans mon projet de chatbot documentation, je suis passe de 2,40€ par jour a 0,25€ avec exactement le meme volume. Le prompt caching n’est pas une option, c’est une evidence economique des que vous avez du contexte repetitif.

Testez sur vos prochaines requetes et regardez les metriques cache_read_input_tokens exploser. C’est la que vous voyez vos economies en temps reel.