当您需要模型像程序一样输出标准格式(这里主要指 JSON 格式)而不是自然语言,方便工具进行标准化处理或展示时,可以使用格式化输出能力。
要启用该能力,需在请求时配置 response_format 对象,来指定模型输出 JSON 格式,甚至通过定义 JSON 结构,进一步定义模型输出哪些字段信息。
与通过提示词控制模型输出 JSON 格式的方法(不推荐)相比,使用结构化输出能力有以下好处:
支持该能力的模型如下:
250615
版本。250615
版本。250615
版本。250428
版本。250415
版本。250328
版本。
json_object
模式。250528
版本。结构化输出 API 字段说明见对话(Chat) API。
支持
json_schema
的方舟 SDK 开发中。
from openai import OpenAI import os from pydantic import BaseModel client = OpenAI( # 从环境变量中获取方舟 API Key api_key=os.environ.get("ARK_API_KEY"), base_url = "https://ark.cn-beijing.volces.com/api/v3", ) class Step(BaseModel): explanation: str output: str class MathResponse(BaseModel): steps: list[Step] final_answer: str completion = client.beta.chat.completions.parse( model = "doubao-1.5-thinking-vision-pro-250428", # 替换为您需要使用的模型 messages = [ {"role": "system", "content": "你是一位数学辅导老师。"}, {"role": "user", "content": "使用中文解题: 8x + 9 = 32 and x + y = 1"}, ], response_format=MathResponse, extra_body={ "thinking": { "type": "disabled" # 不使用深度思考能力 # "type": "enabled" # 使用深度思考能力 } } ) resp = completion.choices[0].message.parsed # 打印 JSON 格式结果 print(resp.model_dump_json(indent=2))
返回预览
{ "steps": [ { "explanation": "解第一个方程8x + 9 = 32,先将等式两边同时减去9,得到8x = 32 - 9", "output": "8x = 23" }, { "explanation": "然后等式两边同时除以8,求出x的值", "output": "x = 23/8" }, { "explanation": "将x = 23/8代入第二个方程x + y = 1,求解y,即y = 1 - x", "output": "y = 1 - 23/8" }, { "explanation": "计算1 - 23/8,通分后得到(8 - 23)/8", "output": "y = -15/8" } ], "final_answer": "x = 23/8,y = -15/8" }
json_schema
与 json_mode
格式化输出可以选择不同类型(type),包括 json_schema
、json_mode
、text
。除 text
是让模型使用自然语言进行回复,json_schema
和 json_mode
均是控制生成 JSON 格式回答,同时 json_schema
是 json_mode
的演进版本,以下是他们的异同点。
当前
json_schema
功能还在beta 测试中,请谨慎评估后再在生产环境使用。
结构化输出 |
|
|
---|---|---|
生成 JSON 回复 | 是 | 是 |
可定义 JSON 结构 | 是 | 否 |
是否推荐 | 是 | 否 |
支持的模型 |
|
|
严格模式
| 支持
| 不涉及 |
配置方式 | ..., | ..., |
您需要在 schema 字段中定义好模型生成的回复的 JSON 结构,可以参考快速开始的示例。
true
。方舟支持的关键字可见附1. JSON Schema 语法支持说明,如果有明显不支持的定义,方舟会显示报错。false
或者未配置 strict 字段,方舟会生成合法 JSON 结构的内容,同时尽可能参考您的定义的结构,不会对语法校验及报错。说明
为了帮助您获得更好的生成质量,下面是定义结构时的一些建议,更多建议见 附2.结构化生成最佳实践:
在 API 中指定结构化输出的模式
..., "response_format": { "type": "json_schema", "json_schema"{ "name":"my_schema", "strict": true, "schema": {...} } }, ...
完整示例代码见 快速开始。
说明
请勿与 frequency_penalty,presence_penalty 等采样参数共同使用,可能会导致模型输出异常。
模型输出结构仍然可能包含错误,可能因为输出长度限制、任务复杂度、格式不清晰等。可以尝试调整指令,或将任务进行拆分为更简单子任务。您可以使用方舟的提示词优化工具来帮您优化模型提示词,详细见 PromptPilot 概述。
说明
#
开头的本地相对引用以上无法 100% 保证区间语义。
字段命名含糊/无描述,导致模型难以判断含义。使用清晰有意义的英文名(如 user_name),并配合 description
详细说明字段用途。
错误示例
{ "type": "object", "properties": { "v1": { "type": "string" } } }
改进后示例
{ "type": "object", "properties": { "user_name": { "type": "string", "description": "用户的姓名" } } }
不过度使用 $ref,结构尽可能一次性展开。无意义的嵌套会增加模型生成难度,提高出错概率。
错误示例
{ "type": "object", "properties": { "date": { "type": "object", "properties": { "value": { "type": "string", "description": "日期" } } } } }
改进后示例
{ "type": "object", "properties": { "date": { "type": "string", "description": "日期,格式为 YYYY-MM-DD" } } }
错误示例
{ "score": { "type": "string" } }
改进后示例
{ "score": { "type": "integer", "description": "成绩,0到100的整数" } }
说明:类型应尽量贴合实际业务。对于数字、布尔值等不能简单用 string 替代。
明确枚举值与格式
错误示例
{ "status": { "type": "string" } }
改进后示例
{ "status": { "type": "string", "description": "处理状态,可为:pending、success 或 failed", "enum": ["pending", "success", "failed"] } }
所有需要的结构明确 required,这样模型会始终输出所有必需字段,格式更规范。
推荐使用 required 时,始终加上"additionalProperties": false
。
错误示例
{ "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "string" } }, "final_answer": { "type": "string" } } // 没有 required }
改进后示例
{ "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "string" } }, "final_answer": { "type": "string" } }, "required": ["steps", "final_answer"], "additionalProperties": false }
错误示例
{ "type": "object", "properties": { "id": { "type": "string", "description": "用户或订单编号" } } }
改进后示例
{ "type": "object", "properties": { "user_id": { "type": "string", "description": "用户编号" }, "order_id": { "type": "string", "description": "订单编号" } } }
错误示例
请用如下 JSON 格式输出,并包含字段 steps、final_answer:8x + 9 = 32,x+y=1。
改进后示例
请求解:8x + 9 = 32,x + y = 1。
错误示例
请输出一个包含 steps 和 final_answer 字段的 JSON。
改进后示例
请一步步推理解答:8x + 9 = 32, x+y=1,并写出最终答案。