多模态模型输出为什么要做 Schema 校验：从字段漂移到重试边界

图片识别接口上线第二天，日志里出现了一个很容易被忽略的变化：模型仍然返回合法 JSON，但原本的 confidence 从数字变成了字符串，缺失的 items 也没有触发异常。解析成功不等于结果可用，应用必须在把结果交给下游前做一次明确的 Schema 校验。

更稳妥的边界是：先用 JSON.parse 处理语法，再用 Schema 校验结构，最后用业务规则判断内容是否值得接受；校验失败时只对可恢复错误重试。

为什么“能解析”仍然不够

多模态模型的输出通常同时受图片内容、提示词和服务端响应格式影响。只写 JSON.parse(text)，只能拦住少量语法错误；它不会告诉你 items 是否存在，也不会阻止 confidence 被写成 "0.92"。

JSON Schema 的价值在于把对象、数组、字符串和数字这些预期写成可执行约束。模型侧若支持结构化输出，可以把 Schema 作为生成约束；服务侧仍建议保留本地校验，因为业务规则往往比通用结构更具体。完成校验后，业务处理才有稳定输入。

const parsed = JSON.parse(text);
const result = validate(parsed, resultSchema);
if (!result.valid) {
  return retryOrReject(result.errors);
}

把输出拆成解析、结构和业务三道门

第一道门是语法：文本无法被 JSON.parse 读取时，说明响应不是可消费的 JSON。第二道门是结构：validate 应检查 items 为数组、label 为字符串、confidence 为数字，并拒绝未声明的关键字段。第三道门是业务：例如空数组可以是合法结构，却未必能完成订单审核。

这三道门要返回不同的错误类型。语法错误通常需要重新请求或转人工；字段类型漂移可以带着错误路径请求模型修正；置信度低于业务阈值时，重试未必有意义，应该进入人工复核。

重试边界要由错误决定

重试不是“模型没答好就再问一次”。重试前应保留原始响应、校验错误路径和请求关联号，限制次数并避免把同一张图片无限放大调用成本。对 items[0].confidence 的类型错误，可以把精确字段和期望类型放进修正提示；对业务值越界，则先确认规则是否合理。

如果模型平台提供严格 Schema 约束，它能减少结构漂移，但不能替代业务校验。比如 confidence 在 0 到 1 之间仍是业务语义，图片里的目标是否真的属于某个类别也需要独立证据。

上线前后的核对清单

• 记录模型原始文本和脱敏后的校验错误，不只记录“失败”。
• 为字段缺失、类型不匹配、未知字段和业务越界分别写测试。
• 设置最大重试次数、超时和人工复核入口。
• 监控 Schema 失败率、重试率与人工复核率，观察模型或提示词变更后的漂移。

常见问题

JSON.parse 成功后还需要校验吗？

需要。解析只覆盖 JSON 语法，字段存在性、类型和取值范围仍要由 Schema 与业务规则检查。

Schema 校验失败是否一定要重试？

不一定。可修复的字段缺失或类型错误适合有限重试，低置信度和业务不成立更适合人工复核或降级。

严格结构化输出能否替代服务端校验？

不能。它能降低结构漂移，但服务端还要校验版本兼容、业务阈值和下游安全边界。

把校验结果变成可观测信号

最后别只看模型请求是否返回 200。把 parse_error、schema_error、business_reject 和 manual_review 分开统计，版本发布时对比这些信号，才能看出问题来自提示词、模型输出结构还是业务规则。这样做，Schema 才不是上线前的一道形式检查，而是模型系统里的真实护栏。