BroadRouter

Structurer ses prompts pour que le préfixe soit mis en cache

Par l’équipe BroadNet Inference · 4 min de lecture · Publié · Mis à jour

Ordonnez chaque requête du plus stable au moins stable : prompt système, définitions d’outils, documents de référence, historique de conversation, puis le nouveau message. Rendez chaque couche identique à l’octet près d’un appel à l’autre : pas d’horodatage ni d’ID en tête, outils triés, JSON sérialisé de façon déterministe et historique uniquement complété. Mesurez ensuite cached_tokens pour confirmer que le préfixe est bien réutilisé.

Les tokens d’entrée en cache coûtent peu : chez BroadNet Inference, DeepSeek V4.1 Flash les facture $0.0055 par million au lieu de $0.175. L’explication des tokens en cache couvre le prix et la lecture du champ usage. Cet article porte sur la conception : comment organiser un prompt pour que le cache fasse vraiment mouche, et comment le prouver.

Pourquoi l’ordre du prompt détermine-t-il le taux de succès du cache ?

Tous les grands fournisseurs mettent en cache par préfixe. Le guide d’OpenAI indique que la réutilisation exige que tout le préfixe rendu corresponde. La documentation de DeepSeek décrit la même règle : une requête n’obtient un succès que si elle correspond entièrement à un préfixe stocké, et une requête qui diverge en cours de route n’en obtient pas. Anthropic construit son cache dans l’ordre outils, système, messages.

En coulisses, le serveur réutilise le cache KV qu’il a construit pour ce préfixe. Le cache est donc une ligne droite à partir du premier token. Le premier octet qui diffère de l’appel précédent met fin à la partie réutilisable. Un horodatage d’une ligne en tête d’un prompt de 50 000 tokens vous fait payer les 50 000 tokens au plein tarif.

Quel est le bon ordre des couches ?

Couche Change Exemple Règle
1. Prompt système À chaque déploiement Rôle, règles, format de sortie Pas de dates, d’ID ni de noms d’utilisateur
2. Définitions d’outils À chaque déploiement Schémas de fonctions JSON trié et déterministe
3. Documents de référence Par session ou par tâche Fichiers du dépôt, contrats, documentation produit Ordre fixe, libellés stables
4. Historique de conversation À chaque tour, en ajout seul Tours précédents de l’utilisateur et de l’assistant Ne jamais modifier ; seulement ajouter
5. Nouveau message À chaque appel La question, plus l’heure actuelle si besoin Les données variables vont ici

La couche 5 accueille tout ce qui varie : la date du jour, la locale de l’utilisateur, un ID de requête, les extraits récupérés qui changent selon la question.

Qu’est-ce qui casse le préfixe sans que vous le remarquiez ?

  1. L’ordre des dictionnaires. Les frameworks construisent souvent le tableau tools à partir d’un dict ou d’un registre. Si les plugins se chargent dans un autre ordre, les octets changent.
  2. Le formatage JSON. json.dumps(x) et json.dumps(x, indent=2) sont des préfixes différents. Tout comme deux sérialiseurs avec des ordres de clés différents.
  3. Les espaces du template. Une espace en fin de ligne, ou un \r\n venant d’un chemin de code et un \n d’un autre.
  4. Les listes d’outils dynamiques. Retirer les outils qu’un utilisateur ne peut pas utiliser change le préfixe. Le guide d’OpenAI recommande de garder les définitions stables et de restreindre l’usage avec tool_choice ou un réglage d’outils autorisés.
  5. Résumer l’historique sur place. Réécrire d’anciens tours en résumé réinitialise tout ce qui suit le prompt système. Résumez rarement et par grandes étapes.
  6. La récupération avant les instructions. Des extraits RAG placés entre le prompt système et les outils changent à chaque requête et cassent aussi la couche des outils.

Comment construire une requête favorable au cache dans le code ?

Faites dépendre chaque couche uniquement d’entrées stables, et sérialisez de façon déterministe :

import json, os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

SYSTEM = open("prompts/system.md").read()  # versioned file, no templating

def stable_tools(registry: dict) -> list:
    # Sort by name, sort keys inside each schema.
    return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]

