AI 结构化输出怎样处理字段缺失

AI 结构化输出出现字段缺失时，先不要在业务代码里用一串默认值“补齐”所有字段。更稳妥的做法是：用 JSON Schema 写清必填字段，把可选字段单独定义为可缺失；收到模型结果后先解析，再检查必填字段，缺失就进入异常或重试路径，可选字段才使用明确的默认值。

官方地址：https://huggingface.co/docs/inference-providers/en/guides/structured-output

处理字段缺失不要硬逼大模型凭空生成不存在的内容，优先对齐业务侧的空值规则，再搭配多层校验拦截异常结果，就能在不污染最终数据的前提下，尽可能降低人工复核成本。

把字段合同写进 JSON Schema

字段缺失通常不是一个单纯的解析异常，而是“输出合同没有写清”或“调用链某一层没有兑现合同”。先把结构拆成三部分：properties 写字段和类型，required 写必填集合，默认值策略留在业务层。不要把默认值直接当成模型已经返回的事实。

{
  "type": "object",
  "properties": {
    "answer": {"type": "string"},
    "confidence": {"type": "number"},
    "citations": {"type": "array", "items": {"type": "string"}},
    "language": {"type": "string"}
  },
  "required": ["answer", "confidence"],
  "additionalProperties": false
}

这个 schema 表示 answer 和 confidence 是最低交付合同，citations 与 language 是否出现要由调用方决定。若把四个字段都放进 required，模型就必须提供四个字段；若只放两个，应用就不能把另外两个字段当成必然存在。

严格结构化输出不等于业务字段永远齐全

Hugging Face 的 Inference Providers 文档将结构化输出描述为按 JSON Schema 返回结果，并示例了 response_format、schema 名称、strict 和模型调用。这个能力的价值是把字段形状前移到接口合同，但文档同时提醒要关注模型与 provider 的兼容性。工程上应把“schema 已声明”和“业务对象已可用”视为两个不同边界。

response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "AnswerContract",
        "schema": schema,
        "strict": True,
    },
}

# 选择支持该 response_format 的模型与 provider，避免把兼容性问题留给业务层猜测。
response = client.chat_completion(
    model="your-model",
    messages=messages,
    response_format=response_format,
)

# 结构化响应通常仍以字符串形式返回，先解析成对象再检查字段。
payload = json.loads(response.choices[0].message.content)

如果 provider 不支持该格式、模型没有兑现严格合同，或者上游对 schema 做了裁剪，仍可能看到缺字段、类型不符或额外字段。不要因为接口名称里有 structured 就跳过应用层的合同检查。

在解析边界区分必填缺失和可选缺失

缺失处理应该集中在模型响应刚解析完成的位置。必填字段缺失时，保留原始响应、记录 provider 和模型信息，并返回可追踪的异常；可选字段则通过显式策略补默认值。这样既不会把不完整回答伪装成完整结果，也不会让下游到处写 if key in payload。

import json

REQUIRED_FIELDS = {"answer", "confidence"}


def normalize_payload(raw_content: str) -> dict:
    # 先解析 JSON；语法错误和字段缺失属于两类不同问题，分别上报。
    payload = json.loads(raw_content)
    missing = sorted(REQUIRED_FIELDS.difference(payload))
    if missing:
        # 必填字段缺失不能静默补空字符串，交给上层隔离或重试。
        raise ValueError(f"结构化输出缺少必填字段: {missing}")

    # 可选字段才使用业务明确的默认值，并保持默认值类型稳定。
    payload.setdefault("citations", [])
    payload.setdefault("language", "unknown")
    return payload

这里的关键是默认值的范围：citations 缺失可以解释为“没有引用”，但 answer 缺失不能随意解释为“空答案”。如果业务确实允许空答案，也要在 schema 和领域模型中明确写出这种语义，而不是靠解析器顺手补值。

把缺字段原因分成三层

排查时可以按合同层、供应层、应用层分组，而不是只盯着最后的 Python 异常：

• 合同层：required 是否真的包含业务必填字段，字段名和类型是否与业务对象一致。
• 供应层：当前模型和 provider 是否支持指定的结构化输出格式，返回内容是否被截断或被中间适配层改写。
• 应用层：解析代码是否把可选字段误当必填，或把必填字段缺失静默改成空值。

三层中，只有应用层适合放默认值。合同层应修正 schema，供应层应更换兼容的模型或 provider，不能用默认值掩盖配置不兼容。

用一个最小样例确认合同没有被吞掉

最小验证不需要跑完整 RAG 或 Agent 链路，只要准备“完整响应”“缺少可选字段”“缺少必填字段”三类样例，确认它们分别落到正常对象、默认值和异常隔离路径。测试断言应关注字段是否存在、类型是否正确，以及原始内容是否仍可追踪。

cases = [
    {"answer": "ok", "confidence": 0.9},
    {"answer": "ok", "confidence": 0.9, "language": "zh"},
    {"confidence": 0.9},
]

for case in cases:
    # 用 JSON 序列化模拟 provider 返回内容，不把测试写成对真实服务的依赖。
    raw = json.dumps(case, ensure_ascii=False)
    try:
        normalized = normalize_payload(raw)
        print("accepted", sorted(normalized))
    except ValueError as exc:
        # 必填缺失只记录可定位的异常，不生成伪造的业务答案。
        print("quarantined", exc)

这组样例的目的不是证明某个模型永远不会漏字段，而是把应用边界的行为固定下来。真实接入时，再把 provider、模型标识、请求 ID 和原始响应摘要写入可检索日志，同时避免把 token、隐私文本或完整敏感提示词直接打进日志。

常见问题

把所有字段都放进 required 能彻底解决缺失吗？

不能。它能明确合同，但模型、provider、适配层和截断仍可能造成调用失败或不完整响应；应用层仍应保留解析与隔离路径。

可选字段缺失时都应该用空字符串吗？

不应该。数组用空数组、布尔值用明确布尔语义，无法表达时宁可保留缺失；默认值要与业务含义和字段类型一致。

为什么不在 prompt 里说“不要漏字段”就结束？

自然语言提醒不能替代结构合同。prompt 可以解释任务，JSON Schema 负责字段形状，应用解析器负责最后的异常边界。