API 怎么返回固定 JSON 字段？JSON mode、结构化输出与验收
要让程序接收固定 JSON 字段，应先确认所用模型和接口支持哪种输出约束，再分别验收语法、结构与事实。JSON 能解析，不代表字段齐全；字段齐全，也不代表从原文提取正确。下面用一份合成活动记录说明接收流程，附可下载样例；它们不是云岚API或上游模型的调用实测。官方文档核对日期为 2026 年 10 月 24 日。
先分清：返回的外壳是 JSON，还是回答内容是 JSON
API 响应外层可能已经是 JSON，里面装着请求标识、用量和生成内容。但在 Chat Completions 中，choices[0].message.content 通常仍是字符串。解析外层成功，只说明拿到了响应包，不能代替解析回答正文。Chat Completions 响应定义
如果你连第一条请求都没有跑通，先按接入起步教程确认地址、Key 和模型。已有可用 Key、只是正文缺字段或无法入库，则保留同一接口与模型，按本文检查，不必先更换服务。
选输出方式，别把三个名字当成同一种保证
| 方式 | 解决什么 | 接收端仍需做什么 |
|---|---|---|
| 提示词要求“只输出 JSON” | 告诉模型期望的表达格式 | 检查是否混入说明文字，以及字段、类型和事实 |
| JSON mode | 在支持的接口中约束 JSON 格式 | 检查完整性和业务所需 schema |
| Structured Outputs | 在支持范围内按指定 schema 约束输出 | 处理拒绝、未完成状态，并核对业务事实 |
OpenAI 文档区分 JSON mode 与 schema 约束：Chat Completions 使用 response_format，Responses 使用 text.format；支持的 schema 也有范围限制。不要把两个接口的参数层级直接互换。官方结构化输出指南
厂商名称相似，配置不一定相同。例如 DeepSeek 的 JSON Output 文档要求设置 json_object，提示中包含 json 并给出期望示例，同时提示可能出现空内容或截断；这些不能被解释成任意 schema 都有保证。DeepSeek JSON Output
先写合格标准，再填请求参数
假设输入只有一句：“活动在苏州举行，共 18 人报名。”应用需要两个字段：城市 city 和报名人数 attendees，不接受额外字段。期望结果为：
{"city":"苏州","attendees":18}
下面是自定义的 Chat Completions 请求参数片段，不是完整请求。它只示范结构，不含模型、messages、地址或密钥；实际使用前须核对所选模型与服务的兼容说明。
{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "event_registration",
"strict": true,
"schema": {
"type": "object",
"properties": {
"city": {"type": "string"},
"attendees": {"type": "integer"}
},
"required": ["city", "attendees"],
"additionalProperties": false
}
}
}
}
这份 schema 规定形状，没有把“苏州”和“18”写死。返回另一个城市仍可能通过结构校验，因此不能把 schema 通过当成提取准确。真实业务还应先定义缺信息时的处理方式：例如退回待补充，或在接口允许的 schema 中明确使用 null；不要把未知人数自动填成零。
若目标是让模型选择工具、生成工具参数并完成执行回传，转到工具调用流程。这里的目标是程序接收一份最终数据记录。
接收端按顺序过四道检查
第一步检查响应状态。遇到拒绝、未完成或空内容，进入独立分支，不直接访问业务字段。不要给截断文本补上右括号就当成功；补齐语法也不能恢复丢失的信息。拒绝与未完成处理说明
第二步解析生成正文。只检查它是不是完整 JSON；说明文字、代码围栏和半段字符串都应留作诊断信息。默认保留原输出，不要用正则截取第一个大括号后静默覆盖原始结果。
第三步用成熟的 JSON Schema 校验库检查字段与类型。下载包使用 jsonschema 的 Draft 2020-12 校验本地样例；这是本地验收选择，不表示每个模型接口实现完整 Draft 2020-12。不要用“有两个键”代替类型、必填项和额外字段检查。校验库文档
第四步回到原文核对事实。本例必须是苏州、18 人。正式任务可以逐条标注一小组代表输入，再比较每次结果；明确记录样本数，不能凭单次通过推算总体准确率。
| 合成输出 | JSON 语法 | 本例 schema | 原文事实 |
|---|---|---|---|
{"city":"苏州","attendees":18} |
通过 | 通过 | 通过 |
{"city":"苏州"} |
通过 | 不通过：缺字段 | 不进入下一步 |
{"city":"苏州","attendees":"18"} |
通过 | 不通过：字符串代替整数 | 不进入下一步 |
{"city":"杭州","attendees":18} |
通过 | 通过 | 不通过：城市不符 |
失败后先定位，再决定是否重试
| 现象 | 优先核对 | 下一步 |
|---|---|---|
| 参数或 schema 被拒绝 | 接口路径、参数层级、模型支持范围 | 修改请求配置，保留错误，不原样循环重试 |
| 正文为空或只收到半段 | 结束状态、输出上限、传输是否完成 | 先查用量与请求记录，再决定重发 |
| JSON 合法但缺字段或类型错 | 实际启用的模式、schema 是否传入 | 保留失败样本，修正后再验收 |
| 字段完整但内容错误 | 输入是否含答案、字段定义是否歧义 | 改规则或交人工处理，不能只调格式参数 |
流式接收时，一个片段不等于完整 JSON 文档；可以使用相应 SDK 的结构化流处理能力，最终入库仍要确认完成状态。若是连接中断、鉴权或限流问题，按常见报错排查定位。
重试应有次数和费用上限。记录“首次失败、修改原因、最终结果”三项；别只留下最后一次成功，把重试费用也算入任务成本核对。
下载一组样例，给自己的接口留验收记录
下载离线验收样例包含合成原文、schema、合格与不合格输出及预期结果。它用于检查你的接收逻辑是否分清各类失败，不需要 API Key，也不会访问服务。
再下载空白 JSON 输出验收记录 CSV，填写日期、服务、接口、模型、模式、schema 版本、结束状态、三层检查与重试次数。未知项留空，记录中不要放 Key 或敏感原文。把真实请求结论与合成样例分开保存。
云岚API的具体分组、模型和协议是否透传某项约束，应以当期说明和对应请求验证为准。一次普通聊天成功，不能证明结构化输出兼容；换模型、分组或接口后也应复验。需要安排完整能力检查时，可接着使用任务验收方法。
常见问题
提示词写“只输出 JSON”就够了吗？
它可以表达要求，但接收程序仍须检查实际结果。已有接口支持 schema 约束时，按文档配置；只支持 JSON mode 时，也应保留结构和事实验收，不能省略错误分支。
把 temperature 设为零能保证固定字段吗？
不要把生成参数当字段校验。即使输出看起来更稳定，也没有替代必填项、类型和原文核对；是否接受该参数还取决于模型与接口。
字段不存在时返回空字符串还是 null？
先按业务定义区分“未知”“空值”和“确实为零”，再让 schema、提示词和数据库保持一致。本页样例只处理信息齐全的一句原文，不规定所有业务的缺失值策略。
云岚API的所有模型都支持 strict 吗？
不能据此断言。本文核对的是官方能力与本地样例，没有对云岚API全部模型、分组逐项测试。请记录实际协议和模型，先确认支持范围，再验证结果与失败行为。
流式返回 JSON 时，先确认输出是否完整
网络读取的一块数据可能只有半个事件或部分文本。先按 API 流式输出的组装与完成判断收集完整输出，再执行本篇的语法、结构与事实验收；不能把局部可解析的片段直接当成整次请求已完成。
多份结果或 PDF 来源，需要再验哪一层？
逐条 JSON 合格之外，异步 Batch 结果对账还要按请求标识检查重复、失败与缺项；从文件提取字段时，PDF 页码与证据验收负责把字段对应回原文。输出结构和来源事实分别留下记录，不能相互替代。