Skip to main content
Geração de texto

Saída estruturada

Ao executar tarefas de extração de informações ou geração de dados estruturados, um modelo pode retornar texto extra (como json ) que interrompe a análise posterior. Ativar a saída estruturada garante que o modelo retorne uma string JSON válida. O modo JSON Schema também oferece controle preciso sobre a estrutura e os tipos da saída, eliminando a necessidade de validações extras ou novas tentativas.

Uso

A saída estruturada suporta dois modos: JSON Object e JSON Schema.
  • Modo JSON Object: Garante que a saída seja uma string JSON válida, mas não assegura uma estrutura específica. Uso:
    1. Defina o parâmetroresponse_format: No corpo da solicitação, defina response_format como {"type": "json_object"}.
    2. Inclua a palavra-chave JSON no prompt: A mensagem do sistema ou do usuário deve conter a palavra "JSON" (sem distinção entre maiúsculas e minúsculas). Caso contrário, a API retorna: 'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.
  • Modo JSON Schema: Assegura que a saída esteja em conformidade com uma estrutura especificada. Uso: defina response_format como {"type": "json_schema", "json_schema": {..., "strict": true}}.
    Não é necessária a palavra-chave JSON no prompt.
Comparação de recursos:

Recurso

Modo JSON Object

Modo JSON Schema

Gera JSON válido

Sim

Sim

Segue estritamente o schema

Não

Sim

Modelos suportados

Maioria dos modelos Qwen

Apenas modelos qwen-plus selecionados

Configuração de response_format

{"type": "json_object"}

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

Requisito do prompt

Deve incluir "JSON"

Recomenda-se descrever explicitamente

Caso de uso

Saída JSON flexível

Validação precisa de schema

Modelos suportados

  • JSON Object
  • JSON Schema
  • Qwen
  • Kimi
  • DeepSeek
  • GLM
  • Stepfun
  • Modelos de geração de texto
    • Qwen-Max: séries Qwen3.8-Max, Qwen3.7-Max
    • Qwen-Max (modo sem raciocínio): séries Qwen3.6-Max, Qwen3-Max, Qwen-Max
    • Qwen-Plus: série Qwen3.7-Plus
    • Qwen-Plus (modo sem raciocínio): séries Qwen3.6-Plus, Qwen3.5-Plus, Qwen-Plus
    • Qwen-Flash: séries Qwen3.8-Flash, Qwen3.7-Flash
    • Qwen-Flash (modo sem raciocínio): séries Qwen3.6-Flash, Qwen3.5-Flash, Qwen-Flash
    • Qwen-Turbo (modo sem raciocínio): 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 (modo sem raciocínio)
    • Série open-source Qwen3.5 (modo sem raciocínio)
    • Série open-source Qwen3 (modo sem raciocínio)
    • Série open-source Qwen3-Coder
    • Série open-source Qwen2.5 (excluindo modelos math e coder)
  • Modelos multimodais
    • Qwen-VL (modo sem raciocínio): séries Qwen3-VL-Plus, Qwen3-VL-Flash, Qwen-VL-Max (excluindo as versões mais recentes e snapshot), Qwen-VL-Plus (excluindo as versões mais recentes e snapshot)
    • Qwen-Omni: série Qwen3.5-Omni-Plus
    • Série open-source Qwen3-VL (modo sem raciocínio)
Os modelos rotulados como "modo sem raciocínio" também aceitam response_format definido como {"type": "json_object"} no modo de raciocínio sem erro, mas alguns podem retornar conteúdo que não é estritamente um JSON válido; se você precisar de um JSON consistentemente válido, consulte o FAQ.
  • Qwen
  • Kimi
  • GLM
  • DeepSeek
  • Modelos de geração de texto
    • Qwen-Max: séries Qwen3.8-Max, Qwen3.7-Max
    • Qwen-Max (modo sem raciocínio): séries Qwen3.6-Max, Qwen3-Max, Qwen-Max
    • Qwen-Plus: série Qwen3.7-Plus
    • Qwen-Plus (modo sem raciocínio): séries Qwen3.6-Plus, Qwen3.5-Plus, Qwen-Plus
    • Qwen-Flash: séries Qwen3.8-Flash, Qwen3.7-Flash
    • Qwen-Flash (modo sem raciocínio): séries Qwen3.6-Flash, Qwen3.5-Flash, Qwen-Flash
    • Qwen-Turbo (modo sem raciocínio): 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 (modo sem raciocínio)
    • Série open-source Qwen3.5 (modo sem raciocínio)
    • Série open-source Qwen3 (modo sem raciocínio)
    • Série open-source Qwen3-Coder
    • Série open-source Qwen2.5 (excluindo modelos math e coder)
  • Modelos multimodais
    • Qwen-VL (modo sem raciocínio): séries Qwen3-VL-Plus, Qwen3-VL-Flash, Qwen-VL-Max (excluindo as versões mais recentes e snapshot), Qwen-VL-Plus (excluindo as versões mais recentes e snapshot)
    • Qwen-Omni: série Qwen3.5-Omni-Plus
    • Série open-source Qwen3-VL (modo sem raciocínio)
