浏览器能打开,只说明你的浏览器、网络和登录状态拿得到这张图;模型服务端是另一台机器,没有这些条件。排查时先把问题拆成四层:图片能否被公网访问、格式是否真实正确、大小和分辨率是否合适、模型和接口是否真的收图。前两层可以用一个 Python 预检脚本在本地先筛掉。本文给出这个脚本、六种故障的模拟结果和四种协议的字段对照。文中所有实验都没有调用任何模型 API,也不比较任何模型或服务商。
一、场景与问题
商品审核服务把商家图片 URL 交给视觉模型,返回"无法读取图片"。开发者把 URL 贴进浏览器,图片清清楚楚;用 requests 在本机请求,也是 200。于是怀疑模型有问题。
这是一类常见场景的示意,不是某个具体案例。一种典型原因是 CDN 的防盗链:带 Referer 的浏览器能看到图,不带的请求拿到的是状态码 200 的提示页。状态码和"能打开"都不是证据,证据是响应体的字节能不能被解码成图片。
二、排查思路:四层,从外到内
- 访问层:URL 是否公网可达,是否要 Cookie 或 Authorization,有无防盗链,签名是否过期,重定向到了哪里,返回的是图片还是 HTML。
- 格式层:Content-Type、扩展名、真实二进制三者是否一致;Base64 是否完整,Data URL 前缀是否正确。
- 限制层:文件字节、像素分辨率、模型的视觉处理预算是三个不同的量,分别检查。
- 能力层:这个型号是不是视觉模型,这个接口是不是接受图片。能生成图片的模型不一定能读图片,同一系列里只有部分型号收图也很常见。
前两层的问题,本地预检能发现。第四层不能靠预检,必须逐个型号核对文档。
三、方案取舍:URL、Base64、文件引用,以及放弃的做法
三种传图方式各有前提:
| 方式 | 好处 | 前提和代价 |
|---|---|---|
| URL | 请求体很小 | 模型服务端必须能自己下载到;多一次下载 |
| Base64 | 不依赖外部下载,适合内网和临时生成的图 | 请求体变大,要处理前缀和 MIME |
| 文件引用(先上传再引用) | 适合大文件和重复使用 | 是否支持、保留多久、多大,取决于具体 API |
没有统一的最优解:图在公网且稳定,用 URL;图在内网或带鉴权,转 Base64 或先转存到对象存储再生成短期预签名 URL。文件引用我只核对了字段(OpenAI Responses 的 input_image 有 file_id,Gemini 有 file_data),上传大小和保留时长没有核对。
预检工具里我放弃了四种常见写法:
- 只发 HEAD 请求:部分服务器对 HEAD 返回 403 或 405,而 GET 正常,所以统一用 GET 流式读取。
- 让 HTTP 库自动跟随重定向:这样无法对每一跳做校验,改为自己逐跳处理。
- 信任 Content-Type 或扩展名:改为用 Pillow 按二进制判定真实格式并完整解码一次。
- 不设下载上限:改为字节上限加超时,即使服务端不声明 Content-Length 也能边读边截断。
如果需要在多个厂商的视觉模型之间切换测试,可以用聚合入口减少接入成本,例如灵眸 AI。按它的模型广场(2026-11-17 查看)的"支持视觉"标注筛选,同一厂商里会看到有的型号带标注、有的不带,例如 GLM 5.3 Flash 带而 GLM 5.3 不带,这正是第四层要逐型号核对的原因。它的文档还写明实际可调用的模型由 API Key 所属分组决定。本文的预检脚本不依赖任何聚合入口。
四、实现:预检工具与协议适配
4.1 预检工具
项目 multimodal-image-preflight/ 的核心是 image_preflight.py:检查 HTTP 状态码、重定向次数和最终 URL、Content-Type、Content-Length、实际下载字节数、真实格式、宽高、能否解码、耗时。HTTP 200 但内容是 HTML 时,输出会直接指出可能是登录页、防盗链页或错误页:
HTTP:200
Content-Type:text/html; charset=utf-8
Actual Format:-
Decodable:no
Note:HTTP 200 但内容是 HTML,不是图片。常见原因:登录页、防盗链提示页、错误页、CDN 拦截页
Result:FAIL
image_format_check.py 负责格式和 Base64:缺 Data URL 前缀、MIME 与真实格式不一致、Base64 含换行、长度不是 4 的倍数、文件被截断,都会报出具体问题。
4.2 四种协议的图片字段
字段不能照搬。下面是 openai 3.52.0、anthropic 2.9.0、google-genai 3.4.0 三个 Python SDK 实际构造请求、在 HTTP 层截获的 JSON(不联网)。证据来源是这些 SDK 的类型定义和实际发出的请求,不是厂商协议规范的完整文本。
// OpenAI Chat Completions POST /v1/chat/completions
{"type": "image_url", "image_url": {"url": "https://example.com/a.jpg"}} // url 也可以是 data:image/jpeg;base64,...
// OpenAI Responses POST /v1/responses
{"type": "input_image", "image_url": "https://example.com/a.jpg", "detail": "auto"} // image_url 是字符串
// Anthropic Messages POST /v1/messages
{"type": "image", "source": {"type": "url", "url": "https://example.com/a.jpg"}}
{"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "<纯 Base64,无 data: 前缀>"}}
// Gemini generateContent(google-genai 序列化后)
{"inlineData": {"data": "<Base64>", "mime_type": "image/jpeg"}}
{"fileData": {"file_uri": "https://example.com/a.jpg", "mime_type": "image/jpeg"}}
要点:Chat 的 image_url 是对象,Responses 的 image_url 是字符串,外层类型名也不同;Anthropic 的 base64 data 不带 data: 前缀,media_type 单独写,anthropic 2.9.0 的类型只允许 jpeg、png、gif、webp;Gemini 的图片放在 parts 里,没有 image_url 字段,另外 google-genai 3.4.0 把 inline 数据序列化成了 URL-safe Base64(_ 代替 /)。
"兼容 OpenAI 协议"只意味着骨架相同,是否接受 detail、Data URL、多图要看各自文档。即使在同一个产品里,限制也可能不同:阿里云百炼的对话接口(2026-11-17 核对)image_url 推荐用 URL,也支持 data:<content_type>;base64,...;智能体应用接口的 images[] 支持 url 和 base64,并写明 Base64 的原图不超过 180KB。所以一个接口的数字不能当通用标准。
五、验证与结果
本地模拟实验。 用 FastAPI 在本机模拟六种源站表现,运行预检(只验证预检逻辑,不代表任何服务商的网络环境):
| 场景 | HTTP | Content-Type | 预检结论 |
|---|---|---|---|
| 正常 JPEG(1600×1200,275 KB) | 200 | image/jpeg | PASS |
| 302 跳转到正常图 | 200 | image/jpeg | PASS,Redirects 1 |
| 403 | 403 | text/plain | FAIL,提示鉴权或防盗链 |
| 200 返回登录页 HTML | 200 | text/html | FAIL,Decodable: no |
| 内容是 JPEG,声明 image/png | 200 | image/png | WARN,真实格式与声明不符 |
| 1.6 MB 图,限制 200 KB | 200 | image/jpeg | FAIL;有长度时不下载,无长度时下载约 208 KB 即中止 |
另对三个公网地址发了普通 HTTP 请求:python.org 的 logo(PNG,580×164)和 httpbin 的 JPEG(239×178)为 PASS;python.org 首页返回 200 加 text/html,为 FAIL,正是"200 但不是图片"。
Base64 体积。 同一张 282,070 字节的 JPEG,Base64 后 376,096 字节,比值 1.3333,即每 3 字节编成 4 个字符。同样的 Chat 请求,用 URL 时请求体 212 字节,用 Data URL 时 376,306 字节。
字节、像素、预算。 4000×3000 的低复杂度图是 1,747,288 字节,约 0.15 字节/像素;1000×750 的噪点图是 662,066 字节,约 0.88 字节/像素,像素和字节没有固定换算。同一张 1600×1200 噪点图,JPEG 质量 90 为 1,573,482 字节,质量 50 为 766,111 字节,像素不变;缩到 800×600 后为 289,124 字节。模型最终花多少视觉 token,取决于它自己的缩放和切块规则,各家不同,以所选模型文档为准。
OCR 与截图文字。 1920 宽、文字高约 14 像素的截图,缩到长边 1280、768、512 后,文字约 9.3、5.6、3.7 像素。这只是算术,我没有跑 OCR。工程上的结论是:缩图前先确定最小文字高度,用自己的样本在目标模型上验证后再定缩放规则。
测试共 27 项,全部离线,全部通过。
六、风险与边界
- 本地预检不能证明模型服务端可访问。 它只证明从这台机器看 URL 返回了合格图片。防盗链、IP 限制、内网地址仍要用目标 API 实测。
- SSRF。 允许用户提交 URL 再由服务器去请求,本身就是 SSRF 入口。工具默认只放行 http/https,主机解析后只要有一个地址是回环、内网或链路本地(如 169.254.169.254)就拒绝,每一跳重定向重新校验,并限制大小和超时。但它存在 DNS rebinding 的时间窗口:校验时解析一次,连接时库可能再解析一次。这个项目是排查和教学用的预检工具,不是生产级的完整 SSRF 防护;服务端处理不可信 URL 应在出口网络层再加限制(专用抓取服务、出口代理、网络策略),并经过自己的安全评审。
- 没有真实模型调用。 本文的证据只有三类:本地模拟实验、SDK 请求体构造、对公网静态图的普通 HTTP 请求。没有任何模型的识别结果、耗时、用量,也没有跨厂商比较。
- 官方文档缺口。 OpenAI 和 Google 官方文档在我的环境里打不开,字段靠 SDK 核对,两家的图片大小和数量限制没有写,请以官方文档为准。
七、总结
排查清单:
| 现象 | 检查位置 | 可能原因 | 处理 |
|---|---|---|---|
| 提示无法下载或读取图片 | 预检的 HTTP 和最终 URL | 403、404、签名过期、防盗链 | 用长有效期预签名 URL,或后端下载后转 Base64 |
| 预检 200 但 Decodable: no | Content-Type 和响应体 | 返回 HTML 登录页或错误页 | 检查重定向到登录的策略和 Referer 白名单 |
| 本地通过,模型仍读不到 | 服务端网络可达性 | 防盗链、IP 限制、内网地址 | 换公网位置或改 Base64,并用目标 API 实测 |
| 格式或 MIME 报错 | 真实格式与声明 | 扩展名、Content-Type、前缀不一致;HEIC | 按真实格式写 MIME,必要时转码 |
| 参数结构报 400 | 请求 JSON | Responses 用了对象写法,或 Data URL 放进 Anthropic 的 data |
对照 4.2,每种协议单独适配 |
| 体积超限 | 请求体大小 | Base64 多图累加 | 改 URL 或文件引用,缩图前先看第五节 |
| 模型说看不到图 | 型号和端点 | 不是视觉型号;Key 分组不含该模型 | 核对型号能力和 Key 可用模型 |
最小的生产流程:用户上传图片 → 校验真实格式并解码 → 检查大小和分辨率 → 存对象存储(短期预签名 URL)或转 Base64 → 确认目标模型支持视觉输入 → 按协议适配字段 → 调用 API → 校验输出。图片传成功不等于模型理解正确,商品审核和票据识别这类业务要用带标注的真实样本验收,并把 URL 失败、格式失败、超限、模型拒答分开记录。
参考资料
- 阿里云百炼《生成对话》,2026-11-17 核对:https://help.aliyun.com/zh/model-studio/web-search-agent-api-chat
- 阿里云百炼《接入百炼智能体应用》,2026-11-17 核对:https://help.aliyun.com/zh/model-studio/multimodal-call-app
- OpenAI Images and vision 指南:https://developers.openai.com/api/docs/guides/images-vision (环境内无法打开,字段以 openai Python SDK 3.52.0 类型定义核对)
- Google Gemini API Image understanding:https://ai.google.dev/gemini-api/docs/image-understanding (环境内无法打开,字段以 google-genai 3.4.0 核对)
- Anthropic Messages 图片输入(字段以 anthropic Python SDK 2.9.0 类型定义核对)