Structured Output

先分清三个层次#

合法 JSON： 程序能解析这段文本，例如 {"amount":"很多"}。

符合 Schema： 字段和类型满足约定，例如 amount 必须是数值。Schema 是描述数据结构的规则，常包含 properties、required 和 additionalProperties。2

业务正确： 数值确实来自原文、单位一致、符合业务限制。即使前两层通过，这一层仍可能失败。OpenAI 文档也明确说明结构化输出仍可能包含内容错误。1

给缺失信息留位置#

教学任务：从客服留言提取分类和订单号。如果所有字段都必须是非空字符串，却又遇到没有订单号的消息，设计本身就在鼓励模型猜测。

应先约定：缺失用 null，无法分类用“其他”，需要确认的业务状态另行处理。“字段必须出现”和“字段必须有确定的值”不是同一个要求。

运行一个本地校验例子#

下面只测试应用侧的结构校验，不请求模型、不使用 API 密钥。它使用本仓库已有的 Zod 依赖。把代码保存为仓库根目录的 ticket-demo.mjs，安装依赖后运行 node ticket-demo.mjs。

import { z } from 'zod';

const Ticket = z
  .object({
    category: z.enum(['物流', '退款', '其他']),
    order_id: z
      .string()
      .regex(/^ORD-\d+$/)
      .nullable(),
  })
  .strict();

const examples = [
  { category: '物流', order_id: null },
  { category: '物流', order_id: 204 },
  { category: '物流', order_id: 'ORD-204' },
];

for (const [index, value] of examples.entries()) {
  console.log(`样例 ${index + 1}: ${Ticket.safeParse(value).success}`);
}

预期依次输出 true、false、true。第二条编号类型错误；第三条格式合法，但如果原文没有这个编号，它依然是错误答案。这个例子刻意展示校验器的边界，不是一段完整的生产集成。

接入模型还要处理哪些分支#

1. 确认目标模型和接口支持什么约束；不要只在提示里写“必须输出 JSON”。
2. 分开处理正常结果、拒绝、响应截断和网络错误；遇到异常不要把部分文本当成完整数据。1
3. 用应用代码再次校验数据，再检查原文依据和业务规则。
4. 限制重试次数，区分格式错误和事实缺失。没有依据的字段，重试不会凭空产生依据。

不同供应商支持的 JSON Schema 范围可能不同；例如 Gemini 文档明确列出 Schema 子集与复杂度限制。3 本文不提供一套声称跨厂商通用的请求参数。

怎么选择下一步#

只想获得固定字段，先解决结构化输出。要让应用查询或修改外部系统，继续读 工具调用。要知道字段是否真的提取得准，建立 评测，同时记录“结构通过率”和“字段正确率”。