# 结构化输出

使用 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 模式示例 [#完整-json-模式示例]

设置 `GFW_API_KEY`。Python 示例依赖 `openai` 包，使用标准库校验输出，不需要额外的 Schema 校验库。



**cURL**


```bash
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
  }'
```



**Python**


```python
import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GFW_API_KEY"],
    base_url="https://api.gfw.net/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    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,
)
if not response.choices:
    raise RuntimeError("响应没有 choices")
choice = response.choices[0]
if choice.finish_reason != "stop":
    raise RuntimeError(f"输出未正常结束：{choice.finish_reason}")
content = choice.message.content
if not content:
    raise RuntimeError("响应没有文本内容")
result = json.loads(content)
if not isinstance(result, dict) or set(result) != {"title", "priority"}:
    raise ValueError("结果字段不符合约定")
if not isinstance(result["title"], str) or not result["title"].strip():
    raise ValueError("title 必须是非空字符串")
if result["priority"] not in ("low", "medium", "high"):
    raise ValueError("priority 值不符合约定")
print(json.dumps(result, ensure_ascii=False, indent=2))
```




## Schema 模式与响应字段 [#schema-模式与响应字段]

在已确认支持 Schema 模式的模型和通道上，可以将 `response_format` 替换为下面的请求片段。它是参数示意，不是所有模型都可使用的通用配置：

```json
{
  "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 响应或实际提取结果：

```json
{"title": "生产支付回调失败", "priority": "high"}
```

先检查 `finish_reason` 与可用内容，再执行 JSON 解析。若模型返回拒绝、空内容或工具请求，应用应进入对应分支；不要把这些情况当作空 JSON 成功。

## 校验与失败处理 [#校验与失败处理]

JSON 能解析不代表语义正确。应用至少检查必要字段、字段类型、枚举、长度与业务范围；重要结论还应回查原始输入。严格 Schema 也不能代替业务权限判断。

解析失败时保留脱敏后的错误原因与响应标识。可以在有界次数内重新请求，但应记录新增调用费用；不要通过无限重试掩盖模型或通道不支持参数的问题。未经明确规则，不要自动删掉代码围栏、补括号或随意修复字段，然后把结果标成符合 Schema。

流式 JSON 可能拆成任意文本片段。先收集完整内容再解析；逐片段解析或执行半成品对象，会让业务状态难以恢复。需要模型发出操作请求时，请使用 [工具调用](/docs/tool-calls)，不要把任意 JSON 字段直接执行成操作。

## 注意事项与相关文档 [#注意事项与相关文档]

某些模型只能遵守提示词，有些支持 JSON 模式，有些还支持 Schema。遇到参数错误，先核对能力与字段位置，不要降级后仍宣称“严格结构保证”。当前网关不提供跨模型一致的 Schema 校验承诺。

相关文档：[OpenAI 兼容 API](/docs/openai-api)、[Responses API](/docs/responses)、[流式输出](/docs/streaming)、[模型与能力](/docs/models)、[错误码与重试](/docs/errors)。