API开发 #OpenAI #API #JSON #Vision #结构化输出 #Node.js #开发

OpenAI API：JSON 结构化输出与 Vision 识图（2026）

在 Node.js 中用 OpenAI API 做稳定 JSON 输出与图片理解：schema、提示词、识图抽取与校验重试，附成本与隐私清单，衔接入门与流式教程。

作者: ChatGPT博客编辑部
发布时间: 2026年9月7日
阅读时长: 约 5 分钟阅读

把大模型接到产品里，最常见的两类需求是：给后端稳定的 JSON，以及读截图/单据/白板照片。网页版 ChatGPT 能试提示词，但线上系统需要可解析、可校验的接口结果。

本文在 API 入门与流式与成本之上，聚焦 JSON 结构化输出 + Vision 识图 的可落地方案。模型名与参数以你账号当前文档为准；先在 ChatGPT 使用入口验证任务表述，再落到 API。

JSON + Vision 四步流水线

前置条件

已完成 Node.js Chat Completions 入门
Node.js 18+，openai SDK 已安装
API Key 只放环境变量，不进仓库

OPENAI_API_KEY=sk-xxxxxxxx

本站为第三方教程，与 OpenAI 无关联；接口字段、JSON mode / Structured Outputs、Vision 支持随版本变化，请对照官方文档。

第 1 步：先定 Schema，再写提示词

不要先喊「给我 JSON」。先把字段钉死：

// 业务约定：会议待办抽取
type ActionItem = {
  title: string;
  owner: string | null;
  due: string | null; // YYYY-MM-DD 或 null
  priority: 'P0' | 'P1' | 'P2';
};

type MeetingExtract = {
  summary: string;
  actions: ActionItem[];
  open_questions: string[];
};

提示词里用同名字段描述，程序侧再用 Zod / JSON Schema 校验。字段越少越稳。

第 2 步：稳定 JSON 输出

提示词约束（通用）

你是数据抽取器。只输出合法 JSON，不要 Markdown 代码块，不要解释。
缺失信息用 null 或空数组，禁止编造人名与日期。
Schema：
{
  "summary": string,
  "actions": [{"title": string, "owner": string|null, "due": string|null, "priority": "P0"|"P1"|"P2"}],
  "open_questions": string[]
}

Node.js 最小示例（JSON 模式思路）

不同 SDK 版本参数名可能是 response_format: { type: 'json_object' } 或 Structured Outputs。核心是：告诉模型「只要 JSON」+ 服务端强制解析。

import OpenAI from 'openai';

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

const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini', // 按你账号可用模型替换
  response_format: { type: 'json_object' },
  messages: [
    {
      role: 'system',
      content:
        '只输出合法 JSON。字段：summary, actions[], open_questions[]。禁止编造。',
    },
    {
      role: 'user',
      content: '会议原文：\n' + meetingNotes,
    },
  ],
});

const raw = completion.choices[0]?.message?.content ?? '{}';
const data = JSON.parse(raw);

生产环境务必：try/catch + 字段校验；失败则带「上次错误」重试最多一次。

第 3 步：Vision 识图 → 同一套 JSON

典型场景：截图里的表格、菜单、白板待办、错误弹窗。流程是 看图抽取 → 填同一 schema，不要「先写散文再让人手工抄」。

const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  response_format: { type: 'json_object' },
  messages: [
    {
      role: 'system',
      content:
        '你是截图信息抽取器。只看用户指定区域。只输出 JSON：fields 为 {label, value} 数组；看不清的 value 用 null。禁止编造。',
    },
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: '请提取表单里的「姓名、邮箱、金额」三列。看不清就标 null。',
        },
        {
          type: 'image_url',
          image_url: {
            url: 'data:image/jpeg;base64,' + base64Image,
            // 或使用可访问的 https 图片 URL
          },
        },
      ],
    },
  ],
});

Vision 提示词要点

指明看哪里：「右上角错误码」「表格第 2–4 列」
先抽后判：先逐项提取，再总结；不要跳步
允许 null：看不清优于瞎猜
脱敏：上传前遮挡身份证号、完整卡号、密钥二维码

网页端多模态试玩可参考对话产品；API 侧以可解析 JSON 为准。图像生成另见 ChatGPT 图像提示词（生成 ≠ 识图）。

第 4 步：校验、重试与成本护栏

解析、校验、隐私护栏

function parseMeetingJson(raw: string): MeetingExtract {
  const data = JSON.parse(raw);
  if (typeof data.summary !== 'string' || !Array.isArray(data.actions)) {
    throw new Error('schema_mismatch');
  }
  return data as MeetingExtract;
}

async function extractWithRetry(userContent: string) {
  let lastErr = '';
  for (let i = 0; i < 2; i++) {
    const content =
      i === 0
        ? userContent
        : userContent + `\n上次 JSON 无效：${lastErr}。请只输出修复后的 JSON。`;
    try {
      const raw = await callModel(content); // 封装你的 completions 调用
      return parseMeetingJson(raw);
    } catch (e) {
      lastErr = e instanceof Error ? e.message : 'parse_error';
    }
  }
  throw new Error('extract_failed');
}

成本与隐私清单

项	建议
图片体积	先压缩；能裁剪就裁到相关区域
Token	schema 字段精简；不要把整份长文档重复贴进 system
重试	最多 1 次；失败走人工或降级规则
隐私	禁止把密钥、证件原图送进 API；日志不落原文
流式	JSON 场景通常等完整响应再 parse；流式见成本文

和对话产品怎么分工

阶段	更合适
试提示词、看识图效果	ChatGPT 对话
要稳定字段进数据库	本篇 JSON + 校验
首字要快的聊天 UI	流式输出
读超长 PDF 人工精读	读长文教程（对话流，非本 API 专题）

常见问题

JSON 外面总是带 ```json 怎么办？

系统提示写死「不要代码块」；仍出现则在服务端去掉围栏后再 JSON.parse，并计入一次失败重试。

Vision 数字经常错？

缩小任务：先「逐项读出可见文本」，再二次请求填 schema；关键金额必须人工或 OCR 复核。

必须用 Structured Outputs 吗？

有官方 Structured Outputs 时优先用，schema 更硬。没有时，json_object + 自建校验也能跑通，但要接受偶发重试。

Structured Outputs 与「提示词要求 JSON」差在哪

做法	含义	适用
只在提示词里写「输出 JSON」	软约束，模型仍可能加前言/代码块	探索阶段、一次性脚本
`response_format: json_object` 一类开关	提高「像 JSON」的概率	中等可靠业务
官方 Structured Outputs / schema 绑定（名称以当前文档为准）	按字段契约生成，失败可重试	要入库、要对齐类型的生产路径

本页把 JSON 契约 + Vision 抽取 + 校验重试 写在一起，避免再拆一篇近重复的「structured-outputs 专页」。若你之后迁移到更新的 Responses 风格接口，原则不变：先定 schema，再选传输层；入门调用仍从 API Node 入门开始。

图像生成（出图）不是本页范围，见图像生成提示词；本页 Vision 是识图 / 读图进字段。

使用入口

立即体验 ChatGPT