AI 结构化输出解析失败怎么办：从提示词到 JSON Schema 逐步定位

AI 接口接入业务系统时，很多团队都会要求模型返回 JSON：客服工单要提取分类和优先级，代码审查要返回风险列表，知识库问答要返回答案和引用。问题是，线上偶尔会出现解析失败：多了一句解释、少了必填字段，或者本来应该是数组却返回了字符串。

这类问题不能只靠“提示词写严一点”。更稳的做法是把结构化输出当成一条调用链来排查：提示词约束、JSON Schema、模型返回、解析层、业务兜底，每一层都要能看见证据。

问题现场：接口偶发解析失败

先看一个典型场景。工单系统把用户描述发给 AI，希望得到统一结构：

{
  "category": "billing",
  "priority": "high",
  "summary": "用户反馈重复扣费",
  "tags": ["支付", "退款"]
}

大多数时候返回正常，但偶尔会变成这样：

下面是整理后的结果：
{
  "category": "billing",
  "priority": "high",
  "summary": "用户反馈重复扣费",
  "tags": "支付,退款"
}

对人来说能看懂，对程序来说就麻烦了：前面多了一句文本，tags 类型也从数组变成了字符串。于是解析层报错，接口返回失败，用户只能重试。

初步判断：先分清是模型多说了，还是结构没收紧

排查第一步不是马上改提示词，而是把失败样本分类。常见有四类：

• 包装文本：JSON 前后多了说明、Markdown 代码块或备注。
• 字段缺失：必填字段没有出现，业务层拿不到值。
• 类型漂移：数组变字符串，数字变文本，布尔值变“是/否”。
• 枚举越界：优先级只允许 low/medium/high，却返回了 urgent。

如果主要是包装文本，说明返回通道没有强约束；如果主要是缺字段和类型漂移，说明 Schema 或字段描述不够明确；如果主要是枚举越界，说明枚举约束和业务兜底都要补。

动手验证：用最小样本复现返回差异

建议先准备 10 到 20 条最小样本，不要一上来跑全量数据。每条样本只保留触发差异的关键内容，例如：

[
  {"id": "case-001", "text": "我昨天已经付款，今天又扣了一次"},
  {"id": "case-002", "text": "订单已取消，但后台还显示待支付"},
  {"id": "case-003", "text": "发票抬头写错了，需要重新开"}
]

请求里同时记录三份信息：

• 输入文本：方便复现。
• 模型原始返回：不要只保留解析后的对象。
• 解析结果：成功、缺字段、类型错误、枚举错误。

只要把这三份信息放在同一条日志里，排查速度会明显提升。否则你只能看到“JSON 解析失败”，却不知道模型到底返回了什么。

定位原因：Schema 太宽和解析层太脆都会放大问题

结构化输出常见问题有两个方向：一边是约束太宽，一边是解析太脆。

约束太宽

很多请求只在提示词里写“请返回 JSON”，但没有告诉模型哪些字段必填、字段类型是什么、枚举范围有哪些。更稳的写法是把这些约束放进 JSON Schema：

{
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "tags"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "order", "invoice", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    },
    "summary": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

这里的关键点是：必填字段要写清，额外字段要控制，枚举值要收窄，数组和对象要写明层级。这样解析层拿到的对象更稳定，业务代码也不用猜字段含义。

解析太脆

另一类问题是解析层只做了一次 json_decode 或等价处理，失败就直接把错误抛给用户。生产环境里更稳的做法是：

• 先保存原始返回，方便排查。
• 解析失败时返回可控错误，不把模型原文直接暴露给终端用户。
• 对非关键场景可做一次重试，但重试提示词要更短、更明确。
• 对关键场景进入人工复核或规则兜底，不让错误对象直接落库。

修复方案：收紧 Schema、固定字段、保留兜底

我们可以把修复流程拆成四步。

第一步：提示词只写任务，不重复结构细节

提示词负责说明任务目标和业务语义，结构细节交给 Schema。这样避免提示词和 Schema 两处规则不一致。

你是工单分类助手。
根据用户描述判断工单类别、优先级，生成简短摘要和标签。
不要臆测用户没有提供的信息。

第二步：Schema 控制字段、类型和枚举

Schema 要尽量贴近业务对象。字段少而明确，比一次要求模型返回十几个字段更稳定。首次落地建议先控制核心字段，等成功率稳定后再增加派生字段。

第三步：解析层统一出错码

解析层不要把所有异常都叫“AI 失败”。建议区分：

• MODEL_REFUSED：模型拒绝回答或无法处理。
• BAD_JSON：返回无法解析成 JSON。
• SCHEMA_MISMATCH：字段或类型不符合 Schema。
• BUSINESS_REJECTED：结构正确，但业务规则不允许落库。

第四步：高风险结果进入人工复核

如果结构化输出会触发退款、封号、发券、审批这类动作，不建议只靠一次模型返回直接落库。可以先写入待确认状态，由人工或规则引擎复核后再进入下一步。

验证结果：看成功率、拒绝样本和回退路径

修复后不要只看“本次请求成功”。建议连续观察三类指标：

• 结构成功率：返回能通过 JSON 和 Schema 检查的比例。
• 类型错误数：字段类型不一致的次数是否下降。
• 回退路径命中：重试、人工复核、规则兜底是否按预期工作。

一个简单的上线检查表可以这样写：

样本集：覆盖正常、边界、空输入、长文本、含歧义描述
结构层：必填字段、枚举、数组、额外字段全部检查
日志层：输入、原始返回、错误码、追踪 ID 保留
业务层：高风险动作不直接落库
回退层：重试和人工复核路径可用

总结：把结构化输出做成可观测流程

AI 结构化输出解析失败，表面上是 JSON 不稳定，根因通常是调用链缺少约束和可观测性。提示词负责说明任务，Schema 负责固定结构，解析层负责统一错误码，业务层负责兜底和复核。

真正稳定的做法不是把提示词越写越长，而是把“输入、Schema、原始返回、解析结果、业务处理”串起来。这样下一次出现缺字段、类型漂移或包装文本时，你能快速判断问题落在哪一层，而不是在提示词里反复猜。