AI 结构化输出如何区分拒答和空结果：finish_reason、schema 校验与用户提示

接入 AI 结构化输出时，最容易误判的是“解析成功但结果为空”。一个合法的空数组可能表示确实没有命中；拒答可能没有业务字段；而 finish_reason 为长度限制时，半截 JSON 甚至不该进入业务层。把这三种状态混成“无结果”，用户会看到错误提示，重试逻辑也会变得不可控。

先看生成状态，再看拒答字段，最后做 JSON Schema 校验；只有三关都通过，才把结果交给业务代码。

为什么“空结果”不能只看 JSON 字段

以“从合同中找出付款节点”为例，模型可能返回 {"items":[]}，也可能返回拒答说明，还可能因为输出过长停在 items 字段中间。三者在日志里都可能出现“没有业务数据”，但处理方式完全不同。

OpenAI 的 Responses API 文档把结构化输出配置为 json_schema，并提供拒答事件与响应状态字段。这个事实只说明接口能表达不同的结束状态，不代表应用可以跳过自己的业务判定；应用仍应把原始响应转换成稳定的内部状态。

先用 finish_reason 判断生成是否完整

解析器入口只做一件事：读取 finish_reason。值为 stop 时，生成正常结束；值为 length 时，优先标记为截断；其他状态先进入未知分支，不要猜测成空结果。

type OutputState string

const (
    StateComplete OutputState = "complete"
    StateTruncated OutputState = "truncated"
    StateUnknown OutputState = "unknown"
)

func stateFromFinishReason(finishReason string) OutputState {
    switch finishReason {
    case "stop":
        return StateComplete
    case "length":
        return StateTruncated
    default:
        return StateUnknown
    }
}

这里的 StateComplete 只是“生成过程结束得正常”，不是“业务内容有效”。例如服务端返回了空字符串，下一关仍然要拦截。

拒答和合法空结果要走两条路

生成完整后，再读取响应中的拒答信息。拒答分支不应尝试把拒答文本强行反序列化成业务对象；它需要一条安全、明确的用户提示。没有拒答时，才把内容交给 JSON Schema 校验。

type ParsedResult struct {
    Items []string `json:"items"`
}

type Decision struct {
    Kind string
    Hint string
    Data ParsedResult
}

func classify(refusal string, finishReason string, raw []byte) Decision {
    if finishReason != "stop" {
        return Decision{Kind: "truncated", Hint: "请缩小问题范围后重试"}
    }
    if refusal != "" {
        return Decision{Kind: "refusal", Hint: "请换一种不涉及敏感内容的问法"}
    }
    var data ParsedResult
    if err := json.Unmarshal(raw, &data); err != nil {
        return Decision{Kind: "schema_invalid", Hint: "结果格式不完整，请稍后重试"}
    }
    return Decision{Kind: "valid", Data: data}
}

为了让这段判断稳定，refusal、finish_reason、ParsedResult 和 json.Unmarshal 都应该进入结构化日志。日志保存原始响应时要注意脱敏，不要把用户合同、密钥或个人信息原样写入公共日志。

JSON Schema 校验通过后，空数组才是业务结果

如果响应没有拒答，且 JSON Schema 校验成功，items: [] 可以被视为合法业务结果。此时页面可以显示“没有找到付款节点”，但不要显示“模型失败”。如果校验失败，保留 schema_invalid 状态，让监控知道这是协议问题而非检索无命中。

常见误区与上线前检查

把空数组直接当成接口失败

空数组是数据层的一个合法值。只有当它和拒答、截断或校验失败同时出现时，才需要升级为异常。

遇到解析错误就无限重试

截断通常需要缩短输入或提高输出预算；拒答需要改变请求边界。盲目重试既浪费额度，也可能重复触发同一问题。

只记录最终提示，不记录判定依据

至少记录脱敏后的 finish_reason、是否有 refusal、schema 校验结果和内部状态，才能定位“页面显示无结果”的真实原因。

相关问题

finish_reason=stop 就一定有合法 JSON 吗？

不一定。它只代表生成正常结束，仍需做 JSON 解析与 JSON Schema 校验。

合法空数组要不要重试？

通常不要。先向用户说明没有命中；只有用户扩大条件或改变问题后，才发起新的请求。

拒答文本可以展示给用户吗？

可以做安全、简短的解释，但不要把内部策略、原始提示或敏感上下文直接回显。

为什么要保存原始响应？

它能帮助区分供应商状态、解析器问题和业务映射错误，但必须先做字段脱敏和访问控制。

把三种状态接到同一条产品链路

稳定的处理顺序是：读取 finish_reason，检查拒答，再验证 schema，最后映射业务字段。这样既能把合法空结果正常呈现，也能把截断和拒答转成用户可执行的下一步，监控指标还会保留足够的诊断信息。