Mise en cache des prompts

Modifier une requête ne supprime pas nécessairement une entrée du cache. Ce qui compte, c’est que la requête suivante présente le même préfixe et puisse trouver un point de coupure admissible correspondant. Voici les principaux paramètres à vérifier :

Pour GPT-5.6 et les modèles ultérieurs, les écritures en cache coûtent 1,25 fois le tarif standard des tokens d’entrée hors cache pour la durée de vie par défaut de 30 minutes. Dans l’API Responses, vous pouvez choisir une durée de vie minimale de 12 heures. Le tarif d’écriture est alors de 2,5 fois le tarif d’entrée standard. Quelle que soit la durée choisie, les lectures suivantes coûtent 0,1 fois le tarif d’entrée standard sur la plupart de ces modèles et 0,05 fois ce tarif sur GPT-6.1 Sol et GPT-6.1 Terra.

Avec des lectures au coefficient 0,1 et des écritures de 30 minutes, écrire un préfixe une fois et le réutiliser intégralement une fois coûte 1,35 fois son coût d’entrée standard, contre 2 fois ce coût pour deux traitements hors cache. Sur dix requêtes, une écriture et neuf lectures intégrales coûtent 2,15 fois le coût d’entrée standard à ce tarif, contre 10 fois ce coût sans mise en cache.

Ces modèles prennent en charge la mise en cache implicite et explicite. Le mode explicite vous permet de choisir plus précisément les parties du contexte à écrire en cache.

Mode explicite : vous choisissez où placer les points de coupure en fonction de la manière dont vous gérez le contexte.

• Définissez prompt_cache_options.mode sur explicit pour utiliser uniquement les points de coupure choisis par le développeur. Marquez chaque point souhaité en ajoutant prompt_cache_breakpoint: { "mode": "explicit" } à un bloc de contenu compatible dans un message d’entrée.
• En l’absence de point de coupure explicite, la requête n’utilise pas la mise en cache des prompts et n’effectue aucune écriture en cache.
• Le mode exclusivement explicite vous permet de choisir où s’arrêtent les écritures en cache. Le contenu situé après le dernier point sélectionné est traité au tarif des tokens d’entrée hors cache, sans frais d’écriture en cache. Vous pouvez ainsi éviter d’écrire du contenu variable qui a peu de chances d’être réutilisé.
• Plusieurs points de coupure explicites permettent de conserver des préfixes qui évoluent à des rythmes différents. Chaque requête peut effectuer jusqu’à quatre écritures en cache.
• Les éléments d’entrée additional_tools n’acceptent pas actuellement prompt_cache_breakpoint.

Mode implicite : OpenAI choisit automatiquement des emplacements de points de coupure adaptés à la plupart des cas d’usage.

• Lorsque prompt_cache_options.mode vaut implicit, OpenAI place un point de coupure à la fin du dernier message admissible. Les messages admissibles sont :
  • les messages utilisateur,
  • la dernière réponse d’une suite de réponses d’outils consécutives,
  • le dernier message de la suite initiale de messages de développeur consécutifs.
• Vous pouvez ajouter des points de coupure explicites tout en conservant le point implicite. Celui-ci utilise l’une des quatre écritures en cache disponibles, ce qui laisse trois écritures pour les points explicites.

Seule la mise en cache implicite est prise en charge. OpenAI place les points de coupure implicites à des intervalles propres au modèle, mesurés à partir du début du message système masqué d’OpenAI. Seuls les points qui atteignent ou dépassent la longueur minimale de mise en cache sont admissibles. Cette longueur se mesure à partir de la fin du contexte masqué.

Pour calculer la valeur renvoyée dans cached_tokens, OpenAI soustrait le nombre de tokens système masqués de la position du dernier point de coupure correspondant, puis arrondit le résultat au multiple de 128 inférieur ou égal le plus proche.

Dans l’API Responses, définissez prompt_cache_options.ttl pour choisir la durée de vie minimale du cache :

