AI 视觉接口如何处理超大图片：预缩放、分块上传与失败重试的取舍

把一张手机原图直接交给 AI 视觉接口，最先暴露的通常不是模型识别能力，而是请求体太大、像素总量超预算，或者网络抖动后重试把同一张图又传了几遍。更稳妥的做法是把图片输入拆成三个阶段：先在本地或服务端预缩放，再按传输条件选择整包或分块上传，最后只对确定可恢复的失败重试。

图片越大，越应该先控制像素和字节，再决定上传方式；重试也必须绑定上传分片或对象版本，不能把整次视觉请求无条件重放。

先把“超大”拆成字节和像素两个问题

工程里常说的“大图”至少有两种含义：文件可能是 25MB，但只有 4000×3000 像素；也可能文件只有几 MB，却是超高分辨率的 PNG。前者更容易撞到请求体或网关限制，后者会让解码、缩放和模型视觉编码消耗大量内存。

因此预检不要只看 Content-Length。建议把原图登记成一条输入记录：

type ImageBudget struct {
    Bytes  int64
    Width  int
    Height int
    Format string
}

func (b ImageBudget) Pixels() int64 { return int64(b.Width) * int64(b.Height) }

这里的两个门槛应该分别记录原因，例如 bytes_limit 和 pixels_limit。这样运营看到失败日志时，能分辨是需要降采样，还是需要改变传输方式，而不是笼统地写成“图片太大”。

能力变化带来的第一个动作：请求前预缩放

多模态接口通常更关心可处理的视觉信息量，而不是原图是否保留了每一个像素。对票据、截图或商品细节，缩放会影响识别结果，所以不能简单把所有图片压成固定宽度。更可靠的策略是按最长边、总像素和业务用途共同决定目标尺寸。

例如，文档问答可以先把最长边控制在 2048 像素；需要看小字的发票则保留更高尺寸，同时限制压缩质量，并在结果中记录 source_sha256、scaled_width 和 scaled_height。这条记录比一句“已优化”更容易复核。

预缩放不是越激进越好。一个实用检查是：缩放后的图片仍能看清任务所需的最小文字或边缘；如果看不清，应返回“需要更清晰原图”，而不是继续增加模型重试。

旧的整包上传何时该换成分块上传

小图片适合一次上传，链路短，服务端也容易做幂等。超过网关体积或移动网络经常中断时，分块上传才有价值：每个分片有序号和校验值，失败后只补传缺失分片，最后再合并成一个不可变对象。

分块大小不必追求一个“标准答案”。分片太小，数据库和请求数量会膨胀；太大，单次失败的代价又接近整包重传。可以从 4MB 或 8MB 起步，用上传耗时、失败率和临时存储占用做实际调整。

type Part struct {
    Number int
    SHA256 string
    Size   int64
}

type UploadSession struct {
    ID       string
    ObjectSHA string
    Parts    []Part
    Status   string // receiving, ready, expired
}

合并前再验一次总大小和整文件哈希。只要分片清单与客户端声明不一致，就把会话标成 invalid，不要让视觉模型接收一个可能缺块的文件。

重试边界要跟错误类型绑定

网络超时、连接被关闭和临时的 5xx 通常可以重试，但应优先续传缺失分片；如果上传已经完成，就复用对象 ID，避免重新提交二进制内容。429 需要遵守服务端给出的等待时间，不能用固定间隔把请求打得更密。

格式不支持、尺寸超过硬上限、鉴权失败、请求参数错误和内容安全拒绝属于不可恢复错误。它们重试只会制造重复日志和重复费用。建议把错误分类写进接口响应：

type RetryDecision string

const (
    RetryPart       RetryDecision = "retry_part"
    RetryWhole      RetryDecision = "retry_whole"
    DoNotRetry      RetryDecision = "do_not_retry"
)

真正发起视觉推理时，再使用 object_id + model + prompt_hash 组成幂等键。即使客户端在收到响应前断线，服务端也能知道这是同一份输入，而不是一张新图片。

迁移时先做一组最小验证

不要一开始就拿生产照片压测。准备三组固定样本：低字节高像素的 PNG、超过网关限制的 JPEG，以及上传中途断网后恢复的图片。每组都保存原图哈希，方便确认压缩和续传没有悄悄换文件。

1. 记录原图字节数、宽高、格式和 SHA-256。
2. 执行预缩放，核对目标尺寸与输出哈希。
3. 分别模拟首个分片失败、中间分片失败和合并后哈希不一致。
4. 确认可恢复错误只补传缺失分片，不可恢复错误只产生一次视觉请求。
5. 检查最终模型调用的幂等键、对象 ID 和费用记录是否能关联。

别把上传成功当成识别成功

文件已经进入对象存储，只说明传输链路完成；模型还可能因为图片内容、输入格式、上下文长度或业务权限拒绝处理。状态机最好把 uploaded、queued、inference_succeeded 和 inference_rejected 分开，前端也据此展示不同的处理建议。

这套拆分的价值不在于让每张图片都通过，而在于失败时知道该修哪一层：像素预算问题回到预缩放，网络问题回到分片续传，参数或内容问题则直接反馈给调用方。

相关问题

小于体积上限的图片也需要预缩放吗？

如果像素总量高、解码内存紧张或任务只需要局部信息，仍然建议预缩放；如果需要保留小字或细纹理，就应该提高目标尺寸并用样本验证识别效果。

分片上传能解决模型输入超长吗？

不能。分片只解决传输和断点续传，模型的视觉输入预算仍要单独检查。上传成功后仍可能因为输入过大被拒绝。

为什么不直接重试整次请求？

整次重试可能重复上传、重复推理和重复计费。先区分失败阶段，再根据对象 ID、分片校验和幂等键决定恢复动作。

最后检查清单

• 是否同时记录字节上限和像素上限，并能解释拒绝原因？
• 预缩放后是否保留原图哈希和输出尺寸？
• 分片是否可单独校验，合并后是否复核整文件哈希？
• 网络错误、限流、参数错误和内容拒绝是否有不同处理？
• 视觉推理是否使用稳定幂等键，避免断线重放造成重复调用？