结构化输出
🎯 引言
假设后台需要根据一段商品描述,自动填写“商品名、类别、价格”三个字段。如果模型返回的是“这是一款价格约 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);
这段代码的重点有三个:
z.object()定义一个商品对象,写清每个字段的类型。zodTextFormat(Product, "product")把 Zod 结构转换为模型接口可使用的输出格式。product是本次结构的名称。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 非负。尝试将输入改成缺少库存的文本,观察模型结果,思考是否需要业务层补充或拒绝保存。
🎉 你已经让模型返回可以被程序处理的对象,下一篇学习如何让模型请求调用业务函数。
