La réflexion approfondie donne à Claude 3.7 Sonnet des capacités de raisonnement améliorées pour les tâches complexes, tout en offrant une transparence sur son processus de réflexion étape par étape avant de fournir sa réponse finale.

​
Comment fonctionne la réflexion approfondie

Lorsque la réflexion approfondie est activée, Claude crée des blocs de contenu thinking où il expose son raisonnement interne. Claude intègre les insights de ce raisonnement avant d’élaborer une réponse finale.

La réponse de l’API inclura à la fois des blocs de contenu thinking et text.

Dans les conversations à plusieurs tours, seuls les blocs de réflexion associés à une session d’utilisation d’outil ou au tour assistant en dernière position sont visibles par Claude et sont facturés comme des tokens d’entrée ; les blocs de réflexion associés aux messages assistant précédents ne sont pas visibles pour Claude pendant l’échantillonnage et ne sont pas facturés comme des tokens d’entrée.

​
Mise en œuvre de la réflexion approfondie

Ajoutez le paramètre thinking et un budget de tokens spécifié à utiliser pour la réflexion approfondie à votre requête API.

Le paramètre budget_tokens détermine le nombre maximum de tokens que Claude est autorisé à 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, bien que Claude puisse ne pas utiliser la totalité du budget alloué, en particulier pour des plages supérieures à 32K.

Votre budget_tokens doit toujours être inférieur au max_tokens spécifié.

La réponse de l’API inclura à la fois des blocs de contenu thinking et text :

{
    "content": [
        {
            "type": "thinking",
            "thinking": "To approach this, let's think about what we know about prime numbers...",
            "signature": "zbbJhbGciOiJFU8zI1NiIsImtakcjsu38219c0.eyJoYXNoIjoiYWJjMTIzIiwiaWFxxxjoxNjE0NTM0NTY3fQ...."
        },
        {
            "type": "text",
            "text": "Yes, there are infinitely many prime numbers such that..."
        }
    ]
}

​
Comprendre les blocs de réflexion

Les blocs de réflexion représentent le processus de pensée interne de Claude. Afin de permettre à Claude de résoudre des problèmes avec des restrictions internes minimales tout en maintenant nos normes de sécurité et nos API sans état, nous avons mis en œuvre les éléments suivants :

  • Les blocs de réflexion contiennent un champ signature. Ce champ contient un jeton cryptographique qui vérifie que le bloc de réflexion a été généré par Claude, et est vérifié lorsque les blocs de réflexion sont renvoyés à l’API. Lors de la diffusion en continu des réponses, la signature est ajoutée via un signature_delta à l’intérieur d’un événement content_block_delta juste avant l’événement content_block_stop. Il n’est strictement nécessaire de renvoyer les blocs de réflexion que lors de l’utilisation d’outils avec réflexion approfondie. Sinon, vous pouvez omettre les blocs de réflexion des tours précédents, ou laisser l’API les supprimer pour vous si vous les renvoyez.
  • Occasionnellement, le raisonnement interne de Claude sera signalé par nos systèmes de sécurité. Lorsque cela se produit, nous chiffrons tout ou partie du bloc thinking et le renvoyons sous forme de bloc redacted_thinking. Ces blocs de réflexion expurgés sont déchiffrés lorsqu’ils sont renvoyés à l’API, permettant à Claude de poursuivre sa réponse sans perdre le contexte.

Voici un exemple montrant à la fois des blocs de réflexion normaux et expurgés :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpP..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Voir des blocs de réflexion expurgés dans votre sortie est un comportement attendu. Le modèle peut toujours utiliser ce raisonnement expurgé pour informer ses réponses tout en maintenant les garde-fous de sécurité.

Si vous devez tester la gestion de la réflexion expurgée dans votre application, vous pouvez utiliser cette chaîne de test spéciale comme invite : ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

