AI 学习笔记（四）：OpenAI API 结构化输出最小实战，从聊天到可落地接口

前面三篇把 Prompt、Token、上下文窗口、Temperature 这些基础打完了。
这一篇进入真正的工程落地：不用聊天窗口，直接用 API 拿到稳定 JSON，给程序继续消费。

很多人第一次接大模型 API 都会卡在同一个问题：

• 模型确实能回答，但输出不稳定
• 一会儿是段落，一会儿是列表，程序很难解析
• 一旦放进自动化流程，失败率马上升高

所以这篇只做一件事：给你一个可以直接跑起来的最小结构化输出示例。

1. 目标：让模型按你定义的 JSON 返回

我们先定义一个常见场景：
输入一段需求描述，让模型输出一个任务拆解清单，字段固定为：

• summary：一句话总结
• tasks：数组，每项包含 title 和 priority

重点不是“写得多复杂”，而是先做到：格式稳定、可解析、可兜底。

2. 最小可用代码（Node.js）

先安装 SDK：

npm i openai

示例代码（node >= 18）：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const schema = {
  type: 'object',
  additionalProperties: false,
  properties: {
    summary: { type: 'string' },
    tasks: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        properties: {
          title: { type: 'string' },
          priority: { type: 'string', enum: ['high', 'medium', 'low'] },
        },
        required: ['title', 'priority'],
      },
    },
  },
  required: ['summary', 'tasks'],
};

const inputText = `
我在维护一个 Hexo 博客，需要新增一篇 AI 学习笔记，
要求包括：选题、示例代码、发布检查清单。
`;

const resp = await client.responses.create({
  model: 'gpt-4.1-mini',
  input: [
    {
      role: 'system',
      content: '你是资深技术编辑，输出必须严格符合 JSON Schema。',
    },
    {
      role: 'user',
      content: inputText,
    },
  ],
  text: {
    format: {
      type: 'json_schema',
      name: 'task_plan',
      schema,
      strict: true,
    },
  },
});

// 不同 SDK 版本字段可能略有差异，这里给一个稳妥解析方式
const jsonText =
  resp.output_text ||
  resp.output?.[0]?.content?.[0]?.text ||
  '{}';

let data;
try {
  data = JSON.parse(jsonText);
} catch {
  data = { summary: '解析失败', tasks: [] };
}

console.log(data);

3. 工程里必须补的两层保护

只靠“让模型按格式输出”还不够，线上要再加两层：

1. 本地校验
   用 zod、ajv 或你已有的校验器，再验证一次返回 JSON，防止边界脏数据进入业务链路。

2. 失败兜底
   当 API 超时、限流、解析失败时，要有默认结果或降级策略，不要把异常直接传到用户界面。

一句话：模型约束 + 本地校验 + 兜底，三件套缺一不可。

4. 什么时候用结构化输出最值

这类场景收益最大：

• 自动生成工单、测试点、发布清单
• 从自然语言提取固定字段写入数据库
• 多步骤 Agent/工作流中间态传递

不太适合：

• 明显偏创意表达、格式不固定的长文写作

5. 一套可直接套用的接入策略

建议按这个顺序推进：

1. 先把 Schema 缩到最小，只保留真正必需字段。
2. 用最小样本跑通 20~50 条，观察失败模式。
3. 给每类失败加可观测日志（超时、限流、解析失败、校验失败）。
4. 再逐步扩字段，不要一开始把 Schema 设计得很大。

这样做的好处是：你能快速得到一个“可上线的稳定版本”，而不是陷在提示词细节里反复试错。

总结

从聊天到 API，关键不是“模型会不会说”，而是“系统能不能稳定吃下输出”。

结构化输出的核心价值在于：

• 降低解析成本
• 提高自动化成功率
• 让 AI 结果真正进入工程流水线

下一篇会继续 Phase 2：
把这个最小示例扩展成一个可复用的服务层封装（重试、日志、限流、错误分类）。

---

先跑通最小闭环，再追求复杂能力。
工程化接入 AI，稳定性永远优先于“看起来很聪明”。

本文永久链接: https://www.mulianju.com/learning-notes/ai-learning-notes-openai-structured-output-minimal-example/