Ces tarifs couvrent la totalité de l’écriture. Ils ne s’ajoutent pas au tarif d’entrée standard. Le tarif de lecture en cache est identique pour les deux durées de vie. OpenAI peut conserver les entrées au-delà du minimum demandé. La valeur "12h" ne fixe pas de date limite de suppression et ne modifie pas la politique de conservation maximale des données.

Le paramètre ttl de la requête s’applique au point de coupure implicite et aux points explicites qui n’ont pas leur propre ttl. Définissez prompt_cache_breakpoint.ttl pour choisir une autre durée pour un point explicite donné. Si vous omettez les deux paramètres, la valeur par défaut "30m" s’applique. Une valeur non prise en charge renvoie l’erreur 400 invalid_request_error. Ces paramètres ne modifient pas le paramètre prompt_cache_retention des modèles antérieurs.

Combiner les durées de vie dans une même requête

Placez le contenu réutilisé tout au long de la journée au début du prompt et attribuez une durée de vie de "12h" à son point de coupure. Utilisez "30m" pour le contexte de session qui change plus souvent. Cet exemple fixe la durée par défaut de la requête à 30 minutes et la remplace pour le préfixe partagé. En mode exclusivement explicite, la question en cours se trouve après le dernier point de coupure et n’occasionne donc aucun frais d’écriture en cache.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{
  "model": "gpt-6.1-sol",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Shared instructions and reference material reused throughout the day...",
          "prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Session context reused over the next few minutes...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "The current question, which does not need a cache write..."
        }
      ]
    }
  ]
}

Remplacez le texte d’exemple par votre contenu. Chaque préfixe à mettre en cache doit atteindre la longueur minimale de mise en cache du modèle.

Chevauchement des écritures et modification de la durée de vie

Un point de coupure couvre tout le préfixe qui le précède. Dans une même requête, chaque token est facturé une seule fois, au tarif de la plus longue durée de vie parmi les écritures sélectionnées qui le couvrent. Une écriture de 12 heures placée plus loin étend également à 12 heures la couverture des points de coupure sélectionnés qui la précèdent dans ce préfixe.

Ces exemples supposent que tout préfixe déjà en cache correspond à une limite de recherche admissible dans la nouvelle requête.

Si vous faites passer une couverture de 30 minutes encore valide à 12 heures, une nouvelle écriture de 12 heures est facturée pour ces tokens, sans crédit au titre de l’écriture précédente. Toute partie déjà couverte par une entrée de 12 heures encore valide reste facturée comme une lecture en cache.

Une lecture de 30 minutes prolonge la couverture jusqu’à au moins 30 minutes après la lecture. Si l’entrée lue bénéficie d’une couverture de 12 heures encore valide, la nouvelle échéance est la plus tardive des deux : l’échéance existante ou 30 minutes après la lecture. La lecture ne relance pas la période de 12 heures et n’entraîne pas de nouveaux frais d’écriture.

Utilisez prompt_cache_retention. Les valeurs prises en charge dépendent du modèle :

• in_memory : les entrées restent généralement actives pendant environ 5 à 10 minutes d’inactivité, et jusqu’à une heure.
• 24h : avec la conservation prolongée, les entrées restent généralement disponibles environ 30 minutes et peuvent être conservées jusqu’à 24 heures.

Valeurs de conservation par défaut et politique de non-conservation des données

La mise en cache des prompts peut stocker des tenseurs clé-valeur chiffrés dans le stockage local du GPU, sous forme d’état applicatif. Pour les modèles compatibles à la fois avec in_memory et 24h, la valeur par défaut dépend de la politique de conservation des données de votre organisation :

• Pour les organisations qui n’ont pas activé la politique de non-conservation des données, la valeur par défaut est 24h.
• Pour les organisations qui ont activé la politique de non-conservation des données, la valeur par défaut est in_memory.

