# 结构化输出(beta) > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 当需要模型输出程序可处理的标准格式（主要是 JSON）而非自然语言时，可开启结构化输出能力，以支持标准化处理或展示。 通过配置 **text.format** 对象，指定模型输出 JSON 格式，还可以通过定义 JSON 结构，限定模型输出字段信息。 相较于通过提示词控制模型输出 JSON 格式，使用结构化输出能力具有以下优势： * 输出可靠：输出结构符合预期数据类型，包括字段层级、名称、类型、顺序等，避免必要字段缺失或枚举值幻觉。 * 使用简单：通过 API 字段定义输出格式，提示词更加简单，无需在提示词中反复强调或使用强约束措辞。 > **说明** > > 该能力尚在 beta 阶段，受资源与平台负载影响，服务可用性可能随访问情况产生波动，请谨慎在生产环境使用。 ## 支持模型 250615及之后版本的大语言模型，如无特殊说明，默认支持 Responses API，方舟平台大语言模型列表，请参见：[结构化输出能力（beta）](/docs/model-list#86588b72)。 ## API文档 [Responses API](/docs/create-model-responses-api) ## json_object 模式 这段代码展示了如何利用 Responses API 实现 JSON Object 结构化输出。 **选项：Curl** ```Bash curl https://ark.cn-beijing.volces.com/api/v3/responses \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seed-2-1-pro-260915", "thinking": { "type": "disabled" }, "text": { "format": { "type": "json_object" } }, "input": [ { "role": "system", "content": "你是一位专业的数学助教，收到用户提出的数学问题后，需以结构化 JSON 格式输出。返回的json中应包含explanation和answer字段" }, { "role": "user", "content": "根号三的近似值是多少" } ] }' ``` **选项：Python** ```Python import os from arkruntime import Ark api_key = os.getenv('ARK_API_KEY') client = Ark( base_url='https://ark.cn-beijing.volces.com/api/v3', api_key=api_key, ) response = client.responses.create( model="doubao-seed-2-1-pro-260915", input=[ {"role": "system", "content": "你是一位专业的数学助教，收到用户提出的数学问题后，需以结构化 JSON 格式输出。" "返回的 JSON 应该包含以下字段：" "1. 'explanation'：对题目的详细推理和解题步骤，内容应简明易懂。" "2. 'answer'：最终的纯数值答案或结论。" "所有内容均用简体中文。请勿输出 JSON 以外的内容。" }, {"role": "user", "content": "根号三的近似值是多少。"} ], text={"format":{"type": "json_object"}} ) print(response) ``` **选项：Go** ```Go package main import ( "context" "fmt" "os" "github.com/volcengine/ark-runtime-go/arkruntime" "github.com/volcengine/ark-runtime-go/arkruntime/model/responses" ) func main() { client := arkruntime.NewClientWithApiKey( // Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey os.Getenv("ARK_API_KEY"), arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), ) ctx := context.Background() resp, err := client.CreateResponses(ctx, &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ easyMessage(responses.MessageRoleSystem, "你是一位专业的数学助教。请以结构化 JSON 输出，并包含 explanation 和 answer 字段。"), easyMessage(responses.MessageRoleUser, "根号三的近似值是多少。"), }), Text: responses.NewOptResponseTextConfig(responses.ResponseTextConfig{Format: responses.TextFormat{Type: responses.TextFormatTypeJSONObject}}), }) if err != nil { fmt.Printf("stream error: %v", err) return } fmt.Println(resp) } func easyMessage(role responses.MessageRole, content string) responses.InputItem { return responses.InputItem{ OneOf: responses.NewItemEasyMessageInputItemSum( responses.ItemEasyMessage{ Role: responses.NewOptMessageRole(role), Content: responses.NewStringMessageContent(content), }, ), } } ``` **选项：Java** ```Java package com.ark.example; import com.volcengine.ark.runtime.models.responses.*; import com.volcengine.ark.runtime.service.ArkService; public class demo { public static void main(String[] args) { String apiKey = System.getenv("ARK_API_KEY"); // The base URL for model invocation ArkService arkService = ArkService.builder().apiKey(apiKey) .baseUrl("https://ark.cn-beijing.volces.com/api/v3") .build(); ResponsesRequest request = ResponsesRequest.builder() .model("doubao-seed-2-1-pro-260915") .input(ResponsesInput.ofList(java.util.Arrays.asList(ItemEasyMessage.builder().role(MessageRole.SYSTEM).content( MessageContent.ofString("你是一位专业的数学助教，收到用户提出的数学问题后，需以结构化 JSON 格式输出。返回的json中应包含explanation和answer字段") ).build(), ItemEasyMessage.builder().role(MessageRole.USER).content( MessageContent.ofString("根号三的近似值是多少") ).build()))) .text(ResponseTextConfig.builder().format(TextFormat.builder().type(TextFormatType.JSON_OBJECT).build()).build()) .build(); Response resp = arkService.createResponse(request); System.out.println(resp); arkService.shutdownExecutor(); } } ``` **选项：OpenAI SDK** ```Python import os from openai import OpenAI api_key = os.getenv('ARK_API_KEY') client = OpenAI( base_url='https://ark.cn-beijing.volces.com/api/v3', api_key=api_key, ) response = client.responses.create( model="doubao-seed-2-1-pro-260915", input=[ {"role": "system", "content": "你是一位专业的数学助教，收到用户提出的数学问题后，需以结构化 JSON 格式输出。" "返回的 JSON 应该包含以下字段：" "1. 'explanation'：对题目的详细推理和解题步骤，内容应简明易懂。" "2. 'answer'：最终的纯数值答案或结论。" "所有内容均用简体中文。请勿输出 JSON 以外的内容。" }, {"role": "user", "content": "根号三的近似值是多少。"} ], text={"format":{"type": "json_object"}} ) print(response) ``` 返回预览 ```JSON { "explanation": "根号三即√3，其近似值可通过逐步逼近法确定。首先，1²=1，2²=4，故√3在1和2之间。进一步计算，1.7²=2.89，1.8²=3.24，因此√3在1.7和1.8之间。继续精确，1.73²=2.9929，1.732²=2.999824（接近3），1.7321²≈3.00017（略大于3）。综上，√3的近似值通常取1.732。", "answer": "1.732" } ``` ## json_schema 模式 这段代码展示了如何利用 Responses API 实现遵循 schema 字段定义的 JSON 结构化输出。 **选项：Curl** ```Bash curl https://ark.cn-beijing.volces.com/api/v3/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -d '{ "model": "doubao-seed-2-1-pro-260915", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "return in json format how can I solve 8x + 7 = -23" } ] } ], "thinking": { "type": "disabled" }, "stream": false, "text": { "format": { "type": "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 } } } }' ``` **选项：OpenAI SDK** ```Python import os from openai import OpenAI from pydantic import BaseModel api_key = os.getenv('ARK_API_KEY') client = OpenAI( base_url='https://ark.cn-beijing.volces.com/api/v3', api_key=api_key, ) class Step(BaseModel): explanation: str # Step details output: str # Step computation results class MathResponse(BaseModel): steps: list[Step] # List of solution steps final_answer: str # Final answer response = client.responses.parse( model="doubao-seed-2-1-pro-260915", input=[ { "role": "user", "content": [ { "type": "input_text", "text": "return in json format how can I solve 8x + 7 = -23" } ] } ], text_format=MathResponse ) print(response.output_parsed) ``` 返回预览 ```JSON { "steps": [ { "explanation": "Subtract 7 from both sides to isolate the term with x", "output": "8x = -23 - 7" }, { "explanation": "Simplify the right side", "output": "8x = -30" }, { "explanation": "Divide both sides by 8 to solve for x", "output": "x = -30/8" }, { "explanation": "Simplify the fraction", "output": "x = -15/4" } ], "final_answer": "x = -15/4" } ``` ## 模式对比：`json_object` 与 `json_schema` `json_schema` 是 `json_object` 的演进版本，两种模式都支持 JSON 结构化输出，具体的异同如下。 |结构化输出 |`json_schema` |`json_object` | |---|---|---| |生成 JSON 回复 |是 |是 | |可定义 JSON 结构 |是 |否 | \ | | |仅保障回复是合法 JSON | |是否推荐 |是 |否 | |支持的模型 |见[结构化输出能力（beta）](/docs/model-list#86588b72) |见[结构化输出能力（beta）](/docs/model-list#86588b72) | |严格模式 |支持 |不涉及 | \ | |通过设置 **strict** 为 `true` 生效。 | | |配置方式 |```JSON |```JSON | \ | |"text": { |"text": { | \ | | "format": { | "format": { | \ | | "type": "json_schema", | "type": "json_object" | \ | | "name": "my_schema", | } | \ | | "strict": true, |} | \ | | "schema": { |``` | \ | | ... | | \ | | } | | \ | | } | | \ | |} | | \ | |``` | | ## 使用限制 * 使用[在线推理（TPM 保障包）](/docs/tpm-guarantee-package)时，不支持使用结构化输出能力。 * Responses API QPS 限流如下。如果需要提升限流值，请提交 [工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00001166)。 |接口名称 |账号维度的 QPS 限流 | |---|---| |创建模型响应 |无 | |查询模型响应 |20 | |列出输入项 |20 | |删除模型响应 |20 |