图像输入与多模态边界

学习目标

读完本课你能：说清图像输入在 OpenAI 兼容接口里的标准形态，以及哪些事必须以提供方文档为准；列出接入图像前的大小、类型、授权与失败检查项；理解本站为什么（暂时）没有默认启用图像输入，要加的话改哪里。

问题场景

你想让 AI 助手「看一眼」报错截图。搜到的示例代码都是 content 里塞一个 image_url，看起来五分钟能搞定。结果一接上，上游返回一个含糊的 4xx，你分不清是图片太大、格式不对、模型根本不支持图像，还是请求体写错了。多模态的坑不在代码量，在于边界信息全在提供方文档里，而示例代码从不提醒你查。

核心解释

通用形态（OpenAI 兼容接口的约定）：content 从字符串升级为数组，文本与图像并列：

{
  "role": "user",
  "content": [
    { "type": "text", "text": "这段代码报什么错？" },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
  ]
}

url 可以是公网图片地址，也可以是 data: 前缀的 base64（本机截图常用后者，体积比原文件大约膨胀 33%）。

以提供方文档为准的部分——这些没有通用约定，换一家就是另一套：

• 哪些模型支持图像输入（同一家不同模型能力不同）；
• 单图大小上限、每条消息几张图；
• 支持的格式（png/jpeg/webp 常见，其余别假设）；
• 图像 token 怎么计费（通常按分辨率折算，比同屏文字贵得多）。

本站的诚实口径：聊天接口 app/api/ai/chat/route.ts 的请求体校验只收文本——message: z.string().min(1).max(8000)，没有图像字段。这是有意为之：站内默认模型以文本对话为主，图像能力随提供方与模型变化，启用前必须先查文档、先过下面的检查清单，而不是把示例代码抄上就开。

示例拆解

假设要接入，接入前的检查清单（每项都有验证方法）：

检查项	要确认什么	怎么验证
模型支持	该模型接受 image_url	查提供方文档 + 用 curl 发一条最小请求
大小	单图上限（常见几 MB）	发一张临界大小的图看返回
类型	png/jpeg/webp 之外的行为	发一张不支持的格式，看错误是否可读
授权	截图里有没有密钥、聊天记录	上传前人工过目，UI 提示「将上传截图」
失败	模型不支持时错误长什么样	确认归类为 model_error 且提示可懂

最小验证请求（本机可做，不动本站代码）：

curl -s "$AI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$AI_MODEL"'",
    "messages": [{"role": "user", "content": [
      {"type": "text", "text": "图里是什么颜色？"},
      {"type": "image_url", "image_url": {"url": "https://example.com/red-pixel.png"}}
    ]}]
  }'

返回正常描述 → 模型支持；返回 4xx → 看报错文本判断是「不支持」还是「参数错」。这五分钟能替你省掉整场接入后的排错。

动手任务

1. 查你所用模型（AI_MODEL）的官方文档，确认它是否支持图像输入，把结论和支持的格式、大小写进笔记。
2. 用上面的 curl 发一条最小图像请求，记录返回结果（成功描述或错误类别）。
3. 写一个 validateImage(file) 小函数（伪代码即可）：校验大小上限与 MIME 类型，超限返回明确的人话错误。

常见错误

• 不查文档直接接：模型不支持时上游报错含糊，你在错误堆里猜，其实文档第一段就写了。
• 原图直传：几 MB 的截图 base64 后更大，又慢又费；接入前压缩或降分辨率。
• 无授权提示：截图可能带着 API 密钥或私人对话，上传是外发行为，UI 必须提前说。
• 把不支持当故障：模型不支持图像是能力边界不是 bug，错误提示要区分「不能做」和「做坏了」。

检查与复盘

• 能写出图像输入的 content 数组形态，说出 base64 与 URL 两种来源
• 说出至少三个「必须以提供方文档为准」的维度
• 确认本站当前未启用图像输入，并能指出要加的话改哪个文件哪层校验

参考资料

• OpenAI 文档：Images and vision —— content 数组形态与图像参数的官方定义
• MDN：Blob —— 前端处理图片文件与类型校验的基础 API
• 智谱开放平台文档 —— 本站默认模型（GLM 系列）的能力与参数以这里为准