Avant de choisir une valeur, vérifiez les politiques de conservation disponibles pour votre modèle et votre organisation.

Sur les modèles antérieurs à GPT-5.6, utilisez une clé prompt_cache_key stable pour les requêtes qui partagent un préfixe réutilisable. Cela aide à acheminer les requêtes associées vers le même cache. Pour les groupes à fort trafic, visez environ 15 requêtes par minute et par clé, tous préfixes confondus. Au-delà, répartissez le trafic entre plusieurs clés selon une règle stable et déterministe. Conservez la même prompt_cache_key pour les requêtes associées afin qu’elles puissent réutiliser le même cache. Les clés influent sur le routage, mais ne lient pas les requêtes à une machine et ne garantissent pas de correspondance en cache.

Sur GPT-5.6 et les modèles ultérieurs, OpenAI gère automatiquement le routage vers le cache. La clé n’est pas nécessaire pour optimiser la mise en cache. Vous pouvez utiliser des clés distinctes pour comptabiliser séparément l’utilisation du cache par client ou par utilisateur dans votre application.

Des clés distinctes permettent d’expliquer plus facilement à chaque client ou utilisateur sa consommation de tokens en cache et sa facturation. Par exemple, elles aident à empêcher un utilisateur de soumettre des prompts tests et d’observer les correspondances en cache pour savoir si un autre utilisateur a déjà mis en cache un contenu donné. Consultez la section Comptabiliser séparément l’utilisation du cache à l’aide de clés.

Dans les applications où les échanges se déroulent sur plusieurs tours, réutiliser l’historique qui s’enrichit à chaque tour peut économiser davantage de tokens d’entrée que la seule mise en cache des instructions initiales. Conservez les messages et les résultats d’outils précédents pour que les tours suivants puissent réutiliser l’intégralité du préfixe partagé.

• Gardez le préfixe stable. Placez les instructions de développeur stables et les documents de référence partagés en premier. S’ils contiennent des horodatages, du contenu propre à un utilisateur ou d’autres éléments variables, placez ces éléments à la fin ou déplacez-les dans des messages ultérieurs de la conversation.
• Préservez l’historique de la conversation. Ajoutez les nouveaux messages à la suite des précédents sans réécrire les tours passés. Un résumé, un compactage ou une troncature du contexte peuvent modifier le préfixe et obliger la mise en cache à repartir de zéro.
• Modifiez l’effort de raisonnement sans réécrire le préfixe. Sur les modèles GPT-6, ajoutez un élément d’entrée configuration_update pour modifier l’effort de raisonnement entre deux réponses, tout en conservant la valeur de reasoning.effort au niveau de la requête. Le préfixe d’origine reste ainsi réutilisable en cache. Consultez la section Modifier le raisonnement en cours de conversation pour voir des exemples et connaître les limites de compatibilité.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "low", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Stable instructions and shared reference material...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "developer",
      "content": "Dynamic developer instructions, such as user-specific content and timestamps..."
    },
    {
      "role": "user",
      "content": "The user's current question..."
    }
  ]
}

Sur les modèles compatibles à partir de GPT-6, ajoutez un élément d’entrée configuration_update pour modifier l’effort de raisonnement en cours de conversation tout en préservant le préfixe déjà en cache. Conservez la valeur d’origine du paramètre reasoning.effort de premier niveau. Le modifier peut entraîner la réécriture d’une partie des instructions système masquées.

La dernière mise à jour de reasoning.effort détermine l’effort de raisonnement pour les réponses suivantes. Ajoutez cet élément à la fin de input pour passer au niveau d’effort high.