Os modelos rotulados como "modo sem raciocínio" também aceitam response_format definido como {"type": "json_object"} no modo de raciocínio sem erro, mas alguns podem retornar conteúdo que não é estritamente um JSON válido; se você precisar de um JSON consistentemente válido, consulte o FAQ.

Primeiros passos

Este exemplo extrai informações estruturadas de um perfil pessoal.
O modo JSON Object não garante nomes de chaves ou tipos de campos estáveis. Os resultados podem variar entre diferentes prompts ou chamadas. Para impor uma estrutura fixa, use o modo JSON Schema.
Obtain an API key e export the API key as an environment variable. Se você usar o OpenAI SDK ou DashScope SDK para fazer chamadas, install the SDK.
  • OpenAI compatible
  • 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 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.8-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)

Resposta 

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

Processamento de dados de imagem e vídeo

Modelos multimodais também suportam saída estruturada para imagens e vídeos. Use o modo JSON para extrair dados estruturados de conteúdo visual, como valores de campos de recibos, localizações de objetos em imagens ou eventos em vídeo.
Para limites de arquivos de imagem e vídeo, consulte Image and video understanding .
  • 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)

Resposta 

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

Otimize os prompts

Prompts ambíguos como "retornar informações do usuário" levam a estruturas de saída imprevisíveis. Para obter resultados confiáveis, descreva o schema esperado no seu prompt: especifique nomes de campos, tipos, status obrigatório versus opcional, restrições de formato (como formato de data) e inclua exemplos.
  • OpenAI compatible
  • 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 Beijing region base_url. 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}.cn-beijing.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="qwen3.8-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)

Resposta 

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

Obtendo saída estruturada

Definir o type de response_format como json_object retorna uma string JSON válida, mas a estrutura pode não corresponder às suas expectativas — adequado para cenários simples. Para análise automatizada, interoperabilidade de API e outros cenários complexos que exigem restrições rigorosas de tipo, defina type como json_schema para forçar o modelo a gerar conteúdo estritamente em conformidade com um formato especificado. Formato e exemplo de 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
    }
  }
}
O exemplo acima força o modelo a gerar um objeto JSON com dois campos obrigatórios (name e age) e um campo opcional email.
Modelos da região Singapore ainda não são suportados.

Como usar

Com o método parse do OpenAI SDK, você pode passar diretamente uma classe Pydantic do Python ou um objeto Zod do Node.js. O SDK converte automaticamente para um JSON Schema — sem necessidade de escrever JSON complexo manualmente. Para o DashScope SDK, construa o JSON Schema manualmente seguindo o formato acima.
  • OpenAI compatible
  • 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 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 in years")

