同一端点的多模态输入格式：视觉模型兼容性矩阵

为什么需要先确认图片输入格式

即使一个聚合端点暴露了统一的 chat/completions 接口，不同视觉模型对图片字段的解析方式也可能不同。常见差异包括：

• 图片是以公网 URL 提供，还是必须内联 Base64
• 是否支持文件上传后引用文件 ID
• 图片对象放在 content 数组里的位置和字段名
• 是否允许一条消息里多张图，以及上限如何报错
• 对图片格式（JPEG/PNG/WebP）和尺寸的接受程度

如果直接批量发送，一个模型失败就可能导致整批任务中断。所以先做一次小规模探测，成本远低于事后排查。

三类常见的图片编码风格

URL 引用式

content 数组里放一个图片对象，其中 image_url 字段指向可公开访问的地址。优点是请求体小、无需本地编码；缺点是服务端要能访问该 URL，内网地址或带鉴权的链接通常不行。

Base64 内联式

把图片字节编码后拼成 data URI，例如 data:image/png;base64,...。这种方式不依赖外网可访问性，但请求体会显著变大，批量时要注意单请求体积和超时设置。

文件 ID 引用式

先通过文件上传接口拿到一个 ID，再在消息里引用。适合反复使用同一张图的场景，但需要额外的上传步骤，而且并非所有模型都走这条路径。

如何为每个模型确认实际行为

不要依赖文档里的统一描述，用下面的最小探测流程验证：

1. 选一张小尺寸、内容明确的图片作为测试样本。
2. 对目标模型分别发送三种编码风格的单条请求。
3. 记录哪种返回成功、哪种返回格式错误。
4. 再发一条包含两张图的请求，观察是否被接受。
5. 把结果填入矩阵表格。

一次探测通常只需要几条请求，就能确定这个模型在当前端点下的真实输入契约。

兼容性矩阵模板

| 模型 | URL | Base64 | 文件 ID | 多图 | 备注 |
| --- | --- | --- | --- | --- | --- |
| 模型 A | 通过 | 通过 | 不支持 | 支持 | URL 需公网可达 |
| 模型 B | 不支持 | 通过 | 通过 | 待测 | — |
| 模型 C | 通过 | 通过 | 不支持 | 不支持 | 多图会报错 |

把这张表填完，再决定批量任务的输入格式，可以避免大部分“模型 A 能跑、模型 B 全挂”的情况。

批量发送前的检查清单

• 所有目标模型是否都支持你计划使用的编码方式
• 是否有模型只接受 Base64，从而影响请求体积估算
• 多图请求是否在目标模型上被支持
• 图片格式和尺寸是否在可接受范围内
• 失败时的错误信息是否足以区分“格式错误”和“内容被拒”

把探测结果固化到代码里

一种实用做法是按模型维护一个小型配置表，记录它接受的编码方式和是否支持多图。批量任务在构造请求前先查这张表，对不支持的模型走降级路径（例如把 URL 转成 Base64）。这样即使聚合端点后面接了新的视觉模型，也只需要补充一行配置，而不用改批量逻辑。

常见误区

• 以为端点统一就等于模型统一：聚合层可能做了字段转换，也可能原样透传，不同模型表现不一致。
• 用 URL 测试成功就默认 Base64 也可用：两者走的是不同解析路径。
• 忽略请求体积：Base64 会让 body 明显变大，批量并发时容易触发超时。
• 不做多图测试：单图通过不代表多图可用。

先花几条请求摸清矩阵，再放大批量规模，是使用多模态端点时比较稳妥的顺序。