Lorsque vous renvoyez des blocs thinking et redacted_thinking à l’API dans une conversation à plusieurs tours, vous devez inclure le bloc complet non modifié pour le dernier tour de l’assistant.

Ceci est crucial pour maintenir le flux de raisonnement du modèle. Nous suggérons de toujours renvoyer tous les blocs de réflexion à l’API. Pour plus de détails, consultez la section Préserver les blocs de réflexion ci-dessous.

​
Suggestions pour gérer la réflexion expurgée en production

Lors de la construction d’applications destinées aux clients qui utilisent la réflexion approfondie :

  • Sachez que les blocs de réflexion expurgés contiennent du contenu chiffré qui n’est pas lisible par l’homme
  • Envisagez de fournir une explication simple comme : “Une partie du raisonnement interne de Claude a été automatiquement chiffrée pour des raisons de sécurité. Cela n’affecte pas la qualité des réponses.”
  • Si vous montrez des blocs de réflexion aux utilisateurs, vous pouvez filtrer les blocs expurgés tout en préservant les blocs de réflexion normaux
  • Soyez transparent sur le fait que l’utilisation des fonctionnalités de réflexion approfondie peut occasionnellement entraîner le chiffrement de certains raisonnements
  • Implémentez une gestion appropriée des erreurs pour gérer gracieusement la réflexion expurgée sans casser votre interface utilisateur

​
Diffusion en continu de la réflexion approfondie

Lorsque la diffusion en continu est activée, vous recevrez le contenu de réflexion via des événements thinking_delta. Voici comment gérer la diffusion en continu avec la réflexion :

Exemple de sortie en streaming :

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

À propos du comportement de streaming avec la réflexion

Lors de l’utilisation du streaming avec la réflexion activée, vous pourriez remarquer que le texte arrive parfois en plus gros morceaux alternant avec une livraison plus petite, token par token. C’est un comportement attendu, en particulier pour le contenu de réflexion.

Le système de streaming doit traiter le contenu par lots pour des performances optimales, ce qui peut entraîner ce modèle de livraison “par morceaux”. Nous travaillons continuellement à améliorer cette expérience, avec des mises à jour futures axées sur une diffusion plus fluide du contenu de réflexion.

Les blocs redacted_thinking n’auront pas de deltas associés et seront envoyés comme un seul événement.

​
Considérations importantes lors de l’utilisation de la réflexion approfondie

Travailler avec le budget de réflexion : Le budget minimum est de 1 024 tokens. Nous suggérons de commencer par le minimum et d’augmenter progressivement le budget de réflexion pour trouver la plage optimale permettant à Claude de bien performer pour votre cas d’utilisation. Des nombres de tokens plus élevés peuvent vous permettre d’obtenir un raisonnement plus complet et nuancé, mais il peut aussi y avoir des rendements décroissants selon la tâche.

  • Le budget de réflexion est un objectif plutôt qu’une limite stricte - l’utilisation réelle des tokens peut varier selon la tâche.
  • Soyez prêt à des temps de réponse potentiellement plus longs en raison du traitement supplémentaire requis pour le processus de raisonnement.
  • Le streaming est requis lorsque max_tokens est supérieur à 21 333.

Pour les budgets de réflexion supérieurs à 32K : Nous recommandons d’utiliser le traitement par lots pour les charges de travail où le budget de réflexion est fixé au-dessus de 32K pour éviter les problèmes de réseau. Les requêtes poussant le modèle à réfléchir au-dessus de 32K tokens causent des requêtes longues qui pourraient se heurter aux délais d’attente du système et aux limites de connexions ouvertes.

Compatibilité de la réflexion avec d’autres fonctionnalités :

  • La réflexion n’est pas compatible avec les modifications de temperature, top_p, ou top_k ainsi qu’avec l’utilisation forcée d’outils.
  • Vous ne pouvez pas pré-remplir les réponses lorsque la réflexion est activée.
  • Les modifications du budget de réflexion invalident les préfixes de prompts mis en cache qui incluent des messages. Cependant, les prompts système et les définitions d’outils mis en cache continueront de fonctionner lorsque les paramètres de réflexion changent.

