火山方舟
火山方舟
文档指南
请输入
调用
视频生成
工具调用
使用 Responses API
推理
训练
模型精调
Managed Agents
配置 Agent 环境
管理 Agent 上下文
高级能力
- 文档首页
火山方舟调用使用 Responses API结构化输出(beta)
复制全文
下载 pdf结构化输出(beta)
文档反馈
问问助手当需要模型输出程序可处理的标准格式（主要是 JSON）而非自然语言时，可开启结构化输出能力，以支持标准化处理或展示。
通过配置 text.format 对象，指定模型输出 JSON 格式，还可以通过定义 JSON 结构，限定模型输出字段信息。
相较于通过提示词控制模型输出 JSON 格式，使用结构化输出能力具有以下优势：
- 输出可靠：输出结构符合预期数据类型，包括字段层级、名称、类型、顺序等，避免必要字段缺失或枚举值幻觉。
- 使用简单：通过 API 字段定义输出格式，提示词更加简单，无需在提示词中反复强调或使用强约束措辞。
说明
该能力尚在 beta 阶段，受资源与平台负载影响，服务可用性可能随访问情况产生波动，请谨慎在生产环境使用。
支持模型
API文档
json_object 模式
这段代码展示了如何利用 Responses API 实现 JSON Object 结构化输出。
Curl
Python
Go
Java
OpenAI SDK
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": "根号三的近似值是多少"
}
]
}'
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)
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),
},
),
}
}
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();
}
}
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)
返回预览
{
"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
OpenAI SDK
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
}
}
}
}'
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)
返回预览
{
"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_schema | json_object |
生成 JSON 回复 | 是 | 是 |
可定义 JSON 结构 | 是 | 否 仅保障回复是合法 JSON |
是否推荐 | 是 | 否 |
支持的模型 | ||
严格模式 | 支持 通过设置 strict 为 true 生效。 | 不涉及 |
配置方式 | "text": { "format": { "type": "json_schema", "name": "my_schema", "strict": true, "schema": { ... } } } | "text": { "format": { "type": "json_object" } } |
使用限制
- 使用在线推理（TPM 保障包）时，不支持使用结构化输出能力。
- Responses API QPS 限流如下。如果需要提升限流值，请提交 工单。
接口名称 | 账号维度的 QPS 限流 |
接口名称 | 账号维度的 QPS 限流 |
创建模型响应 | 无 |
查询模型响应 | 20 |
列出输入项 | 20 |
删除模型响应 | 20 |
最近更新时间：2026.09.22 16:52:18
这个页面对您有帮助吗？
有用
有用
无用
无用