结构化输出
使用 JSON 模式组织模型输出，并在应用层校验解析结果与业务字段。
选择输出约束方式
结构化输出适合数据提取、分类和需要机器读取的结果。先确认模型具备 JSON 输出能力，再确认所选通道接受 response_format。网关转发参数不等于网关替你验证输出。
可将约束分为三层：提示词说明字段，JSON 模式要求可解析 JSON，JSON Schema 模式进一步约束结构。各模型支持层级不同。本文的基础示例使用 GFW 模型 ID deepseek-v4-pro 与 json_object；请在接入时核对能力，不要将示例当作实时可用性证明。
端点与参数
| 字段 | 适用位置 | 说明 |
|---|---|---|
response_format.type=json_object | POST /v1/chat/completions | JSON 模式，要求模型及通道支持；不保证业务字段全部正确 |
response_format.type=json_schema | 同上，条件能力 | Schema 模式，是否支持以及支持哪些 Schema 关键字需单独确认 |
response_format.json_schema | Schema 模式 | 通常包含 name、schema 和可选 strict，不能宣称所有模型支持严格模式 |
messages | Chat Completions | 明确要求 JSON，列出字段、类型和未知值处理规则 |
max_tokens | Chat Completions | 为完整对象预留足够输出空间；上限过小可能截断 JSON |
stream | Chat Completions | 初次接入建议 false，收完整结果后再解析 |
POST /v1/responses 会透传顶层 response_format 至 Chat Completions。当前桥接未实现原生 text.format 的完整映射，使用 Responses 客户端时不能直接照搬所有官方参数。
完整 JSON 模式示例
设置 GFW_API_KEY。Python 示例依赖 openai 包，使用标准库校验输出，不需要额外的 Schema 校验库。
curl --fail-with-body --silent --show-error \
--max-time 120 \
https://api.gfw.net/v1/chat/completions \
-H "Authorization: Bearer ${GFW_API_KEY:?请先设置 GFW_API_KEY}" \
-H 'Content-Type: application/json' \
--data '{
"model": "deepseek-v4-pro",
"messages": [
{"role": "system", "content": "只输出 JSON 对象，字段仅有 title（字符串）和 priority（low、medium、high 之一）。"},
{"role": "user", "content": "提取工单：生产支付回调失败，需要立即处理。"}
],
"response_format": {"type": "json_object"},
"max_tokens": 256,
"stream": false
}'Schema 模式与响应字段
在已确认支持 Schema 模式的模型和通道上，可以将 response_format 替换为下面的请求片段。它是参数示意，不是所有模型都可使用的通用配置：
{
"type": "json_schema",
"json_schema": {
"name": "ticket_summary",
"strict": true,
"schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"priority": {"type": "string", "enum": ["low", "medium", "high"]}
},
"required": ["title", "priority"],
"additionalProperties": false
}
}
}HTTP 响应仍然是 Chat Completions 外层对象，业务 JSON 位于 choices[0].message.content 的字符串中。下面仅表示该字符串解析后的对象，不是完整 API 响应或实际提取结果：
{"title": "生产支付回调失败", "priority": "high"}先检查 finish_reason 与可用内容，再执行 JSON 解析。若模型返回拒绝、空内容或工具请求，应用应进入对应分支；不要把这些情况当作空 JSON 成功。
校验与失败处理
JSON 能解析不代表语义正确。应用至少检查必要字段、字段类型、枚举、长度与业务范围；重要结论还应回查原始输入。严格 Schema 也不能代替业务权限判断。
解析失败时保留脱敏后的错误原因与响应标识。可以在有界次数内重新请求，但应记录新增调用费用；不要通过无限重试掩盖模型或通道不支持参数的问题。未经明确规则，不要自动删掉代码围栏、补括号或随意修复字段，然后把结果标成符合 Schema。
流式 JSON 可能拆成任意文本片段。先收集完整内容再解析；逐片段解析或执行半成品对象，会让业务状态难以恢复。需要模型发出操作请求时，请使用 工具调用，不要把任意 JSON 字段直接执行成操作。
注意事项与相关文档
某些模型只能遵守提示词，有些支持 JSON 模式，有些还支持 Schema。遇到参数错误，先核对能力与字段位置，不要降级后仍宣称“严格结构保证”。当前网关不提供跨模型一致的 Schema 校验承诺。