Mise en cache des prompts Claude

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    base_url="https://aihubmix.com"
)

# Streaming response with caching
with client.messages.stream(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    thinking={
        "type": "enabled",
        "budget_tokens": 16000
    },
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Non-streaming response
message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works."
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
)
print(message.content)

import requests

url = "https://aihubmix.com/v1/messages"
headers = {
    "content-type": "application/json",
    "x-api-key": "sk-***", # Replace with the key you generated in AiHubMix
    "anthropic-version": "2023-06-01"
}
data = {
    "stream": True,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}]
}

response = requests.post(url, headers=headers, json=data, stream=True)

# Check response status
if response.status_code == 200:
    # Process the streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
else:
    print(f"Error: {response.status_code}, {response.text}")

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

Fonctionnement de la mise en cache des prompts

1. Le système vérifie si un préfixe de prompt, jusqu’à un point de rupture de cache spécifié, est déjà mis en cache à partir d’une requête récente.
2. S’il est trouvé, il utilise la version mise en cache, réduisant le temps de traitement et les coûts.
3. Sinon, il traite l’intégralité du prompt et met en cache le préfixe dès que la réponse commence. Cela est particulièrement utile pour :

• Les prompts contenant de nombreux exemples
• De grandes quantités de contexte ou d’informations de fond
• Les tâches répétitives avec des instructions cohérentes
• Les longues conversations multi-tours

​

Erreur courante : « écrire le cache sans jamais le lire »

​

❌ Mauvaise approche : placer la question variable à chaque tour avant le point de rupture

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← changes every turn, yet placed before the breakpoint
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // breakpoint
      ]
    }
  ]
}

​

✅ Bonne approche : grand document en premier + point de rupture + question en dernier

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // breakpoint; prefix stays constant
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← the per-turn question, placed after the breakpoint
      ]
    }
  ]
}

​

Comparaison mesurée (claude-opus-4-6, quelques secondes entre les deux appels)

1. Placez le bloc fixe et volumineux (document de référence, contexte long) tout au début du message utilisateur messages, avec cache_control à sa fin, et n’en modifiez pas un seul caractère ;
2. Placez la question/instruction variable à chaque tour après le point de rupture (après le grand document dans le même message user, ou dans les messages suivants) ; dans les conversations multi-tours, ajoutez uniquement — ne revenez jamais en arrière pour modifier les messages précédents ;
3. Lorsque thinking est activé, les blocs thinking des tours assistant précédents doivent être renvoyés tels quels, sinon le préfixe se brise de la même manière (voir « Ce qui ne peut pas être mis en cache » ci-dessous) ;
4. Si un bloc est plus petit que le seuil minimum de cache (de 512 à 4 096 jetons selon le modèle, voir la section « Limitations du cache » ci-dessous), il ne sera pas écrit dans le cache même s’il est marqué avec cache_control — c’est le comportement attendu, voir « Limitations du cache » ci-dessous.

​

Tarification

• Les jetons d’écriture en cache (5 minutes) sont 1,25 fois le prix des jetons d’entrée de base
• Les jetons d’écriture en cache (1 heure) sont 2 fois le prix des jetons d’entrée de base
• Les jetons de lecture en cache sont 0,1 fois le prix des jetons d’entrée de base
• Les jetons d’entrée et de sortie réguliers sont facturés aux tarifs standard de la plateforme

​

Comment implémenter la mise en cache des prompts

​

Modèles pris en charge

​

Mise en cache automatique (cache_control au niveau racine)

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are an AI assistant tasked with analyzing literary works.",
  "messages": [
    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
  ]
}

​

Structuration de votre prompt

​

Limitations du cache

• « ephemeral » : durée de vie par défaut de 5 minutes
• Cache d’1 heure : réglez "ttl": "1h" dans cache_control, pour les scénarios nécessitant une durée de cache plus longue

​

Durée de cache d’1 heure

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

Quand utiliser le cache d’1 heure

• Traitement par lots : traitement de gros volumes de requêtes avec des préfixes communs
• Sessions de longue durée : conversations nécessitant le maintien du contexte sur des périodes prolongées
• Analyse de documents volumineux : plusieurs types d’analyses différentes sur le même document
• Questions-réponses sur du code : multiples requêtes sur la même base de code sur des périodes prolongées

​

Mélanger différents TTL

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

Ce qui peut être mis en cache