​
Tarification et utilisation des tokens pour la réflexion approfondie

Les tokens de réflexion approfondie comptent dans la fenêtre de contexte et sont facturés comme des tokens de sortie. Puisque les tokens de réflexion sont traités comme des tokens de sortie normaux, ils comptent également dans vos limites de taux. Assurez-vous de tenir compte de cette utilisation accrue de tokens lors de la planification de votre utilisation de l’API.

Pour Claude 3.7 Sonnet, la tarification est :

Utilisation des tokensCoût
Tokens d’entrée3 $ / MTok
Tokens de sortie (y compris les tokens de réflexion)15 $ / MTok
Écriture de mise en cache de prompt3,75 $ / MTok
Lecture de mise en cache de prompt0,30 $ / MTok

Le traitement par lots pour la réflexion approfondie est disponible à 50 % de réduction sur ces prix et se termine souvent en moins d’une heure.

Tous les tokens de réflexion approfondie (y compris les tokens de réflexion expurgés) sont facturés comme des tokens de sortie et comptent dans vos limites de taux.

Dans les conversations à plusieurs tours, les blocs de réflexion associés aux messages assistant précédents ne sont pas facturés comme des tokens d’entrée.

Lorsque la réflexion approfondie est activée, un prompt système spécialisé de 28 ou 29 tokens est automatiquement inclus pour prendre en charge cette fonctionnalité.

​
Capacités de sortie étendues (bêta)

Claude 3.7 Sonnet peut produire des réponses substantiellement plus longues que les modèles précédents avec un support jusqu’à 128K tokens de sortie (bêta) - plus de 15 fois plus long que les autres modèles Claude. Cette capacité étendue est particulièrement efficace pour les cas d’utilisation de réflexion approfondie impliquant un raisonnement complexe, une génération de code riche et une création de contenu complète.

Cette fonctionnalité peut être activée en passant un en-tête anthropic-beta de output-128k-2025-02-19.

Lors de l’utilisation de la réflexion approfondie avec des sorties plus longues, vous pouvez allouer un budget de réflexion plus important pour soutenir un raisonnement plus approfondi, tout en ayant encore amplement de tokens disponibles pour la ré

ponse finale.

Nous suggérons d’utiliser le streaming ou le mode par lots avec cette capacité de sortie étendue ; pour plus de détails, consultez nos conseils sur les considérations de fiabilité réseau pour les requêtes longues.

​
Utilisation de la réflexion approfondie avec la mise en cache des prompts

La mise en cache des prompts avec la réflexion a plusieurs considérations importantes :

Inclusion des blocs de réflexion dans les prompts mis en cache

  • La réflexion n’est incluse que lors de la génération d’un tour d’assistant et n’est pas destinée à être mise en cache.
  • Les blocs de réflexion des tours précédents sont ignorés.
  • Si la réflexion est désactivée, tout contenu de réflexion transmis à l’API est simplement ignoré.

Règles d’invalidation du cache

  • Les modifications des paramètres de réflexion (activation/désactivation ou changements de budget) invalident les points de rupture du cache définis dans les messages.
  • Les prompts système et les outils maintiennent la mise en cache même lorsque les paramètres de réflexion changent.

​
Exemples de mise en cache des prompts avec réflexion approfondie

​
Max tokens et taille de la fenêtre de contexte avec la réflexion approfondie

Dans les modèles Claude plus anciens (avant Claude 3.7 Sonnet), si la somme des tokens de prompt et de max_tokens dépassait la fenêtre de contexte du modèle, le système ajustait automatiquement max_tokens pour s’adapter à la limite de contexte. Cela signifiait que vous pouviez définir une grande valeur max_tokens et le système la réduirait silencieusement selon les besoins.