completion = client.chat.completions.parse(
    model="qwen3.8-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 Singapore 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: "qwen3.8-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}`);
Executar o código produz a seguinte saída:
Name: Liu Wu, Age: 25

Guia de configuração

Siga estas diretrizes ao usar JSON Schema para obter uma saída estruturada mais confiável:
  • Declaração de campo obrigatório Recomenda-se listar os campos obrigatórios no array required. Campos opcionais podem ser omitidos, por exemplo: 
{
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"},
    "email": {"type": "string"}
  },
  "required": ["name", "age"]
}
Se a entrada não fornecer informações de e-mail, a saída não conterá este campo.
  • Implementando campos opcionais Além de omitir do required, você também pode permitir o tipo null: 
{
  "properties": {
    "name": {"type": "string"},
    "email": {"type": ["string", "null"]}  // Can be string or null
  },
  "required": ["name", "email"]  // Both in required
}
A saída sempre incluirá o campo email, mas seu valor pode ser null.
  • Configuração de additionalProperties Controla se deve permitir campos extras não definidos no schema: 
{
  "properties": {"name": {"type": "string"}},
  "required": ["name"],
  "additionalProperties": true  // Allow extra fields
}
Exemplo de entrada: "I'm Zhang San, 25 years old"; saída: {"name": "Zhang San", "age": 25} (inclui o campo age não definido).

Valor

Comportamento

Caso de uso

false

Gera apenas campos definidos

Controle preciso da estrutura

true

Permite campos extras

Capturar mais informações

  • Tipos de dados suportados: string, number, integer, boolean, object, array, enum.

Indo para produção

  • Valide antes de passar para serviços downstream Ao usar o modo JSON Object, valide a saída antes de passá-la para serviços downstream. Use uma biblioteca como jsonschema (Python), Ajv (JavaScript) ou Everit (Java) para garantir que ela esteja em conformidade com o JSON Schema esperado, evitando falhas de análise downstream, perda de dados ou interrupções na lógica de negócios devido a campos ausentes, erros de tipo ou formatos malformados. Em caso de falha, tente novamente a solicitação ou use um modelo para reescrever a saída.
  • Não defina max_tokens Não defina max_tokens quando a saída estruturada estiver ativada. Este parâmetro limita o número de tokens de saída e tem como padrão o máximo do modelo. Defini-lo pode truncar a string JSON no meio da geração, produzindo um JSON inválido que falha na análise.
  • Use o SDK para gerar schemas Utilize o SDK para gerar schemas automaticamente. Isso evita erros de manutenção manual e fornece validação e análise automáticas.
    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="qwen3.8-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}")

FAQ

P: Como o modelo de modo de raciocínio do Qwen produz saída estruturada?

Modelos rotulados como "modo sem raciocínio" retornam conteúdo que não é uma string JSON estritamente válida no modo de raciocínio. Você pode usar a seguinte abordagem de duas etapas para corrigir isso: primeiro chame o modelo de raciocínio para obter uma saída de alta qualidade e, em seguida, passe qualquer JSON malformado por um modelo que suporte o modo JSON para corrigi-lo.
  1. Obtenha a saída do modelo de modo de raciocínio Chame o modelo de modo de raciocínio. O resultado pode não ser um JSON válido.
    Nota: definir o parâmetro response_format como {"type": "json_object"} quando o modo de raciocínio está ativado não causa erro. O exemplo abaixo é um fallback que omite intencionalmente response_format ; use-o apenas para corrigir casos em que a saída de um modelo não é um JSON válido. 
completion = client.chat.completions.create(
    model="qwen3.8-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",
        },
    ],
    # Enable thinking mode; this fallback example omits the response_format parameter (setting it directly does not cause an error)
    extra_body={"enable_thinking": True},
    # Streaming output is required in thinking mode
    stream=True
)
# Extract and print the model-generated JSON result
json_string = ""
for chunk in completion:
    if not chunk.choices:
        continue
    if chunk.choices[0].delta.content is not None:
        json_string += chunk.choices[0].delta.content
  1. Valide e corrija a saída Tente analisar a json_string da etapa anterior:
    • Se o modelo retornou um JSON válido, analise-o e use-o diretamente.
    • Se o modelo retornou um JSON inválido, chame um modelo que suporte saída estruturada (um modelo rápido e de baixo custo, como qwen-flash no modo sem raciocínio, funciona bem) para corrigir o formato.
import json
from openai import OpenAI
import os

# Initialize the OpenAI client (if the client variable isn't defined in the previous code block, uncomment the lines below)
# client = OpenAI(
#     api_key=os.getenv("DASHSCOPE_API_KEY"),
#     base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
# )

try:
    json_object_from_thinking_model = json.loads(json_string)
    print("Generated standard JSON string")
except json.JSONDecodeError:
    print("Did not generate standard JSON string; fixing with a model that supports structured output")
    completion = client.chat.completions.create(
        model="qwen-flash",
        # Use non-thinking mode
        extra_body={"enable_thinking": False},
        messages=[
            {
                "role": "system",
                "content": "You are a JSON format expert. Fix the user's JSON string to standard format",
            },
            {
                "role": "user",
                "content": json_string,
            },
        ],
        response_format={"type": "json_object"},
    )
    json_object_from_thinking_model = json.loads(completion.choices[0].message.content)

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Error codes para resolução.
Começar
Faturamento
Plano de Tokens
Playground de Modelos
Clientes e Ferramentas de Desenvolvedor
Inferência do Modelo
Ajuste fino
Implantação
Avaliação
Compressão de Modelos
Estatísticas e Monitoramento
Segurança e Conformidade
Melhores Práticas
Suporte
Registro de alterações