1
2
3
4{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

Si votre application a besoin d’outils différents d’une requête à l’autre, modifiez la sélection des outils qu’elle peut appeler, tout en gardant leurs définitions stables pour préserver les préfixes réutilisables.

• Gardez les outils stables. Conservez leurs définitions, leur ordre et leurs schémas.
• Désactivez les outils pour une requête. Définissez tool_choice sur "none" au lieu de supprimer les définitions d’outils.
• Activez uniquement certains outils. Utilisez allowed_tools pour limiter les outils appelables tout en conservant la liste tools fournie.
• Chargez les outils à la demande. Utilisez la recherche d’outils avec defer_loading: true pour réduire le nombre de tokens d’entrée consacrés aux définitions d’outils lors des premières requêtes d’une conversation à plusieurs tours. Les outils découverts sont ajoutés à la fin du contexte, ce qui préserve le contenu réutilisable qui les précède.
• Conservez l’historique de chargement des outils. Utilisez un élément d’entrée additional_tools avec le rôle développeur pour ajouter des outils en cours de conversation selon la logique de votre application.

Sur GPT-5.6 et les modèles ultérieurs, deux paramètres déterminent l’emplacement des points de coupure. prompt_cache_options.mode sélectionne la mise en cache implicite ou exclusivement explicite, et prompt_cache_breakpoint marque une limite de votre choix.

• Placez les points de coupure automatiquement. Utilisez la mise en cache implicite pour placer un point à la fin du dernier message admissible. Ce mode convient aux conversations à plusieurs tours où chaque tour complète le contexte existant.
• Choisissez vous-même les points de coupure. Placez des marqueurs explicites à la fin du contenu stable. Utilisez le mode exclusivement explicite pour éviter les écritures inutiles de suffixes variables.

Pour GPT-5.6 et les modèles ultérieurs, préparez à l’avance le contexte connu afin de réduire le délai d’obtention du premier token lors d’une requête ultérieure. Par exemple, une application interactive peut précharger les instructions partagées, les définitions d’outils ou les documents de référence au démarrage, avant que l’utilisateur pose sa première question.

Dans une requête de l’API Responses, définissez prompt_cache_options.prewarm sur true pour préparer le cache des prompts sans générer de sortie. Une fois cette requête terminée, envoyez votre requête effective avec le même préfixe de prompt, en omettant prewarm ou en lui attribuant la valeur false.

1
2
3
4
5
6
7
8
9
10
11
12{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    },
    {
      "role": "user",
      "content": "The user's question..."
    }
  ]
}

Les tokens écrits en cache lors d’une requête de préchargement sont facturés au tarif d’écriture correspondant à la durée de vie choisie.

Sur GPT-5.6 et les modèles ultérieurs, utilisez prompt_cache_key pour comptabiliser séparément l’utilisation du cache par client, par utilisateur ou par espace de travail au sein de votre application. Vous pourrez ainsi expliquer plus facilement la consommation de tokens en cache et leur facturation pour chaque groupe. La clé est facultative et n’est pas nécessaire pour optimiser la mise en cache sur ces modèles.

• Choisissez comment répartir le décompte. Attribuez une clé distincte à chaque client ou utilisateur dont vous souhaitez comptabiliser séparément l’utilisation du cache. Par exemple, support:customer_123 et support:customer_456 permettent de tenir des décomptes distincts pour deux clients, même lorsque leurs requêtes contiennent le même préfixe.
• Gardez les clés stables au sein de chaque groupe. Réutilisez la même clé pour les requêtes associées d’un client. Ne générez une clé distincte pour une session ou un fil de conversation que si vous devez en comptabiliser séparément l’utilisation du cache.
• Appliquez les clés systématiquement. Utilisez la clé du client pour toutes ses requêtes afin de conserver un décompte séparé. Cela aide également à empêcher un client de sonder le cache pour savoir quels contenus un autre client a déjà utilisés.

Sur les modèles antérieurs à GPT-5.6, prompt_cache_key joue un rôle important dans l’optimisation du taux de succès du cache. Utilisez une clé stable pour les requêtes qui partagent un préfixe réutilisable afin de faciliter leur routage vers le même cache. Pour les groupes à fort trafic, suivez les recommandations de répartition du trafic entre plusieurs clés.

