Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Saída estruturada

Faça o modelo retornar válido JSON, e use JSON Schema para restringir a estrutura de saída precisamente

Quando se realiza extração de informações ou geração de dados estruturada, um modelo pode retornar texto extra (como um ` ```Que quebra a análise do rio. Ativar saída estruturada garante que o modelo devolva uma string JSON válida. O modo de esquema JSON vai mais longe e dá-lhe controle preciso sobre a estrutura de saída e tipos, eliminando validação extra ou tentativas de repetição.

Dois modos.

Ver a tabela estruturada nos quadros de referência desta página ↓

Strictamente segue o esquema # # Não

Modelos apoiados Qwen Modelos, Kimi, GLM, DeepSeek Só modelos selecionados | response_format Setting {"type": "json_object"} | {"type": "json_schema", "json_schema": {..., "strict": true}} | "Requisito de alerta" "Deve incluir "JSON" "Recomendado a descrever explicitamente" Use o caso, saída flexível do JSON, validação precisa do esquema.

** modo objeto JSON** garante que a saída é uma string JSON válida, mas não garante uma estrutura específica. Para usá-lo:

Preparar. response_format no corpo de pedido para {"type": "json_object"}.
Incluir a palavra "JSON" (insensível ao caso) na mensagem do sistema ou mensagem do usuário. Caso contrário, a API retorna: 'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.

** modo de esquema JSON** garante que a saída se conforme com uma estrutura especificada. Preparar. response_format para {"type": "json_schema", "json_schema": {..., "strict": true}}.

O modo de esquema JSON não requer a palavra-chave "JSON" na prompt.

Modelos apoiados.

JSON Objecto

Ver a lista completa de modelos

Qwen

** Modelos de geração de texto **

Qwen-Max: Qwen3.8-Max série, Qwen3.7-Max Série
**Qwen-Max(modo de não pensar): Qwen3.6-Max série, Qwen3.7-Max série, Qwen-Max Série
Qwen-Plus: Qwen3.7-Plus Série
**Qwen-Plus(modo de não pensar): Qwen3.6-Plus série, Qwen3.5-Plus série, Qwen-Plus Série
Qwen-Flash: Qwen3.8-Flash série, Qwen3.7-Flash Série
**Qwen-Flash(modo de não pensar): Qwen3.6-Flash série, Qwen3.5-Flash série, Qwen-Flash Série
Qwen-Coder: Qwen3-Coder Série
Qwen-Long: Qwen-Long Série
**Qwen3.8 Série de código aberto
Série de código aberto (modo não pensante): Qwen3.6 Série de código aberto, Qwen3.5 Série de código aberto, Qwen3 Série de código aberto
Série de código aberto: Qwen3.8 Série de código aberto (qwen3.8-2.4t-a95b), Qwen3-Coder Série de código aberto, Qwen2.5 Série de código aberto (excluindo modelos de matemática e codificador)

Modelos multimodais (modo não pensante)

Qwen-VL: Qwen3-VL-Plus Série
Qwen-Omni: Qwen3.8-Omni-Flash, Qwen3.5-Omni-Plus Série
Série de código aberto: Qwen3-VL Série de código aberto

Kimi

kimi-k3
qwen3.7-plus

GLM

glm-5.1
Modo não pensante: glm-5, qwen3.7-plus

DeepSeek

deepseek-v4.1-flash, deepseek-v4-pro-0813, deepseek-v4-pro, deepseek-v4-flash-0731

Modelos rotulados como "modo não pensante" aceitam response_format - Pronto para... {"type": "json_object"} no modo de pensar sem erro, mas saída estruturada pode não fazer efeito. Para obter de forma confiável JSON válido destes modelos no modo de pensar, veja o [FAQ] (#faq).

JSON Schema

Qwen3.8-Max série, Qwen3.8-Flash série, Qwen3.7-Max série, Qwen3.7-Plus série, e Qwen3.7-Flash Série. Mais modelos virão logo.

Começando.

Este exemplo extrai informações estruturadas de um perfil pessoal usando o modo objeto JSON.

O modo objeto JSON não garante nomes de chaves estáveis ou tipos de campo. Os resultados podem variar em diferentes prompts ou chamadas. Para fazer uma estrutura fixa, use o modo JSON Schema.

Antes de ligar, [obtenha uma chave API] (/api-reference/preparation/api-key) e [exportar como uma variável de ambiente] (/api-reference/preparation/export-api-key-env). Para ligar através do OpenAI SDK ou DashScope SDK, [instalar o SDK] (/api-reference/preparation/install-sdk- Primeiro.

OpenAI compatible

  ```python Python {16}
  from openai import OpenAI
  import os

  client = OpenAI(
    # If you have not configured the environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.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)
  ```

  ```javascript Node.js {15}
  import OpenAI from "openai";

  const openai = new OpenAI({
    // If you have not configured the environment variable, replace the next line with: apiKey: "sk-xxx"
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
  });

  const completion = await openai.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" }
  });
  const jsonString = completion.choices[0].message.content;
  console.log(jsonString);
  ```

  ```bash curl {10}
  curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"}
  }'
  ```



 Resposta SDK:

```json
{
  "name": "Alex Brown",
  "age": 34
}
```

Resposta completa.

  ```json
  {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "{\"name\":\"Alex Brown\",\"age\":34}"
        },
        "finish_reason": "stop",
        "index": 0,
        "logprobs": null
      }
    ],
    "object": "chat.completion",
    "usage": {
      "prompt_tokens": 207,
      "completion_tokens": 20,
      "total_tokens": 227,
      "prompt_tokens_details": {
        "cached_tokens": 0
      }
    },
    "created": 1756455080,
    "system_fingerprint": null,
    "model": "qwen3.8-max",
    "id": "chatcmpl-624b665b-fb93-99e7-9ebd-bb6d86d314d2"
  }
  ```

DashScope

  ```python Python {16}
  import os
  import dashscope

  dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'

  messages = [
    {"role": "system", "content": [{"text": "Extract the user's name and age, and return them in JSON format"}]},
    {"role": "user", "content": [{"text": "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 = dashscope.MultiModalConversation.call(
    # If you have not configured the environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen3.8-max",
    messages=messages,
    response_format={'type': 'json_object'},
  )
  json_string = response.output.choices[0].message.content[0]["text"]
  print(json_string)
  ```

  ```java Java {35}
  // The DashScope Java SDK version must be 2.21.4 or higher
  import java.util.Arrays;
  import java.util.Collections;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
  import com.alibaba.dashscope.common.MultiModalMessage;
  import com.alibaba.dashscope.common.ResponseFormat;
  import com.alibaba.dashscope.common.Role;
  import com.alibaba.dashscope.exception.ApiException;
  import com.alibaba.dashscope.exception.NoApiKeyException;
  import com.alibaba.dashscope.exception.UploadFileException;
  import com.alibaba.dashscope.utils.Constants;

  public class Main {
    static {
      Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
    }

    public static void simpleMultiModalConversationCall()
        throws ApiException, NoApiKeyException, UploadFileException {
      MultiModalConversation conv = new MultiModalConversation();
      MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
          .content(Arrays.asList(
              Collections.singletonMap("text", "Extract the user's name and age, and return them in JSON format"))).build();
      MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
          .content(Arrays.asList(
              Collections.singletonMap("text", "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"))).build();
      ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
      MultiModalConversationParam param = MultiModalConversationParam.builder()
          // If you have not configured the environment variable, replace the next line with: .apiKey("sk-xxx")
          .apiKey(System.getenv("DASHSCOPE_API_KEY"))
          .model("qwen3.8-max")
          .messages(Arrays.asList(systemMessage, userMessage))
          .responseFormat(jsonMode)
          .build();
      MultiModalConversationResult result = conv.call(param);
      System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
    }

    public static void main(String[] args) {
      try {
        simpleMultiModalConversationCall();
      } catch (ApiException | NoApiKeyException | UploadFileException e) {
        System.out.println(e.getMessage());
      }
    }
  }
  ```

  ```bash curl {19}
  curl -X POST https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "input": {
      "messages": [
        {
          "role": "system",
          "content": [{"text": "Extract the user'\''s name and age, and return them in JSON format"}]
        },
        {
          "role": "user",
          "content": [{"text": "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"}]
        }
      ]
    },
    "parameters": {
      "response_format": {"type": "json_object"}
    }
  }'
  ```



 Resposta:

```json
{
  "name": "Alex Brown",
  "age": 34
}
```

Extrair dados estruturados de imagens e vídeo

Modelos multimodais suportam saída estruturada para imagens e vídeo. Use o modo JSON para extrair dados estruturados de conteúdo visual, como valores de campo de recibos, locais de objetos em imagens ou eventos em vídeo.

O exemplo a seguir extrai os campos de ticket e fatura de um recibo digitalizado.

Para limites de imagens e arquivos de vídeo, veja [Compreensão de imagens e vídeos] (/developer-guides/multimodal/vision).

OpenAI compatible

  ```python Python {29}
  import os
  from openai import OpenAI

  client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.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)
  ```

  ```javascript Node.js {31}
  import OpenAI from "openai";

  const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
  });

  const response = await openai.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" }
  });
  console.log(response.choices[0].message.content);
  ```

  ```bash curl {19}
  curl --location 'https://maas.qwencloudapi.com/compatible-mode/v1/chat/completions' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "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"}
  }'
  ```

DashScope

  ```python Python {24}
  import os
  import dashscope

  dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'

  messages = [
    {
      "role": "system",
      "content": [{"text": "You are a helpful assistant."}],
    },
    {
      "role": "user",
      "content": [
        {"image": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"},
        {"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 = dashscope.MultiModalConversation.call(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen3-vl-plus',
    messages=messages,
    response_format={'type': 'json_object'},
  )
  json_string = response.output.choices[0].message.content[0]["text"]
  print(json_string)
  ```

  ```java Java {35}
  // The DashScope Java SDK version must be 2.21.4 or higher
  import java.util.Arrays;
  import java.util.Collections;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
  import com.alibaba.dashscope.common.MultiModalMessage;
  import com.alibaba.dashscope.common.ResponseFormat;
  import com.alibaba.dashscope.common.Role;
  import com.alibaba.dashscope.exception.ApiException;
  import com.alibaba.dashscope.exception.NoApiKeyException;
  import com.alibaba.dashscope.exception.UploadFileException;
  import com.alibaba.dashscope.utils.Constants;

  public class Main {
    static {
      Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
    }

    public static void simpleMultiModalConversationCall()
        throws ApiException, NoApiKeyException, UploadFileException {
      MultiModalConversation conv = new MultiModalConversation();
      MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
          .content(Arrays.asList(
              Collections.singletonMap("text", "You are a helpful assistant."))).build();
      MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
          .content(Arrays.asList(
              Collections.singletonMap("image", "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"),
              Collections.singletonMap("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"))).build();
      ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
      MultiModalConversationParam param = MultiModalConversationParam.builder()
          .apiKey(System.getenv("DASHSCOPE_API_KEY"))
          .model("qwen3-vl-plus")
          .messages(Arrays.asList(systemMessage, userMessage))
          .responseFormat(jsonMode)
          .build();
      MultiModalConversationResult result = conv.call(param);
      System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
    }

    public static void main(String[] args) {
      try {
        simpleMultiModalConversationCall();
      } catch (ApiException | NoApiKeyException | UploadFileException e) {
        System.out.println(e.getMessage());
      }
    }
  }
  ```

  ```bash curl {30}
  curl -X POST https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-vl-plus",
    "input": {
      "messages": [
        {
          "role": "system",
          "content": [
            {
              "text": "You are a helpful assistant."
            }
          ]
        },
        {
          "role": "user",
          "content": [
            {
              "image": "http://duguang-labelling.oss-cn-shanghai.aliyuncs.com/demo_ocr/receipt_zh_demo.jpg"
            },
            {
              "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"
            }
          ]
        }
      ]
    },
    "parameters": {
      "response_format": {
        "type": "json_object"
      }
    }
  }'
  ```

Resposta:

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

Otimizar as instruções.

Prompts ambíguos como "informação de retorno do usuário" levam a estruturas de saída imprevisíveis. Para resultados confiáveis, descreva o esquema esperado em seu alerta: especifique nomes de campos, tipos, status obrigatório vs. opcional, restrições de formato (como formato de data) e inclua exemplos.

O sistema de alerta abaixo faz tudo isso. Ele restringe tipos de campo, distingue os necessários dos campos opcionais, e usa quatro exemplos para mostrar que o hobby O campo é omitido quando não se mencionam passatempos.

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: {"info":{"name":"Alice","age":"25 years old","email":"alice@example.com"},"hobby":["singing"]}
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: {"info":{"name":"Bob","age":"30 years old","email":"bob@example.com"},"hobby":["dancing","swimming"]}
Example 3 (without hobby):
Q: My name is Dave, I'm 28 years old, and my email is dave@example.com
A: {"info":{"name":"Dave","age":"28 years old","email":"dave@example.com"}}
Example 4 (without hobby):
Q: I'm Sun Qi, 35 years old, and my email is sunqi@example.com
A: {"info":{"name":"Sun Qi","age":"35 years old","email":"sunqi@example.com"}}

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.

Passe como a mensagem do sistema:

OpenAI compatible

  ```python Python {17}
  from openai import OpenAI
  import os

  client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
  )

  system_prompt = """..."""  # Replace with the system prompt above

  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"},
  )
  print(completion.choices[0].message.content)
  ```

  ```javascript Node.js {16}
  import OpenAI from "openai";

  const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
  });

  const systemPrompt = `...`;  // Replace with the system prompt above

  const completion = await openai.chat.completions.create({
    model: "qwen3.8-max",
    messages: [
      { role: "system", content: systemPrompt },
      { 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" }
  });
  console.log(completion.choices[0].message.content);
  ```

DashScope

  ```python Python {17}
  import os
  import dashscope

  dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'

  system_prompt = """..."""  # Replace with the system prompt above

  messages = [
    {"role": "system", "content": [{"text": system_prompt}]},
    {"role": "user", "content": [{"text": "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 = dashscope.MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen3.8-max",
    messages=messages,
    response_format={"type": "json_object"},
  )
  print(response.output.choices[0].message.content[0]["text"])
  ```

  ```java Java {35}
  // The DashScope Java SDK version must be 2.21.4 or higher
  import java.util.Arrays;
  import java.util.Collections;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
  import com.alibaba.dashscope.common.MultiModalMessage;
  import com.alibaba.dashscope.common.ResponseFormat;
  import com.alibaba.dashscope.common.Role;
  import com.alibaba.dashscope.exception.ApiException;
  import com.alibaba.dashscope.exception.NoApiKeyException;
  import com.alibaba.dashscope.exception.UploadFileException;
  import com.alibaba.dashscope.utils.Constants;

  public class Main {
    // Replace with the system prompt above
    private static final String SYSTEM_PROMPT = "...";

    static {
      Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
    }

    public static void main(String[] args) {
      try {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage systemMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
            .content(Arrays.asList(Collections.singletonMap("text", SYSTEM_PROMPT))).build();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
            .content(Arrays.asList(Collections.singletonMap("text", "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"))).build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model("qwen3.8-max")
            .messages(Arrays.asList(systemMessage, userMessage))
            .responseFormat(jsonMode)
            .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
      } catch (ApiException | NoApiKeyException | UploadFileException e) {
        System.out.println(e.getMessage());
      }
    }
  }
  ```

Resposta:

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

Restrinja a saída precisamente com o esquema JSON.

O modo objeto JSON só garante que a saída é válida JSON - nomes de campos, tipos e ninhos ainda podem ser diferentes do que você espera. Para análise automatizada, interoperabilidade API, e outros casos que precisam de restrições de tipo estritas, definir type para json_schema. O modelo segue o esquema exatamente.

O response_format A estrutura é assim:

Entradas multimodais (imagem, vídeo, áudio, etc.) não suportam json_schema E automaticamente vai voltar para json_object; as restrições do esquema não farão efeito.

{
  "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
      "required": [...],         // List of required fields
      "additionalProperties": false  // Recommended: only output defined fields
    }
  }
}

{
  "type": "json_schema",
  "json_schema": {
    "name": "user_info",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "User name"
        },
        "age": {
          "type": "integer",
          "description": "User age"
        },
        "email": {
          "type": "string",
          "description": "Email address"
        }
      },
      "required": ["name", "age"],
      "additionalProperties": false
    }
  }
}

Este exemplo força o modelo a produzir um objeto JSON com os campos necessários. name e age, mais o campo opcional email.

Como usar

O OpenAI SDK's parse O método aceita uma classe Pydantic Python ou um objeto Zod Node.js diretamente e converte-o em um esquema JSON para você, então você nunca escreve o esquema à mão. Com o SDK DashScope, construa o esquema JSON manualmente usando o formato acima.

OpenAI compatible

  ```python Python {14,20}
  from pydantic import BaseModel, Field
  from openai import OpenAI
  import os

  client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.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,          # <-- pass the Pydantic class directly
  )
  result = completion.choices[0].message.parsed
  print(f"Name: {result.name}, Age: {result.age}")
  ```

  ```javascript Node.js {15,21}
  import OpenAI from "openai";
  import { zodResponseFormat } from "openai/helpers/zod";
  import { z } from "zod";

  const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.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"),  // <-- pass the Zod object directly
  });
  const userInfo = completion.choices[0].message.parsed;
  console.log(`Name: ${userInfo.name}`);
  console.log(`Age: ${userInfo.age}`);
  ```

DashScope

  O modo Esquema JSON ainda não é suportado pelo Java SDK DashScope.



```python Python {18}
import os
import json
import dashscope

dashscope.base_http_api_url = "https://maas.qwencloudapi.com/api/v1"

messages = [
  {
    "role": "user",
    "content": [{"text": "My name is Liu Wu, I'm 25 years old."}],
  },
]

response = dashscope.MultiModalConversation.call(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen3.8-max",
  messages=messages,
  response_format={
    "type": "json_schema",
    "json_schema": {
      "name": "user_info",
      "strict": True,
      "schema": {
        "type": "object",
        "title": "UserInfo",
        "properties": {
          "name": {"title": "Name", "type": "string"},
          "age": {"title": "Age", "type": "integer"},
        },
        "required": ["name", "age"],
      },
    },
  },
)
json_object = json.loads(response.output.choices[0].message.content[0]["text"])
print(f"Name: {json_object['name']}, Age: {json_object['age']}")
```

Resposta:

Name: Liu Wu, Age: 25

Guia de configuração

Declaring required fields

 Listar campos obrigatórios no `required` Arranjo e deixo campos opcionais fora:

```json
{
  "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 omite o campo.

Implementing optional fields

 Além de deixar um campo fora de `required` Você pode permitir que `null`  Tipo:

```json
{
  "properties": {
    "name": {"type": "string"},
    "email": {"type": ["string", "null"]}  // Can be string or null
  },
  "required": ["name", "email"]  // Both in required
}
```

A saída então sempre inclui o `email`  campo, mas seu valor pode ser `null`.

additionalProperties configuration

Controla se o modelo pode produzir campos não definidos no esquema:

```json
{
  "properties": {"name": {"type": "string"}},
  "required": ["name"],
  "additionalProperties": true  // Allow extra fields
}
```

Para a entrada "Eu sou Zhang San, 25 anos", a saída é `{"name": "Zhang San", "age": 25}` - incluindo o indefinido `age` Campo.

Valor * Comportamento * Use o caso * | ------- | -------------------------- | ------------------------- | | false Apenas campos definidos de saída, controle preciso da estrutura. | true Deixe campos extras Capture mais informações

Tipos de dados suportados.

`string`, `number`, `integer`, `boolean`, `object`, `array`, `enum`.

Indo ao vivo

? Validar antes de passar rio abaixo ?

No modo objeto JSON, a saída é garantida como válida, mas não para combinar com seu esquema de negócios. Validar com uma biblioteca como jsonschema (Python), Ajv (JavaScript), ou Everit (Java) antes de entregá-lo a serviços a jusante, então campos ou erros de tipo ausentes não causam falhas de análise, perda de dados ou lógica de negócios quebrada. Quando falhar, tente novamente o pedido ou tenha um modelo reescrever a saída.

Não definam os números

Saia. max_tokens Desativar quando a saída estruturada está ativada. Este parâmetro cobre o número de tokens de saída (o padrão é o máximo do modelo) e pode truncar a cadeia JSON no meio da saída, produzindo JSON inválido.

Use o SDK para gerar esquemas

Deixe o SDK gerar o esquema. Isso evita erros de esquemas manuseados à mão e dá a você validação automática mais um resultado seguro.

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

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.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}")

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

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
});

const UserInfo = z.object({
  name: z.string().describe("User name"),
  age: z.number().int().describe("User age"),
  email: z.string().optional().nullable()   // Optional field
});

const completion = await 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: zodResponseFormat(UserInfo, "user_info")
});
console.log(completion.choices[0].message.parsed);

FAQ

Como eu consigo uma saída estruturada de um modelo chamado "modo não pensante" quando o pensamento é ativado?

Modelos rotulados como "modo não pensante" em [Modelos suportados] (#supported-models Pode devolver conteúdo que não é estritamente válido JSON quando [modo de pensamento] (/developer-guides/text-generation/thinking- Está ligado. Use uma abordagem de dois passos: primeiro ligue para o modelo de pensamento para obter uma saída de alta qualidade, e então passe qualquer JSON malformado através de um modelo que suporta o modo objeto JSON para corrigi-lo.

Passo 1: Obtenha a saída do modo de pensar

Setting `response_format` para `{"type": "json_object"}` com o modo de pensar ativado não causa um erro. O exemplo abaixo é um recuo que intencionalmente omite `response_format`; use-o apenas para demonstrar o reparo de duas etapas quando a saída de um modelo não é válida JSON.

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 response_format (setting it directly does not cause an error)
  extra_body={"enable_thinking": True},
  # Streaming output is required in thinking mode
  stream=True,
)
# Accumulate 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

Passo 2: Valide e conserte a saída

Tente analisar o json_string do passo anterior. Se for válido, use-o diretamente. Se não, chame um modelo que suporte saída estruturada para repará-lo - escolher um modelo rápido, de baixo custo, como qwen-flash em modo não pensante.

import json
from openai import OpenAI
import os

# 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://maas.qwencloudapi.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",
    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 uma chamada falhar e retornar uma mensagem de erro, veja [Mensagens de erro] (/api-reference/preparation/error-messages) para resolução.

Quadros de referência

Tabelas restauradas a partir da referência original; a ordem das colunas e os valores técnicos foram preservados.

Quadro 1

Característica	Modo Objeto JSON	JSON Modo Esquema
Saídas válidas JSON	Sim	Sim
Apenas segue o esquema.	Não	Sim
Modelos apoiados.	A maioria Qwen Modelos, Kimi, GLM, DeepSeek	Apenas modelos selecionados.
`response_format` ajuste	`{"type": "json_object"}`	`{"type": "json_schema", "json_schema": {..., "strict": true}}`
Exigência imediata.	Deve incluir "JSON"	Recomendado para descrever explicitamente
Use o caso.	Saída flexível do JSON	Validação precisa do esquema.

Quadro 2

Valor	Comportamento	Use o caso.
`false`	Apenas campos definidos de saída	Controle preciso da estrutura
`true`	Permita campos extras.	Capture mais informações.