Reasoning

Configurez l’effort de raisonnement pour les tâches complexes et lisez correctement les résultats, résumés et données Usage.

Reasoning convient aux analyses en plusieurs étapes, aux contraintes complexes, aux démonstrations mathématiques, à la planification de code ou à la coordination d’outils. Les modèles de raisonnement permettent généralement de régler l’effort et peuvent retourner des résumés, des Thinking Blocks ou un Usage associé ; leur forme dépend du modèle et du protocole.

Pour une classification simple, une conversion de format ou une réponse courte, davantage de raisonnement n’améliore pas nécessairement le résultat et peut augmenter le délai et la consommation de tokens.

Le raisonnement n’utilise pas un champ universel

Chat, Responses, Anthropic Messages et Gemini représentent différemment la configuration du raisonnement, les résultats exposés et l’état des conversations. Ne copiez pas directement les champs d’un protocole dans un autre.

Quand l’utiliser

Tâche	Recommandation
Planification sous contraintes et analyse complexe	Choisir un modèle de raisonnement et commencer par un effort faible ou par défaut
Mathématiques, code et logique	Vérifier aussi la réponse finale ; l’effort ne garantit pas l’exactitude
Workflow d’appels d’outils	Conserver les appels, résultats et états requis et limiter les itérations
Reformulation courte, extraction et classification	Tester d’abord un modèle classique ou un effort faible pour éviter les coûts inutiles

Vérifiez d’abord les modèles, protocoles et capacités disponibles pour le compte dans le Catalogue de modèles. Remplacez MODEL_ID par un modèle du compte qui prend en charge la configuration de raisonnement indiquée.

Configurer l’effort de raisonnement avec Responses

Responses place la configuration dans l’objet reasoning :

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "input": "Comparez deux stratégies de migration de base de données et justifiez votre choix.",
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    }
  }'

effort règle l’effort de raisonnement et summary demande un résumé que le protocole autorise à exposer. Les valeurs disponibles et leur application dépendent du modèle ; consultez Responses Reference.

Représentation du raisonnement selon le protocole

Chat utilise reasoning_effort pour demander un niveau d’effort. Lorsque la réponse les fournit, les tokens de raisonnement figurent généralement dans les détails de complétion de l’Usage ; la réponse finale reste dans l’Assistant Message.

{
  "model": "MODEL_ID",
  "messages": [
    {"role": "user", "content": "Analysez les principaux risques de ce plan de déploiement."}
  ],
  "reasoning_effort": "medium"
}

Les valeurs illustrent uniquement l’emplacement des champs ; tous les modèles n’acceptent pas les mêmes niveaux ou budgets. Consultez les références Chat Completions, Anthropic Messages et Gemini Generate Content.

Lire la réponse finale et les informations de raisonnement exposées

L’application doit généralement traiter séparément les éléments suivants :

Réponse finale : contenu affiché à l’utilisateur ou transmis aux processus suivants.
Résumé de raisonnement ou Thinking Block : à lire uniquement s’il est explicitement retourné, sans l’assimiler au processus de pensée interne complet.
Usage : enregistrer les tokens d’entrée, de sortie finale et de raisonnement ; leur emplacement varie selon le protocole.
Arrêt ou état incomplet : vérifier si le budget de sortie, une politique de contenu, une annulation ou une erreur a interrompu la réponse.

Si seule la conclusion est nécessaire, il n’est pas utile de conserver le raisonnement exposé. Avant de l’enregistrer, évaluez la confidentialité, le périmètre des journaux et la conservation des données.

Streaming et appels d’outils

Le flux peut retourner séparément les incréments de raisonnement et de texte final ; utilisez des tampons distincts.
Des états de protocole ou des Thinking Blocks peuvent apparaître avant et après les appels d’outils ; ne conservez pas uniquement le texte final.
L’exécution respecte les exigences de validation, d’autorisation et d’idempotence de Tool Calling.
Pour poursuivre, retransmettez uniquement l’historique requis, sans modifier les signatures, identifiants d’appel ou états opaques.

Consultez Streaming pour le traitement complet des flux.

Définir le budget de sortie

Les tokens de raisonnement et la réponse visible peuvent partager le budget de sortie. Un budget trop faible peut laisser le modèle terminer l’analyse sans lui permettre de produire une réponse finale complète.

En production, surveillez simultanément :

La complétude de la réponse finale ;
La raison de l’arrêt ou de l’état incomplet ;
L’Usage du raisonnement et de la sortie visible ;
La qualité, la latence et le coût selon le niveau d’effort ;
La fin du cycle d’outils dans les limites d’itérations et de durée.

Vérifications avant la mise en production

Le compte a accès au modèle cible, à son endpoint de raisonnement et aux champs vérifiés.
L’application n’envoie que les champs de raisonnement acceptés par le protocole.
La réponse finale, le raisonnement exposé et l’Usage sont traités séparément.
Le streaming, les conversations et les appels d’outils conservent l’état de protocole nécessaire.
Les budgets insuffisants, refus, délais dépassés et réponses incomplètes disposent de branches explicites.
L’effort, les résumés et le Thinking exposé ne sont pas présentés comme des garanties d’exactitude.

En cas d’échec, consultez Erreurs et dépannage. Avant de changer de modèle ou de protocole, consultez Choix du protocole.