Mise en cache des prompts Claude

Documentation Index

Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt

Use this file to discover all available pages before exploring further.

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."
      }
    ]
  }'

{"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

​

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

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Structuration de votre prompt

​

Limitations du cache

• 1024 jetons pour Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 et Claude Opus 3
• 2048 jetons pour Claude Haiku 3.5 et Claude Haiku 3

• « ephemeral » : durée de vie par défaut de 5 minutes
• Cache 1 heure (Beta) : pour les scénarios nécessitant une durée de cache plus longue

​

Durée de cache d’1 heure (Beta)

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -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.

​

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. Les prompts mis en cache ne sont pas facturés, la récupération des jetons en cache coûte la moitié du tarif normal, et les caches sont automatiquement effacés après 5 à 10 minutes d’inactivité. Détails
• 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.