Fenêtres de contexte

À mesure que les conversations s'allongent, vous finirez par approcher des limites de la fenêtre de contexte. Pour les conversations de longue durée et les flux de travail agentiques, la compaction côté serveur constitue la stratégie principale de gestion du contexte.

Fonctionnement de la fenêtre de contexte

La « context window » (fenêtre de contexte) désigne l'ensemble du texte qu'un modèle de langage peut référencer lors de la génération d'une réponse, y compris la réponse elle-même. Ceci est différent du grand corpus de données sur lequel le modèle de langage a été entraîné, et représente plutôt une « mémoire de travail » pour le modèle. Une fenêtre de contexte plus grande permet au modèle de traiter des prompts plus complexes et plus longs, mais davantage de contexte n'est pas automatiquement préférable. À mesure que le nombre de tokens augmente, la précision et le rappel se dégradent, un phénomène connu sous le nom de « context rot » (dégradation du contexte). Cela rend la sélection de ce qui figure dans le contexte tout aussi importante que la quantité d'espace disponible.

Le diagramme suivant illustre le comportement standard de la fenêtre de contexte pour les requêtes API¹ :

¹ Les interfaces de chat telles que claude.ai peuvent également gérer la fenêtre de contexte selon un principe glissant « premier entré, premier sorti ».