• Outils : définitions d’outils dans le tableau tools
• Messages système : blocs de contenu dans le tableau system
• Messages : blocs de contenu dans le tableau messages.content, à la fois pour les tours utilisateur et assistant
• Images et documents : blocs de contenu dans le tableau messages.content, dans les tours utilisateur
• Utilisation d’outils et résultats d’outils : blocs de contenu dans le tableau messages.content, à la fois pour les tours utilisateur et assistant

​

Ce qui ne peut pas être mis en cache

• Les blocs thinking ne peuvent pas être mis en cache directement avec cache_control. Cependant, les blocs thinking PEUVENT être mis en cache aux côtés d’autres contenus lorsqu’ils apparaissent dans des tours assistant précédents. Lorsqu’ils sont mis en cache de cette manière, ils COMPTENT comme jetons d’entrée lorsqu’ils sont lus depuis le cache.
• Les sous-blocs de contenu (comme les citations) ne peuvent pas être mis en cache directement. Mettez plutôt en cache le bloc de niveau supérieur.
• Les blocs de texte vides ne peuvent pas être mis en cache.

​

Suivi des performances du cache

• cache_creation_input_tokens : nombre de jetons écrits dans le cache lors de la création d’une nouvelle entrée.
• cache_read_input_tokens : nombre de jetons récupérés depuis le cache pour cette requête.
• input_tokens : nombre de jetons d’entrée qui n’ont pas été lus depuis ou utilisés pour créer un cache.

​

Bonnes pratiques pour une mise en cache efficace

• Mettez en cache du contenu stable et réutilisable comme les instructions système, les informations de fond, les contextes volumineux ou les définitions d’outils fréquentes.
• Placez le contenu mis en cache au début du prompt pour de meilleures performances.
• Utilisez les points de rupture de cache de manière stratégique pour séparer différentes sections de préfixe pouvant être mises en cache.
• Analysez régulièrement les taux de succès du cache et ajustez votre stratégie au besoin.
• Pour le contenu à long terme, envisagez d’utiliser le cache d’1 heure pour une meilleure efficacité des coûts.

​

Optimisation selon les cas d’usage

• Agents conversationnels : réduisez le coût et la latence pour les conversations prolongées, en particulier celles avec de longues instructions ou des documents téléchargés.
• Assistants de programmation : améliorez l’auto-complétion et les questions-réponses sur la base de code en gardant les sections pertinentes ou une version résumée de la base de code dans le prompt.
• Traitement de documents volumineux : intégrez du contenu long complet, y compris des images, dans votre prompt sans augmenter la latence de réponse.
• Ensembles d’instructions détaillées : partagez des listes étendues d’instructions, de procédures et d’exemples pour affiner les réponses de Claude. Les développeurs incluent souvent un ou deux exemples dans le prompt, mais avec la mise en cache des prompts, vous pouvez obtenir de meilleures performances en incluant plus de 20 exemples variés de réponses de haute qualité.
• Utilisation agentique d’outils : améliorez les performances pour les scénarios impliquant plusieurs appels d’outils et modifications itératives de code, où chaque étape nécessite généralement un nouvel appel d’API.
• Dialoguer avec des livres, articles, documentations, transcriptions de podcasts et autres contenus longs : donnez vie à n’importe quelle base de connaissances en intégrant l’ensemble du ou des documents dans le prompt, et permettez aux utilisateurs de poser des questions.

​

Dépannage des problèmes courants

• Assurez-vous que les sections mises en cache sont identiques et marquées avec cache_control aux mêmes emplacements à travers les appels
• Vérifiez que les appels sont effectués dans la durée de vie du cache (5 minutes ou 1 heure)
• Vérifiez que tool_choice et l’utilisation des images restent cohérents entre les appels
• Vérifiez que vous mettez en cache au moins le nombre minimum de jetons
• Bien que le système tentera d’utiliser le contenu précédemment mis en cache aux positions antérieures à un point de rupture de cache, vous pouvez utiliser un paramètre cache_control supplémentaire pour garantir la recherche en cache sur les portions précédentes du prompt, ce qui peut être utile pour les requêtes contenant de très longues listes de blocs de contenu

​

Stockage et partage du cache

• Isolation par organisation : les caches sont isolés entre les organisations. Différentes organisations ne partagent jamais leurs caches, même si elles utilisent des prompts identiques.
• Correspondance exacte : les hits de cache nécessitent des segments de prompt 100 % identiques, y compris tous les textes et images jusqu’au bloc marqué avec cache_control (inclus). Le même bloc doit être marqué avec cache_control lors des lectures et créations de cache.
• Génération de jetons de sortie : la mise en cache des prompts n’a aucun effet sur la génération des jetons de sortie. La réponse que vous recevez sera identique à celle que vous obtiendriez sans la mise en cache des prompts.

