Contrôler le niveau d'effort du modèle de raisonnement (Chat Completions)

Description de l'API

Étant donné un prompt, le modèle renverra une ou plusieurs réponses de complétion prédites (prend en charge le contrôle du niveau d'effort de réflexion du modèle de raisonnement).

Référence de la documentation officielle : OpenAI Reasoning Guides
Statut de l'API : Publié (released)

Instructions de requête

Méthode de requête : POST
Point de terminaison : https://api.codingplanx.ai/v1/chat/completions

En-têtes de requête (Headers)

Nom du paramètre	Requis	Type	Valeur d'exemple	Description
`Content-Type`	Oui	`string`	`application/json`	Format des données
`Accept`	Oui	`string`	`application/json`	Format de réception
`Authorization`	Non	`string`	`Bearer {{YOUR_API_KEY}}`	Identifiants d'authentification

Paramètres du corps de la requête (Body)

Format des données : application/json

Nom du paramètre	Requis	Type	Description
`model`	Oui	`string`	L'ID du modèle à utiliser (par exemple, `o4-mini`, etc.).
`messages`	Oui	`array`	La liste des messages composant la conversation jusqu'à présent. Contient `role` (ex: user/assistant) et `content` (contenu du message).
`tools`	Oui	`array`	Une liste d'outils (fonctions) que le modèle peut appeler. Utilisé pour fournir des fonctions pour lesquelles le modèle peut générer une entrée JSON.
`tool_choice`	Oui	`object`	Contrôle quelle fonction le modèle appelle. `none` signifie aucun appel, `auto` signifie sélection automatique.
`reasoning_effort`	Non	`string`	Paramètre principal : Contrôle le niveau d'effort (profondeur de réflexion) du modèle de raisonnement lors de la génération de la réponse. Les valeurs possibles courantes sont `low`, `medium`, `high`.
`temperature`	Non	`number`	Température d'échantillonnage, comprise entre 0 et 2. Des valeurs plus élevées (ex: 0.8) rendent la sortie plus aléatoire, tandis que des valeurs plus basses (ex: 0.2) la rendent plus ciblée et déterministe. Il est recommandé de modifier soit ce paramètre, soit `top_p`, mais pas les deux.
`top_p`	Non	`number`	Échantillonnage par noyau (Nucleus sampling). 0.1 signifie que seuls les tokens composant les 10 % supérieurs de la masse de probabilité sont considérés. Il est recommandé de modifier soit ce paramètre, soit `temperature`, mais pas les deux.
`n`	Non	`integer`	Par défaut à 1. Le nombre de choix de complétion de chat à générer pour chaque message d'entrée.
`stream`	Non	`boolean`	Par défaut à false. Si défini sur true, des deltas de messages partiels seront envoyés sous forme de Server-Sent Events (SSE), et le flux se terminera par `data: [DONE]`.
`stop`	Non	`string`	Jusqu'à 4 séquences de chaînes de caractères où l'API s'arrêtera de générer des tokens supplémentaires.
`max_tokens`	Non	`integer`	Le nombre maximum de tokens générés dans la complétion de chat. La longueur totale des tokens d'entrée et générés est limitée par la longueur de contexte du modèle.
`presence_penalty`	Non	`number`	Un nombre entre -2.0 et 2.0. Des valeurs positives pénalisent les nouveaux tokens en fonction de leur apparition préalable dans le texte, augmentant ainsi la probabilité que le modèle aborde de nouveaux sujets.
`frequency_penalty`	Non	`number`	Un nombre entre -2.0 et 2.0. Des valeurs positives pénalisent les nouveaux tokens en fonction de leur fréquence actuelle dans le texte, réduisant la probabilité que le modèle répète exactement la même ligne.
`logit_bias`	Non	`object`	Accepte un objet JSON mappant les ID de tokens à une valeur de biais (de -100 à 100), utilisé pour modifier la probabilité d'apparition de tokens spécifiés dans la complétion.
`user`	Non	`string`	Un identifiant unique représentant votre utilisateur final, qui aide à surveiller et à détecter les abus.
`response_format`	Non	`object`	Spécifie le format que le modèle doit générer. Par exemple, `{"type": "json_object"}` active le mode JSON.
`seen`	Non	`integer`	Fonctionnalité en phase de test (similaire à seed). S'il est spécifié, le système fera de son mieux pour échantillonner de manière déterministe, de sorte que les mêmes paramètres renvoient les mêmes résultats.

Exemple de requête

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "Bonjour, veuillez expliquer en détail les principes de l'informatique quantique."
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

Description de la réponse

Paramètres du corps de réponse

Format des données : application/json

Nom du paramètre	Type	Description
`id`	`string`	L'identifiant unique de cette requête.
`object`	`string`	Le type d'objet, généralement `chat.completion`.
`created`	`integer`	Le timestamp (horodatage) de l'heure de création.
`choices`	`array`	Une liste des résultats de complétion.
└ `index`	`integer`	L'index de ce choix dans la liste.
└ `message`	`object`	Le corps du message de réponse généré par le modèle. Contient `role` et `content`.
└ `finish_reason`	`string`	La raison pour laquelle le modèle a cessé de générer (par exemple, `stop`, `length`).
`usage`	`object`	Statistiques d'utilisation des tokens.
└ `prompt_tokens`	`integer`	Nombre de tokens consommés par le prompt.
└ `completion_tokens`	`integer`	Nombre de tokens consommés par la génération du modèle.
└ `total_tokens`	`integer`	Nombre total de tokens consommés.

Exemple de réponse (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQ (Foire Aux Questions)

1. Quel est le rôle du paramètre `reasoning_effort` ?

reasoning_effort est utilisé pour contrôler la quantité de ressources de calcul et de temps que les modèles dotés de capacités de raisonnement avancé (tels que la série o1/o4 d'OpenAI) consacrent à la réflexion interne avant de fournir une réponse finale. Il prend généralement en charge trois niveaux : low (faible), medium (moyen) et high (élevé). Lorsqu'il est défini sur high, le modèle effectuera des déductions logiques plus approfondies, ce qui est idéal pour résoudre des problèmes mathématiques ou de programmation complexes ; cependant, le temps de réponse augmentera en conséquence.

2. Pourquoi ne reçois-je pas une réponse JSON standard après avoir activé `stream: true` ?

Lorsque le streaming est activé (stream: true), l'API utilise le protocole Server-Sent Events (SSE) pour renvoyer des blocs de données en continu (Chunks). Chaque bloc est envoyé sous la forme data: {...}. Lorsque tout le contenu a été transmis, un message data: [DONE] est envoyé. Les développeurs doivent lire le flux ligne par ligne et analyser la chaîne JSON qui suit data: pour reconstituer la réponse complète.

3. La documentation suggère de ne modifier qu'un seul des paramètres entre `temperature` et `top_p`, pourquoi ?

Ces deux paramètres sont utilisés pour contrôler l'aléatoire et la diversité de la sortie du modèle. temperature modifie la distribution de probabilité en redimensionnant les logits, tandis que top_p (échantillonnage par noyau) restreint le pool de candidats en tronquant les mots ayant une faible probabilité cumulée. Ajuster ces deux paramètres simultanément rendrait le comportement du modèle difficile à prédire et à contrôler. Par conséquent, la meilleure pratique consiste à en fixer un (en gardant généralement la valeur par défaut) et à n'ajuster que l'autre pour répondre à vos besoins de contrôle de l'aléatoire.

4. Que signifie un `finish_reason` renvoyant `"length"` ?

Cela signifie que la réponse du modèle a été coupée de force. Il y a généralement deux raisons à cela : premièrement, le nombre de tokens générés a atteint la limite supérieure max_tokens définie dans les paramètres de la requête ; deuxièmement, le nombre total de tokens de votre prompt (requête) plus la réponse générée par le modèle dépasse la limite de la fenêtre de contexte maximale autorisée pour ce modèle. Dans ce cas, il est recommandé de raccourcir l'historique de la conversation ou d'augmenter la valeur du paramètre max_tokens.

5. Comment forcer le modèle à renvoyer des données au format JSON ?

Vous pouvez activer le mode JSON en passant "response_format": {"type": "json_object"} dans le corps de la requête. Très important : Tout en activant ce mode, vous devez demander explicitement au modèle de générer du JSON en utilisant le langage naturel dans la section messages (généralement dans le prompt system ou user). Sinon, le modèle pourrait se retrouver dans une boucle infinie de génération d'espaces blancs jusqu'à ce que la limite de tokens soit atteinte.