让模型稳定返回合法 JSON,并可通过 JSON Schema 精确约束输出结构
执行信息抽取或结构化数据生成任务时,模型可能返回多余文本(如
JSON Object 模式:确保输出为标准格式的 JSON 字符串,但不保证符合特定结构。使用方式:
Qwen3.7-Plus 系列、Qwen3.7-Flash 系列、Qwen3.7-Max 系列、Qwen3.8-Max 系列、Qwen3.8-Flash 系列。
以从个人简介中抽取信息为例,演示 JSON Object 模式的基本用法。
SDK 返回结果:
多模态模型同样支持对图像和视频数据进行结构化输出。通过 JSON Object 模式,可以从视觉内容中提取结构化数据,例如票据字段、图像中的目标位置或视频中的事件信息。
返回结果:
启用思考模式后,模型会先进行推理再生成 JSON,输出结果通常比非思考模式更准确。思考模式下需开启流式输出。
模糊的提示词(如"返回用户信息")会导致输出结构不可预期。为获得可靠的结果,建议在提示词中明确描述预期的结构:指定字段名称、类型、是否必填、格式要求(如日期格式),并提供示例。
以下 System Prompt 演示了这一写法:约束字段类型、区分必填与非必填字段,并用 4 个示例说明"未提及爱好时省略
将上述内容作为 System Message 传入即可:
返回结果:
JSON Object 模式只保证输出是合法 JSON,字段名、类型、层级都可能与预期不符。对于自动化解析、API 互操作等需要严格类型约束的场景,将
上述示例会强制模型输出包含
通过 OpenAI SDK 的
返回结果:
有效性校验
使用 JSON Object 模式时,输出只保证是合法 JSON,不保证符合业务约定的结构。传递给下游业务前,建议用 jsonschema(Python)、Ajv(JavaScript)、Everit(Java)等工具校验,避免因字段缺失、类型错误导致下游解析失败、数据丢失或业务逻辑中断。校验失败时可通过重试或让模型改写来修复。
禁用 max_tokens
开启结构化输出时请勿设置
如果模型调用失败并返回报错信息,请参见错误码进行解决。
```json 包裹符),导致下游解析失败。开启结构化输出可确保模型输出标准格式的 JSON 字符串;使用 JSON Schema 模式还能精确控制输出的结构和类型,无需额外校验或重试。
两种模式
| 特性 | JSON Object 模式 | JSON Schema 模式 |
|---|---|---|
| 输出合法 JSON | 是 | 是 |
| 严格遵循 Schema | 否 | 是 |
| 支持模型 | 千问大部分模型、Kimi、GLM、DeepSeek、Stepfun | 仅支持部分模型 |
response_format 设置 | {"type": "json_object"} | {"type": "json_schema", "json_schema": {..., "strict": true}} |
| 提示词要求 | 必须包含 "JSON" | 建议明确说明 |
| 适用场景 | 灵活的 JSON 输出 | 精确的结构验证 |
- 将请求体中的
response_format参数设置为{"type": "json_object"}。 - System Message 或 User Message 中包含 "JSON" 关键词(不区分大小写),否则会报错:
'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.
response_format 设置为 {"type": "json_schema", "json_schema": {..., "strict": true}}。
JSON Schema 模式下,提示词无需包含 "JSON" 关键词。
支持的模型
JSON Object
展开查看完整模型列表
展开查看完整模型列表
千问
文本生成模型- 千问 Max:Qwen3.8-Max 系列、Qwen3.7-Max 系列
- 千问 Max(非思考模式):Qwen3.6-Max 系列、Qwen3-Max 系列、Qwen-Max 系列
- 千问 Plus:Qwen3.7-Plus 系列
- 千问 Plus(非思考模式):Qwen3.6-Plus 系列、Qwen3.5-Plus 系列、Qwen-Plus 系列
- 千问 Flash:Qwen3.8-Flash 系列、Qwen3.7-Flash 系列
- 千问 Flash(非思考模式):Qwen3.6-Flash 系列、Qwen3.5-Flash 系列、Qwen-Flash 系列
- 千问 Turbo(非思考模式):Qwen-Turbo 系列
- 千问 Coder:Qwen3-Coder 系列
- 千问 Long:Qwen-Long 系列
- 开源系列:Qwen3.8 开源系列
- 开源系列(非思考模式):Qwen3.6 开源系列、Qwen3.5 开源系列、Qwen3 开源系列
- 开源系列:Qwen3-Coder 开源系列、Qwen2.5 开源系列(不含 math 与 coder 模型)
- 千问 VL:Qwen3-VL-Plus 系列、Qwen3-VL-Flash 系列、Qwen-VL-Max 系列(不包括最新版与快照版模型)、Qwen-VL-Plus 系列(不包括最新版与快照版模型)
- 千问 Omni:Qwen3.5-Omni-Plus 系列
- 开源系列:Qwen3-VL 开源系列
Kimi
千问AI平台部署kimi-k3kimi-k2-thinking
kimi/kimi-k3、kimi/kimi-k2.7-code-highspeed、kimi/kimi-k2.7-code、kimi/kimi-k2.6、kimi/kimi-k2.5
DeepSeek
千问AI平台部署deepseek-v4-pro-0813、deepseek-v4-pro、deepseek-v4-flash
vanchin/deepseek-v3.2-think、vanchin/deepseek-v3、vanchin/deepseek-ocr
GLM
glm-5.1、glm-4.5、glm-4.5-air- 非思考模式:
glm-5、glm-4.7、glm-4.6
Stepfun
- 混合思考模式:
stepfun/step-3.7-flash
标注为"非思考模式"的模型,在思考模式下将
response_format 设置为 {"type": "json_object"} 不会报错,但结构化输出可能失效。如需稳定获取标准 JSON,请参见常见问题。JSON Schema
Qwen3.7-Plus 系列、Qwen3.7-Flash 系列、Qwen3.7-Max 系列、Qwen3.8-Max 系列、Qwen3.8-Flash 系列。
快速开始
以从个人简介中抽取信息为例,演示 JSON Object 模式的基本用法。
JSON Object 模式不保证键名与字段类型稳定,不同提示词或不同次调用的返回结果可能存在差异。如需固定结构,请使用 JSON Schema 模式。
调用前需先获取 API Key 并配置到环境变量。通过 OpenAI SDK 或 DashScope SDK 调用还需安装 SDK。
- OpenAI 兼容
- DashScope
curl 完整响应
curl 完整响应
从图片和视频中提取结构化数据
多模态模型同样支持对图像和视频数据进行结构化输出。通过 JSON Object 模式,可以从视觉内容中提取结构化数据,例如票据字段、图像中的目标位置或视频中的事件信息。
图片、视频的文件限制请参见图像与视频理解。
- OpenAI 兼容
- DashScope
思考模型的结构化输出
启用思考模式后,模型会先进行推理再生成 JSON,输出结果通常比非思考模式更准确。思考模式下需开启流式输出。
- OpenAI 兼容
- DashScope
返回结果(含思考过程)
返回结果(含思考过程)
优化提示词
模糊的提示词(如"返回用户信息")会导致输出结构不可预期。为获得可靠的结果,建议在提示词中明确描述预期的结构:指定字段名称、类型、是否必填、格式要求(如日期格式),并提供示例。
以下 System Prompt 演示了这一写法:约束字段类型、区分必填与非必填字段,并用 4 个示例说明"未提及爱好时省略 hobby 字段"。
System Prompt
- OpenAI 兼容
- DashScope
使用 JSON Schema 精确约束输出
JSON Object 模式只保证输出是合法 JSON,字段名、类型、层级都可能与预期不符。对于自动化解析、API 互操作等需要严格类型约束的场景,将 type 设为 json_schema,模型会严格按照给定的 Schema 输出。
response_format 的结构如下:
name 和 age 两个必填字段、以及可选的 email 字段的 JSON 对象。
使用方法
通过 OpenAI SDK 的 parse 方法,可直接传入 Python Pydantic 类或 Node.js Zod 对象,SDK 会自动转换为 JSON Schema,无需手动编写。DashScope SDK 需按上文格式手动构造 JSON Schema。
- OpenAI 兼容
- DashScope
配置指南
必填字段声明
必填字段声明
将必填字段列在 若输入未提供 email 信息,输出中将不包含此字段。
required 数组中,可选字段不列入:可选字段的实现方式
可选字段的实现方式
除了不列入 此时输出将始终包含
required,也可以通过允许 null 类型实现可选字段:email 字段,但其值可能为 null。additionalProperties 配置
additionalProperties 配置
控制是否允许输出未在 Schema 中定义的额外字段:输入"我叫张三,25岁"时,输出为
{"name": "张三", "age": 25},包含未定义的 age 字段。| 值 | 行为 | 适用场景 |
|---|---|---|
false | 只输出定义的字段 | 需要精确控制结构 |
true | 允许额外字段 | 需要捕获更多信息 |
支持的数据类型
支持的数据类型
string、number、integer、boolean、object、array、enum。应用于生产环境
有效性校验
使用 JSON Object 模式时,输出只保证是合法 JSON,不保证符合业务约定的结构。传递给下游业务前,建议用 jsonschema(Python)、Ajv(JavaScript)、Everit(Java)等工具校验,避免因字段缺失、类型错误导致下游解析失败、数据丢失或业务逻辑中断。校验失败时可通过重试或让模型改写来修复。
禁用 max_tokens
开启结构化输出时请勿设置 max_tokens。该参数限制输出 Token 数(默认为模型最大输出 Token 数),设置后可能导致 JSON 字符串在输出过程中被截断,产生无效 JSON。
使用 SDK 辅助生成 Schema
推荐用 SDK 自动生成 Schema,避免手写维护出错,同时获得自动校验与类型安全的解析结果。
常见问题
标注为“非思考模式”的模型,开启思考后如何获得结构化输出?
标注为“非思考模式”的模型,开启思考后如何获得结构化输出?
支持的模型中标注为"非思考模式"的模型,在思考模式下返回的内容可能不是严格的标准 JSON。可采用两步法:先调用思考模型获取高质量输出,再把格式不正确的 JSON 交给支持 JSON Object 模式的模型修复。第一步:获取思考模式下的输出第二步:校验并修复输出尝试解析上一步得到的
开启思考模式时设置
response_format 为 {"type": "json_object"} 不会报错。以下为兜底示例,仅在模型返回内容不是标准 JSON 时用于演示两步修复法,因此未设置 response_format。json_string。若是有效 JSON,直接使用;若无效,调用支持结构化输出的模型修复(建议选择速度快、成本低的模型,如非思考模式的 qwen-flash)。