• Accumulation progressive des tokens : à mesure que la conversation progresse au fil des tours, chaque message utilisateur et chaque réponse de l'assistant s'accumulent dans la fenêtre de contexte, et les tours précédents sont intégralement conservés.
• Capacité de la fenêtre de contexte : la fenêtre de contexte (jusqu'à 1M de tokens, selon le modèle) contient l'historique de la conversation ainsi que la nouvelle sortie générée par Claude.
• Flux entrée-sortie : chaque tour se compose de :
  • Phase d'entrée : contient tout l'historique de conversation précédent ainsi que le message utilisateur actuel.
  • Phase de sortie : génère une réponse textuelle qui devient une partie de l'entrée du tour suivant.

Tout ce qui figure dans la requête est comptabilisé dans la fenêtre de contexte : le « system prompt » (invite système), chaque message dans messages (y compris les résultats d'outils, les images et les documents), ainsi que vos définitions d'outils. La sortie que Claude génère pour le tour, y compris sa réflexion étendue, est également comptabilisée. Chaque réponse indique ce que la requête a consommé dans son champ usage. Si vous utilisez le « prompt caching » (mise en cache des prompts), le décompte des entrées est réparti entre input_tokens, cache_read_input_tokens et cache_creation_input_tokens, et les trois sont comptabilisés dans la fenêtre. Pour estimer une requête avant de l'envoyer, utilisez l'API de comptage de tokens.

Tailles de fenêtre de contexte par modèle

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 et Claude Mythos Preview disposent d'une fenêtre de contexte de 1M de tokens. Une seule requête adressée à l'un de ces modèles peut générer jusqu'à 128k tokens de sortie (max_tokens). Les autres modèles Claude, y compris Claude Sonnet 4.5, disposent d'une fenêtre de contexte de 200k tokens.

Pour chaque modèle doté d'une fenêtre de contexte de 1M de tokens, 1M est la valeur par défaut : vous n'avez pas besoin d'en-tête bêta, et les requêtes à contexte long sont facturées au tarif standard.

Une seule requête peut inclure jusqu'à 600 images ou pages PDF (100 pour les modèles dotés d'une fenêtre de contexte de 200k tokens). Si vous envoyez de nombreuses images ou des documents volumineux, vous pourriez atteindre les limites de taille de requête avant la limite de tokens.

Consultez le tableau de comparaison des modèles pour obtenir la liste des tailles de fenêtre de contexte par modèle.

La fenêtre de contexte avec la réflexion

Avec la réflexion, tous les tokens d'entrée et de sortie, y compris les tokens de réflexion, sont comptabilisés dans la limite de la fenêtre de contexte, avec quelques nuances dans les situations multi-tours.

Les tokens de réflexion constituent un sous-ensemble de votre paramètre max_tokens, sont facturés comme des tokens de sortie et sont comptabilisés dans les limites de débit. Avec la réflexion adaptative, Claude détermine dynamiquement son allocation de réflexion, de sorte que l'utilisation des tokens de réflexion varie d'une requête à l'autre.

Le maintien ou non des blocs de réflexion des tours précédents de l'assistant dans la fenêtre de contexte dépend du modèle. Sur Claude Opus 4.5 et les modèles Opus ultérieurs, Claude Sonnet 4.6 et les modèles Sonnet ultérieurs, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview, l'API conserve par défaut les blocs de réflexion précédents, et ceux-ci sont comptabilisés dans la fenêtre de contexte comme n'importe quels autres tokens d'entrée. Sur les modèles Opus et Sonnet antérieurs ainsi que sur tous les modèles Haiku, l'API supprime automatiquement les blocs de réflexion précédents de l'historique de conversation lorsque vous les renvoyez, ce qui préserve la capacité en tokens pour le contenu de la conversation. Pour connaître les valeurs par défaut de chaque modèle, consultez la section conservation des blocs de réflexion par modèle. Pour remplacer la valeur par défaut dans un sens ou dans l'autre, utilisez l'effacement des blocs de réflexion.

Le diagramme suivant montre comment les tokens sont gérés lorsque la réflexion est activée sur un modèle qui supprime les blocs de réflexion précédents :

• Suppression des blocs de réflexion : sur les modèles qui suppriment les blocs de réflexion précédents, les blocs de réflexion (représentés en gris foncé) sont générés pendant la phase de sortie de chaque tour, mais ne sont pas reportés comme tokens d'entrée pour les tours suivants. Vous n'avez pas besoin de supprimer vous-même les blocs de réflexion : si vous les renvoyez, l'API Claude les supprime automatiquement.
• Facturation : les tokens de réflexion sont facturés une seule fois comme tokens de sortie, au moment de leur génération. Sur les modèles qui conservent les blocs de réflexion précédents, les blocs conservés font ensuite partie de l'entrée des requêtes ultérieures et sont facturés comme tokens d'entrée, au même titre que le reste de l'historique de conversation.

La fenêtre de contexte avec la réflexion et l'utilisation d'outils

Le diagramme suivant illustre comment les tokens sont gérés lorsque vous combinez la réflexion avec le « tool use » (utilisation d'outils) sur un modèle qui supprime les blocs de réflexion précédents :

1. 1

   Architecture du premier tour

   • Composants d'entrée : configuration des outils et message utilisateur.
   • Composants de sortie : réflexion + réponse textuelle + requête d'utilisation d'outil.
   • Calcul des tokens : tous les composants d'entrée et de sortie sont comptabilisés dans la fenêtre de contexte, et tous les composants de sortie sont facturés comme tokens de sortie.
2. 2

   Traitement du résultat d'outil (tour 2)

   • Composants d'entrée : chaque bloc du premier tour ainsi que le tool_result. Vous devez renvoyer le bloc de réflexion avec les résultats d'outils correspondants. C'est le seul cas où vous devez renvoyer des blocs de réflexion.
   • Composants de sortie : une fois les résultats d'outils renvoyés à Claude, Claude répond uniquement par du texte (aucune réflexion supplémentaire avant le prochain message user, sauf si la réflexion entrelacée est activée).
   • Calcul des tokens : tous les composants d'entrée et de sortie sont comptabilisés dans la fenêtre de contexte, et tous les composants de sortie sont facturés comme tokens de sortie.
3. 3

   Nouveau tour utilisateur (tour 3)

   • Composants d'entrée : toutes les entrées et la sortie du tour précédent sont reportées. Le bloc de réflexion du cycle d'utilisation d'outils terminé n'a plus besoin de rester dans le contexte : sur les modèles qui suppriment les blocs de réflexion précédents, l'API l'abandonne automatiquement lorsque vous le renvoyez, et sur les modèles qui conservent les blocs de réflexion précédents, il reste en place sauf si vous l'effacez à l'aide de l'effacement des blocs de réflexion. C'est également à ce stade que vous ajoutez le tour user suivant.
   • Composants de sortie : comme il y a un nouveau tour user en dehors du cycle d'utilisation d'outils, Claude génère un nouveau bloc de réflexion et poursuit à partir de là.
   • Calcul des tokens : sur les modèles qui suppriment les blocs de réflexion précédents, les tokens de réflexion précédents ne sont plus comptabilisés dans la fenêtre de contexte. Tous les autres blocs précédents restent comptabilisés dans la fenêtre de contexte, tout comme le bloc de réflexion du tour assistant actuel.

• Considérations relatives à l'utilisation d'outils avec la réflexion :
  • Lorsque vous envoyez des résultats d'outils, vous devez inclure l'intégralité du bloc de réflexion non modifié qui accompagne cette requête d'outil, y compris sa signature.
  • L'API utilise des signatures cryptographiques pour vérifier l'authenticité des blocs de réflexion. Si vous modifiez un bloc de réflexion, l'API renvoie une erreur.

Pour réduire le contexte consommé par les définitions d'outils elles-mêmes, consultez Gérer le contexte des outils, ou différez les définitions d'outils à l'aide de l'outil de recherche d'outils.

Conscience du contexte

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 et Claude Haiku 4.5 disposent de la « context awareness » (conscience du contexte) : ces modèles suivent leur fenêtre de contexte restante (leur « budget de tokens ») tout au long d'une conversation. Cela permet au modèle de gérer les tâches de longue durée en fonction de l'espace restant plutôt que de deviner combien de tokens il reste. La conscience du contexte est automatique : vous n'avez rien à activer, et vous n'envoyez jamais vous-même les balises présentées dans cette section. C'est l'API qui les injecte.

Fonctionnement

Dans l'invite système de chaque requête, l'API indique à Claude sa fenêtre de contexte totale :

<budget:token_budget>200000</budget:token_budget>

Le budget correspond à la fenêtre de contexte disponible pour votre requête : 1M de tokens pour Claude Sonnet 5 et Claude Sonnet 4.6, et 200k tokens pour Claude Sonnet 4.5 et Claude Haiku 4.5. Les exemples de cette section montrent un modèle doté d'une fenêtre de contexte de 200k tokens.

Après chaque appel d'outil, l'API fournit à Claude une mise à jour de sa capacité restante :

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

Les tokens d'image sont inclus dans ces budgets.

Claude Opus 4.7 et les modèles Opus ultérieurs, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 et Claude Mythos 5 ne reçoivent pas ces balises injectées. Sur ces modèles, vous pouvez attribuer au modèle un budget explicite à l'aide des budgets de tâche, qui sont en version bêta.

Pour obtenir des conseils de prompting sur l'utilisation de la conscience du contexte, consultez les bonnes pratiques de prompting.

Gérer le contexte avec la compaction

Si vos conversations approchent régulièrement des limites de la fenêtre de contexte, utilisez la compaction côté serveur. La compaction résume automatiquement les parties antérieures de la conversation sur le serveur, afin que la conversation puisse se poursuivre au-delà de la limite de la fenêtre de contexte. Elle est disponible en version bêta pour les modèles Claude 4.6 et ultérieurs ainsi que pour Claude Mythos Preview.

Pour des besoins plus spécialisés, l'édition de contexte propose des stratégies supplémentaires :

• Effacement des résultats d'outils : effacez les anciens résultats d'outils dans les flux de travail agentiques.
• Effacement des blocs de réflexion : gérez les blocs de réflexion lorsque vous utilisez la réflexion étendue.

Les préfixes de prompt mis en cache occupent toujours la fenêtre de contexte : la mise en cache des prompts modifie ce que vous payez pour ces tokens, et non le fait qu'ils soient comptabilisés.

Comportement en cas de dépassement de la fenêtre de contexte

Si l'entrée seule dépasse déjà la fenêtre de contexte du modèle, l'API renvoie une erreur 400 invalid_request_error (« prompt is too long ») sur tous les modèles.

Sur les modèles Claude 4.5 et plus récents, si la somme des tokens d'entrée et de max_tokens dépasse la taille de la fenêtre de contexte, l'API accepte la requête. Si la génération atteint ensuite la limite de la fenêtre de contexte, elle s'arrête avec stop_reason: "model_context_window_exceeded". Sur les modèles antérieurs, l'API renvoie à la place une erreur de validation. Pour activer le comportement model_context_window_exceeded sur ces modèles, utilisez l'en-tête bêta model-context-window-exceeded-2025-08-26. Consultez Raisons d'arrêt et solutions de repli pour plus de détails.

Pour rester dans les limites de la fenêtre de contexte, utilisez l'API de comptage de tokens afin d'estimer l'utilisation des tokens avant d'envoyer des messages à Claude.

Étapes suivantes