Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
La « extended thinking » (réflexion étendue) en mode manuel vous donne un contrôle direct sur la quantité de réflexion de Claude. Vous définissez un budget de tokens de réflexion sur chaque requête avec thinking: {type: "enabled", budget_tokens: N}, et Claude réfléchit dans la limite de ce budget avant de commencer sa réponse finale. Le mode manuel reste utile lorsque votre charge de travail nécessite une latence prévisible ou un contrôle précis des coûts de réflexion. Cette page explique comment définir et ajuster le budget, comment le mode manuel interagit avec la réflexion entrelacée et la mise en cache des prompts, et comment migrer vers la réflexion adaptative.
Pour comprendre le fonctionnement de la réflexion elle-même, y compris les blocs de réflexion et la forme de la réponse, le paramètre display, le streaming, la réflexion avec l'utilisation d'outils et le chiffrement, consultez la vue d'ensemble de la réflexion.
La disponibilité de la réflexion étendue par modèle, y compris les modèles où la réflexion étendue est le seul mode, est répertoriée dans le tableau de configuration par modèle.
Voici un exemple d'utilisation de la réflexion étendue dans l'API Messages :
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# La réponse contient des blocs de réflexion résumés et des blocs de texte
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")Pour activer la réflexion étendue manuelle, ajoutez un objet thinking avec type défini sur enabled et une valeur budget_tokens.
Le paramètre budget_tokens définit une cible pour le nombre de tokens que Claude peut utiliser pour son processus de raisonnement interne. Des budgets plus importants peuvent améliorer la qualité des réponses en permettant une analyse plus approfondie des problèmes complexes.
budget_tokens doit satisfaire ces contraintes :
max_tokens. Les tokens de réflexion comptent dans la limite max_tokens du tour, le budget doit donc laisser de la place pour la réponse finale. La seule exception est la réflexion entrelacée, où budget_tokens peut dépasser max_tokens car le budget couvre tous les blocs de réflexion au sein d'un même tour de l'assistant.budget_tokens doit être inférieur à max_tokens, la réflexion étendue ne peut pas être combinée avec max_tokens: 0 (préchauffage du cache).Le budget est une cible plutôt qu'un plafond strict. L'utilisation réelle des tokens varie selon la tâche, et Claude peut arrêter de raisonner bien avant que le budget ne soit épuisé ; max_tokens reste le plafond absolu de la sortie totale.
Sur Claude Opus 4.5, le seul modèle limité à la réflexion étendue qui prend en charge l'effort, l'effort façonne la réponse globale tandis que budget_tokens définit la profondeur de réflexion ; définissez les deux.
Pour ajuster le budget :
Pour suivre ce qu'un budget vous coûte réellement, surveillez le champ usage.output_tokens_details.thinking_tokens dans la réponse, qui indique combien de tokens de sortie facturés correspondaient à du raisonnement interne. En streaming, cette répartition n'apparaît que sur l'événement message_delta final.
Lorsque vous êtes prêt à abandonner les budgets manuels, consultez Migrer vers la réflexion adaptative.
La réflexion entrelacée permet à Claude de réfléchir entre les appels d'outils au sein d'un même tour de l'assistant, en raisonnant sur chaque résultat d'outil avant de décider quoi faire ensuite. Pour le concept, la structure des tours et son comportement sur les modèles à réflexion adaptative, consultez réflexion entrelacée dans la vue d'ensemble de la réflexion. Cette section explique comment l'activer lorsque vous utilisez la réflexion manuelle type: "enabled".
Sur Claude Opus 4.5, Claude Sonnet 4.5 et les modèles Claude 4 antérieurs (Claude Opus 4.1 (obsolète), Claude Opus 4 et Claude Sonnet 4), ajoutez l'en-tête bêta interleaved-thinking-2025-05-14 à votre requête API.
La génération 4.6 se divise en mode manuel :
type: "enabled" est toujours fonctionnel mais obsolète. Préférez la réflexion adaptative, qui entrelace automatiquement sans en-tête.thinking: {type: "adaptive"} si vous avez besoin de raisonnement entre les appels d'outils sur ce modèle.Claude Haiku 4.5 ne prend pas en charge la réflexion entrelacée. Sur l'API Claude, l'en-tête bêta est accepté mais ignoré.
Deux autres considérations pour la réflexion entrelacée en mode manuel :
budget_tokens peut dépasser max_tokens ici ; les règles de budget expliquent cette exception.Le traitement de l'en-tête bêta diffère selon les plateformes. L'API Claude et Claude Platform sur AWS acceptent interleaved-thinking-2025-05-14 sur n'importe quel modèle et l'ignorent là où il n'est pas pris en charge. L'acceptation n'équivaut pas à l'effet : sur les modèles qui rejettent type: "enabled" (4.7 et ultérieurs) ou qui n'ont pas d'entrelacement en mode manuel (Claude Opus 4.6), l'en-tête n'a aucun effet en mode manuel ; la réflexion adaptative y entrelace automatiquement.
Les plateformes exploitées par des partenaires (Amazon Bedrock et Google Cloud) acceptent également l'en-tête sur n'importe quel modèle sans renvoyer d'erreur, et l'ignorent sur les modèles qui ne prennent pas en charge la réflexion entrelacée.
Les règles générales de structure des tours, y compris la boucle d'utilisation d'outils en un seul tour, la gestion des conflits en milieu de tour et le basculement de la réflexion entre les tours, se trouvent sur Réflexion avec utilisation d'outils.
Le mode manuel ajoute une exigence : le tour final de l'assistant d'une requête avec réflexion activée doit commencer par un bloc de réflexion (la réflexion adaptative supprime cette exigence). Changer la configuration de réflexion entre les tours invalide également la mise en cache des prompts ; consultez la section suivante.
Le mode manuel ajoute une règle en plus du comportement de mise en cache indépendant du mode décrit dans réflexion et mise en cache des prompts : changer budget_tokens entre les requêtes invalide les points de rupture du cache, tout comme le changement de mode de réflexion, car la valeur du budget est rendue dans le prompt. Les points de rupture au niveau des messages échouent toujours après un changement de budget ; le fait que les points de rupture des outils et de l'invite système échouent aussi dépend de l'endroit où le modèle rend la configuration.
En pratique, choisissez un budget et maintenez-le stable pendant toute la durée d'une conversation mise en cache. Exécuter une conversation multi-tours avec mise en cache au niveau des messages sur Claude Sonnet 4.6 et changer le budget à la troisième requête de 4 000 à 8 000 tokens montre directement l'invalidation :
First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }
Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }
Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }La troisième requête recrée le cache (cache_creation_input_tokens=1370, cache_read_input_tokens=0) car le budget a changé entre les requêtes. Pour une version exécutable de la même expérience en mode adaptatif, où le niveau d'effort joue le rôle de cache que budget_tokens joue ici, consultez Mise en cache des prompts sur la page de pilotage.
La plupart des comportements de réflexion sont indépendants du mode et documentés une seule fois sur la page Réflexion. Tout ce qui s'y trouve s'applique aussi en mode manuel :
Si votre modèle ne prend en charge que la réflexion étendue (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 et les modèles Claude 4 antérieurs), aucune action n'est nécessaire pour l'instant : la réflexion adaptative n'y est pas disponible, et type: "adaptive" renvoie une erreur 400. Conservez budget_tokens jusqu'à ce que vous passiez à un modèle qui prend en charge la réflexion adaptative, puis appliquez la correspondance qui suit.
Vous devez migrer depuis type: "enabled" si :
budget_tokens est obsolète.type: "enabled" renvoie une erreur 400.La correspondance est simple : supprimez budget_tokens, définissez thinking: {type: "adaptive"}, et contrôlez la profondeur de raisonnement avec output_config: {effort: ...} au lieu d'un budget de tokens.
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
}
}devient :
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
}
}effort: "high" correspond à la valeur par défaut de l'API ; il n'apparaît ici que pour montrer où se trouve désormais le contrôle de la profondeur, et son omission produit un comportement identique.
Attendez-vous à une différence de comportement, pas seulement à un changement de syntaxe. Avec un budget fixe, Claude réfléchit à chaque requête. Avec la réflexion adaptative, Claude décide s'il doit réfléchir et dans quelle mesure à chaque requête, et aux niveaux d'effort plus faibles, il peut complètement ignorer la réflexion sur les entrées faciles. Vous pouvez également supprimer l'en-tête bêta interleaved-thinking-2025-05-14 après la migration : la réflexion adaptative entrelace automatiquement, et l'API Claude ignore l'en-tête sur ces modèles. La préservation des blocs de réflexion change aussi : Claude Opus 4.5 et les modèles numérotés 4.6 et supérieurs conservent les blocs de réflexion des tours précédents dans le contexte et les facturent comme entrée, alors que Claude Sonnet 4.5, Claude Haiku 4.5 et les modèles antérieurs les supprimaient ; consultez préservation des blocs de réflexion par modèle.
Changer de mode est un changement de configuration de réflexion, donc la première requête après le changement invalide les points de rupture du cache, comme décrit dans Mise en cache des prompts en mode manuel.
Pour des conseils complets, consultez la réflexion adaptative, l'effort et le guide de migration des modèles.
Découvrez comment fonctionne la réflexion : blocs, affichage, streaming et utilisation d'outils.
Laissez Claude décider quand et dans quelle mesure réfléchir à chaque requête.
Préservez les blocs de réflexion et gérez la réflexion à travers les appels d'outils et les tours.
Was this page helpful?