AI 接口 JSON 返回不稳定排查：从提示词到结构化输出

很多 AI 应用在 Demo 阶段看起来很顺：让模型“返回 JSON”，前端能解析，后端也能落库。可一到真实用户输入，问题就来了：有时多一句解释，有时字段名变了，有时数组里混进空对象，偶尔还会少一个必填字段。

这篇文章按一次排查过程来走：我们先复现“看似 JSON、实际不稳定”的现象，再一步步把输出约束收紧，最后用结构化输出和服务端校验兜住边界。

问题现场：明明要求 JSON，解析还是失败

假设我们做一个“文章摘要提取”接口，希望 AI 返回标题、摘要、关键词和风险提示。最开始的提示词可能是这样的：

请阅读用户输入的文章内容，并返回 JSON：
{
  "title": "标题",
  "summary": "摘要",
  "keywords": ["关键词"],
  "risk": "风险提示"
}

看起来很直观，但线上日志里经常出现几类问题：

• 返回体前面多了“下面是结果”。
• keywords 有时是字符串，有时是数组。
• risk 没有内容时被省略。
• 用户输入很长时，结果在中间截断。

这类问题最烦人的地方在于：它不是每次都失败。少量测试样本里能过，真实输入一多，解析失败和脏数据就会慢慢冒出来。

初步判断：普通提示词只是在“请求配合”

我们先看第一个猜测：是不是提示词写得不够明确？于是很多人会补一句“只返回 JSON，不要返回任何解释”。这一步有帮助，但它仍然只是自然语言约定，不等于机器可验证的接口契约。

更稳的思路是把问题拆成四层：

• 输出模式：要求模型朝 JSON 方向生成。
• 字段结构：要求字段名、类型、必填项固定。
• 服务端校验：接口收到结果后再次检查。
• 失败兜底：校验失败时重试、降级或返回明确错误。

这张链路图的重点是：不要把全部希望压在一句提示词上。提示词负责表达意图，结构约束和服务端校验负责把输出变成稳定数据。

动手验证：给结果加一层格式约束

如果接口提供 JSON 模式或类似能力，第一步可以先要求结果必须是 JSON 对象。这样至少能减少“多余解释文本”这类问题。

request_body = {
    "model": "gpt-4.1-mini",
    "input": [
        {
            "role": "user",
            "content": "请提取标题、摘要、关键词和风险提示，只返回 JSON。"
        }
    ],
    "text": {
        "format": {
            "type": "json_object"
        }
    }
}

但做到这里还不够。JSON 对象只说明“外形像 JSON”，并不保证 keywords 一定是数组，也不保证 summary 一定存在。

所以我们继续验证第二层：能不能把字段类型、必填字段和数组元素都写成明确 schema。

定位原因：缺少字段级约束和服务端校验

问题定位到这里就比较清楚了：普通提示词解决的是“模型是否知道你想要什么”，但接口稳定性需要解决“结果是否满足机器契约”。这两件事不是一回事。

例如下面这个 schema，把四个字段都固定下来：

{
  "type": "object",
  "additionalProperties": false,
  "required": ["title", "summary", "keywords", "risk"],
  "properties": {
    "title": { "type": "string" },
    "summary": { "type": "string" },
    "keywords": {
      "type": "array",
      "items": { "type": "string" }
    },
    "risk": { "type": "string" }
  }
}

字段级约束能把“看起来像 JSON”推进到“结构可预测”。但是，后端仍然不能完全跳过校验。原因很简单：接口可能返回拒答、截断、网络异常，也可能因为输入过长导致结果不完整。

修复方案：结构化输出加校验闭环

现在可以给出修复方案：请求时使用结构化输出能力，返回后用服务端模型做二次校验，失败时进入可控分支。

from pydantic import BaseModel, Field

class ArticleDigest(BaseModel):
    title: str = Field(min_length=1)
    summary: str = Field(min_length=1)
    keywords: list[str]
    risk: str

def parse_digest(raw_text: str) -> ArticleDigest:
    return ArticleDigest.model_validate_json(raw_text)

def handle_ai_result(raw_text: str):
    try:
        digest = parse_digest(raw_text)
        return {"ok": True, "data": digest.model_dump()}
    except Exception as err:
        return {
            "ok": False,
            "reason": "AI 返回结构未通过校验",
            "detail": str(err)[:200]
        }

这里的重点不是某个库，而是闭环：

• 请求侧：告诉模型必须按固定结构返回。
• 解析侧：只接受通过校验的数据。
• 失败侧：记录原因，允许重试或给用户明确提示。
• 存储侧：只保存通过校验后的结构化对象。

验证结果：用三类输入复查稳定性

修完后不要只用正常输入测试。建议准备三类样本：

如果三类输入都能得到可控结果，就说明接口稳定性已经从“希望模型听话”变成了“后端能验证并处理”。

总结清单

• 只写“请返回 JSON”不够，它更像提示，不是接口契约。
• 先用 JSON 输出模式减少多余文本，再用 schema 固定字段结构。
• 数组、必填字段、空字段和额外字段都要提前约束。
• 服务端必须做二次校验，不能直接相信 AI 返回体。
• 校验失败时要有重试、降级或明确错误，避免脏数据进入数据库。

一句话总结：AI 接口要稳定返回 JSON，关键不是把提示词写得更凶，而是把提示词、结构化输出、服务端校验和失败兜底连成闭环。这样接口才更像可靠的数据生产链路，而不是一次“看运气”的文本生成。