Skip to main content

Structured output

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 :
    1. Définissez le paramètreresponse_format: Dans le corps de la requête, définissez response_format sur {"type": "json_object"}.
    2. 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'.
  • Mode JSON Schema : Garantit que la sortie est conforme à une structure spécifiée. Utilisation : définissez response_format sur {"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

response_format setting

{"type": "json_object"}

{"type": "json_schema", "json_schema": {...}, "strict": true}

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

Les modèles étiquetés « mode sans réflexion » ne prennent en charge la sortie structurée qu'en mode sans réflexion.
  • 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
from openai import OpenAI
import os

client = OpenAI(
    # API keys differ by region. If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # If you use Singapore region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "system",
            "content": "Extract the user's name and age, and return them in JSON format"
        },
        {
            "role": "user",
            "content": "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling",
        },
    ],
    response_format={"type": "json_object"}
)

json_string = completion.choices[0].message.content
print(json_string)

Réponse

{
  "Name": "Alex Brown",
  "Age": 34
}

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
import os
from openai import OpenAI

client = OpenAI(
    # API keys differ by region. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # For Beijing region models, replace base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."}],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"
                    },
                },
                {"type": "text", "text": "Extract ticket (array type, including travel_date, trains, seat_num, arrival_site, price) and invoice information (array type, including invoice_code and invoice_number) from the image. Output a JSON containing both ticket and invoice arrays"},
            ],
        },
    ],
    response_format={"type": "json_object"}
)
json_string = completion.choices[0].message.content
print(json_string)

Réponse

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "stream",
      "seat_num": "371",
      "arrival_site": "Development Zone",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

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
from openai import OpenAI
import os
import json
import textwrap  # Handles indentation for multi-line strings to improve code readability

# Predefined example responses to show the model the expected output format
# Example 1: Complete response with all fields
example1_response = json.dumps(
    {
        "info": {"name": "Alice", "age": "25 years old", "email": "alice@example.com"},
        "hobby": ["singing"]
    },
    ensure_ascii=False
)
# Example 2: Response with multiple hobbies
example2_response = json.dumps(
    {
        "info": {"name": "Bob", "age": "30 years old", "email": "bob@example.com"},
        "hobby": ["dancing", "swimming"]
    },
    ensure_ascii=False
)
# Example 3: Response without hobby field (hobby is optional)
example3_response = json.dumps(
    {
        "info": {"name": "Dave", "age": "28 years old", "email": "dave@example.com"}
    },
    ensure_ascii=False
)
# Example 4: Another response without hobby field
example4_response = json.dumps(
    {
        "info": {"name": "Sun Qi", "age": "35 years old", "email": "sunqi@example.com"}
    },
    ensure_ascii=False
)

# Initialize the OpenAI client
client = OpenAI(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    # API keys differ by region. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This is the Singapore region base_url. If you use Chine (Pékin) region models, replace base_url with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# dedent removes common leading whitespace from each line, allowing the string to be indented nicely in code without including extra spaces at runtime
system_prompt = textwrap.dedent(f"""\
    Extract personal information from the user input and output it in the specified JSON Schema format:

    [Output format requirements]
    The output must strictly follow this JSON structure:
    {{
      "info": {{
        "name": "string type, required field, user's name",
        "age": "string type, required field, format 'number years old', e.g., '25 years old'",
        "email": "string type, required field, standard email format, e.g., 'user@example.com'"
      }},
      "hobby": ["string array type, optional field, contains all user hobbies; omit entirely if not mentioned"]
    }}

    [Field extraction rules]
    1. name: Identify the user's name from the text, must extract
    2. age: Identify age information, convert to 'number years old' format, must extract
    3. email: Identify email address, keep original format, must extract
    4. hobby: Identify user hobbies, output as string array; omit hobby field entirely if hobbies are not mentioned

    [Reference examples]
    Example 1 (with hobby):
    Q: My name is Alice, I'm 25 years old, my email is alice@example.com, and my hobby is singing
    A: {example1_response}

    Example 2 (with multiple hobbies):
    Q: My name is Bob, I'm 30 years old, my email is bob@example.com, and I enjoy dancing and swimming
    A: {example2_response}

    Example 3 (without hobby):
    Q: My name is Dave, I'm 28 years old, and my email is dave@example.com
    A: {example3_response}

    Example 4 (without hobby):
    Q: I'm Sun Qi, 35 years old, and my email is sunqi@example.com
    A: {example4_response}

    Extract information and output JSON strictly according to the above format and rules. Do not include the hobby field if the user doesn't mention hobbies.\
""")

# Call the model API for information extraction
completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "system",
            "content": system_prompt
        },
        {
            "role": "user",
            "content": "Hi everyone, my name is Alex Brown, I'm 34 years old, my email is alexbrown@example.com, and I enjoy playing basketball and traveling",
        },
    ],
    response_format={"type": "json_object"},  # Specify JSON format return
)