def docs_block(paths: list[str]) -> str:
    parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
    return "\n\n".join(parts)

def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
    return (
        [{"role": "system", "content": SYSTEM},
         {"role": "user", "content": docs_block(doc_paths)}]
        + history                                   # append-only
        + [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
    )

resp = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",
    messages=build_messages(history, question, now_iso, files),
    tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]

Deux détails. L’heure actuelle va dans le dernier message, pas dans le prompt système. Et l’historique stocke le message de l’assistant exactement tel qu’il a été renvoyé, pour que l’appel suivant renvoie des octets identiques.

Comment prouver que le préfixe est en cache ?

Lancez un test à deux appels dans la CI ou dans un notebook :

  1. Construisez une requête avec votre vrai prompt système, vos outils et vos documents.
  2. Envoyez-la. Notez usage.prompt_tokens.
  3. Modifiez uniquement le dernier message utilisateur et renvoyez.
  4. Lisez usage.prompt_tokens_details.cached_tokens au second appel. La valeur devrait couvrir presque tout le préfixe commun.
  5. Si elle est nulle ou faible, comparez octet par octet les corps de requête sérialisés. La première différence est ce qui casse votre cache.

Chez la plupart des fournisseurs, le cache fonctionne au mieux (best effort), et la documentation de DeepSeek le dit explicitement : un échec isolé ne prouve donc pas un bug. Un échec systématique, si. Suivez le ratio tokens en cache / tokens de prompt par requête dans vos journaux d’usage, et utilisez le calculateur de prompt caching pour voir ce qu’un meilleur taux de succès fait économiser.

Qu’est-ce qui change pour les agents et le contexte long ?

Les agents en profitent le plus, car ils renvoient le même gros préfixe des dizaines de fois par tâche. Deux habitudes comptent :

  • Une conversation par tâche. Démarrer une nouvelle conversation pour chaque sous-étape jette le préfixe.
  • Lire les fichiers une fois, près du début. Si l’agent relit un fichier, ajoutez la nouvelle copie au lieu de remplacer l’ancienne, sauf si le fichier a changé.

Avec une fenêtre de contexte de 1 M de tokens, la couche 3 peut contenir un dépôt entier. Avec une clé facturée au token, ce n’est abordable que si cela passe par le cache : c’est pourquoi l’ordre des couches compte davantage à mesure que les prompts grossissent. Les préfixes en cache réduisent aussi souvent le délai avant le premier token ; voir TTFT ou débit.

La place de BroadNet Inference

Chez BroadNet Inference, le bloc usage indique prompt_tokens_details.cached_tokens quand le modèle le renvoie, et l’entrée en cache sur DeepSeek V4.1 Flash, GLM 5.3 et Qwen3.8 27B est facturée au tarif réduit indiqué sur la page de prix. Sa documentation ne propose ni points de rupture de cache explicites ni paramètre de clé de cache : l’organisation ci-dessus constitue donc toute la technique. Avec un forfait illimité, le cache ne change pas la facture, car les sessions n’ont pas de compteur de tokens, mais la même structure aide toujours la latence.

Questions fréquentes

Pourquoi le taux de succès de mon cache de prompt est-il faible ?

Quelque chose au début du prompt change à chaque appel. Les causes habituelles sont un horodatage ou un ID de requête dans le prompt système, des outils sérialisés dans un ordre différent, des documents récupérés placés avant les instructions, ou un historique résumé et réécrit.

La question de l’utilisateur doit-elle venir avant ou après les longs documents ?

Après. Placez les documents en premier et la question en dernier. Les documents forment alors un préfixe réutilisable, et beaucoup de modèles répondent aussi mieux quand la question suit le contenu.

Les définitions d’outils cassent-elles le prompt caching ?

Seulement si elles changent. Les outils font partie du préfixe : gardez le même ensemble, dans le même ordre, avec le même JSON. Pour limiter les outils sur un appel, utilisez tool_choice plutôt que de modifier la liste.

L’ordre des exemples few-shot compte-t-il pour le cache ?

Oui. Des exemples mélangés produisent un préfixe différent à chaque fois. Fixez l’ordre, ou placez les exemples qui changent selon la requête après la partie stable.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity