如何让通义千问生成JSON字符串 - 大模型服务平台百炼

执行信息抽取或结构化数据生成任务时，大模型可能返回多余文本（如 ```json）导致下游解析失败。开启结构化输出可确保大模型输出标准格式的 JSON 字符串，使用 JSON Schema 模式还能精确控制输出结构和类型，无需额外验证或重试。

使用方式

结构化输出支持JSON Object 与 JSON Schema两种模式：

JSON Object 模式：确保输出为标准格式的 JSON 字符串，但不保证符合特定结构。使用方式：
1. 设置response_format参数：在请求体中，将 response_format 参数设置为 {"type": "json_object"}。
2. 提示词包含 JSON 关键词：System Message 或 User Message 中需要包含 "JSON" 关键词（不区分大小写），否则会报错：'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.
JSON Schema 模式：确保输出内容为指定的结构。使用方式：设置 response_format 为{"type": "json_schema", "json_schema": {...}, "strict": true}。
提示词无需包含 JSON 关键词。

功能对比：

特性	JSON Object 模式	JSON Schema 模式
输出有效 JSON	是	是
严格遵循 Schema	否	是
支持模型	Qwen 大部分模型	仅支持 qwen-plus 系列部分模型
`response_format` 参数设置	`{"type": "json_object"}`	`{"type": "json_schema", "json_schema": {...}, "strict": true}`
提示词要求	必须包含 "JSON"	建议明确说明
适用场景	灵活的 JSON 输出	精确的结构验证

支持的模型

JSON Object

文本生成模型
- 通义千问Max 系列：qwen3-max、qwen3-max-2025-09-23、qwen3-max-preview（非思考模式）、qwen-max、qwen-max-latest、qwen-max-2025-01-25 及之后的快照模型
- 通义千问Plus 系列（非思考模式）：qwen-plus、qwen-plus-latest、qwen-plus-2025-01-25及之后的快照模型
- 通义千问Flash 系列（非思考模式）：qwen-flash、qwen-flash-2025-07-28及之后的快照模型
- 通义千问Turbo 系列（非思考模式）：qwen-turbo、qwen-turbo-latest、qwen-turbo-2024-11-01及之后的快照模型
- 通义千问Coder 系列：qwen3-coder-plus、qwen3-coder-plus-2025-07-22、qwen3-coder-flash、qwen3-coder-flash-2025-07-28
- 通义千问Long 系列：qwen-long-latest、qwen-long-2025-01-25
文本生成开源模型
- Qwen3（非思考模式）
- Qwen3-Coder
- Qwen2.5 系列的文本模型（不含math与coder模型）
多模态模型
- 通义千问3-VL-Plus 系列（非思考模式）：qwen3-vl-plus、qwen3-vl-plus-2025-09-23及之后的快照模型
- 通义千问3-VL-Flash 系列（非思考模式）：qwen3-vl-flash、qwen3-vl-flash-2025-10-15及之后的快照模型
- 通义千问VL-Max 系列：qwen-vl-max（不包括最新版与快照版模型）
- 通义千问VL-Plus 系列：qwen-vl-plus（不包括最新版与快照版模型）
多模态开源模型
- Qwen3-VL（非思考模式）

说明

思考模式的模型暂不支持结构化输出功能。

JSON Schema

北京地域的 qwen-plus、qwen-plus-latest、qwen-plus-2025-07-28 及之后更新的快照模型。

更多模型逐步支持中。

模型的上下文、价格、快照版本等信息请参见模型列表。

快速开始

以从个人简介中抽取信息的简单场景为例，介绍快速使用结构化输出的方法。

您需要已获取与配置 API Key并配置API Key到环境变量。如果通过OpenAI SDK或DashScope SDK进行调用，还需要安装SDK。

OpenAI兼容

Python

from openai import OpenAI
import os

client = OpenAI(
    # 新加坡和北京地域的API Key不同；如果没有配置环境变量，请用API Key将下行替换为：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为新加坡地域base_url，北京地域base_url：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen-flash",
    messages=[
        {
            "role": "system",
            "content": "请抽取用户的姓名与年龄信息，以JSON格式返回"
        },
        {
            "role": "user",
            "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游", 
        },
    ],
    response_format={"type": "json_object"}
)

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

返回结果

{
  "姓名": "刘五",
  "年龄": 34
}

Node.js

import OpenAI from "openai";

const openai = new OpenAI({
    // 如果没有配置环境变量，请用API Key将下行替换为：apiKey: "sk-xxx"
    apiKey: process.env.DASHSCOPE_API_KEY,
    // 以下为新加坡地域baseURL，使用北京地域的模型请将baseURL替换为：https://dashscope.aliyuncs.com/compatible-mode/v1
    baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

const completion = await openai.chat.completions.create({
    model: "qwen-flash",
    messages: [
        {
            role: "system",
            content: "请抽取用户的姓名与年龄信息，以JSON格式返回"
        },
        {
            role: "user",
            content: "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游"
        }
    ],
    response_format: {
        type: "json_object"
    }
});

const jsonString = completion.choices[0].message.content;
console.log(jsonString);

返回结果

{
  "姓名": "刘五",
  "年龄": 34
}

curl

# ======= 重要提示 =======
# 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
# === 执行时请删除该注释 ===
curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "你需要提取出name（名字，为string类型）、age（年龄，为string类型）与email（邮箱，为string类型），请输出JSON 字符串，不要输出其它无关内容。\n示例：\nQ：我叫张三，今年25岁，邮箱是zhangsan@example.com\nA：{\"name\":\"张三\",\"age\":\"25岁\",\"email\":\"zhangsan@example.com\"}\nQ：我叫李四，今年30岁，我的邮箱是lisi@example.com\nA：{\"name\":\"李四\",\"age\":\"30岁\",\"email\":\"lisi@example.com\"}\nQ：我叫王五，我的邮箱是wangwu@example.com，今年40岁\nA：{\"name\":\"王五\",\"age\":\"40岁\",\"email\":\"wangwu@example.com\"}"
        },
        {
            "role": "user", 
            "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com"
        }
    ],
    "response_format": {
        "type": "json_object"
    }
}'

返回结果

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "{\"name\":\"刘五\",\"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": "qwen-plus",
    "id": "chatcmpl-624b665b-fb93-99e7-9ebd-bb6d86d314d2"
}

DashScope

Python

import os
import dashscope
# 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

messages=[
    {
        "role": "system",
        "content": "请抽取用户的姓名与年龄信息，以JSON格式返回"
    },
    {
        "role": "user",
        "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游", 
    },
]
response = dashscope.Generation.call(
    # 如果使用华北2（北京）地域的模型，需要使用华北2（北京）地域的 API Key，获取链接：https://bailian.console.alibabacloud.com/?tab=model#/api-key
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-flash", 
    messages=messages,
    result_format='message',
    response_format={'type': 'json_object'}
    )
json_string = response.output.choices[0].message.content
print(json_string)

返回结果

{
  "姓名": "刘五",
  "年龄": 34
}

Java

DashScope Java SDK 版本需要不低于 2.18.4。

// DashScope Java SDK 版本需要不低于 2.18.4

import java.util.Arrays;
import java.lang.System;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.protocol.Protocol;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/api/v1
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("请抽取用户的姓名与年龄信息，以JSON格式返回")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游")
                .build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        GenerationParam param = GenerationParam.builder()
                // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-flash")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .responseFormat(jsonMode)
                .build();
        return gen.call(param);
    }

    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 使用日志框架记录异常信息
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
    }
}

返回结果

{
  "姓名": "刘五",
  "年龄": 34
}

curl

# ======= 重要提示 =======
# 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
# === 执行时请删除该注释 ===

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-flash",
    "input": {
        "messages": [
            {
                "role": "system",
                "content": "请抽取用户的姓名与年龄信息，以JSON格式返回"
            },
            {
                "role": "user", 
                "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游"
            }
        ]
    },
    "parameters": {
        "result_format": "message",
        "response_format": {
            "type": "json_object"
        }
    }
}'

返回结果

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "{\n  \"姓名\": \"刘五\",\n  \"年龄\": 34\n}"
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 72,
        "output_tokens": 18,
        "input_tokens": 54,
        "cached_tokens": 0
    },
    "request_id": "xxx-xxx-xxx-xxx-xxx"
}

图片、视频数据处理

除了文本信息，多模态模型还支持针对图像、视频数据进行结构化输出，实现视觉信息抽取、定位、事件监测等功能。

图片、视频文件限制请参见视觉理解。

OpenAI兼容

Python

import os
from openai import OpenAI

client = OpenAI(
    # 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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": "提取图中ticket(包括 travel_date、trains、seat_num、arrival_site、price)和 invoice 的信息（包括 invoice_code 和 invoice_number ），请输出包含 ticket 和 invoice 数组的JSON"},
            ],
        },
    ],
    response_format={"type": "json_object"}
)
json_string = completion.choices[0].message.content
print(json_string)

返回结果

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "流水",
      "seat_num": "371",
      "arrival_site": "开发区",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

Node.js

import OpenAI from "openai";

const openai = new OpenAI({
  // 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
  // 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey: "sk-xxx"
  apiKey: process.env.DASHSCOPE_API_KEY,
  // 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为https://dashscope.aliyuncs.com/compatible-mode/v1
  baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

async function main() {
  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: "提取图中ticket(包括 travel_date、trains、seat_num、arrival_site、price)和 invoice 的信息（数组类型，包括 invoice_code 和 invoice_number ），请输出包含 ticket 和 invoice 数组的JSON"
          }
        ]
      }
    ],
    response_format: {type: "json_object"}
  });
  console.log(response.choices[0].message.content);
}

main()

返回结果

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "流水",
      "seat_num": "371",
      "arrival_site": "开发区",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

curl

# ======= 重要提示 =======
# 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
# 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === 执行时请删除该注释 ===

curl --location 'https://dashscope-intl.aliyuncs.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": "提取图中ticket(包括 travel_date、trains、seat_num、arrival_site、price)和 invoice 的信息（数组类型，包括 invoice_code 和 invoice_number ），请输出包含 ticket 和 invoice 数组的JSON"}
    ]
  }],
  "response_format":{"type": "json_object"}
}'

返回结果

{
  "choices": [{
    "message": {
      "content": "{\n  \"ticket\": [\n    {\n      \"travel_date\": \"2013-06-29\",\n      \"trains\": \"流水\",\n      \"seat_num\": \"371\",\n      \"arrival_site\": \"开发区\",\n      \"price\": \"8.00\"\n    }\n  ],\n  \"invoice\": [\n    {\n      \"invoice_code\": \"221021325353\",\n      \"invoice_number\": \"10283819\"\n    }\n  ]\n}",
      "role": "assistant"
    },
    "finish_reason": "stop",
    "index": 0,
    "logprobs": null
  }],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 486,
    "completion_tokens": 112,
    "total_tokens": 598,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "created": 1755767481,
  "system_fingerprint": null,
  "model": "qwen3-vl-plus",
  "id": "chatcmpl-33249829-e9f3-9cbc-93e4-0536b3d7d713"
}

DashScope

Python

import os
import dashscope

# 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.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": "提取图中ticket(包括 travel_date、trains、seat_num、arrival_site、price)和 invoice 的信息（数组类型，包括 invoice_code 和 invoice_number ），请输出包含 ticket 和 invoice 数组的JSON"}]
}]
response = dashscope.MultiModalConversation.call(
    #若没有配置环境变量， 请用百炼API Key将下行替换为： api_key ="sk-xxx"
    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)

返回结果

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "流水",
      "seat_num": "371",
      "arrival_site": "开发区",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

Java

// DashScope Java SDK 版本需要不低于 2.21.4

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.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    
    // 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/api/v1
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.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", "提取图中ticket(包括 travel_date、trains、seat_num、arrival_site、price)和 invoice 的信息（数组类型，包括 invoice_code 和 invoice_number ），请输出包含 ticket 和 invoice 数组的JSON"))).build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // 若没有配置环境变量，请用百炼API Key将下行替换为：.apiKey("sk-xxx")
                .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());
        }
    }
}

返回结果

{
  "ticket": [
    {
      "travel_date": "2013-06-29",
      "trains": "流水",
      "seat_num": "371",
      "arrival_site": "开发区",
      "price": "8.00"
    }
  ],
  "invoice": [
    {
      "invoice_code": "221021325353",
      "invoice_number": "10283819"
    }
  ]
}

curl

# ======= 重要提示 =======
# 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
# 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === 执行时请删除该注释 ===

curl -X POST https://dashscope-intl.aliyuncs.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": "提取图中ticket(包括 travel_date、trains、seat_num、arrival_site、price)和 invoice 的信息（数组类型，包括 invoice_code 和 invoice_number ），请输出包含 ticket 和 invoice 数组的JSON"}
                ]
            }
        ]
    },
    "parameters": {
        "response_format": {"type": "json_object"}
    }
}'

返回结果

{
  "output": {
    "choices": [
      {
        "message": {
          "content": [
            {
              "text": "{\n  \"ticket\": [\n    {\n      \"travel_date\": \"2013-06-29\",\n      \"trains\": \"流水\",\n      \"seat_num\": \"371\",\n      \"arrival_site\": \"开发区\",\n      \"price\": \"8.00\"\n    }\n  ],\n  \"invoice\": [\n    {\n      \"invoice_code\": \"221021325353\",\n      \"invoice_number\": \"10283819\"\n    }\n  ]\n}"
            }
          ],
          "role": "assistant"
        },
        "finish_reason": "stop"
      }
    ]
  },
  "usage": {
    "total_tokens": 598,
    "input_tokens_details": {
      "image_tokens": 418,
      "text_tokens": 68
    },
    "output_tokens": 112,
    "input_tokens": 486,
    "output_tokens_details": {
      "text_tokens": 112
    },
    "image_tokens": 418
  },
  "request_id": "b129dce1-0d5d-4772-b8b5-bd3a1d5cde63"
}

优化提示词

模糊的提示词（如“返回用户信息”）会使模型生成非预期结果。建议在提示词中准确描述预期 Schema，包括字段类型、必需性、格式要求（如日期格式），并提供示例。

OpenAI兼容

Python

from openai import OpenAI
import os
import json
import textwrap  # 用于处理多行字符串的缩进，提高代码可读性

# 预定义示例响应，用于向模型展示期望的输出格式
# 示例1：包含所有字段的完整响应
example1_response = json.dumps(
    {
        "info": {"name": "张三", "age": "25岁", "email": "zhangsan@example.com"},
        "hobby": ["唱歌"]
    },
    ensure_ascii=False
)
# 示例2：包含多个hobby的响应
example2_response = json.dumps(
    {
        "info": {"name": "李四", "age": "30岁", "email": "lisi@example.com"},
        "hobby": ["跳舞", "游泳"]
    },
    ensure_ascii=False
)
# 示例3：不包含hobby字段的响应（hobby非必需）
example3_response = json.dumps(
    {
        "info": {"name": "赵六", "age": "28岁", "email": "zhaoliu@example.com"}
    },
    ensure_ascii=False
)
# 示例4：不包含hobby字段的响应
example4_response = json.dumps(
    {
        "info": {"name": "孙七", "age": "35岁", "email": "sunqi@example.com"}
    },
    ensure_ascii=False
)

# 初始化OpenAI客户端，配置API密钥和基础URL
client = OpenAI(
    # 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# dedent的作用是去除每行开头的公共缩进，使字符串在代码中可以美观地缩进，但在运行时不会包含这些额外的空格
system_prompt = textwrap.dedent(f"""\
    请从用户输入中提取个人信息并按照指定的JSON Schema格式输出：

    【输出格式要求】
    输出必须严格遵循以下JSON结构：
    {{
      "info": {{
        "name": "字符串类型，必需字段，用户姓名",
        "age": "字符串类型，必需字段，格式为'数字+岁'，例如'25岁'",
        "email": "字符串类型，必需字段，标准邮箱格式，例如'user@example.com'"
      }},
      "hobby": ["字符串数组类型，非必需字段，包含用户的所有爱好，如未提及则完全不输出此字段"]
    }}

    【字段提取规则】
    1. name: 从文本中识别用户姓名，必需提取
    2. age: 识别年龄信息，转换为"数字+岁"格式，必需提取
    3. email: 识别邮箱地址，保持原始格式，必需提取
    4. hobby: 识别用户爱好，以字符串数组形式输出，如未提及爱好信息则完全省略hobby字段

    【参考示例】
    示例1（包含爱好）：
    Q：我叫张三，今年25岁，邮箱是zhangsan@example.com，爱好是唱歌
    A：{example1_response}

    示例2（包含多个爱好）：
    Q：我叫李四，今年30岁，邮箱是lisi@example.com，平时喜欢跳舞和游泳
    A：{example2_response}

    示例3（不包含爱好）：
    Q：我叫赵六，今年28岁，我的邮箱是zhaoliu@example.com
    A：{example3_response}

    示例4（不包含爱好）：
    Q：我是孙七，35岁，邮箱sunqi@example.com
    A：{example4_response}

    请严格按照上述格式和规则提取信息并输出JSON。如果用户未提及爱好，则不要在输出中包含hobby字段。\
""")

# 调用大模型API进行信息提取
completion = client.chat.completions.create(
    model="qwen-plus",  # 指定使用qwen-plus模型
    messages=[
        {
            "role": "system",
            "content": system_prompt  # 使用优化后的system prompt
        },
        {
            "role": "user",
            "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游", 
        },
    ],
    response_format={"type": "json_object"},  # 指定返回JSON格式，确保输出结构化数据
)

# 提取并打印模型生成的JSON结果
json_string = completion.choices[0].message.content
print(json_string)

返回结果

{
  "info": {
    "name": "刘五",
    "age": "34岁",
    "email": "liuwu@example.com"
  },
  "hobby": ["打篮球", "旅游"]  
}

Node.js

import OpenAI from "openai";

// 预定义示例响应（用于向模型展示期望的输出格式）
// 示例1：包含所有字段的完整响应
const example1Response = JSON.stringify({
    info: { name: "张三", age: "25岁", email: "zhangsan@example.com" },
    hobby: ["唱歌"]
}, null, 2);

// 示例2：包含多个hobby的响应
const example2Response = JSON.stringify({
    info: { name: "李四", age: "30岁", email: "lisi@example.com" },
    hobby: ["跳舞", "游泳"]
}, null, 2);

// 示例3：不包含hobby字段的响应（hobby非必需）
const example3Response = JSON.stringify({
    info: { name: "赵六", age: "28岁", email: "zhaoliu@example.com" }
}, null, 2);

// 示例4：另一个不包含hobby字段的响应
const example4Response = JSON.stringify({
    info: { name: "孙七", age: "35岁", email: "sunqi@example.com" }
}, null, 2);

// 初始化OpenAI客户端配置
const openai = new OpenAI({
    // 新加坡地域与北京地域的API Key不同
    // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY,
    // 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/compatible-mode/v1
    baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

// 创建聊天完成请求，使用结构化提示词来提高输出准确性
const completion = await openai.chat.completions.create({
    model: "qwen-plus",
    messages: [
        {
            role: "system",
            content: `请从用户输入中提取个人信息并按照指定的JSON Schema格式输出：

【输出格式要求】
输出必须严格遵循以下JSON结构：
{
  "info": {
    "name": "字符串类型，必需字段，用户姓名",
    "age": "字符串类型，必需字段，格式为'数字+岁'，例如'25岁'",
    "email": "字符串类型，必需字段，标准邮箱格式，例如'user@example.com'"
  },
  "hobby": ["字符串数组类型，非必需字段，包含用户的所有爱好，如未提及则完全不输出此字段"]
}

【字段提取规则】
1. name: 从文本中识别用户姓名，必需提取
2. age: 识别年龄信息，转换为"数字+岁"格式，必需提取
3. email: 识别邮箱地址，保持原始格式，必需提取
4. hobby: 识别用户爱好，以字符串数组形式输出，如未提及爱好信息则完全省略hobby字段

【参考示例】
示例1（包含爱好）：
Q：我叫张三，今年25岁，邮箱是zhangsan@example.com，爱好是唱歌
A：${example1Response}

示例2（包含多个爱好）：
Q：我叫李四，今年30岁，邮箱是lisi@example.com，平时喜欢跳舞和游泳
A：${example2Response}

示例3（不包含爱好）：
Q：我叫赵六，今年28岁，我的邮箱是zhaoliu@example.com
A：${example3Response}

示例4（不包含爱好）：
Q：我是孙七，35岁，邮箱sunqi@example.com
A：${example4Response}

请严格按照上述格式和规则提取信息并输出JSON。如果用户未提及爱好，则不要在输出中包含hobby字段。`
        },
        {
            role: "user",
            content: "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游"
        }
    ],
    response_format: {
        type: "json_object"
    }
});

// 提取并打印模型生成的JSON结果
const jsonString = completion.choices[0].message.content;
console.log(jsonString);

返回结果

{
  "info": {
    "name": "刘五",
    "age": "34岁",
    "email": "liuwu@example.com"
  },
  "hobby": [
    "打篮球",
    "旅游"
  ]
}

DashScope

Python

import os
import json
import dashscope
# 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 预定义示例响应（用于向模型展示期望的输出格式）
example1_response = json.dumps(
    {
        "info": {"name": "张三", "age": "25岁", "email": "zhangsan@example.com"},
        "hobby": ["唱歌"]
    },
    ensure_ascii=False
)
example2_response = json.dumps(
    {
        "info": {"name": "李四", "age": "30岁", "email": "lisi@example.com"},
        "hobby": ["跳舞", "游泳"]
    },
    ensure_ascii=False
)
example3_response = json.dumps(
    {
        "info": {"name": "王五", "age": "40岁", "email": "wangwu@example.com"},
        "hobby": ["Rap", "篮球"]
    },
    ensure_ascii=False
)

messages=[
        {
            "role": "system",
            "content": f"""请从用户输入中提取个人信息并按照指定的JSON Schema格式输出：

【输出格式要求】
输出必须严格遵循以下JSON结构：
{{
  "info": {{
    "name": "字符串类型，必需字段，用户姓名",
    "age": "字符串类型，必需字段，格式为'数字+岁'，例如'25岁'",
    "email": "字符串类型，必需字段，标准邮箱格式，例如'user@example.com'"
  }},
  "hobby": ["字符串数组类型，非必需字段，包含用户的所有爱好，如未提及则完全不输出此字段"]
}}

【字段提取规则】
1. name: 从文本中识别用户姓名，必需提取
2. age: 识别年龄信息，转换为"数字+岁"格式，必需提取
3. email: 识别邮箱地址，保持原始格式，必需提取
4. hobby: 识别用户爱好，以字符串数组形式输出，如未提及爱好信息则完全省略hobby字段

【参考示例】
示例1（包含爱好）：
Q：我叫张三，今年25岁，邮箱是zhangsan@example.com，爱好是唱歌
A：{example1_response}

示例2（包含多个爱好）：
Q：我叫李四，今年30岁，邮箱是lisi@example.com，平时喜欢跳舞和游泳
A：{example2_response}

示例3（包含多个爱好）：
Q：我的邮箱是wangwu@example.com，今年40岁，名字是王五，会Rap和打篮球
A：{example3_response}

请严格按照上述格式和规则提取信息并输出JSON。如果用户未提及爱好，则不要在输出中包含hobby字段。"""
        },
        {
            "role": "user",
            "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游", 
        },
    ]
response = dashscope.Generation.call(
    # 如果使用华北2（北京）地域的模型，需要使用华北2（北京）地域的 API Key，获取链接：https://bailian.console.alibabacloud.com/?tab=model#/api-key
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus", 
    messages=messages,
    result_format='message',
    response_format={'type': 'json_object'}
    )
json_string = response.output.choices[0].message.content
print(json_string)

返回结果

{
  "info": {
    "name": "刘五",
    "age": "34岁",
    "email": "liuwu@example.com"
  },
  "hobby": [
    "打篮球",
    "旅游"
  ]
}

Java

import java.util.Arrays;
import java.lang.System;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.common.ResponseFormat;
import com.alibaba.dashscope.protocol.Protocol;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/api/v1
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("""
                请从用户输入中提取个人信息并按照指定的JSON Schema格式输出：

【输出格式要求】
输出必须严格遵循以下JSON结构：
{
  "info": {
    "name": "字符串类型，必需字段，用户姓名",
    "age": "字符串类型，必需字段，格式为'数字+岁'，例如'25岁'",
    "email": "字符串类型，必需字段，标准邮箱格式，例如'user@example.com'"
  },
  "hobby": ["字符串数组类型，非必需字段，包含用户的所有爱好，如未提及则完全不输出此字段"]
}

【字段提取规则】
1. name: 从文本中识别用户姓名，必需提取
2. age: 识别年龄信息，转换为"数字+岁"格式，必需提取
3. email: 识别邮箱地址，保持原始格式，必需提取
4. hobby: 识别用户爱好，以字符串数组形式输出，如未提及爱好信息则完全省略hobby字段

【参考示例】
示例1（包含爱好）：
Q：我叫张三，今年25岁，邮箱是zhangsan@example.com，爱好是唱歌
A：{"info":{"name":"张三","age":"25岁","email":"zhangsan@example.com"},"hobby":["唱歌"]}

示例2（包含多个爱好）：
Q：我叫李四，今年30岁，邮箱是lisi@example.com，平时喜欢跳舞和游泳
A：{"info":{"name":"李四","age":"30岁","email":"lisi@example.com"},"hobby":["跳舞","游泳"]}

示例3（不包含爱好）：
Q：我叫王五，我的邮箱是wangwu@example.com，今年40岁
A：{"info":{"name":"王五","age":"40岁","email":"wangwu@example.com"}}""")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游")
                .build();
        ResponseFormat jsonMode = ResponseFormat.builder().type("json_object").build();
        GenerationParam param = GenerationParam.builder()
                // 如果使用华北2（北京）地域的模型，需要使用华北2（北京）地域的 API Key，获取链接：https://bailian.console.alibabacloud.com/?tab=model#/api-key
                // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .responseFormat(jsonMode)
                .build();
        return gen.call(param);
    }
    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 使用日志框架记录异常信息
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
    }
}

返回结果

{
  "info": {
    "name": "刘五",
    "age": "34岁",
    "email": "liuwu@example.com"
  },
  "hobby": [
    "打篮球",
    "旅游"
  ]
}

获取指定格式的输出

将response_format的type设为json_object，可返回标准 JSON 字符串，但内容结构可能不符合预期，适用于简单场景。对于自动化解析、API 互操作等需要严格类型约束的复杂场景，可将 type 设置为 json_schema，强制大模型输出严格符合指定格式的内容。response_format 格式与示例如下：

格式

示例

{
  "type": "json_schema",
  "json_schema": {
    "name": "schema_name",       // Schema 的名称
    "strict": true,              // 推荐设置为 true，严格遵守格式
    "schema": {
      "type": "object",
      "properties": {...},       // 定义字段结构，见右侧具体示例
      "required": [...],         // 必填字段列表
      "additionalProperties": false  // 推荐设置为 false，只输出定义的字段
    }
  }
}

{
  "type": "json_schema",
  "json_schema": {
    "name": "user_info",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "用户姓名"
        },
        "age": {
          "type": "integer",
          "description": "用户年龄"
        },
        "email": {
          "type": "string",
          "description": "邮箱地址"
        }
      },
      "required": ["name", "age"],
      "additionalProperties": false
    }
  }
}

上述示例会强制模型输出包含 name 和 age 两个必填字段，以及可选的 email 字段的 JSON 对象。

仅支持北京地域的以下模型：qwen-plus-latest、qwen-plus-2025-12-01、qwen-plus-2025-09-11、qwen-plus-2025-07-28。

暂不支持新加坡地域模型。

使用方法

通过 OpenAI SDK 的 parse 方法，可直接传入 Python Pydantic 类或 Node.js Zod 对象。SDK 会自动将其转换为 JSON Schema，无需手动编写复杂 JSON。DashScope SDK 需参考上文格式，手动构造 JSON Schema。

OpenAI 兼容

Python

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

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

class UserInfo(BaseModel):
    name: str = Field(description="用户的姓名")
    age: int = Field(description="用户的年龄，单位为岁")

completion = client.chat.completions.parse(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "提取姓名与年龄信息。"},
        {"role": "user", "content": "我叫刘五，今年25岁。"},
    ],
    response_format=UserInfo,
)

result = completion.choices[0].message.parsed
print(f"姓名：{result.name}，年龄：{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,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

const UserInfo = z.object({
  name: z.string().describe("用户的姓名"),
  age: z.number().int().describe("用户的年龄，单位为岁"),
});

const completion = await openai.chat.completions.parse({
  model: "qwen-plus",
  messages: [
    { role: "system", content: "提取姓名与年龄信息。" },
    { role: "user", content: "我叫刘五，今年25岁。" },
  ],
  response_format: zodResponseFormat(UserInfo, "user_info"),
});

const userInfo = completion.choices[0].message.parsed;
console.log(`姓名：${userInfo.name}`);
console.log(`年龄：${userInfo.age}`);

运行代码可获得以下输出：

姓名：刘五，年龄：25

DashScope

暂不支持 Java SDK。

Python

import os
import dashscope
import json

messages = [
    {
        "role": "user",
        "content": "我叫刘五，今年25岁。",
    },
]
response = dashscope.Generation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-plus",
    messages=messages,
    result_format="message",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "user_info",
            "schema": {
                "properties": {
                    "name": {"title": "Name", "type": "string"},
                    "age": {"title": "Age", "type": "integer"},
                },
                "required": ["name", "age"],
                "title": "UserInfo",
                "type": "object",
            },
        },
        "strict": True,
    },
)
json_object = json.loads(response.output.choices[0].message.content)
print(f"姓名：{json_object['name']}，年龄：{json_object['age']}")

运行代码可获得以下输出：

姓名：刘五，年龄：25

配置指南

使用 JSON Schema 时，遵循以下规范可获得更可靠的结构化输出：

必填字段声明
推荐将必填字段列在 required数组中。可选字段可不列入，例如：
```
{
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"},
    "email": {"type": "string"}
  },
  "required": ["name", "age"]
}
```
若输入未提供 email 信息，输出中将不包含此字段。

可选字段的实现方式

除不列入 required 外，也可通过允许 null 类型实现：

{
  "properties": {
    "name": {"type": "string"},
    "email": {"type": ["string", "null"]}  // 可以是字符串或 null
  },
  "required": ["name", "email"]  // 两个都在 required 中
}

输出将始终包含 email 字段，但其值可能为 null。

additionalProperties 配置
控制是否允许输出未在 schema 中定义的额外字段：
```
{
  "properties": {"name": {"type": "string"}},
  "required": ["name"],
  "additionalProperties": true  // 允许额外字段
}
```
示例输入："我叫张三，25岁"；输出：{"name": "张三", "age": 25}（包含未定义的 age 字段）。
值
行为
适用场景
false
只输出定义的字段
需要精确控制结构
true
允许额外字段
需要捕获更多信息
支持的数据类型：string、number、integer、boolean、object、array、enum。

应用于生产环境

有效性校验
若使用 JSON Object 模式，将输出传递给下游业务前，建议使用工具对其进行有效性校验，如 jsonschema (Python)、Ajv (JavaScript)、Everit (Java)等，确保其符合指定的 JSON Schema 要求，避免因字段缺失、类型错误或格式不规范导致下游系统解析失败、数据丢失或业务逻辑中断。失败时可通过重试、大模型改写等策略进行修复。
禁用 max_tokens
请勿在开启结构化输出时指定 max_tokens（控制模型输出 Token 数的参数，默认值为模型最大输出 Token 数），否则返回的 JSON 字符串可能不完整，导致下游业务解析失败。

使用 SDK 辅助生成 Schema

推荐使用 SDK 自动生成 Schema，避免手动维护导致的错误，并可以自动验证和解析。

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"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
class UserInfo(BaseModel):
    name: str = Field(description="用户姓名")
    age: int = Field(description="用户年龄")
    email: Optional[str] = None  # 可选字段

completion = client.chat.completions.parse(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "提取姓名与年龄信息。"},
        {"role": "user", "content": "我叫刘五，今年25岁。"},
    ],
    response_format=UserInfo  # 直接传入 Pydantic 模型
)

result = completion.choices[0].message.parsed  # 类型安全的解析结果
print(f"姓名：{result.name}，年龄：{result.age}")

Node.js

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://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

const UserInfo = z.object({
  name: z.string().describe("用户姓名"),
  age: z.number().int().describe("用户年龄"),
  email: z.string().optional().nullable()  // 可选字段
});

const completion = await client.chat.completions.parse({
  model: "qwen-plus",
  messages: [
    { role: "system", content: "提取姓名与年龄信息。" },
    { role: "user", content: "我叫刘五，今年25岁。" },
  ],
  response_format: zodResponseFormat(UserInfo, "user_info")
});

console.log(completion.choices[0].message.parsed);

常见问题

Q：Qwen 的思考模式模型如何结构化输出？

A：Qwen 的思考模式模型暂不支持结构化输出。如需在思考模式下获取标准 JSON 字符串，可在 JSON 解析失败时引入支持 JSON Mode 的模型进行修复。

获取思考模式下的输出

调用思考模式模型获取高质量的输出，但可能不是标准的 JSON 字符串。

开启思考模式请勿设置response_format参数为{"type": "json_object"}，否则会报错。

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": system_prompt},
        {
            "role": "user",
            "content": "大家好，我叫刘五，今年34岁，邮箱是liuwu@example.com，平时喜欢打篮球和旅游",
        },
    ],
    # 开启思考模式，请勿设置response_format参数为{"type": "json_object"}，否则会报错
    extra_body={"enable_thinking": True},
    # 思考模式下需要开启流式输出
    stream=True
)
# 提取并打印模型生成的JSON结果
json_string = ""
for chunk in completion:
    if chunk.choices[0].delta.content is not None:
        json_string += chunk.choices[0].delta.content

校验并修复输出

尝试解析上一步获取的 json_string：

若模型生成了标准格式JSON字符串，可直接解析并返回。
若模型生成非标准格式JSON字符串，可调用支持结构化输出的模型（建议选择速度快、成本低的模型，如非思考模式的qwen-flash）修复格式。

import json

try:
    json_object_from_thinking_model = json.loads(json_string)
    print("生成标准格式JSON字符串")
except json.JSONDecodeError:
    print("未生成标准格式JSON字符串，通过支持结构化输出的模型进行修复")
    completion = client.chat.completions.create(
        model="qwen-flash",
        messages=[
            {
                "role": "system",
                "content": "你是一个json格式修复专家，请将用户输入的json字符串修复为标准格式",
            },
            {
                "role": "user",
                "content": json_string,
            },
        ],
        response_format={"type": "json_object"},
    )
    json_object_from_thinking_model = json.loads(completion.choices[0].message.content)

错误码

如果模型调用失败并返回报错信息，请参见错误信息进行解决。

值	行为	适用场景
`false`	只输出定义的字段	需要精确控制结构
`true`	允许额外字段	需要捕获更多信息