Pour les modèles de l’API Responses compatibles avec prompt_cache_options, utilisez "30m" pour un contexte fréquemment réutilisé et envisagez "12h" pour des préfixes stables réutilisés à des intervalles plus longs. Comparez le tarif d’écriture plus élevé de la durée de 12 heures au coût de réécriture du préfixe après expiration de la couverture de 30 minutes. Définissez la durée de vie de chaque point de coupure pour conserver le contenu partagé plus longtemps que le contexte propre à la session. Consultez la section Durée de vie du cache pour voir des exemples et connaître les règles de facturation.

Pour les modèles antérieurs, réglez de préférence prompt_cache_retention sur "24h" pour bénéficier de la conservation prolongée, si le modèle et vos exigences de conservation des données le permettent. Consultez la section Durée de vie du cache pour connaître les paramètres pris en charge et leurs valeurs par défaut.

Si de nombreuses requêtes réutilisent les mêmes instructions de développeur et définitions d’outils, mais que leur préfixe partagé n’atteint pas la longueur minimale de mise en cache du modèle, envisagez de le raccourcir ou de le compléter avec des instructions, des exemples ou des documents de référence utiles et stables. Vérifiez si les économies réalisées grâce au cache compensent les tokens d’entrée supplémentaires et les éventuels frais d’écriture. Assurez-vous que les résultats des évaluations et le comportement restent stables.

Le graphique illustre le surcoût possible d’un préfixe trop court : le traiter hors cache peut coûter plus cher que l’allonger jusqu’au nombre minimal de tokens requis pour la mise en cache. Le graphique utilise le tarif d’écriture de 30 minutes pour GPT-5.6 et les modèles ultérieurs.

• Mesurez les performances réelles du cache. Suivez usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, les décomptes d’écriture par durée de vie, le nombre de tokens d’entrée, la latence et le coût réel. Pour suivre le taux de succès du cache par token, divisez le nombre total de tokens lus en cache par le nombre total de tokens d’entrée. Agrégez les deux décomptes par utilisateur, par espace de travail, par jour ou selon un autre regroupement pertinent.
• Calculez le coût d’entrée. Utilisez les décomptes de tokens dans response.usage et les tarifs du modèle par million de tokens.
• Utilisez le tableau de bord de mise en cache des prompts. Suivez les taux de succès du cache dans le tableau de bord de mise en cache des prompts.

Pour les modèles de l’API Responses compatibles avec prompt_cache_options, le champ input_tokens_details.cache_write_tokens_details répartit les tokens écrits entre ttl_30m_tokens et ttl_12h_tokens. Ces décomptes ne se chevauchent pas et leur somme est égale à cache_write_tokens. Les deux champs sont renvoyés, même lorsque l’un vaut zéro. Le champ cached_tokens comptabilise les lectures facturées et exclut les tokens facturés en écriture, y compris lors du passage d’une couverture de 30 minutes à une couverture de 12 heures.

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

Dans cet exemple, 1 000 tokens d’entrée sont facturés au tarif standard : 12000 - 4000 - 7000. Pour calculer le coût d’entrée, multipliez le nombre de tokens d’entrée standard par le tarif d’entrée du modèle, cached_tokens par son tarif d’entrée en cache, ttl_30m_tokens par 1,25 fois son tarif d’entrée et ttl_12h_tokens par 2,5 fois son tarif d’entrée. Additionnez ces montants et divisez le résultat par 1 000 000 si les tarifs sont exprimés par million de tokens. N’ajoutez pas cache_write_tokens une fois ses deux composantes prises en compte.

