图片 + JSON：做一个分类助手

9.1 今天你要完成什么

图片答案也可以变成 JSON。这样页面可以根据 category 显示不同颜色、按钮或提示。

• 能让 AI 看图后输出 category、item、reason、confidence。
• 能理解 confidence 不是保证正确，只是信心程度。
• 能给低信心结果加“请人工确认”。
• 能用至少 5 张图片测试分类。

9.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

• 核心理论：图片输入让模型多了一种观察材料，但观察结果仍然需要检查，不能把推测当事实。
• 证据理论：看图时要先列“我确定看见什么”，再写“我猜可能是什么”。这能减少乱编。
• 置信度理论：confidence 表示模型有多确定，不代表一定正确。低置信度结果要提醒人工确认。
• 输入契约：先规定用户要给什么资料。本课的输入要围绕“AI垃圾分类助手”，不要让用户随便输入到程序无法处理。
• 输出契约：先规定 AI 必须交出什么结果。本课重点是“图像识别、结构化输出、人工确认”，所以输出要能被人读懂，也要方便程序检查。
• 验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
• 安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

9.3 课堂讲解

这一课的项目是“AI垃圾分类助手”，重点是“图像识别、结构化输出、人工确认”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 Image Input + Structured Outputs。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课把图片也放进输入里。看图很有趣，但也更容易出现“看起来像”的判断，所以事实和推测要分开。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：图片中是一只纸杯；图片中是一节旧电池；图片中是果皮。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

图片模糊时不要硬说确定。一个靠谱的助手会说“我不确定”，并提醒用户人工确认。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

• 如果把“AI垃圾分类助手”交给低年级学生使用，哪一步最容易让他们困惑？
• 这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
• 如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
• 你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
• 如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

9.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

{
  "item": "纸杯",
  "category": "其他垃圾",
  "reason": "纸杯通常有涂层，不能直接按普通纸张回收。",
  "confidence": 0.72,
  "need_human_check": true
}

你可以替换成这些输入

• 图片中是一只纸杯。
• 图片中是一节旧电池。
• 图片中是果皮。
• 图片很模糊，只能看出盒子。
• 图片中有多个物品，请分别分类。

9.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

1. 新建文件 lesson-09.mjs，把下面完整代码放进去。
2. 在终端运行：npm init -y
3. 安装依赖：npm install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：node lesson-09.mjs
6. 把最后一行的示例输入换成你自己的测试内容。

Node.js 完整代码

import OpenAI from "openai";

const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

const imageUrl =
  "https://upload.wikimedia.org/wikipedia/commons/thumb/8/89/Tomato_je.jpg/640px-Tomato_je.jpg";

const imageClassSchema = {
  type: "object",
  properties: {
    item: { type: "string" },
    category: {
      type: "string",
      enum: ["可回收物", "厨余垃圾", "有害垃圾", "其他垃圾", "不确定"],
    },
    reason: { type: "string" },
    confidence: { type: "number", minimum: 0, maximum: 1 },
    need_human_check: { type: "boolean" },
  },
  required: ["item", "category", "reason", "confidence", "need_human_check"],
  additionalProperties: false,
};

const response = await client.responses.create({
  model: MODEL,
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "请识别图片中的物品，并按垃圾分类输出 JSON。" },
        { type: "input_image", image_url: imageUrl },
      ],
    },
  ],
  text: {
    format: {
      type: "json_schema",
      name: "trash_classification",
      strict: true,
      schema: imageClassSchema,
    },
  },
});

const result = JSON.parse(response.output_text);
console.log(JSON.stringify(result, null, 2));

Python 运行方式

1. 新建文件 lesson-09.py，把下面完整代码放进去。
2. 建议新建虚拟环境后再安装依赖。
3. 安装依赖：pip install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：python lesson-09.py
6. 把 main 里的示例输入换成你自己的测试内容。

Python 完整代码

from openai import OpenAI
import json
import os

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/8/89/Tomato_je.jpg/640px-Tomato_je.jpg"

image_class_schema = {
    "type": "object",
    "properties": {
        "item": {"type": "string"},
        "category": {
            "type": "string",
            "enum": ["可回收物", "厨余垃圾", "有害垃圾", "其他垃圾", "不确定"],
        },
        "reason": {"type": "string"},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        "need_human_check": {"type": "boolean"},
    },
    "required": ["item", "category", "reason", "confidence", "need_human_check"],
    "additionalProperties": False,
}

response = client.responses.create(
    model=MODEL,
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "请识别图片中的物品，并按垃圾分类输出 JSON。"},
                {"type": "input_image", "image_url": image_url},
            ],
        }
    ],
    text={
        "format": {
            "type": "json_schema",
            "name": "trash_classification",
            "strict": True,
            "schema": image_class_schema,
        }
    },
)

result = json.loads(response.output_text)
print(json.dumps(result, ensure_ascii=False, indent=2))

9.6 跟着做

1. 先定义允许的分类类别。
2. 设计固定 JSON 字段。
3. 要求 AI 说明判断理由。
4. 加入 confidence 和 need_human_check。
5. 用清楚图片和模糊图片分别测试。

9.7 常见错误

• 没有固定类别，结果每次叫法不同。
• confidence 写成 100% 绝对确定。
• 没有提醒不同城市规则可能不同。
• 只测试容易图片，不测试模糊图片。

9.8 课后练习

1. 把垃圾分类助手改成“食物营养识别提示器”。
2. 输出 item、possible_nutrients、not_sure、next_question。
3. 所有健康相关结果都要提醒人工核查。

9.9 自测清单

• 我的 JSON 字段固定吗？
• 我有没有处理不确定情况？
• 分类结果有没有理由？
• 页面能根据字段做不同展示吗？