结构化输出

使用 JSON Schema 和 Zod 约束模型输出,并正确处理拒绝和不完整响应。

🎯 引言

假设后台需要根据一段商品描述,自动填写“商品名、类别、价格”三个字段。如果模型返回的是“这是一款价格约 199 元的鼠标”,前端还得想办法从自然语言里提取信息;而且不同回答的格式可能不一样。

我们需要的不是一段好看的文字,而是 能被程序直接读取的对象。本文将使用 OpenAI 官方 SDK 的结构化输出能力,生成符合指定格式的数据。


🧱 为什么只要求“请返回 JSON”还不够

你可以在提示词里写“只返回 JSON”,但模型仍可能多输出解释、遗漏字段,或者返回不符合预期的数据类型。即使字符串可以 JSON.parse(),也不意味着它符合业务约定。

例如程序期望:

{
    "name": "无线鼠标",
    "category": "数码",
    "price": 199
}

下面这种结果也是合法 JSON,却不符合业务结构:

{
    "title": "无线鼠标",
    "price": "199元"
}

因此要把两个步骤区分开:模型按照结构约束生成,以及 应用判断结果是否满足业务要求。


🛠 使用 Zod 定义字段

沿用项目中的 Node.js 24.x、openai@7.62.0,本篇额外安装 zod@4.1.0:

npm install --save-exact zod@4.1.0

创建 05.structured.mjs:

import OpenAI from "openai";
import { z } from "zod";
import { zodTextFormat } from "openai/helpers/zod";

const client = new OpenAI();

const Product = z.object({
    name: z.string(),
    category: z.enum(["数码", "家居", "服饰"]),
    price: z.number()
});

const response = await client.responses.parse({
    model: process.env.OPENAI_MODEL,
    input: "商品信息:黑色无线鼠标,属于数码产品,售价 199 元。请提取字段。",
    text: {
        format: zodTextFormat(Product, "product")
    }
});

if (response.status !== "completed" || !response.output_parsed) {
    throw new Error("没有得到完整且可解析的商品数据");
}

console.log(response.output_parsed);

这段代码的重点有三个:

  1. z.object() 定义一个商品对象,写清每个字段的类型。
  2. zodTextFormat(Product, "product") 把 Zod 结构转换为模型接口可使用的输出格式。product 是本次结构的名称。
  3. responses.parse() 在请求后尝试解析结构化结果,output_parsed 是可直接读取的对象。

这里的 price 是数字 199,而不是字符串“199元”。生成结构化结果并不代表价格一定真实,本文只是从给定文本中提取信息,不做商品事实核验。


🧱 结构约束与业务校验不是同一件事

结构约束能帮助模型返回符合 Schema 的字段,但你的业务可能还有其他条件,例如价格必须大于零、商品类别必须存在于数据库中。

我们可以在拿到对象后进行业务校验。下面的片段 接在上面 response 的示例后面,不是一个独立文件:

const product = response.output_parsed;

if (product.price <= 0) {
    throw new Error("商品价格必须大于零");
}

console.log("可以保存:", product);

实际生产系统还需要校验字段的业务来源,不应把模型生成的数据直接当成可信事实。

结构化输出并不保证每次都有正常对象。模型拒绝回答、生成超出限制、接口错误时,必须处理 output_parsed 为空或状态不完整的情况。

⚖️ 什么时候应该使用结构化输出

场景推荐返回
聊天回复、文章解释普通文本
商品信息提取结构化对象
意图分类具有固定枚举值的对象
前端表单自动填充与表单字段一致的对象

如果业务希望展示一段自然语言,没必要强行转换成 JSON。选择哪种输出,取决于程序下一步要做什么。


❓ 知识问答

Q1:JSON 输出与结构化输出一样吗?

不完全一样。一个字符串即使是合法 JSON,也可能缺少字段或类型不对。结构化输出还要求符合给定的字段和类型规则。

Q2:使用 Zod 后,是不是不需要后端校验?

仍然需要。Schema 主要处理数据结构,价格范围、用户权限、数据库是否存在某条记录等业务规则,要由应用负责。


🧪 小练习

增加一个 stock 数字字段,用于提取库存数量;输入文本改成“USB-C 扩展坞,数码,售价 129 元,库存 35 件”。

验证标准:输出对象同时包含 name、category、price、stock,并验证 stock 非负。尝试将输入改成缺少库存的文本,观察模型结果,思考是否需要业务层补充或拒绝保存。


🎉 你已经让模型返回可以被程序处理的对象,下一篇学习如何让模型请求调用业务函数。