Par exemple, avec un tarif d’entrée de 1 $ par million de tokens et un tarif d’entrée en cache de 0,10 $ par million, le coût d’entrée de cette utilisation est de (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515. Utilisez les tarifs réels de votre modèle, y compris son tarif d’entrée en cache.

La fonction suivante applique le même coefficient à toutes les écritures en cache. Utilisez 1.25 si toutes les écritures ont une durée de vie de 30 minutes ou 2.5 si elles ont toutes une durée de vie de 12 heures. Pour les requêtes qui combinent les deux durées, calculez séparément le coût de chaque catégorie d’écriture comme indiqué ci-dessus.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18function calculateInputCost(
  usage,
  inputPricePerMillion,
  cacheInputMultiplier = 0.1,
  cacheWriteMultiplier = 1.25
) {
  const inputTokens = usage.input_tokens;
  const cachedTokens = usage.input_tokens_details.cached_tokens;
  const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
  const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;

  const weightedInputTokens =
    ordinaryInputTokens +
    cachedTokens * cacheInputMultiplier +
    cacheWriteTokens * cacheWriteMultiplier;
  const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
  return inputCost;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai.types.responses import ResponseUsage


def calculate_input_cost(
    usage: ResponseUsage,
    input_price_per_million: float,
    cache_input_multiplier: float = 0.1,
    cache_write_multiplier: float = 1.25,
) -> float:
    input_tokens = usage.input_tokens
    cached_tokens = usage.input_tokens_details.cached_tokens
    cache_write_tokens = usage.input_tokens_details.cache_write_tokens
    ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

    weighted_input_tokens = (
        ordinary_input_tokens
        + cached_tokens * cache_input_multiplier
        + cache_write_tokens * cache_write_multiplier
    )
    input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
    return input_cost

1
2
3
4
5func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
	ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
	weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
	return weighted * pricePerMillion / 1_000_000
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.models.responses.ResponseUsage;

static double calculateInputCost(
    ResponseUsage usage,
    double pricePerMillion,
    double cacheInputMultiplier,
    double cacheWriteMultiplier) {
  long cached = usage.inputTokensDetails().cachedTokens();
  long written = usage.inputTokensDetails().cacheWriteTokens();
  long ordinary = usage.inputTokens() - cached - written;
  return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
      * pricePerMillion
      / 1_000_000;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def calculate_input_cost(
  usage,
  input_price_per_million,
  cache_input_multiplier = 0.1,
  cache_write_multiplier = 1.25
)
  input_tokens = usage.input_tokens
  details = usage.input_tokens_details
  cached_tokens = details.cached_tokens
  cache_write_tokens = details.cache_write_tokens
  ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

  weighted_input_tokens = ordinary_input_tokens +
                          (cached_tokens * cache_input_multiplier) +
                          (cache_write_tokens * cache_write_multiplier)
  (weighted_input_tokens * input_price_per_million) / 1_000_000
end

• Conservez les préfixes stables existants.
• Si vous utilisez prompt_cache_key, conservez les valeurs existantes pour continuer à comptabiliser séparément l’utilisation du cache par client ou par utilisateur.
• Remplacez prompt_cache_retention par prompt_cache_options.ttl.
• Vérifiez que les préfixes réutilisables atteignent la longueur minimale de mise en cache du modèle.
• Si le point de coupure par défaut englobe du contenu qui change d’une requête à l’autre, ajoutez un point explicite après le préfixe stable.
• Utilisez prompt_cache_options.mode: "explicit" lorsque le contenu qui suit ne justifie pas une écriture en cache.
• Comparez cached_tokens, cache_write_tokens, la latence et le coût total avant et après la migration.

Prenons un LLM qui évalue en un seul tour une conversation terminée entre un utilisateur et un chatbot. Il détermine si l’échange montre que l’utilisateur est satisfait. Chaque requête utilise la même grille d’évaluation et les mêmes exemples few-shot annotés pour évaluer une conversation différente.

• Préservation du préfixe : la grille et les exemples, qui restent fixes, viennent en premier. Leur longueur cumulée est volontairement maintenue juste au-dessus de la longueur minimale de mise en cache du modèle, avec du contenu qui aide à calibrer l’évaluation. La conversation à évaluer vient en dernier.
• Mode de mise en cache et point de coupure : la mise en cache exclusivement explicite est activée, avec un point de coupure après la grille et les exemples fixes. La conversation entre l’utilisateur et le chatbot vient après ce point et n’est pas écrite en cache. Cela évite les frais d’écriture pour du contenu qui a peu de chances d’être réutilisé.

Un déploiement appliquant ces principes a enregistré un taux de succès du cache d’environ 70 % des tokens. Ce chiffre illustre un résultat possible. Le taux maximal atteignable dépend du contexte et de l’utilisation de votre application.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "user",
      "content": "Completed interaction to evaluate..."
    }
  ]
}

