首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >图像生成 API 接入生产化:异步任务、幂等键与状态机设计

图像生成 API 接入生产化:异步任务、幂等键与状态机设计

原创
作者头像
码林拾遗
发布于 2026-11-21 12:39:21
发布于 2026-11-21 12:39:21
200
举报

把图像生成能力接进业务系统,第一个撞上的问题不是画质,是时间:一次请求从十几秒到几十秒不等,而同步调用链路上到处是超时——网关 30 秒掐连接,客户端 SDK 默认 10 秒,用户盯着转圈到第 15 秒开始刷新页面。同步模式下的生图接入,超时误判是头号事故源:请求其实还在服务端排队,客户端却当失败重发了一遍。

标准形态:提交-查询两段式

生产化的解法业界已经收敛:提交任务拿任务号,凭任务号查结果。

代码语言:txt
复制
POST /v1/images/tasks          →  { "task_id": "..." }   # 秒回
GET  /v1/images/tasks/{id}     →  { "status": "processing" | "succeeded" | "failed", ... }

提交接口本身必须在秒级返回——它只做参数校验和入队,产图在服务端异步进行。这一步顺带消灭了超时误判:秒回的网络请求,重试语义是干净的。

但两段式引入一个新问题:「提交失败」和「提交成功但没收到响应」在客户端看起来一模一样——都是连接断了。不加处理,一次用户点击会变成两个任务、两份资源消耗,还拿到两张不同的图(seed 不同),谁也不知道该留哪张。

幂等键:一条唯一索引的事

解法朴素但必须做:客户端为每个逻辑需求生成唯一 ID(UUID 即可),随提交请求一起发;服务端对 (app_id, client_request_id) 建唯一索引。重复提交命中索引时不再创建任务,直接返回原 task_id。

三个实现细节决定这套机制的成色:

  1. 幂等记录要有保留期。唯一索引的生命周期要显著长于业务重试窗口——至少覆盖客户端最大重试时长加安全余量,否则「过期后的重发」会绕过幂等保护,变成最难查的偶发重复。
  2. 返回原任务而不是报冲突错。对客户端来说,命中幂等和提交成功应当走同一条代码路径,只是拿到的 task_id 是旧的。让调用方处理「你重复了」的错误分支,等于把幂等做成了负担。
  3. 参数快照要落库。命中幂等时顺带 diff 一下本次参数与首次参数,不一致就打告警——那是客户端 bug 的信号(同一个 request_id 配了不同 prompt),值得在网关层就拦住。

状态机漂移:processing 僵尸

任务表最阴的状态不是 failed,是永远 processing。worker 领了任务、进程崩了,状态停在 processing,查询接口永远回「请等待」。防治办法是租约制:worker 领任务时写 lease_expire_at = now + 生成超时上限,执行期间心跳续租;清扫协程周期扫描过期租约,把任务重置回待执行或标记超时失败——重置回队列要限次数,防止毒任务无限循环。

轮询侧配合退避:客户端按 1s→2s→4s 封顶 30s 拉状态,服务端在响应里回 retry_after 更稳。有 webhook 能力时以回调为主通道、轮询做兜底:回调可能丢,轮询一定会到达终态。

验收清单

上线前把四件事测穿:断网重发同一 request_id,只产生一个 task_id;杀 worker 进程,僵尸任务在一个租约周期内被回收;结果文件可下载且哈希稳定;失败任务的错误码可分类(参数错、内容拒绝、超时),因为这三类的客户端策略完全不同——改参、放弃、重放。

收尾

同步接口把复杂度藏进超时,异步任务把复杂度显式化进状态机。生图接入的工程含量恰恰就在这套「不好看」的部分:幂等索引、租约定时器、退避曲线。它们不出现在 demo 里,但决定了上线第一周要不要熬夜。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 标准形态:提交-查询两段式
  • 幂等键:一条唯一索引的事
  • 状态机漂移:processing 僵尸
  • 验收清单
  • 收尾
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档