AI API 结构化输出总有空字段怎么办？
结构化输出偶尔出现空字段、字段串位或 JSON 可解析但业务不可用时，应从样本、schema、失败重放和人工复核四层定位。
- 站内相关：AI API JSON 解析契约怎么定
- 站内相关：开发者 AI JSON Schema 校验失败怎么修复
- AI API 接入专题
- Codex 安装与插件专题
- CCSwitch 配置专题
- AI 自动化办公专题
真实问题
很多团队把 AI API 接入跑通以后，会很快把输出结果交给业务系统处理。前几天看起来正常，样本一多就出现空字段、字段串位、数组长度不稳定、金额单位丢失等问题。最麻烦的是 JSON 本身可以解析，接口也返回 200，但后续表格、工单或审批流已经拿到错误数据。永沃云枢在 https://ai.jn83.com 的接入说明里一直建议把结构化输出当成业务契约，而不是把它当成普通文案的排版要求。
这个问题不只发生在开发者 AI 调用里，AI 自动化办公也很常见。比如从会议纪要提取负责人，模型把“待确认”写成空字符串；从发票备注里抽项目名，模型把项目名和部门名混在一起；用 Codex 接入做静态页生成时，标题、摘要和 canonical 字段缺一个，后面 sitemap 更新就会被迫返工。
适用场景
适合已经有 AI API 接入、AI 模型接口、模型调用管理后台或 CCSwitch 配置的团队。只要输出结果会进入数据库、表格、工单、CRM、知识库、PPT 或自动化脚本，就不能只看自然语言是否通顺，而要检查字段是否完整、类型是否一致、空值是否有业务含义。新手搜索“GPT 中转”时常把它理解成换一个接口地址，真正落地时还要把 schema、重试、日志和验收标准补齐。
操作步骤
第一步，整理 20 到 50 条真实样本，覆盖正常、缺字段、长文本、空输入、混合语言和异常格式，不要只用演示样本。第二步，把 schema 写清楚：字段名、类型、是否必填、枚举范围、日期格式、金额单位、数组最大长度都要明确。第三步，在请求日志里保存 prompt_version、schema_version、model、temperature、trace_id 和原始输入摘要，方便失败重放。第四步，对返回结果先做机器校验，校验失败不要直接重试三次，而要记录失败原因。第五步，把失败样本分成输入不清、schema 不清、模型能力不足、后处理缺失四类，再分别修。第六步，修复后用旧样本回归，不只看新样本通过率。
排错路径
如果字段经常为空，先看输入里是否真的有对应信息，再看提示词是否允许“无法判断”这种显式值。空字符串、null 和“未提供”在业务上不是一回事，建议统一成可枚举状态。如果字段串位，通常是 schema 描述太接近，或示例里把两个字段放在同一句话里。可以把字段说明改成互斥定义，并加入反例。如果数组忽长忽短，要明确“只输出证据存在的项目”，不要让模型补全。
如果接口偶发输出多余解释文字，先检查是否混用了自由问答 prompt 和结构化输出 prompt，再检查模型 profile 是否被 CCSwitch 或环境变量切到了旧配置。必要时参考站内的 JSON 解析契约和 Schema 校验修复文章，把解析、校验、重放拆成三步。
常见问题 / 避坑
问：只要 JSON 能解析是不是就算成功？不是。业务字段必须通过类型、必填、范围和证据检查。问：失败后自动重试能不能解决？只能解决少量偶发问题，不能掩盖 schema 设计不清。问：可以让模型自己修复自己的 JSON 吗？可以作为兜底，但修复前后都要保留 trace_id。问：字段缺失时要不要猜？涉及合同、金额、客户资料和审批时不要猜，应返回“无法判断”并进入人工复核。
检查清单
检查 schema 是否标明必填字段、枚举值、日期格式和金额单位。检查日志是否能按 trace_id 找到原始输入、模型名、版本和返回内容。检查校验失败是否会阻断写入，而不是带病进入业务库。检查 Codex 接入生成的页面是否同时包含 title、description、canonical、JSON-LD 和站内链接。检查 AI 自动化办公任务是否给人工复核留下入口。
验收标准
随机抽取 30 条历史失败样本，修复后字段完整率应明显提升，且不能增加新的串位问题。再抽取 10 条边界样本，确认空值、无法判断、证据不足都有稳定表达。最后模拟一次模型版本切换，确认 schema_version 和 prompt_version 可以让你定位是哪次配置导致波动。做到这些，结构化输出才从“看起来像 JSON”进入“可以接业务流程”的状态。
落地提醒
上线前还要把“谁来处理失败结果”写清楚。很多结构化输出事故不是模型第一次返回错，而是失败结果被脚本静默吞掉，第二天才在业务报表里暴露。建议给每类任务设置一个失败队列：低风险内容进入自动重试，高风险字段进入人工复核，明显 schema 不匹配的样本进入开发排查。复核人处理时只需要看到原始输入摘要、失败字段、校验规则和建议动作，不必翻完整日志。这样既能减少客服、运营和研发之间来回问，也能让后续模型版本升级有可比较的基线。对于永沃云枢这类需要长期维护的 AI API 接入场景，失败队列比一次性修提示词更可靠。