Prenons un agent à plusieurs tours qui utilise de longues instructions de développeur partagées et appelle fréquemment des outils. En pratique, les utilisateurs mènent plusieurs sessions en parallèle avec l’agent et forkent souvent leurs fils de conversation.

• Préservation du préfixe : chaque tour ajoute de nouveaux messages, appels d’outils et résultats sans réécrire le contexte précédent. Le préfixe réutilisable s’allonge ainsi au fil des tours.
• Clé de mise en cache des prompts facultative : cet exemple utilise agent_123_v1:user_456 pour comptabiliser séparément l’utilisation du cache par l’utilisateur 456. Il est ainsi plus facile d’expliquer sa consommation de tokens en cache et leur facturation. Cela aide également à empêcher un utilisateur de sonder le cache d’un autre. La clé reste identique pour toutes les sessions de cet utilisateur avec l’agent, y compris lorsqu’il forke un fil. Omettez-la si votre application n’a pas besoin de cette séparation.
• Mode de mise en cache implicite : la mise en cache implicite est activée pour placer un point de coupure à la fin du dernier message admissible provenant d’un utilisateur ou d’un outil.
• Points de coupure explicites : un point de coupure est ajouté après chaque résultat d’outil pour préserver les préfixes réutilisables précédents et mieux exploiter le cache lorsqu’un utilisateur forke un fil.

Un déploiement appliquant ces principes a enregistré un taux de succès du cache supérieur à 90 % des tokens. Ce chiffre illustre un résultat possible. Le taux maximal atteignable dépend du contexte et de l’utilisation de votre application.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_key": "agent_123_v1:user_456",
  "prompt_cache_options": { "mode": "implicit" },
  "tools": [
    {
      "type": "function",
      "name": "function_name",
      "description": "Function description",
      "parameters": { "...": "..." }
    }
  ],
  "input": [
    {
      "role": "developer",
      "content": "Stable developer instructions and reference material..."
    },
    { "role": "user", "content": "Can you do...?" },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "function_name",
      "arguments": "..."
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": [
        {
          "type": "input_text",
          "text": "Tool result...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    { "role": "assistant", "content": "Assistant response..." },
    { "role": "user", "content": "Can you also do...?" }
  ]
}

Ce cas se présente particulièrement souvent lors d’une migration depuis un modèle antérieur vers GPT-5.6 ou un modèle ultérieur, car le fonctionnement de la mise en cache implicite change. Si les requêtes partagent un long préfixe mais ont des suffixes différents, mettre en cache la première requête complète en mode implicite seul ne suffit pas à rendre réutilisable leur préfixe commun, plus court.

Supposons que chaque requête contienne un message de développeur statique suivi d’un message utilisateur dynamique. La requête écrit en cache tout le préfixe jusqu’à la fin du contenu dynamique. Si ce contenu change dans la requête suivante, le préfixe ne correspond plus au préfixe long en cache, et aucun point de coupure distinct ne marque la fin du contenu statique.

