Mise en cache des prompts GPT

​

Démarrage rapide

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [placez ici de longues instructions fixes ou des documents de référence, ≥1024 jetons]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # clé lue depuis la variable d'environnement
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [longues instructions fixes ou documents de référence, ≥1024 jetons]"

# Envoyer deux fois de suite le même préfixe ; la deuxième requête utilise le cache
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 1er appel : aucun hit
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2e appel : le préfixe touche le cache
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

Facturation du cache

​

Comment le cache s’applique automatiquement

1. Si le préfixe atteint 1 024 jetons et qu’un préfixe en cache identique est trouvé, la partie correspondante est facturée au tarif de lecture de cache et la latence du premier jeton diminue ;
2. Sinon, la requête est traitée comme entrée régulière et le préfixe est écrit dans le cache (facturé 1,25x pour GPT-5.6 et suivants) ;
3. Un hit exige une correspondance octet par octet du préfixe ; toute modification en un point du préfixe invalide l’ensemble du cache situé après ce point.

• Longues instructions système fixes ou nombreux exemples few-shot
• Longs documents de référence cités de manière répétée dans les scénarios RAG
• Workflows d’agents transportant de nombreuses définitions d’outils (tools)
• Longues conversations multi-tours qui ajoutent uniquement des messages à la fin

​

Paramètres de cache de GPT-5.6

1. Défaut (mode implicit) : le cache est écrit automatiquement même sans aucun paramètre de cache — le système place automatiquement un point de rupture à la position du message le plus récent. Pour GPT-5.6 et suivants, les écritures en cache automatiques sont également facturées à 1,25x.
2. Mode implicit + point de rupture explicite : en plus du point de rupture automatique, prompt_cache_breakpoint peut être placé sur un bloc de contenu pour fixer la limite du cache à la fin du contenu stable ; les modifications situées après le point de rupture ne détruisent pas le cache du préfixe qui le précède.
3. Mode explicit : lorsque prompt_cache_options.mode vaut "explicit", seuls les points de rupture manuels sont utilisés ; si aucun point de rupture n’est défini, la requête n’utilise pas le cache et ne génère pas de frais d’écriture. Texte officiel : “If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[long contenu unique qui ne sera pas réutilisé]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[longues instructions fixes ou documents de référence, ≥1024 jetons]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• Chaque requête crée au maximum 4 nouvelles écritures en cache ; en mode implicit, le point de rupture automatique en occupe 1 ;
• Le préfixe situé avant un point de rupture doit toujours atteindre 1 024 jetons pour être mis en cache ;
• À la lecture, le préfixe correspondant le plus long est retenu parmi les 50 derniers points de rupture ;
• Un point de rupture placé sur un bloc de contenu non pris en charge renvoie 400 invalid_request_error. Chat Completions prend en charge les blocs text / image_url / input_audio / file / refusal, la Responses API les blocs input_text / input_image / input_file.

​

Pourquoi le cache n’est pas touché

• Préfixe inférieur à 1 024 jetons : les requêtes en dessous de la longueur minimale de cache sont traitées comme entrée régulière ;
• Contenu variable mêlé au préfixe : horodatages, identifiants de session, variables utilisateur doivent être placés après le contenu fixe ; toute modification dans le préfixe invalide le cache situé après ;
• Définitions ou ordre des tools modifiés : la liste d’outils participe au calcul du préfixe ; les définitions et leur ordre doivent être strictement identiques ;
• Paramètre detail d’image incohérent : detail influe sur la tokenisation des images et doit rester identique ;
• Schéma de sortie structurée modifié : le JSON Schema de response_format participe au cache en tant que préfixe du message système ; un changement de schéma change le préfixe ;
• reasoning_effort modifié : cité officiellement parmi les causes courantes d’une baisse du taux de hits (“Changes to reasoning effort”) ;
• Durée de rétention dépassée : avant GPT-5.6, le cache est effacé après 5–10 minutes d’inactivité ; GPT-5.6 et suivants le conservent au moins 30 minutes ;
• prompt_cache_key non défini (GPT-5.6) : sans ce paramètre, un hit automatique reste possible, mais le mécanisme de correspondance plus fiable n’est pas utilisé.

​

Bonnes pratiques

• Placez le contenu fixe (instructions système, exemples, documents de référence, définitions d’outils) au tout début de la requête, et le contenu variable à chaque tour à la fin ;
• Attribuez la même prompt_cache_key stable au trafic partageant le même préfixe ; maintenez le trafic total d’une key autour de 15 requêtes/minute et répartissez sur plusieurs keys par activité au-delà ;
• Dans les conversations multi-tours, ajoutez uniquement des messages à la fin, sans modifier les messages historiques ;
• Maintenez un trafic continu sur les requêtes partageant le même préfixe pour réduire l’effacement du cache ;
• Pour les longues requêtes uniques dont le préfixe ne sera pas réutilisé, utilisez le mode explicit pour éviter les frais d’écriture en cache (GPT-5.6 et suivants) ;
• Surveillez en continu les hits via usage.prompt_tokens_details.cached_tokens.

​

Foire aux questions (FAQ)

​

La mise en cache des prompts GPT doit-elle être activée manuellement ?

​

Comment sont calculés les frais d’écriture en cache de GPT-5.6 ? Comment éviter des frais d’écriture inutiles ?

​

Combien de temps le cache est-il conservé ?

​

Quelle différence entre les points de rupture explicites de GPT-5.6 et le cache_control de Claude ?

​

Le cache influe-t-il sur le contenu de sortie ?

​

Références officielles

• Annonce de lancement de GPT-5.6 : règle de facturation — écriture en cache 1,25x / lecture avec remise de 90 %
• Guide de mise en cache des prompts : mécanisme, paramètres, champs usage et limites
• OpenAI Pricing : tarifs officiels de chaque modèle
• Documentation du modèle GPT-5.6 : fenêtre de contexte, seuil de facturation du contexte long