当您需要模型像程序一样输出标准格式（这里主要指 JSON 格式）而不是自然语言，方便工具进行标准化处理或展示时，可以使用格式化输出能力。
要启用该能力，需在请求时配置 response_format 对象，来指定模型输出 JSON 格式，甚至通过定义 JSON 结构，进一步定义模型输出哪些字段信息。
区别于在提示词中让模型输出 JSON 格式（不推荐），使用结构化输出能力有以下好处：

• 输出更可靠：输出结构始终符合预期数据类型，包括结构中字段层级、名称、类型、顺序等，不必担心丢失必要的字段或生成幻觉的枚举值等，
• 使用更加简单：使用更简单的提示词，无需在提示词中反复强调或使用强烈措辞。

支持该能力的模型如下：

• doubao-1.5-thinking-vision-pro 的250428版本。
• doubao-1.5-thinking-pro 的250415 版本。
• doubao-1.5-vision-pro的250328版本。
  • 只支持 json_object模式。

结构化输出 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))

curl --location 'https://ark.cn-beijing.volces.com/api/v3/chat/completions' \
--header 'Authorization: Bearer $ARK_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "model": "doubao-1.5-thinking-vision-pro-250428",
  "messages": [
    {
      "role": "system",
      "content": "你是一位数学辅导老师。"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "使用中文解题: 8x + 9 = 32 and x + y = 1"
        }
      ]
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "math_reasoning",
      "schema": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "explanation": {
                  "type": "string"
                },
                "output": {
                  "type": "string"
                }
              },
              "required": [
                "explanation",
                "output"
              ],
              "additionalProperties": false
            }
          },
          "final_answer": {
            "type": "string"
          }
        },
        "required": [
          "steps",
          "final_answer"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  },
  "thinking": {
    "type": "disabled"
  }
}'

返回预览

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

格式化输出可以选择不同类型（type），包括 json_schema、json_mode 、text。除 text 是让模型使用自然语言进行回复，json_schema 和 json_mode 均是控制生成 JSON 格式回答，同时 json_schema 是 json_mode 的演进版本，以下是他们的异同点。

当前 json_schema 功能还在beta 测试中，请谨慎评估后再在生产环境使用。

1.定义结构

您需要在 schema 字段中定义好模型生成的回复的 JSON 结构，可以参考快速开始的示例。

• 当您需要模型严格按照结构输出时，需配置 strict 字段为 true。方舟支持的关键字可见附1. JSON Schema 语法支持说明，如果有明显不支持的定义，方舟会显示报错。
• 当您配置 strict 字段为 false 或者未配置 strict 字段，方舟会生成合法 JSON 结构的内容，同时尽可能参考您的定义的结构，不会对语法校验及报错。

2.API 中进行配置JSON Schema

在 API 中指定结构化输出的模式

...,
"response_format": { 
  "type": "json_schema", 
  "json_schema"{
    "name":"my_schema",
    "strict": true, 
    "schema": {...}
  }
},
...

完整示例代码见 快速开始。

3. 处理错误案例

模型输出结构仍然可能包含错误，可能因为输出长度限制、任务复杂度、格式不清晰等。可以尝试调整指令，或将任务进行拆分为更简单子任务。您可以使用方舟的提示词优化工具来帮您优化模型提示词，详细见 Prompt 优解概述。

Schema 层面公共关键字

• type
  • integer
  • number
  • string
  • boolean
  • null
  • array
  • object
• $ref
  • 只支持 # 开头的本地相对引用
• $defs
• const
• enum
• anyOf
• oneOf
  • 不严格保证 exactly one 语义
• allOf
  • 不严格保证 all 语义

type 相关的关键字

• "type": "integer"
  • minimum
  • maximum
  • exclusiveMinimum
  • exclusiveMaximum

以上无法 100% 保证区间语义。

• "type": "string"
  • pattern
• "type": "array"
  • prefixItems
  • items
  • unevaluatedItems
• "type": "object"
  • properties
  • required
  • additionalProperties
  • unevaluatedProperties