结构化输出
response_format 的 json_schema 用法、严格模式（strict）语义、模型不支持时的失败回退建议，以及完整请求与响应 JSON 示例
平台数据平面兼容 OpenAI 规范的结构化输出：通过 response_format 声明一个 JSON Schema，约束模型必须返回符合该 schema 的 JSON，从而让您的应用稳定解析模型输出，免去对自由文本的脆弱正则抽取。本页说明 response_format 的 json_schema 用法、严格模式（strict）语义、模型不支持时的失败回退建议，以及完整示例。
适用场景。 当您需要把模型输出直接喂给下游程序（写库、调接口、填表单、做分类标注）时，结构化输出能把"模型返回什么形状"这件事固定下来，显著降低解析失败率。它常与 工具调用 配合：工具调用让模型"做动作"，结构化输出让模型"按格式给结论"。
1. response_format 用法
在 /v1/chat/completions 请求体中加入 response_format 字段，类型设为 "json_schema"，并在 json_schema 对象中给出 schema：
{
"model": "<模型名>",
"messages": [
{ "role": "system", "content": "你是一名严谨的工单分类助手。" },
{ "role": "user", "content": "把这条反馈归类并抽取要点：『登录后页面一直转圈，多次重试都进不去』" }
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "ticket_classification",
"strict": true,
"schema": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["功能异常", "性能问题", "使用咨询", "其他"]
},
"severity": {
"type": "string",
"enum": ["高", "中", "低"]
},
"summary": {
"type": "string",
"description": "一句话概括反馈要点"
}
},
"required": ["category", "severity", "summary"],
"additionalProperties": false
}
}
}
}json_schema 对象各字段：
| 字段 | 含义 |
|---|---|
name | 本结构的命名，便于您在多种结构间区分；建议用小写下划线命名 |
strict | 是否启用严格模式（见第 2 节）；建议置 true 以获得稳定结构 |
schema | 标准 JSON Schema 定义，描述期望返回的字段、类型与约束 |
三类常用约束。
enum限定取值集合（适合分类 / 枚举字段），required列出必填字段，additionalProperties: false禁止模型返回 schema 之外的多余字段。三者配合能把输出形状收得很紧。
2. 严格模式（strict）语义
strict 控制模型对 schema 的遵循程度：
strict | 语义 |
|---|---|
true | 严格模式：模型输出必须完全符合 schema——字段齐全、类型匹配、不含 schema 外的多余字段；适合直接喂给下游程序 |
false 或省略 | 宽松模式：模型尽力返回 JSON，但不保证逐字段严格符合 schema；适合容错性较高的场景 |
严格模式下的几点行为约定：
- 结构稳定可解析。 严格模式旨在保证返回内容为可解析的 JSON 且字段形状符合 schema，您的应用可直接
JSON.parse后按字段取值，无需对自由文本兜底。 - schema 需自洽。 严格模式要求 schema 本身规范、自洽（如
required字段须在properties中声明）；schema 不自洽可能导致约束无法生效。 - 配合 system 提示更稳。 建议在
system消息中简要说明任务与字段含义，与 schema 双重约束，进一步降低字段语义偏差。
3. 读取结构化响应
结构化输出的最终内容仍承载在标准 message.content 中，但其值为符合 schema 的 JSON 字符串：
{
"object": "chat.completion",
"model": "<本次实际路由的模型名>",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "{\"category\":\"功能异常\",\"severity\":\"高\",\"summary\":\"登录后页面持续加载，多次重试无法进入\"}"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0,
"cached_input_tokens": 0,
"price_tier": "<本次适用单价档>",
"thinking": false
}
}| 读取要点 | 说明 |
|---|---|
| content 为 JSON 字符串 | message.content 是 JSON 文本，需在本地 JSON.parse 后按字段使用 |
| 计量口径不变 | 结构化输出的输入 / 输出统一计价词元仍按常规 6 档口径 计量，与普通查询一致 |
| 可叠加流式 | 结构化输出可与流式（stream: true）配合，但分片中途的 JSON 可能不完整，须在所有分片拼接完成后再解析 |
4. 失败回退建议
并非所有模型都支持结构化输出 / 严格模式；同时，即便支持，也应在应用侧对解析做兜底。建议按以下顺序处理：
| 情形 | 建议处理 |
|---|---|
| 模型不支持结构化输出 | 以 模型列表接口 返回的能力标注为准选择模型；对不支持的模型，平台会按其能力据实处理，您应在应用侧改用提示词约束 + 容错解析 |
| 返回内容无法解析为 JSON | 本地 JSON.parse 失败时，回退到一次"重试请求"或宽松解析；不要把未校验内容直接写入下游 |
| JSON 可解析但字段不全 | 对缺失的 required 字段做默认值兜底，或携带原始反馈重试一次（可在 system 中强调字段必填） |
| 反复无法得到合规结构 | 降级为宽松模式（strict: false）+ 应用侧抽取，或改用 工具调用 让模型按函数参数 schema 产出结构化入参 |
务实策略。 把结构化输出当作"大幅提高合规率的手段"而非"100% 保证"。生产链路中始终保留一层应用侧校验与回退：先按 schema 解析，解析或校验失败再走重试 / 降级路径，确保下游不被异常结构污染。
5. 与工具调用的取舍
结构化输出与 工具调用 都能让模型产出结构化数据，适用场景不同：
| 您想要的 | 推荐 |
|---|---|
| 让模型直接给出一份固定形状的结论 JSON（分类、抽取、打分等） | 结构化输出（response_format） |
| 让模型决定调用哪个函数、传什么参数，由您执行后回填 | 工具调用（tools / tool_calls） |
| 既要模型调用外部能力、又要最终结论按固定结构返回 | 两者配合：工具调用取数 + 结构化输出收口结论 |