AI 应用怎样让结构化输出失败时安全回退

AI 应用调用结构化输出时，最危险的误区不是“模型返回了普通文本”，而是“返回了符合 JSON Schema、却不符合业务含义的数据”。更稳妥的做法是把处理分成两层：先让 Gemini 按 schema 生成 JSON，再在应用端做字段和业务规则校验；任意一层失败，都进入带状态的回退对象，不把原始回答直接写入订单、工单或数据库。

官方地址：https://ai.google.dev/gemini-api/docs/structured-output

先把结构化输出和业务可信度分开

Gemini 的结构化输出可以通过 application/json 和 JSON Schema 约束响应形状，支持对象、数组、字符串、数字、布尔值等类型。它的边界也很明确：schema 是受支持的子集，部分长度或数量约束不会由服务端强制执行；即使 JSON 能解析，字段内容也可能不符合你的业务规则。

例如，工单分类结果可以要求 category 是字符串、priority 是枚举，但“priority 为 high 时必须有 evidence”属于业务规则，应该在应用端检查。建议把结果状态分成 accepted、pending_review 和 failed，不要用一个空对象掩盖三种情况。

先封装一次结构化调用

下面的示例使用 Python GenAI SDK。schema 只保留抽取所需字段，避免把不必要的嵌套、超长枚举和复杂约束一起交给模型。代码中的 model.generate_content 只负责得到候选结果，真正进入业务流程前还要经过本地校验。

import json
import os
from dataclasses import dataclass
from typing import Any

from google import genai
from google.genai import types


@dataclass
class Candidate:
    # state 用来区分可入库结果、待审核结果和系统失败。
    state: str
    data: dict[str, Any] | None
    reason: str | None = None


SCHEMA = {
    "type": "object",
    "properties": {
        "category": {"type": "string", "description": "工单分类"},
        "priority": {"type": "string", "enum": ["low", "normal", "high"]},
        "evidence": {"type": "string", "description": "支持分类判断的原文依据"},
    },
    "required": ["category", "priority", "evidence"],
}


def request_structured(text: str) -> Candidate:
    # 只从环境变量读取密钥，避免把凭据写进代码或文章。
    client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
    try:
        response = client.models.generate_content(
            model="gemini-2.5-flash",
            contents=f"请从工单中抽取分类、优先级和依据：\n{text}",
            config=types.GenerateContentConfig(
                response_mime_type="application/json",
                response_schema=SCHEMA,
            ),
        )
        # JSON 可解析只代表语法成立，下一步还要检查业务规则。
        data = json.loads(response.text)
        if not isinstance(data, dict):
            return Candidate("pending_review", None, "root_not_object")
        if not data.get("category") or not data.get("evidence"):
            return Candidate("pending_review", data, "required_value_empty")
        if data.get("priority") == "high" and len(data["evidence"]) 

回退时返回状态，不要回退成“看起来像成功”

结构化请求失败后，可以根据失败类型做有限重试：网络超时或临时服务错误适合使用相同请求标识重试；schema 被拒绝则应简化 schema；解析或业务校验失败则应进入审核队列。无论哪一种，都不要把模型的原始文本拼进 SQL、订单字段或自动执行参数。

def safe_extract(text: str, request_id: str) -> dict[str, Any]:
    # accepted 才允许下游写入业务表，其余状态只进入审核队列。
    result = request_structured(text)
    if result.state == "accepted":
        return {
            "request_id": request_id,
            "state": "accepted",
            "data": result.data,
        }

    # 回退对象保留失败原因和原文引用，方便人工判断或受控重放。
    return {
        "request_id": request_id,
        "state": "pending_review" if result.state != "failed" else "failed",
        "data": None,
        "reason": result.reason,
        "raw_text_ref": f"review://ai-output/{request_id}",
    }

这里的 raw_text_ref 只是审计存储的引用，不代表要把完整原文返回给业务消费者。生产环境应限制访问权限、设置保留期限，并让人工审核或重放任务通过 request_id 找到原始请求和响应。

用失败阶段决定重试和告警

告警也要按阶段区分：短时 API 错误适合观察错误率和重试成功率；业务校验失败持续升高，通常说明输入分布、schema 或业务规则发生了变化。不要用“回退成功”掩盖“自动处理率下降”，这两个指标应该分别统计。

常见问题

结构化输出已经符合 schema，还需要校验吗？

需要。schema 主要约束响应的结构和类型，不能替你判断字段是否真实、完整或满足业务规则。

能不能把失败响应再 JSON.parse 一次？

可以把它作为受控诊断，但不能把解析成功当成业务成功。解析失败、字段缺失和语义不合格都应进入待审核或失败状态。

什么情况下应该重试？

网络超时、临时服务错误等可重试错误适合有限退避重试；schema 过复杂、业务规则不满足或内容本身不可判定时，应先修配置或转人工。