Avec Claude 3.7 Sonnet, max_tokens (qui inclut votre budget de réflexion lorsque la réflexion est activée) est appliqué comme une limite stricte. Le système renverra maintenant une erreur de validation si les tokens de prompt + max_tokens dépassent la taille de la fenêtre de contexte.

​
Comment la fenêtre de contexte est calculée avec la réflexion approfondie

Lors du calcul de l’utilisation de la fenêtre de contexte avec la réflexion activée, il y a quelques considérations à prendre en compte :

  • Les blocs de réflexion des tours précédents sont supprimés et ne sont pas comptés dans votre fenêtre de contexte
  • La réflexion du tour actuel compte dans votre limite max_tokens pour ce tour

Le diagramme ci-dessous montre la gestion spécialisée des tokens lorsque la réflexion approfondie est activée :

La fenêtre de contexte effective est calculée comme suit :

fenêtre de contexte =
  (tokens d'entrée actuels - tokens de réflexion précédents) +
  (tokens de réflexion + tokens de réflexion expurgés + tokens de sortie texte)

Nous recommandons d’utiliser l’API de comptage des tokens pour obtenir des décomptes précis des tokens pour votre cas d’utilisation spécifique, en particulier lors du travail avec des conversations à plusieurs tours qui incluent de la réflexion.

Vous pouvez consulter notre guide sur les fenêtres de contexte pour une analyse plus approfondie.

​
Gestion des tokens avec la réflexion approfondie

Étant donné le nouveau comportement de la fenêtre de contexte et de max_tokens avec les modèles de réflexion approfondie comme Claude 3.7 Sonnet, vous devrez peut-être :

  • Surveiller et gérer plus activement votre utilisation des tokens
  • Ajuster les valeurs max_tokens à mesure que la longueur de votre prompt change
  • Potentiellement utiliser les points de terminaison de comptage des tokens plus fréquemment
  • Être conscient que les blocs de réflexion précédents ne s’accumulent pas dans votre fenêtre de contexte

Ce changement a été fait pour fournir un comportement plus prévisible et transparent, en particulier alors que les limites maximales de tokens ont considérablement augmenté.

​
Réflexion approfondie avec utilisation d’outils

Lors de l’utilisation de la réflexion approfondie avec l’utilisation d’outils, soyez conscient du modèle de comportement suivant :

  1. Premier tour de l’assistant : Lorsque vous envoyez un message initial de l’utilisateur, la réponse de l’assistant inclura des blocs de réflexion suivis de demandes d’utilisation d’outils.

  2. Tour de résultat d’outil : Lorsque vous passez le message utilisateur avec des blocs de résultat d’outil, le message assistant suivant ne contiendra pas de blocs de réflexion supplémentaires.

Pour développer ici, l’ordre normal d’une conversation avec utilisation d’outils et réflexion suit ces étapes :

  1. L’utilisateur envoie le message initial
  2. L’assistant répond avec des blocs de réflexion et des demandes d’outils
  3. L’utilisateur envoie un message avec les résultats des outils
  4. L’assistant répond soit avec plus d’appels d’outils, soit juste du texte (pas de blocs de réflexion dans cette réponse)
  5. Si plus d’outils sont demandés, répétez les étapes 3-4 jusqu’à ce que la conversation soit terminée

Cette conception permet à Claude de montrer son processus de raisonnement avant de faire des demandes d’outils, mais de ne pas répéter le processus de réflexion après avoir reçu les résultats des outils. Claude ne produira pas un autre bloc de réflexion jusqu’après le prochain tour user non-tool_result.

Le diagramme ci-dessous illustre la gestion des tokens de la fenêtre de contexte lors de la combinaison de la réflexion approfondie avec l’utilisation d’outils :

​
Préservation des blocs de réflexion

Pendant l’utilisation d’outils, vous devez renvoyer les blocs thinking et redacted_thinking à l’API, et vous devez inclure le bloc complet non modifié à l’API. C’est crucial pour maintenir le flux de raisonnement du modèle et l’intégrité de la conversation.

Bien que vous puissiez omettre les blocs thinking et redacted_thinking des tours assistant précédents, nous suggérons de toujours renvoyer tous les blocs de réflexion à l’API pour toute conversation à plusieurs tours. L’API va :

  • Filtrer automatiquement les blocs de réflexion fournis
  • Utiliser les blocs de réflexion pertinents nécessaires pour préserver le raisonnement du modèle
  • Ne facturer que les tokens d’entrée pour les blocs montrés à Claude

​
Pourquoi les blocs de réflexion doivent être préservés

Lorsque Claude invoque des outils, il met en pause la construction d’une réponse pour attendre des informations externes. Lorsque les résultats des outils sont renvoyés, Claude continuera à construire cette réponse existante. Cela nécessite de préserver les blocs de réflexion pendant l’utilisation des outils, pour deux raisons :

  1. Continuité du raisonnement : Les blocs de réflexion capturent le raisonnement étape par étape de Claude qui a conduit aux demandes d’outils. Lorsque vous postez les résultats des outils, inclure la réflexion originale garantit que Claude peut continuer son raisonnement là où il s’est arrêté.

  2. Maintien du contexte : Bien que les résultats des outils apparaissent comme des messages utilisateur dans la structure de l’API, ils font partie d’un flux de raisonnement continu. La préservation des blocs de réflexion maintient ce flux conceptuel à travers plusieurs appels API.

Important : Lors de la fourniture de blocs thinking ou redacted_thinking, la séquence entière de blocs thinking ou redacted_thinking consécutifs doit correspondre aux sorties générées par le modèle lors de la requête originale ; vous ne pouvez pas réorganiser ou modifier la séquence de ces blocs.

​
Conseils pour tirer le meilleur parti du mode de réflexion approfondie

Pour tirer le meilleur parti de la réflexion approfondie :

  1. Définir des budgets appropriés : Commencez avec des budgets de réflexion plus importants (16 000+ tokens) pour les tâches complexes et ajustez selon vos besoins.

  2. Expérimentez avec les budgets de tokens de réflexion : Le modèle peut se comporter différemment avec différents paramètres de budget de réflexion maximum. Augmenter le budget de réflexion maximum peut améliorer la réflexion du modèle, au prix d’une latence accrue. Pour les tâches critiques, envisagez de tester différents paramètres de budget pour trouver l’équilibre optimal entre qualité et performance.

  3. Vous n’avez pas besoin de supprimer vous-même les blocs de réflexion précédents : L’API Anthropic ignore automatiquement les blocs de réflexion des tours précédents et ils ne sont pas inclus dans le calcul de l’utilisation du contexte.

  4. Surveillez l’utilisation des tokens : Gardez une trace de l’utilisation des tokens de réflexion pour optimiser les coûts et les performances.

  5. Utilisez la réflexion approfondie pour les tâches particulièrement complexes : Activez la réflexion pour les tâches qui bénéficient d’un raisonnement étape par étape comme les mathématiques, la programmation et l’analyse.

  6. Tenez compte du temps de réponse prolongé : Prenez en compte que la génération de blocs de réflexion peut augmenter le temps de réponse global.

  7. Gérez le streaming de manière appropriée : Lors du streaming, soyez prêt à gérer les blocs de contenu de réflexion et de texte à mesure qu’ils arrivent.

  8. Ingénierie des prompts : Consultez nos conseils d’ingénierie des prompts pour la réflexion approfondie si vous voulez maximiser les capacités de réflexion de Claude.

​
Prochaines étapes

Essayez le livre de recettes de réflexion approfondie

Explorez des exemples pratiques de réflexion dans notre livre de recettes.

Conseils d'ingénierie des prompts pour la réflexion approfondie

Apprenez les meilleures pratiques d’ingénierie des prompts pour la réflexion approfondie.

Was this page helpful?

Conseils pour la réflexion approfondieSupport multilingue