Lors de tâches d'extraction d'informations ou de génération de données structurées, un modèle peut renvoyer du texte supplémentaire (tel que json ) qui perturbe l'analyse en aval. L'activation de la sortie structurée garantit que le modèle renvoie une chaîne JSON valide. Le mode JSON Schema vous offre également un contrôle précis sur la structure et les types de sortie, éliminant ainsi toute validation supplémentaire ou tentative répétée.
Utilisation
La sortie structurée prend en charge deux modes : JSON Object et JSON Schema.
-
Mode JSON Object : Garantit que la sortie est une chaîne JSON valide, mais ne garantit pas une structure spécifique. Utilisation :
- Définissez le paramètreresponse_format: Dans le corps de la requête, définissez
response_formatsur{"type": "json_object"}. - Incluez le mot-clé JSON dans votre invite : Le message système ou le message utilisateur doit contenir le mot « JSON » (insensible à la casse), sinon l'API renvoie :
'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.
- Définissez le paramètreresponse_format: Dans le corps de la requête, définissez
-
Mode JSON Schema : Garantit que la sortie est conforme à une structure spécifiée. Utilisation : définissez
response_formatsur{"type": "json_schema", "json_schema": {...}, "strict": true}.Aucun mot-clé JSON n'est requis dans l'invite.
Les paramètres ci-dessus s'appliquent à l'API Chat Completions. Si vous utilisez l'API Responses, définissez plutôt text.format ; le format de la valeur est identique. Consultez les exemples ci-dessous. En mode JSON Object, l'API Responses exige également que l'invite contienne le mot « JSON » ; sinon, une erreur 400 est renvoyée.
Comparaison des fonctionnalités :
Fonctionnalité | Mode JSON Object | Mode JSON Schema |
|---|---|---|
Génère un JSON valide | Oui | Oui |
Suit strictement le schéma | Non | Oui |
Modèles pris en charge | La plupart des modèles Qwen | Uniquement certains modèles qwen-plus sélectionnés |
|
|
|
Exigence relative à l'invite | Doit inclure « JSON » | Il est recommandé de décrire explicitement |
Cas d'utilisation | Sortie JSON flexible | Validation précise du schéma |
Modèles pris en charge
- JSON Object
- JSON Schema
- Qwen
- Kimi
- DeepSeek
- GLM
- Stepfun
-
Modèles de génération de texte
- Qwen-Max : série Qwen4-Max, séries Qwen3.8-Max, Qwen3.7-Max
- Qwen-Max (mode sans réflexion) : séries Qwen3.6-Max, Qwen3-Max, Qwen-Max
- Qwen-Plus : série Qwen3.7-Plus
- Qwen-Plus (mode sans réflexion) : séries Qwen3.6-Plus, Qwen3.5-Plus, Qwen-Plus
- Qwen-Flash : série Qwen3.7-Flash
- Qwen-Flash (mode sans réflexion) : séries Qwen3.6-Flash, Qwen3.5-Flash, Qwen-Flash
- Qwen-Turbo (mode sans réflexion) : série Qwen-Turbo
- Qwen-Coder : série Qwen3-Coder
- Qwen-Long : série Qwen-Long
- Série open source Qwen3.8
- Série open source Qwen3.6 (mode sans réflexion)
- Série open source Qwen3.5 (mode sans réflexion)
- Série open source Qwen3 (mode sans réflexion)
- Série open source Qwen3-Coder
- Série open source Qwen2.5 (à l'exception des modèles math et coder)
-
Modèles multimodaux
- Qwen-VL (mode sans réflexion) : séries Qwen3-VL-Plus, Qwen3-VL-Flash, série Qwen-VL-Max (à l'exception des versions les plus récentes et des snapshots), série Qwen-VL-Plus (à l'exception des versions les plus récentes et des snapshots)
- Qwen-Omni : série Qwen3.5-Omni-Plus
- Série open source Qwen3-VL (mode sans réflexion)
- Qwen
- GLM
- DeepSeek
-
Modèles de génération de texte
- Qwen-Max : série Qwen4-Max, séries Qwen3.8-Max, Qwen3.7-Max
- Qwen-Max (mode sans réflexion) : séries Qwen3.6-Max, Qwen3-Max, Qwen-Max
- Qwen-Plus : série Qwen3.7-Plus
- Qwen-Plus (mode sans réflexion) : séries Qwen3.6-Plus, Qwen3.5-Plus, Qwen-Plus
- Qwen-Flash : série Qwen3.7-Flash
- Qwen-Flash (mode sans réflexion) : séries Qwen3.6-Flash, Qwen3.5-Flash, Qwen-Flash
- Qwen-Turbo (mode sans réflexion) : série Qwen-Turbo
- Qwen-Coder : série Qwen3-Coder
- Qwen-Long : série Qwen-Long
- Série open source Qwen3.8
- Série open source Qwen3.6 (mode sans réflexion)
- Série open source Qwen3.5 (mode sans réflexion)
- Série open source Qwen3 (mode sans réflexion)
- Série open source Qwen3-Coder
- Série open source Qwen2.5 (à l'exception des modèles math et coder)
-
Modèles multimodaux
- Qwen-VL (mode sans réflexion) : séries Qwen3-VL-Plus, Qwen3-VL-Flash, série Qwen-VL-Max (à l'exception des versions les plus récentes et des snapshots), série Qwen-VL-Plus (à l'exception des versions les plus récentes et des snapshots)
- Qwen-Omni : série Qwen3.5-Omni-Plus
- Série open source Qwen3-VL (mode sans réflexion)
Premiers pas
Cet exemple extrait des informations structurées à partir d'un profil personnel.
Obtenir une clé API et exporter la clé API en tant que variable d'environnement. Si vous utilisez le SDK OpenAI ou le SDK DashScope pour effectuer des appels, installez le SDK.
- API Chat Completions compatible avec OpenAI
- OpenAI-Compatible Responses API
- DashScope
- Python
- Node.js
- curl
Réponse
Traitement des données image et vidéo
Les modèles multimodaux prennent également en charge la sortie structurée pour les images et les vidéos. Utilisez le mode JSON pour extraire des données structurées à partir de contenus visuels, tels que les valeurs de champs sur des reçus, l'emplacement d'objets dans des images ou des événements dans une vidéo.
Pour connaître les limites relatives aux fichiers image et vidéo, consultez Compréhension des images et des vidéos .
- OpenAI compatible
- DashScope
- Python
- Node.js
- curl
Réponse
Optimiser les invites
Des invites ambiguës telles que « renvoyer les informations utilisateur » entraînent des structures de sortie imprévisibles. Pour obtenir des résultats fiables, décrivez le schéma attendu dans votre invite : spécifiez les noms et types des champs, indiquez s'ils sont obligatoires ou facultatifs, définissez les contraintes de format (comme le format de date) et incluez des exemples.
- Compatible OpenAI
- DashScope
- Python
- Node.js
Réponse
Obtenir une sortie structurée
Définir response_format type sur json_object renvoie une chaîne JSON valide, mais la structure peut ne pas correspondre à vos attentes ; cette approche convient aux scénarios simples. Pour l'analyse automatisée, l'interopérabilité des API et d'autres scénarios complexes nécessitant des contraintes de type strictes, définissez type sur json_schema afin de forcer le modèle à produire un contenu qui respecte strictement un format spécifié. Le format et un exemple pour response_format :
name et age) ainsi qu'un champ facultatif email.
Les modèles de la région de Singapour ne sont pas encore pris en charge.
Utilisation
Avec la méthode parse du SDK OpenAI, vous pouvez transmettre directement une classe Python Pydantic ou un objet Node.js Zod. Le SDK le convertit automatiquement en schéma JSON, ce qui évite d'écrire manuellement du JSON complexe. Pour le SDK DashScope, construisez le schéma JSON manuellement en suivant le format ci-dessus.
- API Chat Completions compatible avec OpenAI
- OpenAI-Compatible Responses API
- DashScope
Python
Node.js
Guide de configuration
Suivez ces recommandations lors de l'utilisation de JSON Schema pour obtenir des sorties structurées plus fiables :
-
Déclaration des champs obligatoires
Il est recommandé de répertorier les champs obligatoires dans le tableau
required. Les champs facultatifs peuvent être omis, par exemple :Si l'entrée ne fournit pas d'informations sur l'e-mail, la sortie n'inclura pas ce champ. -
Implémentation des champs facultatifs
Outre l'omission du champ dans
required, vous pouvez également autoriser le typenull:La sortie inclura toujours le champemail, mais sa valeur peut êtrenull. -
Configuration de additionalProperties
Contrôle l'autorisation ou non de champs supplémentaires non définis dans le schéma :
Exemple d'entrée :
"I'm Zhang San, 25 years old"; sortie :{"name": "Zhang San", "age": 25}(inclut le champagenon défini).Valeur
Comportement
Cas d'utilisation
falseSortie uniquement des champs définis
Contrôle précis de la structure
trueAutorisation des champs supplémentaires
Capture d'informations supplémentaires
- Types de données pris en charge : string, number, integer, boolean, object, array, enum.
Mise en production
- Validez avant de transmettre en aval Lorsque vous utilisez le mode JSON Object, validez la sortie avant de la transmettre aux services en aval. Utilisez une bibliothèque telle que jsonschema (Python), Ajv (JavaScript) ou Everit (Java) pour garantir la conformité au JSON Schema attendu, évitant ainsi les échecs d'analyse, la perte de données ou les perturbations de la logique métier dues à des champs manquants, des erreurs de type ou des formats incorrects. En cas d'échec, réessayez la requête ou utilisez un modèle pour réécrire la sortie.
-
Ne définissez pas max_tokens
Ne définissez pas
max_tokenslorsque la sortie structurée est activée. Ce paramètre limite le nombre de jetons de sortie et prend par défaut la valeur maximale du modèle. Sa définition risque de tronquer la chaîne JSON en cours de génération, produisant un JSON invalide impossible à analyser. -
Utilisez le SDK pour générer des schémas
Utilisez le SDK pour générer automatiquement les schémas. Cela évite les erreurs liées à la maintenance manuelle et offre une validation et une analyse automatiques.
Python