La mise en cache du contexte de DeepSeek réutilise sur disque certaines parties déjà traitées d’un préfixe d’entrée. Lorsqu’une requête ultérieure réemploie intégralement une unité de préfixe persistée, les tokens correspondants peuvent être comptés comme un cache hit. Ce mécanisme est activé par défaut par DeepSeek : il ne demande ni endpoint séparé ni modification obligatoire du code.
Ce guide se concentre sur le fonctionnement du Context Caching on Disk, la conception de préfixes réutilisables, la lecture des compteurs de tokens et la séparation entre cache, mémoire conversationnelle et conservation des données. Pour une présentation générale des modèles et paramètres, consultez notre documentation de l’API DeepSeek.
Transparence : deepseek-fr.ai est un guide indépendant, non affilié à DeepSeek. Il n’héberge pas l’API et ne reçoit pas les prompts envoyés directement à DeepSeek.
Dernière vérification factuelle : 20 juillet 2026, à partir de la documentation API, de la tarification et des politiques officielles de DeepSeek.
Le cache de contexte DeepSeek en bref
- Le cache disque est activé par défaut pour tous les utilisateurs de l’API.
- Chaque requête participe à la construction du cache.
- Un hit exige la réutilisation complète d’une unité de préfixe déjà persistée.
- DeepSeek persiste des unités aux limites des requêtes, lors de la détection d’un préfixe commun et à intervalles fixes pour les entrées ou sorties longues.
- Les champs
prompt_cache_hit_tokensetprompt_cache_miss_tokenspermettent de mesurer le résultat réel. - Le système fonctionne en best effort : un taux de hit de 100 % n’est pas garanti.
- Le cache d’entrée ne réutilise pas une ancienne réponse : la sortie est générée à nouveau.
- Le cache n’est ni une mémoire de conversation ni une politique de conservation des données.
Comment fonctionne le KV cache sur disque ?
Une requête Chat Completions contient un préfixe formé notamment par les messages transmis au modèle. DeepSeek peut enregistrer sur disque des états intermédiaires associés à certaines portions de ce préfixe. Si une requête suivante commence par une unité déjà persistée et la reproduit entièrement, cette partie peut être récupérée depuis le cache.
La documentation actuelle insiste sur la notion d’unité de préfixe complète. Un simple chevauchement partiel ne suffit pas nécessairement. Une modification placée tôt dans le prompt — date dynamique, identifiant de requête, espace, ordre différent ou instruction réécrite — peut donc réduire la portion réutilisable.
Les trois mécanismes de persistance
- Limites de requête : chaque requête produit une unité à la fin de l’entrée utilisateur et une autre à la fin de la sortie du modèle. Une requête suivante peut les réutiliser si elle les reproduit intégralement.
- Détection d’un préfixe commun : lorsque plusieurs requêtes partagent un début identique, DeepSeek peut persister cette partie commune comme une unité indépendante.
- Intervalles fixes : pour les entrées ou sorties longues, le système découpe aussi des unités à intervalles de tokens fixes. La documentation ne publie pas la taille de ces intervalles.
Ces règles remplacent l’idée trop simpliste selon laquelle « tout texte déjà envoyé est automatiquement mis en cache ». Ce qui compte est l’existence d’une unité persistée et sa correspondance complète avec le début de la nouvelle requête.
Deux exemples de correspondance de préfixe
Conversation multitour : A + B, puis A + B + C
Supposons que la première requête contienne un message système et une question, représentés par A + B. L’application conserve ensuite exactement ces messages, ajoute la réponse du modèle et une nouvelle question. La seconde requête devient A + B + C.
Comme le début A + B correspond entièrement à une unité créée à la limite de la première requête, cette partie peut produire un hit. Cela suppose que l’application renvoie bien les mêmes messages dans le même ordre.
Document commun, questions différentes : A + B, A + C, puis A + D
Une première requête contient un long document commun A suivi de la question B. La suivante réutilise le document mais pose la question C. Elle ne correspond pas entièrement à l’unité A + B et peut donc manquer le cache.
Après avoir observé les deux requêtes, le système peut détecter et persister leur préfixe commun A. Une troisième requête A + D peut alors réutiliser cette unité. Les entrées longues peuvent aussi bénéficier des unités créées à intervalles fixes, mais il faut toujours vérifier le résultat dans les compteurs d’usage au lieu de le supposer.
Cache, mémoire conversationnelle et conservation : trois notions distinctes
L’endpoint ne réinjecte pas automatiquement les tours précédents dans le contexte du modèle : l’application doit renvoyer les messages utiles à chaque requête. Cela ne décrit ni la journalisation, ni le cache disque, ni la durée de conservation des données par DeepSeek.
| Notion | Rôle | Ce qu’elle ne prouve pas |
|---|---|---|
| Mémoire conversationnelle | L’application stocke les tours utiles et les renvoie dans messages. | Elle ne prouve pas qu’un préfixe donnera un cache hit. |
| KV cache sur disque | DeepSeek peut réutiliser une unité de préfixe persistée pour comptabiliser une partie de l’entrée comme hit. | Il ne mémorise pas à la place de l’application les messages à transmettre au modèle. |
| Journalisation et conservation | Elles relèvent des politiques de données, des conditions du service et des obligations du développeur. | La disparition d’un KV cache ne prouve pas la suppression des logs, entrées ou autres données personnelles. |
Pour construire une véritable conversation multitour, utilisez le tableau messages décrit dans notre guide Chat Completions DeepSeek. Le cache peut rendre une partie de cette entrée moins coûteuse, mais il ne remplace pas la gestion d’état de votre application.
Mesurer les cache hits dans la réponse
DeepSeek expose deux champs dans l’objet usage :
prompt_cache_hit_tokens: nombre de tokens d’entrée ayant trouvé une correspondance dans le cache ;prompt_cache_miss_tokens: nombre de tokens d’entrée n’ayant pas trouvé de correspondance.
La référence API précise que prompt_tokens est égal à la somme des tokens hit et miss. Enregistrez les trois valeurs pour chaque requête, avec le modèle, la version du préfixe et le cas d’usage. Un taux moyen global masque souvent les différences entre conversations courtes, longs documents et prompts fréquemment modifiés.
{
"usage": {
"prompt_tokens": 12000,
"prompt_cache_hit_tokens": 9000,
"prompt_cache_miss_tokens": 3000,
"completion_tokens": 450,
"total_tokens": 12450
}
}Les nombres ci-dessus sont uniquement un exemple de lecture, pas une promesse de taux de hit. Calculez notamment :
taux_de_hit = prompt_cache_hit_tokens / prompt_tokensSi prompt_tokens vaut zéro, ne calculez pas le ratio. Pour une réponse en streaming, demandez les statistiques avec stream_options={"include_usage": True} et lisez le bloc d’usage envoyé avant la fin du flux.
Exemple Python : préfixe stable et suivi des tokens
L’exemple suivant place les instructions et le document commun avant la question variable. Les premières requêtes peuvent manquer le cache avant que le préfixe commun soit persisté. Le script mesure donc chaque réponse au lieu d’annoncer un hit à l’avance.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
)
MODEL = "deepseek-v4-pro"
USER_ID = "tenant_7f1a"
SYSTEM_PROMPT = (
"Tu analyses uniquement le document fourni. "
"Si la réponse n'y figure pas, indique-le clairement. "
"Réponds en français et cite le passage utilisé."
)
DOCUMENT = """
Rapport de référence version 2026-07.
Remplacez ce texte par le document réellement analysé.
Conservez exactement cette partie si vous souhaitez tester
la réutilisation du même préfixe.
""".strip()
def poser_question(question: str) -> None:
messages = [
{
"role": "system",
"content": SYSTEM_PROMPT,
},
{
"role": "user",
"content": (
f"DOCUMENT DE RÉFÉRENCE\n{DOCUMENT}"
f"\n\nQUESTION\n{question}"
),
},
]
response = client.chat.completions.create(
model=MODEL,
messages=messages,
max_tokens=600,
extra_body={
"user_id": USER_ID,
},
)
usage = response.usage.model_dump()
hit = usage.get("prompt_cache_hit_tokens", 0)
miss = usage.get("prompt_cache_miss_tokens", 0)
prompt = usage.get("prompt_tokens", hit + miss)
print(response.choices[0].message.content)
print(
{
"prompt_tokens": prompt,
"cache_hit_tokens": hit,
"cache_miss_tokens": miss,
"hit_rate": round(hit / prompt, 4) if prompt else None,
}
)
poser_question("Quels sont les objectifs du rapport ?")
poser_question("Quelles limites le rapport mentionne-t-il ?")
poser_question("Quelles actions sont prioritaires ?")Les trois appels réutilisent le même message système et le même document. Seule la fin de l’entrée change. Ne transformez cependant pas ce résultat en test artificiel : mesurez aussi les prompts, documents, longueurs et fréquences réels de votre application.
Concevoir un préfixe réutilisable
Placer le contenu stable en premier
Un ordre utile pour une application documentaire est :
- instructions système stables ;
- règles métier ou format de réponse stable ;
- document ou contexte partagé ;
- question, identifiant de tâche ou donnée variable.
Évitez d’insérer avant le contenu réutilisable une date générée à chaque appel, un UUID, une signature variable ou une phrase reformulée aléatoirement. Ces éléments modifient le début de la séquence et peuvent empêcher la correspondance des unités suivantes.
Stabiliser la sérialisation
- Conservez le même ordre de messages et les mêmes rôles.
- Normalisez les sauts de ligne et espaces produits par votre application.
- Évitez de réordonner sans nécessité les sections d’un document.
- Versionnez les instructions ; changez-les volontairement, pas à chaque déploiement par accident.
- Pour une conversation multitour, ajoutez les nouveaux messages à la fin au lieu de reconstruire différemment les anciens tours.
La recherche d’un meilleur taux de hit ne doit pas figer une instruction incorrecte. La qualité et la sécurité du prompt restent prioritaires. Lors d’un changement nécessaire, créez une nouvelle version, mesurez-la séparément et acceptez que son cache doive se reconstruire.
Calculer le coût sans figer un tarif obsolète
DeepSeek facture actuellement les tokens d’entrée en distinguant cache hit et cache miss, puis facture séparément les tokens de sortie. Les prix dépendent du modèle et peuvent changer. Pour cette raison, cette page ne duplique pas un tableau tarifaire statique.
Consultez toujours notre page des prix actuels de l’API DeepSeek et la tarification officielle DeepSeek avant une estimation budgétaire.
coût_entrée =
(cache_hit_tokens × tarif_hit_par_million
+ cache_miss_tokens × tarif_miss_par_million)
/ 1_000_000
coût_sortie =
completion_tokens × tarif_sortie_par_million
/ 1_000_000
coût_total = coût_entrée + coût_sortieUn bon taux de hit ne suffit pas à garantir un faible coût total. Une sortie très longue, un modèle plus cher, des prompts inutilement volumineux ou un grand nombre d’appels peuvent dominer la facture. Suivez donc les tokens hit, miss et de sortie ainsi que le nombre de requêtes.
Isoler le KV cache avec user_id
DeepSeek permet d’envoyer un paramètre user_id pour isoler le KV cache entre les utilisateurs de votre application sous un même compte. Ce paramètre sert aussi à l’isolation de planification et au traitement de sûreté du contenu.
- Utilisez une valeur opaque et stable pour le périmètre à isoler.
- N’envoyez ni nom, ni adresse e-mail, ni téléphone, ni autre donnée personnelle dans
user_id. - La valeur doit respecter
[a-zA-Z0-9\-_]+. - La longueur maximale documentée est de 512 caractères.
- Avec le SDK OpenAI, placez-la dans
extra_body.
response = client.chat.completions.create(
model="deepseek-v4-pro",
messages=messages,
extra_body={
"user_id": "tenant_7f1a",
},
)Ne réutilisez pas le même identifiant pour des locataires qui doivent être isolés. À l’inverse, changer d’identifiant à chaque requête empêche de conserver un périmètre de cache cohérent pour le même utilisateur. Consultez aussi notre guide des limites de requêtes et de l’isolation user_id.
Confidentialité : ce que le cache ne garantit pas
DeepSeek indique que le cache fonctionne en best effort, que sa construction peut prendre quelques secondes et qu’un cache inutilisé est généralement supprimé automatiquement après quelques heures à quelques jours. Cette indication décrit le cycle technique du KV cache, pas la durée globale de conservation des données personnelles.
La politique de confidentialité officielle indique notamment que DeepSeek peut collecter les entrées, fichiers, historique, informations de compte et données techniques afin de fournir, sécuriser, développer et améliorer ses services. Elle précise aussi que les données personnelles sont directement collectées, traitées et stockées en République populaire de Chine, et que le service n’est pas conçu pour recevoir des données personnelles sensibles.
Pour une application destinée à des utilisateurs finaux, les conditions de l’Open Platform indiquent que le développeur doit publier ses propres règles de traitement, disposer d’une base légale et répondre aux demandes concernant les droits des personnes. La politique générale de DeepSeek ne couvre pas à elle seule le traitement effectué dans votre application en aval.
- Minimisez le contenu transmis et retirez les données inutiles.
- N’envoyez pas de données sensibles uniquement parce que le cache est temporaire.
- Utilisez un
user_idopaque et sans information personnelle. - Définissez votre propre durée de conservation des messages et journaux applicatifs.
- Documentez les transferts, sous-traitants, finalités et droits applicables avant une mise en production en France ou dans l’EEE.
Notre analyse DeepSeek est-il sûr ? détaille les risques d’accès cloud, les données traitées et les vérifications à effectuer avant un usage professionnel.
Résoudre les problèmes de cache fréquents
| Symptôme | Cause possible | Action |
|---|---|---|
prompt_cache_hit_tokens reste à zéro | Préfixe nouveau, unité pas encore persistée, contenu variable placé au début ou user_id différent. | Comparer exactement les premières sections, exécuter plusieurs requêtes représentatives et vérifier l’identifiant d’isolation. |
| Le second appel manque mais le troisième réussit | Le système a dû détecter puis persister un préfixe commun entre les deux premiers appels. | Comportement compatible avec la règle de détection des préfixes communs ; continuer à mesurer. |
| Le taux de hit varie sans changement apparent | Cache en best effort, délai de construction, nettoyage d’un cache inutilisé ou différence de sérialisation. | Journaliser une empreinte locale du préfixe, les compteurs d’usage et l’heure des appels. |
| La réponse change malgré un cache hit | Le cache ne réutilise que le préfixe d’entrée ; la sortie est générée de nouveau. | Ne pas utiliser le hit comme preuve d’une réponse identique ou correcte. |
| Les compteurs manquent en streaming | L’option d’inclusion des statistiques n’a pas été demandée ou le bloc final n’est pas lu. | Activer stream_options.include_usage et traiter le bloc d’usage avant [DONE]. |
| Le coût reste élevé | Nombreux tokens miss, sorties longues, beaucoup d’appels ou modèle plus coûteux. | Calculer séparément hits, misses, sorties et volume de requêtes avec les tarifs actuels. |
Checklist de mise en production
- Placer les instructions et documents stables avant les valeurs variables.
- Versionner et tester chaque préfixe important.
- Mesurer
prompt_cache_hit_tokens,prompt_cache_miss_tokens, les tokens de sortie et le nombre d’appels. - Tester les premiers appels, les appels répétés et la reprise après plusieurs heures.
- Ne pas considérer le best effort comme une garantie de capacité ou de coût.
- Utiliser un
user_idopaque pour isoler les utilisateurs ou locataires. - Ne placer aucune donnée personnelle dans cet identifiant.
- Ne pas confondre nettoyage du cache et suppression des données au sens juridique.
- Consulter la tarification et les politiques officielles à chaque révision.
- Prévoir un fonctionnement correct même lorsqu’aucun cache hit ne se produit.
Questions fréquentes
Faut-il activer manuellement le cache DeepSeek ?
Non. La documentation indique que le Context Caching on Disk est activé par défaut pour tous les utilisateurs. Il faut surtout concevoir des préfixes réutilisables et lire les champs d’usage.
La première requête donne-t-elle un cache hit ?
Un préfixe qui n’a jamais été persisté ne doit pas être supposé disponible. La première requête participe à la construction du cache. Selon la structure des appels, un préfixe commun peut n’être exploitable qu’après plusieurs requêtes.
Un cache hit signifie-t-il que DeepSeek renvoie l’ancienne réponse ?
Non. Le cache concerne le préfixe d’entrée. DeepSeek précise que la sortie est toujours produite par calcul et inférence ; elle peut donc différer.
Combien de temps le KV cache est-il conservé ?
DeepSeek indique qu’un cache qui n’est plus utilisé est généralement supprimé après quelques heures à quelques jours. Il ne s’agit pas d’un engagement sur la conservation ou la suppression de toutes les autres données.
Le cache remplace-t-il l’historique de conversation ?
Non. L’application doit conserver et renvoyer les messages nécessaires à chaque appel. Le cache peut seulement réutiliser techniquement une partie identique de l’entrée transmise.
Peut-on mettre une adresse e-mail dans user_id ?
Non. DeepSeek demande explicitement de ne pas inclure d’information privée dans user_id. Utilisez un identifiant interne opaque respectant les caractères et la longueur autorisés.
Comment connaître l’économie réelle ?
Multipliez séparément les tokens hit, les tokens miss et les tokens de sortie par les tarifs actuels du modèle, puis comparez plusieurs périodes représentatives. N’utilisez pas un prix copié dans un ancien article.
