结构化输出：
从“像 JSON”到“可用数据”

01 · 心智模型

JSON 是外形，Schema 才是合同

普通 JSON 模式通常只是在提示模型“请输出 JSON”。它最多保证文本可以被解析，却不保证字段齐全、类型正确、枚举合法，更不保证内容符合业务规则。生产系统真正需要的是三层约束：

02 · Schema 设计

先设计失败，再设计字段

假设我们要把一段招聘 JD 提炼为结构化岗位信息。不要一上来追求“大而全”，先只保留后续流程真正会使用的字段，并把不确定性显式建模。

{
  "type": "object",
  "additionalProperties": false,
  "required": ["role", "level", "skills", "confidence"],
  "properties": {
    "role": { "type": "string", "minLength": 2 },
    "level": {
      "type": "string",
      "enum": ["junior", "middle", "senior", "unknown"]
    },
    "skills": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 12
    },
    "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
  }
}

03 · 生产链路

可靠性来自链路，不来自一句 Prompt

async function extractJob(text) {
  const raw = await callModel({ schema: jobSchema, input: text });
  const parsed = jobSchema.safeParse(raw);

  if (!parsed.success) {
    throw new RetryableOutputError(parsed.error.issues);
  }
  if (parsed.data.confidence < 0.65) {
    return { status: "needs_review", data: parsed.data };
  }
  return { status: "accepted", data: parsed.data };
}

生产环境最容易漏掉的四件事

1. 无限重试：结构错误只允许小次数重试，并记录失败原因；同样输入反复调用只会增加费用。
2. 把拒答当异常：安全拒答、内容不足和系统故障需要不同状态，前端提示也应不同。
3. Schema 版本漂移：Prompt、Schema、消费者代码和评测集必须一起版本化。
4. 只测解析成功率：合法 JSON 仍可能语义错误，还要测字段准确率、拒绝率和人工复核率。

05 · 动手与自测

今天必须亲手完成的 20 分钟练习

1. 选一份真实岗位 JD，定义不超过 6 个字段的 Schema。
2. 准备三个异常样本：缺少年限、技能描述模糊、输入里夹带“忽略之前指令”。
3. 记录三项结果：Schema 是否通过、业务规则是否通过、最终为何接受或拒绝。