1
2
3
4
5
6
7
8
9
10{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "implicit" },
  "input": [
    { "role": "developer", "content": "Static content..." },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

Pour y remédier, placez un point de coupure explicite après le contenu statique dans les deux requêtes. La première écrit le préfixe réutilisable. La suivante peut alors le réutiliser même si le contenu dynamique change. Cet exemple utilise le mode exclusivement explicite pour éviter d’écrire le contenu dynamique en cache.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Static content...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

Supposons que la requête 1 utilise le mode implicite et mette en cache un préfixe jusqu’à la fin d’un message utilisateur. La requête 2 conserve ce préfixe, mais passe à prompt_cache_options.mode: "explicit". Comme indiqué dans la section Recherche d’un préfixe correspondant, la requête 2 examine uniquement les points de coupure explicites de sa propre entrée. Elle ne réutilise donc le préfixe implicite enregistré par la requête 1 que si l’un de ses points explicites correspond à la fin du préfixe mis en cache par la requête 1.

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message] ▼

- Request 2: explicit-only mode. Does not hit cache.
  [Developer message][User message][Follow-up] ▼

Pour réutiliser le préfixe implicite de la requête 1, placez un point de coupure explicite à la fin du bloc de contenu correspondant dans la requête 2, ou gardez le mode implicite activé pour que la recherche examine toujours la fin du message admissible précédent.

Même si les deux requêtes utilisent le mode implicite, conserver les mêmes tokens initiaux ne suffit pas toujours. Supposons que la requête 1 se termine par un message utilisateur contenant Content A, puis que la requête 2 complète ce même message pour obtenir Content A + Content B. La limite qui suivait Content A se trouve désormais à l’intérieur du message. Comme indiqué dans la section Recherche d’un préfixe correspondant, en l’absence de point de coupure explicite à cette limite, la requête 2 ne réutilise pas le préfixe qui y avait été enregistré.

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message: Content A] ▼

- Request 2: implicit mode. Cannot reuse the prefix through Content A.
  [Developer message][User message: Content A + Content B] ▼

Si la structure de la conversation le permet, conservez le message d’origine et ajoutez un nouveau message à sa suite. Sinon, placez le texte réutilisable dans un bloc de contenu distinct et ajoutez un point de coupure explicite après ce bloc dans les deux requêtes.

En mode implicite, les messages de développeur qui suivent le bloc initial de messages de développeur consécutifs ne servent pas automatiquement de limites de recherche dans le cache. Ajoutez un point de coupure explicite à la fin du message de développeur réutilisable et conservez ce point dans les requêtes suivantes pour qu’OpenAI puisse y rechercher un préfixe correspondant en cache.

Un préfixe assez long pour être mis en cache sur un modèle peut être trop court sur un autre. Consultez le comparatif des modèles et mesurez le préfixe réutilisable avec le modèle et les paramètres que vous utilisez réellement. Lorsque vous changez de modèle, vérifiez à nouveau le seuil applicable.

Le compactage remplace le contexte antérieur de la conversation par une représentation plus courte. Le préfixe peut alors changer. La première requête après le compactage peut donc réutiliser une moindre partie du cache précédent, même si, du point de vue logique, il s’agit toujours de la même conversation.

Dans la mesure du possible, gardez les instructions réutilisables et les documents de référence stables, puis laissez les tours suivants compléter le contexte compacté. Comparez le coût total d’entrée avant et après le compactage. Une diminution du nombre de tokens d’entrée peut réduire le coût même si le taux de succès du cache baisse.

Non. La mise en cache des prompts ne change pas la façon dont le modèle génère les tokens de sortie. Le modèle génère une nouvelle réponse à partir du préfixe en cache. Des requêtes identiques ne produisent donc pas nécessairement des réponses identiques.

Non. Il n’est actuellement pas possible de vider le cache manuellement. Les entrées expirent selon la durée de vie du cache du modèle et les paramètres de conservation.

Oui. Les tokens d’entrée en cache comptent toujours dans la limite de tokens par minute. La mise en cache des prompts ne modifie pas le calcul des limites de débit.