Construire avec la réflexion étendue

La réflexion étendue 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 étendue

Lorsque la réflexion étendue 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 pour 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 étendue

Ajoutez le paramètre thinking et un budget de tokens spécifié à utiliser pour la réflexion étendue à 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 du streaming 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 la réflexion étendue. 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é. Dans ce cas, 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.
• Les blocs thinking et redacted_thinking sont renvoyés avant les blocs text dans la réponse.

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..."
    }
  ]
}

Lorsque vous renvoyez des blocs thinking et redacted_thinking à l’API dans une conversation à plusieurs tours, vous devez inclure le bloc complet non modifié à l’API 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.

​

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

Lors de la création d’applications destinées aux clients qui utilisent la réflexion étendue :

• 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 étendue 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

​

Streaming de la réflexion étendue

Lorsque le streaming est activé, vous recevrez le contenu de réflexion via des événements thinking_delta. Voici comment gérer le streaming 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"}

[Le reste de la traduction continue dans le prochain message en raison de la limite de caractères…]