# Extract and print the model-generated JSON result
json_string = completion.choices[0].message.content
print(json_string)

Réponse

{
  "info": {
    "name": "Alex Brown",
    "age": "34 years old",
    "email": "alexbrown@example.com"
  },
  "hobby": ["Basketball", "Traveling"]
}

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 :
{
  "type": "json_schema",
  "json_schema": {
    "name": "schema_name",       // Name of the schema
    "strict": true,              // Recommended: strictly follow the format
    "schema": {
      "type": "object",
      "properties": {...},       // Define field structure (see example on right)
      "required": [...],         // List of required fields
      "additionalProperties": false  // Recommended: only output defined fields
    }
  }
}
L'exemple ci-dessus force le modèle à générer un objet JSON comportant deux champs obligatoires (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

from pydantic import BaseModel, Field
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Chine (Pékin) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

class UserInfo(BaseModel):
    name: str = Field(description="User name")
    age: int = Field(description="User age in years")

completion = client.chat.completions.parse(
    model="qwen4-max",
    messages=[
        {"role": "system", "content": "Extract name and age information."},
        {"role": "user", "content": "My name is Liu Wu, I'm 25 years old."},
    ],
    response_format=UserInfo,
)

result = completion.choices[0].message.parsed
print(f"Name: {result.name}, Age: {result.age}")

Node.js

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const openai = new OpenAI(
    {
        apiKey: process.env.DASHSCOPE_API_KEY,
        // The following URL is for the Chine (Pékin) region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    }
);

const UserInfo = z.object({
  name: z.string().describe("User name"),
  age: z.number().int().describe("User age in years"),
});

const completion = await openai.chat.completions.parse({
  model: "qwen4-max",
  messages: [
    { role: "system", content: "Extract name and age information." },
    { role: "user", content: "My name is Liu Wu, I'm 25 years old." },
  ],
  response_format: zodResponseFormat(UserInfo, "user_info"),
});

const userInfo = completion.choices[0].message.parsed;
console.log(`Name: ${userInfo.name}`);
console.log(`Age: ${userInfo.age}`);
L'exécution du code produit la sortie suivante :
Name: Liu Wu, Age: 25

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 :
    {
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "email": {"type": "string"}
      },
      "required": ["name", "age"]
    }
    
    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 type null :
    {
      "properties": {
        "name": {"type": "string"},
        "email": {"type": ["string", "null"]}  // Can be string or null
      },
      "required": ["name", "email"]  // Both in required
    }
    
    La sortie inclura toujours le champ email, mais sa valeur peut être null.
  • Configuration de additionalProperties Contrôle l'autorisation ou non de champs supplémentaires non définis dans le schéma :
    {
      "properties": {"name": {"type": "string"}},
      "required": ["name"],
      "additionalProperties": true  // Allow extra fields
    }
    
    Exemple d'entrée : "I'm Zhang San, 25 years old" ; sortie : {"name": "Zhang San", "age": 25} (inclut le champ age non défini).

    Valeur

    Comportement

    Cas d'utilisation

    false

    Sortie uniquement des champs définis

    Contrôle précis de la structure

    true

    Autorisation 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_tokens lorsque 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
    from pydantic import BaseModel, Field
    from typing import Optional
    from openai import OpenAI
    import os
    
    client = OpenAI(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # The following URL is for the Singapore region. Replace {WorkspaceId} with your actual Workspace ID. URLs vary by region.
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    )
    class UserInfo(BaseModel):
        name: str = Field(description="User name")
        age: int = Field(description="User age")
        email: Optional[str] = None  # Optional field
    
    completion = client.chat.completions.parse(
        model="qwen4-max",
        messages=[
            {"role": "system", "content": "Extract name and age information."},
            {"role": "user", "content": "My name is Liu Wu, I'm 25 years old."},
        ],
        response_format=UserInfo  # Pass the Pydantic model directly
    )
    
    result = completion.choices[0].message.parsed  # Type-safe parsed result
    print(f"Name: {result.name}, Age: {result.age}")
    

Codes d'erreur

Si l'appel au modèle échoue et renvoie un message d'erreur, consultez la rubrique Codes d'erreur pour résoudre le problème.