模型输出 JSON 缺字段时如何设计兜底解析

模型返回 JSON 后，某个字段缺失时不要直接用 dict.get() 全部填空。更稳妥的做法是把处理拆成三层：先判断 JSON 能否解析，再对允许缺失的可选字段归一化，最后校验必填字段和业务范围。可选字段可以降级，必填字段缺失则应返回明确的 degraded 状态或触发一次受控重试。

如果使用 OpenAI Structured Outputs，可以先查看官方文档：https://developers.openai.com/api/docs/guides/structured-outputs。官方文档区分了 JSON mode 与 Structured Outputs：前者只保证结果是合法 JSON，后者才用于约束输出符合给定 schema；应用层仍然要处理截断、拒答和业务语义不满足等情况。

先分清 JSON 缺字段到底是哪一类异常

同样是“拿不到结果”，根因可能完全不同。响应不是合法 JSON 时，问题在文本边界或生成过程；响应是对象但没有 answer，属于字段缺失；confidence 存在却是字符串，则属于类型错误；字段类型正确但置信度为 3，又是业务范围错误。四类问题不能共用一个空对象兜底，否则下游很容易把异常响应当成正常结果。

建议先给输出契约分级。answer 是必须有内容的核心字段，confidence 和 citations 可以在产品允许时使用默认值；未知字段可以忽略但应记日志。对于 null，不要自动等同于缺失，要根据字段约定决定它是“明确没有值”还是“不符合协议”。

用解析、归一化、验证三层承接模型输出

不要让业务代码同时负责解析字符串、补默认值和判断范围。下面的示例把三件事放进一个边界函数中，返回统一的状态和原因；它只是文章中的实现示例，不代表已经在本机执行。

import json

def parse_model_json(raw: str) -> dict:
    # 先处理语法边界，避免把不可解析文本当作空对象。
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        return {"status": "invalid_json", "reason": str(exc), "data": None}

    # 顶层必须是对象，数组或字符串无法直接映射到输出契约。
    if not isinstance(data, dict):
        return {"status": "invalid_shape", "reason": "top_level_not_object", "data": None}

    missing = [name for name in ("answer",) if name not in data]
    if missing:
        # 必填字段缺失时保留降级状态，不用默认文案制造成功假象。
        return {"status": "degraded", "reason": "required_missing",
                "missing_fields": missing, "data": None}

    confidence = data.get("confidence", 0.0)
    citations = data.get("citations", [])
    # 只给明确约定的可选字段补默认值，并记录补过哪些字段。
    if not isinstance(confidence, (int, float)) or isinstance(confidence, bool):
        return {"status": "invalid_type", "reason": "confidence_not_number", "data": None}
    if not 0 

这里的关键不是把代码写得更长，而是让每个返回状态都能被调用方消费。invalid_json 可以进入一次有限重试；degraded 交给上层决定是否展示“信息不完整”；invalid_type 和 invalid_value 则通常应记录样本并阻断下游写入。

默认值、降级和重试要按字段重要性分层

兜底解析最容易出错的地方，是把所有字段都当成可选。可以先用一张小表固定团队约定：

重试也要有边界：同一请求最多一次，重试提示只描述缺少的字段，不把原始响应无限拼回上下文。若连续出现同一字段缺失，应优先检查 schema、提示词和模型配置，而不是不断提高重试次数。

把兜底结果变成可追踪的业务信号

每次解析至少记录 status、missing_fields、defaulted_fields、schema 版本和重试次数；原始响应可能包含用户数据，不建议直接写入普通日志，可以保存脱敏后的摘要或哈希。监控上分别统计 JSON 解析失败、必填字段缺失、默认值命中和语义校验失败，才能判断是模型输出漂移，还是业务契约本身设计得太紧。

最后再做一次面向业务的检查：答案不能为空，置信度必须在 0 到 1 之间，引用项必须是字符串，数组长度和文本长度要符合产品上限。结构化输出能减少缺字段，但不能替代这些业务规则。稳定的兜底策略应让异常“可见、可解释、可恢复”，而不是让接口永远返回一个看似完整的 JSON。

常见问题

模型返回合法 JSON 但缺少字段，还需要重试吗？

不一定。可选字段可以直接补默认值；核心字段缺失时建议先返回降级状态，再根据成本和场景最多重试一次。

字段是 null 时能不能当成缺失处理？

要看协议。若 null 表示“明确没有值”，应保留并由业务处理；若字段不允许 null，则返回类型或语义错误，不要静默改成空字符串。

JSON mode 已经保证合法 JSON，为什么还要做 schema 校验？

合法 JSON 只解决语法问题，并不保证字段存在、类型正确或业务值有效。schema 校验和业务校验仍然要在应用边界执行。