​

Activer la mise en cache Claude dans les clients / plateformes

​

Dify (via le plugin Aihubmix)

1. Encadrez le prompt à mettre en cache (le prompt système fixe / le contexte long) avec <cache>…</cache> ; le plugin le convertira automatiquement en un point de rupture cache_control à cet endroit ;
2. Dans les paramètres du modèle, réglez le « seuil de mise en cache automatique des messages volumineux » sur un entier positif : le cache n’est réellement écrit qu’une fois que le contenu atteint ce seuil de jetons (toujours soumis à l’exigence de cache minimum décrite dans « Limitations du cache » ci-dessous, soit 4096 jetons pour Opus 4.5/4.6 et Haiku 4.5) ; le régler à 0 ou le laisser vide le désactive.

​

Cherry Studio

1. Cliquez sur l’engrenage à droite du nom du fournisseur Aihubmix pour ouvrir les « API Settings » :

2. Configurez les trois éléments suivants, et le client injectera automatiquement cache_control pour Claude en conséquence :

• Cache Token Threshold : un point de rupture de cache n’est injecté qu’une fois que le contenu dépasse ce nombre de jetons (réglez un nombre positif pour activer, 0 ou vide pour désactiver) ;
• Cache System Message : une fois activé, un point de rupture de cache est placé sur le message system (idéal pour mettre en cache un prompt système long et fixe) ;
• Cache Last N Messages : place un point de rupture de cache sur les N messages les plus récents (idéal pour une mise en cache glissante dans les conversations multi-tours).

​

Foire aux questions (FAQ)

​

Pourquoi le cache est-il écrit (cache_creation_input_tokens élevé) mais jamais lu (cache_read_input_tokens à 0) ?

​

Combien de jetons faut-il au minimum pour la mise en cache ?

​

Combien de temps le cache reste-t-il valide ? Peut-on passer à 1 heure ?

​

Comment activer la mise en cache dans Dify / Cherry Studio ?

​

Prise en charge selon les différents modèles

• La prise en charge de la mise en cache des prompts dépend du modèle lui-même.
• Si le modèle prend en charge nativement la mise en cache sans nécessiter de déclarations de paramètres explicites, cela peut être pris en charge via la redirection compatible OpenAI.
• OpenAI prend en charge la mise en cache des prompts par défaut, avec application automatique (préfixe ≥1024 jetons). Pour les modèles antérieurs à GPT-5.6, l’écriture en cache est sans facturation supplémentaire et le cache est effacé automatiquement après 5 à 10 minutes d’inactivité ; pour GPT-5.6 et suivants, l’écriture en cache est facturée à 1,25 fois le prix d’entrée, la lecture à 0,1 fois, le cache est conservé au moins 30 minutes et les points de rupture de cache explicites sont pris en charge. Détails sur Mise en cache des prompts GPT.
• Claude nécessite la déclaration native cache_control: { type: "ephemeral" }. Le taux de mise en cache est 1,25 fois le coût d’entrée standard (5 minutes) ou 2 fois (1 heure), la récupération des jetons en cache coûte 0,1 fois le tarif normal, avec un cycle de vie de 5 minutes ou 1 heure. Détails
• Deepseek V3 et R1 prennent en charge nativement la mise en cache. Le taux de mise en cache est égal au coût d’entrée standard, la récupération des jetons en cache coûte 0,1 fois le tarif normal. Détails
• Gemini prise en charge du cache implicite :
  • Mise en cache implicite : activée par défaut pour tous les modèles Gemini 2.5. Si votre requête atteint le cache, les économies de coûts sont automatiquement appliquées. Cette fonctionnalité est effective depuis le 8 mai 2025. Le nombre minimum de jetons d’entrée pour la mise en cache du contexte est de 1 024 pour Gemini 2.5 Flash et 2 048 pour Gemini 2.5 Pro.
  • Astuces pour améliorer le taux de succès du cache implicite :
    • Essayez de placer le contenu volumineux et fréquemment réutilisé au début du prompt.
    • Essayez d’envoyer des requêtes avec des préfixes similaires dans une courte fenêtre temporelle.
  • Vous pouvez voir le nombre de jetons en cache hit dans le champ usage_metadata de l’objet de réponse.
  • Les économies de coûts sont calculées sur la base des hits de cache de prefill. Seuls le cache de prefill et le cache de prétraitement vidéo YouTube sont éligibles à la mise en cache implicite.