用幂等队列处理 AI 图片上传重试
文章将图片生成和对象存储拆成两个队列任务,先暂存生成结果,再按任务 ID 派生固定对象键上传。TypeScript 示例对 429 和其他瞬时错误执行退避重试,遵守 Retry-After,并避免把平台鉴权头传给预签名上传地址。
AI 深度解读
AI 图片已经生成,上传对象存储却遇到 429,这时重跑整个任务,会把模型调用也再跑一遍。作者给出的做法是把生成和上传拆成两个队列步骤,先持久化图片字节,再让上传任务用同一个对象键重试。
这套设计也适用于有删除期限的签署文件。对写 Node.js 队列的同学,最值得拆开看的是三个问题:上传失败后从哪里恢复,两个 worker 同时写会发生什么,以及文件到期后由谁负责删除。
上传失败后,为什么应该从图片字节恢复
生成 worker 先把图片写入短期本地存储或数据库,保存字节引用和 jobId,再交给上传 worker。重试时,上传 worker 读取同一份字节,并根据不可变的 jobId 算出同一个键 marketplace/${jobId}.png。只要这份引用在重启后仍可读取,上传失败就可以从交接点恢复,省掉一次模型调用。
原文用两个存储路由示范了这个过程,先检查对象是否存在,再决定是否写入。
const baseUrl = process.env.STORAGE_API_BASE_URL;
const apiKey = process.env.INFRAI_API_KEY;
if (!baseUrl || !apiKey) throw new Error("STORAGE_API_BASE_URL and INFRAI_API_KEY are required");
type StoredImage = { bytes: Uint8Array; contentType: string };
async function requestWithBackoff(url: string, init: RequestInit): Promise<Response> {
for (let attempt = 0; attempt < 6; attempt += 1) {
const response = await fetch(url, init);
if (response.status !== 429 && response.status < 500) return response;
if (attempt === 5) return response;
const retryAfter = Number(response.headers.get("retry-after"));
const waitMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 250 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, waitMs));
}
throw new Error("retry loop exhausted");
}
async function putImage(bucket: string, jobId: string, image: StoredImage) {
const key = `marketplace/${jobId}.png`;
const auth = { Authorization: `Bearer ${apiKey}` };
const existing = await requestWithBackoff(
`${baseUrl}/storage/object/head/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`,
{ method: "GET", headers: auth },
);
if (existing.ok) return { key, status: "already-present" };
if (existing.status !== 404) throw new Error(`HEAD failed: ${existing.status} ${await existing.text()}`);
const upload = await requestWithBackoff(
`${baseUrl}/storage/object/put/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`,
{
method: "PUT",
headers: { ...auth, "Content-Type": image.contentType, "x-infrai-acl": "private" },
body: image.bytes,
},
);
if (!upload.ok) throw new Error(`PUT failed: ${upload.status} ${await upload.text()}`);
return { key, status: "uploaded" };
}
要留意 Number(response.headers.get("retry-after")) 这一行。响应缺少该头时,Number(null) 会得到 0,预期的 250 * 2 ** attempt 毫秒退避就会失效。响应头如果给的是 HTTP 日期,这段代码也无法按指定时间等待。fetch 抛出的网络异常同样会直接跳出循环,上传超时后的恢复要由外层队列处理。
STORAGE_API_BASE_URL 指向供应商的 /v1 API 基址,INFRAI_API_KEY 用于 Bearer 鉴权。代码通过 GET 调用 /storage/object/head/... 做存在性检查,只有收到 404 才通过 PUT 调用 /storage/object/put/...。两条路由各自最多请求六次。原文另外建议队列最多尝试六次、上传成功后才确认消息,并让暂存字节覆盖整个重试窗口。若同时采用两层重试,请求次数会叠加。
对象键固定了,为什么还要管并发
假如一次写入已经成功,worker 却在收到响应前超时,下一次执行 putImage 可以先查同一个键,找到对象就返回 already-present。但两个 worker 若同时查到 404,仍可以先后写入同一个位置。原文所述接口缺少 If-Match 条件写入,也没有对象版本控制或 WORM 锁,误覆盖后无法靠存储桶自身恢复。需要协调同键写入时,作者建议用数据库租约或队列分区。
签署文件和私有图片可以写成 private 对象,读取时再签发短期 URL。原文的代码直接写平台 API,Authorization 头也只用在这里。如果前端想直接上传,作者指出该服务没有独立的 set_cors 路由,浏览器直传需要应用控制上传路径,或改用其他供应商。
删除期限和 429 分别由谁处理
把删除时间戳存到任务行,独立的生命周期流程才能按这个字段执行。原文提到存储生命周期的最小粒度为一天,适合按日处理。若业务承诺小时级删除,就得把到期任务交给应用队列或数据库调度器。
上传遇到 429,作者建议把消息放入延迟队列。其余 4xx 通常转人工检查。试用额度无法支付持久化写入时,进入 billing-required 状态,并按保留策略暂存字节。日志记录 jobId、尝试次数、HTTP 状态、Retry-After、对象键和最终响应体,再把生成与上传的指标分开,排查时才能定位是模型、队列投递还是存储出了问题。
我的判断
我认同把重试范围缩到失败的步骤。模型输出已经落盘时,复用同一份字节能省掉重复生成,也能让一次上传故障保留原有结果。对单 worker 小任务,进程内等待实现起来更省事。工作进程会重启、并发处理多项任务时,队列延迟重投更适合接管等待和恢复。
作者描述了在两次队列确认之间注入重启的 Node.js 练习,也称两条路由已经过发现验证。原文没给故障注入日志、压测结果或单队列与拆分队列的对照数据,因此拆分的收益属于工程经验。作者还提到 Infrai 一把密钥可访问 20 个模块的 295 条路由,这说明接口覆盖范围。选型时仍要按业务逐项核对版本恢复、跨区域复制和公开读取托管,作者给出的接口不提供这些能力。
能拿来做什么
- 给 Node.js 图片生成任务保存
jobId和可恢复的字节引用,在生成结束、上传开始前重启 worker,验证恢复后能沿用原字节和对象键。 - 给上传重试分别注入带
Retry-After的429、缺少响应头的429和网络超时,核对延迟是否生效,并统一计算队列与 HTTP 客户端的尝试预算。 - 给签署文件记录明确的删除时间和删除结果,用实际到期任务验证调度粒度是否满足业务期限。