1. 当业务代码直接拥抱图像生成API混乱是从哪一步开始的过去半年做文生图业务的后端改造我最大的感受是图像生成这种服务和普通HTTP接口完全不是一个物种。一个文生图请求动辄5秒到30秒一次生成可能消耗大量计算资源供应商的限流策略各不相同失败时返回的错误五花八门。最开始的版本里业务代码直接调用各个供应商的API每个生成请求的处理逻辑都是if-else堆出来的后面几乎到没法维护的程度。后来抽了一层独立的Gateway抽象才把参数、重试和幂等的复杂度从这个泥潭里剥出来。如果你也在接图像生成能力我建议你先别急着写对接代码想清楚这一层Gateway该怎么建后面能省掉大量返工。1.1 三个供应商三种步数一开始接入的是两个云厂家的文生图API和一个自建的ComfyUI服务。业务侧期望很简单传入提示词、尺寸、张数拿到图片URL。但实际对接下来发现A厂商叫stepsB厂商叫inference_steps或者num_inference_stepsComfyUI内部又是用workflow JSON里某个节点上的steps字段。如果不做一层统一业务代码里就得写三套参数映射而且每次新增供应商都要改动业务方代码。更麻烦的是有些供应商默认值还不一样——A厂商不传steps默认50B厂商默认20同一句提示词在两边的出图风格差异可以非常大。如果你以为只有步数一个参数存在命名差异那就天真了。采样器名称、CFG引导系数、种子字段、尺寸单位几乎每个核心参数都有各自叫法。有的供应商还要求尺寸必须是64的倍数有的必须是32的倍数传了非法参数直接甩一个生硬的400连具体哪个字段出错都不说。这些细节单独看都能忍堆在一起就变成了业务代码里永无止境的兼容逻辑。1.2 超时与重试各有各的小算盘这个问题比参数命名更隐蔽。A厂商的接口在排队时间较长时会返回202需要携带任务ID轮询B厂商直接同步返回但5秒超时就断开自建ComfyUI在GPU忙时可能10秒不响应。三个服务三种超时模型重试的语义也不一样——A厂商轮询不需要重试B厂商超时后重发通常没问题ComfyUI如果是任务已进入队列重发会导致同一个任务跑两遍。我在早期版本里吃过一次很大的亏某个供应商的网关偶尔返回502当时图省事给所有请求都加了一个简单的失败即重试。结果有一个ComfyUI任务算图其实已经成功了只是响应在返回途中超时重试又把同一个提示词塞进队列一次。用户最终收到了两张几乎一样的图计费也计了两次。这种事情发生一次你就能深刻理解什么样的失败可以被重试这件事绝不能靠猜。1.3 真正压垮思路的用户多点了两次生成业务上用户双击生成按钮、前端WebSocket断线自动重发、多个端H5/小程序/PC同时操作同一个订单这些都会导致一个逻辑上的生成一次变成物理上的提交三次。没有幂等设计的时候用户就会看到三张几乎相同的图账单上也是三笔。图像生成比普通写接口贵得多这种重复成本完全不可接受。第一次重构后我确认了一件事Gateway抽象不是架构洁癖而是把供应商差异、网络不确定性、用户重复操作这三类问题挡在业务之外的唯一干净位置。把这三件事下放到一个个具体service里只会让每一个业务方都重新踩一遍我已经踩过的坑。2. 参数适配的关键把供应商方言翻译成业务普通话2.1 参数契约先定字段名再谈对接Gateway层第一个要定义的是内部参数契约。这个契约应该完全站在业务视角跟任何供应商无关。我最终定的核心字段大概是这些参数类型说明promptstring提示词必填negative_promptstring反向提示词width / heightint图像尺寸stepsint采样步数默认30cfg_scalefloatCFG引导系数默认7.5samplerstring采样器名称使用标准名称seedlong随机种子-1表示随机image_countint单次生成张数默认1定义契约时要注意的是字段名尽量用行业通用叫法SD-WebUI生态里已经很统一了但服务端内部处理时统一以小驼峰存到DTO里对外API则根据前端需要再序列化。请不要把供应商的JSON字段直接透传给业务方否则参数冲突只是时间问题。比如某个供应商的返回体里有个cost字段含义是本次消耗的算力点数你直接透传出去前端很可能误以为那是金额再比如另一个供应商返回images是一个对象数组另一个返回image_urls是一个字符串数组不统一的话前端就要写两套解析。2.2 参数校验下沉到Gateway的三个理由很多团队会把参数校验放在各自的service里但我必须强调图像生成的参数校验放在Gateway层最值得。原因有三点第一参数语义统一。比如width必须是64的倍数不同供应商对宽度范围要求不同但业务层只认合法的最小单位和范围统一在这里兜底后续即使切换供应商业务参数不会变。第二错误格式统一。供应商返回的invalid parameter五花八门有的甚至直接返回HTML错误页我遇到过返回502错误页而不是JSON的Gateway统一捕获后转成业务错误码和友好提示。第三默认值集中管理。CFG、steps、宽高比例这些默认值放在Gateway配置中心里运营调参不需要改业务代码。这里还要多说一句图像生成领域经常有参数联动关系。比如steps40时部分供应商要求batch_size1二次元风格下width/height一般不建议超过1024否则细节崩坏。这类约束必须想在Gateway的参数校验阶段而不是等发到供应商那里拿一个模糊的报错。2.3 默认值与动态参数同一个提示词不同的出图配置这个场景很常见同一个prompt用户可能在快速模式steps15和高质量模式steps40之间切换还可能叠加不同的风格模板比如二次元会把negative_prompt强制替换成特定文本写实会动态调整cfg_scale。这些组合逻辑如果没有落在Gateway而是散落在各个业务方就会出现同一个动作在不同端出图效果不一致的问题。我的做法是在Gateway里维护一个spec扩展机制。业务层传的是高层描述风格、模式、尺寸档位、是否需要高清放大。Gateway拿到之后通过配置的模板引擎展开成具体的供应商参数再走参数校验。带来的好处很明显运营想调整快速模式的步数上限改配置发个布就行不需要前端、客户端、小程序同时改版本。要调整某个风格的负面提示词也不用每个端都跟着动。另外要提醒一点不要把上游供应商的sampler名字原样透传。不同供应商对采样器的命名有差异比如DPM 2M Karras有的简写成dpmpp_2m_karas有的是DPM 2M Karras带空格。Gateway里应该定义一套标准枚举然后由适配器映射到各供应商的实际取值。这样业务方只需要知道我要用DPM 2M Karras这个标准名不用关心对方API的拼写规则。3. 重试策略图片生成场景下什么值得重试什么必须放弃3.1 失败分类可重试失败与不可重试失败做重试的第一个前提是给失败分类。我处理过大量图像生成失败把它们归为这么几类可重试网络超时、上游5xx、上游网关错误如502/503、限流429但响应头带有Retry-After不可重试请求体不合法400、认证失败401/403、资源不存在404、供应商明确表示任务已无效例如任务被取消这里有个容易犯的错把HTTP层面的超时和业务失败混在一起。图像生成API的超时可能是连接超时、也可能是等待任务完成超时。前者重试几乎没代价后者重试很可能造成重复任务必须谨慎。我见过最典型的错误是给任务轮询超时直接做重试——结果底层任务还在跑导致相同任务被重复执行两次。正确做法是轮询超时先查状态确认任务不存在或明确失败后再决定是否重试而不是盲目重发。还有一个判断维度是请求是否已到达上游。如果连接都没建立重试肯定安全如果请求已经发出但响应超时这就是结果未知必须靠幂等键或查询接口来兜底。这也是为什么我在Gateway里强制要求每个生成请求都带requestId这个ID会向下传递给供应商的适配器能传就传能查就查。3.2 指数退避与抖动别让Gateway变成二次故障源重试策略我推荐指数退避随机抖动公式大致是delay min(max_delay, base_delay * 2^retry_count) random(0, jitter_max)比如基础延迟500ms重试上限3次最大延迟8秒抖动范围200~500ms。之所以加随机抖动是因为如果所有请求同时失败所有客户端同时立即重试会给上游造成重试风暴让原本只是偶发的超时变成雪崩。用大白话说你的Gateway可能本来只想救一个请求结果因为重试太整齐划一反而把上游打挂了。对于图像生成这种慢接口重试次数一定要控制在很低的水平。我的经验是同步生成场景最多重试2次异步任务场景最多重试1次因为一次生成请求已经占用了比较长的链路时间和算力多一次重试的成本非常直接。这不是普通的读接口重试一次重试背后是实打实的GPU计算时长。3.3 超时判定从连接超时到整链路超时图像生成网关的超时设置要分成几层连接超时connectTimeout建议3~5秒读取超时socketTimeout如果走同步接口建议比供应商最大响应时长再多20%例如供应商承诺15秒内返回则设20秒整链路超时requestTimeout包含排队、生成、传输的全部时间一般30~60秒特别要注意的是不要只依赖HTTP客户端自带的超时。在Gateway层我会给每个请求生成一个截止时间deadline例如当前时间60秒内必须完成。时间一到无论下游在干什么都直接中断并返回超时。这个截止时间会向下传递比如轮询任务剩余时间、Socket读超时都会以截止时间倒推计算避免出现总超时60秒但某个环节就消耗了55秒的异常情况。举个具体例子一个请求走了异步轮询路径总截止时间是60秒供应商返回的排队时间是50秒。如果轮询间隔设成10秒一次那第一次查询完就只剩10秒第二次查询很可能在轮到的时候刚好截止。这种Case我建议把轮询间隔和截止时间联动剩余时间不足一个轮询周期时直接放弃并返回超时不要再傻等。3.4 502 Bad Gateway的定位思路开发调试时最常撞见的错误就是502 Bad Gateway。我在日志里见过几种unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses502 bad gateway: cc switch local proxy failed while handling...纯网关错误页HTML格式502的本质是网关无法从上游获得有效响应。当请求路径是客户端 - 业务服务 - Gateway - 图像生成服务时502可能出现在任何一跳。定位我有几个固定步骤看是哪个节点的日志报出的502。是业务服务报的还是Gateway报的还是本地代理层报的。127.0.0.1这种地址通常说明有本地代理比如内网转发、本地端口映射先确认那个端口对应的服务进程是否还活着。确认是连接失败还是上游超时。前者往往是端口没监听、防火墙拦截后者则需要看上游服务的负载和队列。看上游服务有没有实际收到请求。如果没有收到基本可判定是网络层问题如果收到了但响应没回来那就是上游处理超时或响应格式异常。检查网关配置。很多502跟网关的upstream配置有关比如TCP连接超时设太短、上游地址写错、keepalive配置冲突。在Gateway抽象里我会专门用一组成熟的健康检查探活上游一旦连续失败达到阈值就摘除该上游节点并在错误响应中带上upstream_name字段方便快速定位是哪个服务出了问题。如果没有这层探活遇到502时你只能一台台机器去翻日志效率极低。4. 幂等设计让再点一次和点一次结果完全一致4.1 为什么图像生成比普通写操作更需要幂等说句实话我以前做电商下单时也做幂等但那更多是为了防止重复扣款。图像生成场景的幂等有一个独特的地方生成成本高、耗时长、用户感知强。一次误重试可能意味着多付一次算力成本用户还会看到两张几乎一样的图体验上很像系统抽风了。引发重复提交的典型来源有三个前端防抖失效用户双击、弱网下点完没反应又点一次中间层自动重试业务服务内部对Gateway的超时发起了自动重试消息/任务重复消费通过MQ异步生成时消费者收到两条相同消息这些来源有一个共同点在业务语义上都应该被合并成同一次生成。所以幂等不能在业务层靠前端按钮禁用解决必须在Gateway层用一个明确的机制兜住。一旦这个机制不在Gateway而在业务方每个调用方都要各自实现一套总有人偷懒不做最后出问题的概率非常高。4.2 幂等键的一生从请求头到结果缓存幂等键Idempotency-Key的设计我参考了成熟支付API的做法客户端生成幂等键推荐使用UUID v4但要注意每个键只能对应一个生成意图。比如用户点了两次前端应生成两个不同的键如果确实是两个不同意图还是同一个键如果用户意图重复——按场景决定。通常同一意图用同一个键新意图用新键。Gateway收到请求后先查幂等表如果已经存在相同键且状态是成功直接返回上一次的结果不再调用上游如果存在且状态是处理中返回处理中或等待如果不存在则创建新记录状态为处理中然后才去调上游。上游成功返回后Gateway把结果图片URL数组、成本等存到幂等记录里状态改成成功。上游失败后记录状态改成失败同时允许同键重试即下一次同键请求可以重新发起上游调用。一个典型的请求长这样POST /v1/generations Idempotency-Key: 6e8bc430-9c3f-11e9-9d1e-0a0027000015 Content-Type: application/json { prompt: a cat sitting on a chair, watercolor style, width: 512, height: 512, steps: 30 }服务器第一次返回202 Accepted之后如果客户端用同一个幂等键再发一次Gateway会直接返回第一次的结果而不是重新调用上游。这个流程里最关键的坑是第2步到第3步之间的并发控制。如果两个相同幂等键的请求同时到达必须保证只有一个请求真的去调上游另一个等结果或直接返回处理中。实现上可以用数据库唯一索引事务INSERT ... ON CONFLICT DO NOTHING插入失败的请求走查询/等待路径。这也是为什么幂等状态必须落库而不是放在内存里。4.3 状态机把生成中变成一等公民图像生成请求天然是异步的。即使供应商提供同步接口在Gateway层也应该按异步模型来设计。我的状态机比较朴素CREATED - PROCESSING - SUCCEEDED |- FAILED |- TIMEOUT新增的请求先进CREATED调用上游前进入PROCESSING结果回来后落到终态。需要注意PROCESSING不能靠内存标记必须持久化因为Gateway自身可能重启TIMEOUT之后还要允许一次查询上游真实状态的补偿操作因为上游可能实际上已经生成成功了只是响应没回来状态变更都要记录操作时间方便排查。有了状态机WebSocket推送、前端轮询、消息回调全部可以围绕同一份状态记录来展开而不会出现前端显示失败但账单已经扣款的情况。我遇到过好几次类似的线上问题用户那边看到生成失败点重试之后又提示任务已存在就是因为状态没有在一个统一的地方管理不同环节拿到的是互相矛盾的信息。4.4 成本侧兜底重复提交的钱怎么处理聊个比较实际的问题如果重复请求已经走了同一幂等键上游确实只被调用了一次那账单上就只有一笔费用。但万一在早期版本里幂等没做好上游被调了两次图片却只保留了一次这个钱怎么办我的经验是不要试图在上游退款而是把是否重复计费这件事记录在幂等表里让计费系统以幂等表为准。也就是说Gateway不只是保存图片结果还会保存本次生成实际消耗的算力次数例如upstream_call_count。计费时如果同一幂等键对应多次上游调用只在账单展示一次并标记风险单如果两个不同幂等键但业务方认为是同一意图则走业务侧合并打款的流程。这类问题最好在系统设计阶段就想清楚不然后面核对账单会非常痛苦。5. 从抽象到落地一个最小可复制的图像生成Gateway5.1 核心接口定义代码层面我推荐先用接口把图像生成从具体供应商中抽象出来例如interface ImageGenerationProvider { generate(spec: GenerationSpec): PromiseGenerationResult; queryStatus(requestId: string): PromiseTaskStatus; cancel(requestId: string): Promisevoid; } interface GenerationSpec { prompt: string; negativePrompt?: string; width: number; height: number; steps: number; cfgScale: number; sampler?: string; seed?: number; imageCount: number; requestId: string; idempotencyKey: string; } interface GenerationResult { requestId: string; taskStatus: succeeded | failed | processing; imageUrls: string[]; upstream: string; costCredits: number; }这一步的价值在于每个新供应商只需要实现这一个接口业务方完全看不见差异。接入新供应商的成本从改业务代码降到新增一个适配器。拿参数映射来说供应商A的适配器内部会把steps转成inference_steps供应商B的适配器会原样透传但这些转换逻辑都被封装在适配器里Gateway核心流程完全无感。5.2 数据库模型设计幂等表和任务表其实可以合成一张表。字段设计我建议这样以PostgreSQL为例CREATE TABLE generation_request ( id BIGSERIAL PRIMARY KEY, idempotency_key VARCHAR(64) NOT NULL, biz_order_id VARCHAR(64) NOT NULL, status VARCHAR(20) NOT NULL DEFAULT CREATED, spec_json JSONB NOT NULL, result_json JSONB, upstream_name VARCHAR(50), upstream_request_id VARCHAR(128), retry_count INT NOT NULL DEFAULT 0, upstream_call_count INT NOT NULL DEFAULT 0, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), UNIQUE (biz_order_id, idempotency_key) ); CREATE INDEX idx_generation_status ON generation_request(status, updated_at);UNIQUE (biz_order_id, idempotency_key)是幂等并发控制的基石。业务订单ID幂等键唯一就能保证同一个订单下的同一个意图不会重复落库。retry_count和upstream_call_count要分开记前者是Gateway尝试次数后者是上游真实消耗次数方便做成本核算。spec_json存的是经过校验和归一化之后的完整请求参数后续要复现问题或做数据对账可以直接从这个字段读取不用再去找业务日志。5.3 重试与幂等的串联代码这是Gateway里最关键的路径我用简化伪代码描述核心逻辑async function createGeneration(dao, provider, req) { // 1. 尝试插入幂等记录利用唯一索引 const inserted await dao.tryInsert( req.bizOrderId, req.idempotencyKey, req.spec ); if (!inserted) { // 2. 已存在查询旧记录 const existing await dao.findByKey( req.bizOrderId, req.idempotencyKey ); if (existing.status SUCCEEDED) return existing.result; if (existing.status PROCESSING) throw new ProcessingError(existing.requestId); // 3. 旧记录是失败状态允许重新发起 if (existing.status FAILED) { await dao.markProcessing(existing.id); return callUpstreamWithRetry(dao, provider, existing); } } else { return callUpstreamWithRetry(dao, provider, { id: inserted.id, spec: req.spec }); } } async function callUpstreamWithRetry(dao, provider, record) { const deadline Date.now() GLOBAL_TIMEOUT_MS; let lastError; for (let attempt 1; attempt MAX_RETRY; attempt) { try { const result await provider.generate(record.spec); await dao.markSucceeded(record.id, result); return result; } catch (e) { lastError e; if (!canRetry(e) || Date.now() BACKOFF_MAX deadline) break; await sleep(backoffWithJitter(attempt)); await dao.incrementRetry(record.id); } } await dao.markFailed(record.id, lastError.message); throw lastError; }这段代码的要点是幂等插入和状态更新统一走数据库重试只发生在callUpstreamWithRetry内部每次重试都会更新retry_count。这里有个我反复强调的细节——provider.generate本身必须是可重试的。如果上游是同步接口且支持幂等通过requestId重试是安全的如果不支持重试前要先查状态例如用queryStatus确认没有重复创建任务。5.4 健康检查与熔断网关的自我防护Gateway不能只做转发还要有自我保护。我给每个上游服务挂了两个东西健康检查每隔10秒发送一个轻量级探测请求比如查询任务状态的接口连续3次失败后标记为不健康熔断器统计最近1分钟内的失败率超过50%则快速失败Fast Fail不再发起上游调用而是直接返回上游繁忙。熔断状态机分三态关闭正常、打开快速失败、半开放少量流量试探。图像生成场景中熔断的恢复要特别谨慎因为一个慢服务在恢复初期的压力承受能力很低。半开状态下我建议只放1个测试请求成功后再逐步放大流量。如果测试请求又失败立刻回到打开状态不要反复试探。6. 我踩过的几个坑以及现在会提前做的事6.1 参数的隐式类型转换有一个印象很深的线上问题业务方传了image_count: 1字符串JSON反序列化到int时很多库会宽松转换但参数从Gateway转发到供应商时重新序列化又变成了1。表面看起来没问题但某个供应商对参数类型极其敏感直接返回400。排查了半天最后发现是Gateway对外API层用一个宽松的MapString, Object接收参数类型信息在传递中丢失了。现在我的习惯是对外API的DTO用强类型字段类型严格定义Gateway内部统一用规范化的GenerationSpec对象任何外部传入的Map或JsonNode必须在入口做一次显式转换和校验不转换不清算。这条规则看起来很简单但它能避免一类特别隐蔽的偶发400问题尤其是在多个语言、多个端对接时。6.2 重试风暴到底有多可怕有次压测环境里一个上游的GPU服务因为显存不足开始返回500业务服务没做熔断只是每个请求都重试3次。结果就是上游CPU被打满原本只需要30秒恢复的故障硬生生拖了15分钟。事后看日志同一个提示词在1秒内被重试了7次。那次之后我把重试策略改成了全局并发令牌熔断双重限制进入重试逻辑前先看当前对该上游的并发请求数如果已经超过阈值比如100直接放弃重试走快速失败。熔断是保护上游并发令牌是保护Gateway自己两者缺一不可。如果只有一个熔断器没有并发限制Gateway自己也可能被大量堆积的等待请求拖垮。6.3 幂等键的过期问题如果幂等记录永久保留表会无限膨胀如果过早清理用户几天前生成的图片想重新获取时Gateway又会调用上游再生成一次既多花钱又可能出现图与预期不一致。我的做法是成功状态幂等记录保留30天因为用户可能还要查询旧图失败状态记录保留24小时过了24小时同键重试视为新请求处理中状态记录保留48小时并配合一个兜底任务把所有卡住的请求置为超时。过期清理通过定时任务在低峰期执行顺便统计业务侧的重复率。如果你发现幂等键重复率异常高往往说明前端防抖没做好或者业务层有隐性的多次调用这时候就要去查调用方的代码而不只是看Gateway本身。6.4 可观测性Gateway一定要有日志和追踪最后说一个最容易忽略的事。Gateway处于中间层调试难度天然比直连更大。如果没有可观测性出了问题只能靠猜。我的最低标准是每个请求记录idempotency_key、upstream_name、retry_count、upstream_request_id每次上游调用记录开始时间、结束时间、耗时、状态码、错误信息错误日志必须包含完整的请求参数摘要避免打全量prompt太长且可能涉及隐私有条件的团队建议接入分布式追踪把业务服务、Gateway、上游服务之间的调用链串起来。有了这几条排查为什么这次生成很慢为什么同一个请求被重试了为什么上游扣了两次费这种问题效率会高非常多。图像生成Gateway这层抽象本质上是在复杂异构的上游服务和多样化的业务诉求之间划出一道清晰边界边界划好了后续无论换供应商、调策略还是加新业务都是在边界两侧各自演进不会互相拖累。
图像生成Gateway设计与实践：参数适配、重试与幂等全解析
1. 当业务代码直接拥抱图像生成API混乱是从哪一步开始的过去半年做文生图业务的后端改造我最大的感受是图像生成这种服务和普通HTTP接口完全不是一个物种。一个文生图请求动辄5秒到30秒一次生成可能消耗大量计算资源供应商的限流策略各不相同失败时返回的错误五花八门。最开始的版本里业务代码直接调用各个供应商的API每个生成请求的处理逻辑都是if-else堆出来的后面几乎到没法维护的程度。后来抽了一层独立的Gateway抽象才把参数、重试和幂等的复杂度从这个泥潭里剥出来。如果你也在接图像生成能力我建议你先别急着写对接代码想清楚这一层Gateway该怎么建后面能省掉大量返工。1.1 三个供应商三种步数一开始接入的是两个云厂家的文生图API和一个自建的ComfyUI服务。业务侧期望很简单传入提示词、尺寸、张数拿到图片URL。但实际对接下来发现A厂商叫stepsB厂商叫inference_steps或者num_inference_stepsComfyUI内部又是用workflow JSON里某个节点上的steps字段。如果不做一层统一业务代码里就得写三套参数映射而且每次新增供应商都要改动业务方代码。更麻烦的是有些供应商默认值还不一样——A厂商不传steps默认50B厂商默认20同一句提示词在两边的出图风格差异可以非常大。如果你以为只有步数一个参数存在命名差异那就天真了。采样器名称、CFG引导系数、种子字段、尺寸单位几乎每个核心参数都有各自叫法。有的供应商还要求尺寸必须是64的倍数有的必须是32的倍数传了非法参数直接甩一个生硬的400连具体哪个字段出错都不说。这些细节单独看都能忍堆在一起就变成了业务代码里永无止境的兼容逻辑。1.2 超时与重试各有各的小算盘这个问题比参数命名更隐蔽。A厂商的接口在排队时间较长时会返回202需要携带任务ID轮询B厂商直接同步返回但5秒超时就断开自建ComfyUI在GPU忙时可能10秒不响应。三个服务三种超时模型重试的语义也不一样——A厂商轮询不需要重试B厂商超时后重发通常没问题ComfyUI如果是任务已进入队列重发会导致同一个任务跑两遍。我在早期版本里吃过一次很大的亏某个供应商的网关偶尔返回502当时图省事给所有请求都加了一个简单的失败即重试。结果有一个ComfyUI任务算图其实已经成功了只是响应在返回途中超时重试又把同一个提示词塞进队列一次。用户最终收到了两张几乎一样的图计费也计了两次。这种事情发生一次你就能深刻理解什么样的失败可以被重试这件事绝不能靠猜。1.3 真正压垮思路的用户多点了两次生成业务上用户双击生成按钮、前端WebSocket断线自动重发、多个端H5/小程序/PC同时操作同一个订单这些都会导致一个逻辑上的生成一次变成物理上的提交三次。没有幂等设计的时候用户就会看到三张几乎相同的图账单上也是三笔。图像生成比普通写接口贵得多这种重复成本完全不可接受。第一次重构后我确认了一件事Gateway抽象不是架构洁癖而是把供应商差异、网络不确定性、用户重复操作这三类问题挡在业务之外的唯一干净位置。把这三件事下放到一个个具体service里只会让每一个业务方都重新踩一遍我已经踩过的坑。2. 参数适配的关键把供应商方言翻译成业务普通话2.1 参数契约先定字段名再谈对接Gateway层第一个要定义的是内部参数契约。这个契约应该完全站在业务视角跟任何供应商无关。我最终定的核心字段大概是这些参数类型说明promptstring提示词必填negative_promptstring反向提示词width / heightint图像尺寸stepsint采样步数默认30cfg_scalefloatCFG引导系数默认7.5samplerstring采样器名称使用标准名称seedlong随机种子-1表示随机image_countint单次生成张数默认1定义契约时要注意的是字段名尽量用行业通用叫法SD-WebUI生态里已经很统一了但服务端内部处理时统一以小驼峰存到DTO里对外API则根据前端需要再序列化。请不要把供应商的JSON字段直接透传给业务方否则参数冲突只是时间问题。比如某个供应商的返回体里有个cost字段含义是本次消耗的算力点数你直接透传出去前端很可能误以为那是金额再比如另一个供应商返回images是一个对象数组另一个返回image_urls是一个字符串数组不统一的话前端就要写两套解析。2.2 参数校验下沉到Gateway的三个理由很多团队会把参数校验放在各自的service里但我必须强调图像生成的参数校验放在Gateway层最值得。原因有三点第一参数语义统一。比如width必须是64的倍数不同供应商对宽度范围要求不同但业务层只认合法的最小单位和范围统一在这里兜底后续即使切换供应商业务参数不会变。第二错误格式统一。供应商返回的invalid parameter五花八门有的甚至直接返回HTML错误页我遇到过返回502错误页而不是JSON的Gateway统一捕获后转成业务错误码和友好提示。第三默认值集中管理。CFG、steps、宽高比例这些默认值放在Gateway配置中心里运营调参不需要改业务代码。这里还要多说一句图像生成领域经常有参数联动关系。比如steps40时部分供应商要求batch_size1二次元风格下width/height一般不建议超过1024否则细节崩坏。这类约束必须想在Gateway的参数校验阶段而不是等发到供应商那里拿一个模糊的报错。2.3 默认值与动态参数同一个提示词不同的出图配置这个场景很常见同一个prompt用户可能在快速模式steps15和高质量模式steps40之间切换还可能叠加不同的风格模板比如二次元会把negative_prompt强制替换成特定文本写实会动态调整cfg_scale。这些组合逻辑如果没有落在Gateway而是散落在各个业务方就会出现同一个动作在不同端出图效果不一致的问题。我的做法是在Gateway里维护一个spec扩展机制。业务层传的是高层描述风格、模式、尺寸档位、是否需要高清放大。Gateway拿到之后通过配置的模板引擎展开成具体的供应商参数再走参数校验。带来的好处很明显运营想调整快速模式的步数上限改配置发个布就行不需要前端、客户端、小程序同时改版本。要调整某个风格的负面提示词也不用每个端都跟着动。另外要提醒一点不要把上游供应商的sampler名字原样透传。不同供应商对采样器的命名有差异比如DPM 2M Karras有的简写成dpmpp_2m_karas有的是DPM 2M Karras带空格。Gateway里应该定义一套标准枚举然后由适配器映射到各供应商的实际取值。这样业务方只需要知道我要用DPM 2M Karras这个标准名不用关心对方API的拼写规则。3. 重试策略图片生成场景下什么值得重试什么必须放弃3.1 失败分类可重试失败与不可重试失败做重试的第一个前提是给失败分类。我处理过大量图像生成失败把它们归为这么几类可重试网络超时、上游5xx、上游网关错误如502/503、限流429但响应头带有Retry-After不可重试请求体不合法400、认证失败401/403、资源不存在404、供应商明确表示任务已无效例如任务被取消这里有个容易犯的错把HTTP层面的超时和业务失败混在一起。图像生成API的超时可能是连接超时、也可能是等待任务完成超时。前者重试几乎没代价后者重试很可能造成重复任务必须谨慎。我见过最典型的错误是给任务轮询超时直接做重试——结果底层任务还在跑导致相同任务被重复执行两次。正确做法是轮询超时先查状态确认任务不存在或明确失败后再决定是否重试而不是盲目重发。还有一个判断维度是请求是否已到达上游。如果连接都没建立重试肯定安全如果请求已经发出但响应超时这就是结果未知必须靠幂等键或查询接口来兜底。这也是为什么我在Gateway里强制要求每个生成请求都带requestId这个ID会向下传递给供应商的适配器能传就传能查就查。3.2 指数退避与抖动别让Gateway变成二次故障源重试策略我推荐指数退避随机抖动公式大致是delay min(max_delay, base_delay * 2^retry_count) random(0, jitter_max)比如基础延迟500ms重试上限3次最大延迟8秒抖动范围200~500ms。之所以加随机抖动是因为如果所有请求同时失败所有客户端同时立即重试会给上游造成重试风暴让原本只是偶发的超时变成雪崩。用大白话说你的Gateway可能本来只想救一个请求结果因为重试太整齐划一反而把上游打挂了。对于图像生成这种慢接口重试次数一定要控制在很低的水平。我的经验是同步生成场景最多重试2次异步任务场景最多重试1次因为一次生成请求已经占用了比较长的链路时间和算力多一次重试的成本非常直接。这不是普通的读接口重试一次重试背后是实打实的GPU计算时长。3.3 超时判定从连接超时到整链路超时图像生成网关的超时设置要分成几层连接超时connectTimeout建议3~5秒读取超时socketTimeout如果走同步接口建议比供应商最大响应时长再多20%例如供应商承诺15秒内返回则设20秒整链路超时requestTimeout包含排队、生成、传输的全部时间一般30~60秒特别要注意的是不要只依赖HTTP客户端自带的超时。在Gateway层我会给每个请求生成一个截止时间deadline例如当前时间60秒内必须完成。时间一到无论下游在干什么都直接中断并返回超时。这个截止时间会向下传递比如轮询任务剩余时间、Socket读超时都会以截止时间倒推计算避免出现总超时60秒但某个环节就消耗了55秒的异常情况。举个具体例子一个请求走了异步轮询路径总截止时间是60秒供应商返回的排队时间是50秒。如果轮询间隔设成10秒一次那第一次查询完就只剩10秒第二次查询很可能在轮到的时候刚好截止。这种Case我建议把轮询间隔和截止时间联动剩余时间不足一个轮询周期时直接放弃并返回超时不要再傻等。3.4 502 Bad Gateway的定位思路开发调试时最常撞见的错误就是502 Bad Gateway。我在日志里见过几种unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses502 bad gateway: cc switch local proxy failed while handling...纯网关错误页HTML格式502的本质是网关无法从上游获得有效响应。当请求路径是客户端 - 业务服务 - Gateway - 图像生成服务时502可能出现在任何一跳。定位我有几个固定步骤看是哪个节点的日志报出的502。是业务服务报的还是Gateway报的还是本地代理层报的。127.0.0.1这种地址通常说明有本地代理比如内网转发、本地端口映射先确认那个端口对应的服务进程是否还活着。确认是连接失败还是上游超时。前者往往是端口没监听、防火墙拦截后者则需要看上游服务的负载和队列。看上游服务有没有实际收到请求。如果没有收到基本可判定是网络层问题如果收到了但响应没回来那就是上游处理超时或响应格式异常。检查网关配置。很多502跟网关的upstream配置有关比如TCP连接超时设太短、上游地址写错、keepalive配置冲突。在Gateway抽象里我会专门用一组成熟的健康检查探活上游一旦连续失败达到阈值就摘除该上游节点并在错误响应中带上upstream_name字段方便快速定位是哪个服务出了问题。如果没有这层探活遇到502时你只能一台台机器去翻日志效率极低。4. 幂等设计让再点一次和点一次结果完全一致4.1 为什么图像生成比普通写操作更需要幂等说句实话我以前做电商下单时也做幂等但那更多是为了防止重复扣款。图像生成场景的幂等有一个独特的地方生成成本高、耗时长、用户感知强。一次误重试可能意味着多付一次算力成本用户还会看到两张几乎一样的图体验上很像系统抽风了。引发重复提交的典型来源有三个前端防抖失效用户双击、弱网下点完没反应又点一次中间层自动重试业务服务内部对Gateway的超时发起了自动重试消息/任务重复消费通过MQ异步生成时消费者收到两条相同消息这些来源有一个共同点在业务语义上都应该被合并成同一次生成。所以幂等不能在业务层靠前端按钮禁用解决必须在Gateway层用一个明确的机制兜住。一旦这个机制不在Gateway而在业务方每个调用方都要各自实现一套总有人偷懒不做最后出问题的概率非常高。4.2 幂等键的一生从请求头到结果缓存幂等键Idempotency-Key的设计我参考了成熟支付API的做法客户端生成幂等键推荐使用UUID v4但要注意每个键只能对应一个生成意图。比如用户点了两次前端应生成两个不同的键如果确实是两个不同意图还是同一个键如果用户意图重复——按场景决定。通常同一意图用同一个键新意图用新键。Gateway收到请求后先查幂等表如果已经存在相同键且状态是成功直接返回上一次的结果不再调用上游如果存在且状态是处理中返回处理中或等待如果不存在则创建新记录状态为处理中然后才去调上游。上游成功返回后Gateway把结果图片URL数组、成本等存到幂等记录里状态改成成功。上游失败后记录状态改成失败同时允许同键重试即下一次同键请求可以重新发起上游调用。一个典型的请求长这样POST /v1/generations Idempotency-Key: 6e8bc430-9c3f-11e9-9d1e-0a0027000015 Content-Type: application/json { prompt: a cat sitting on a chair, watercolor style, width: 512, height: 512, steps: 30 }服务器第一次返回202 Accepted之后如果客户端用同一个幂等键再发一次Gateway会直接返回第一次的结果而不是重新调用上游。这个流程里最关键的坑是第2步到第3步之间的并发控制。如果两个相同幂等键的请求同时到达必须保证只有一个请求真的去调上游另一个等结果或直接返回处理中。实现上可以用数据库唯一索引事务INSERT ... ON CONFLICT DO NOTHING插入失败的请求走查询/等待路径。这也是为什么幂等状态必须落库而不是放在内存里。4.3 状态机把生成中变成一等公民图像生成请求天然是异步的。即使供应商提供同步接口在Gateway层也应该按异步模型来设计。我的状态机比较朴素CREATED - PROCESSING - SUCCEEDED |- FAILED |- TIMEOUT新增的请求先进CREATED调用上游前进入PROCESSING结果回来后落到终态。需要注意PROCESSING不能靠内存标记必须持久化因为Gateway自身可能重启TIMEOUT之后还要允许一次查询上游真实状态的补偿操作因为上游可能实际上已经生成成功了只是响应没回来状态变更都要记录操作时间方便排查。有了状态机WebSocket推送、前端轮询、消息回调全部可以围绕同一份状态记录来展开而不会出现前端显示失败但账单已经扣款的情况。我遇到过好几次类似的线上问题用户那边看到生成失败点重试之后又提示任务已存在就是因为状态没有在一个统一的地方管理不同环节拿到的是互相矛盾的信息。4.4 成本侧兜底重复提交的钱怎么处理聊个比较实际的问题如果重复请求已经走了同一幂等键上游确实只被调用了一次那账单上就只有一笔费用。但万一在早期版本里幂等没做好上游被调了两次图片却只保留了一次这个钱怎么办我的经验是不要试图在上游退款而是把是否重复计费这件事记录在幂等表里让计费系统以幂等表为准。也就是说Gateway不只是保存图片结果还会保存本次生成实际消耗的算力次数例如upstream_call_count。计费时如果同一幂等键对应多次上游调用只在账单展示一次并标记风险单如果两个不同幂等键但业务方认为是同一意图则走业务侧合并打款的流程。这类问题最好在系统设计阶段就想清楚不然后面核对账单会非常痛苦。5. 从抽象到落地一个最小可复制的图像生成Gateway5.1 核心接口定义代码层面我推荐先用接口把图像生成从具体供应商中抽象出来例如interface ImageGenerationProvider { generate(spec: GenerationSpec): PromiseGenerationResult; queryStatus(requestId: string): PromiseTaskStatus; cancel(requestId: string): Promisevoid; } interface GenerationSpec { prompt: string; negativePrompt?: string; width: number; height: number; steps: number; cfgScale: number; sampler?: string; seed?: number; imageCount: number; requestId: string; idempotencyKey: string; } interface GenerationResult { requestId: string; taskStatus: succeeded | failed | processing; imageUrls: string[]; upstream: string; costCredits: number; }这一步的价值在于每个新供应商只需要实现这一个接口业务方完全看不见差异。接入新供应商的成本从改业务代码降到新增一个适配器。拿参数映射来说供应商A的适配器内部会把steps转成inference_steps供应商B的适配器会原样透传但这些转换逻辑都被封装在适配器里Gateway核心流程完全无感。5.2 数据库模型设计幂等表和任务表其实可以合成一张表。字段设计我建议这样以PostgreSQL为例CREATE TABLE generation_request ( id BIGSERIAL PRIMARY KEY, idempotency_key VARCHAR(64) NOT NULL, biz_order_id VARCHAR(64) NOT NULL, status VARCHAR(20) NOT NULL DEFAULT CREATED, spec_json JSONB NOT NULL, result_json JSONB, upstream_name VARCHAR(50), upstream_request_id VARCHAR(128), retry_count INT NOT NULL DEFAULT 0, upstream_call_count INT NOT NULL DEFAULT 0, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), UNIQUE (biz_order_id, idempotency_key) ); CREATE INDEX idx_generation_status ON generation_request(status, updated_at);UNIQUE (biz_order_id, idempotency_key)是幂等并发控制的基石。业务订单ID幂等键唯一就能保证同一个订单下的同一个意图不会重复落库。retry_count和upstream_call_count要分开记前者是Gateway尝试次数后者是上游真实消耗次数方便做成本核算。spec_json存的是经过校验和归一化之后的完整请求参数后续要复现问题或做数据对账可以直接从这个字段读取不用再去找业务日志。5.3 重试与幂等的串联代码这是Gateway里最关键的路径我用简化伪代码描述核心逻辑async function createGeneration(dao, provider, req) { // 1. 尝试插入幂等记录利用唯一索引 const inserted await dao.tryInsert( req.bizOrderId, req.idempotencyKey, req.spec ); if (!inserted) { // 2. 已存在查询旧记录 const existing await dao.findByKey( req.bizOrderId, req.idempotencyKey ); if (existing.status SUCCEEDED) return existing.result; if (existing.status PROCESSING) throw new ProcessingError(existing.requestId); // 3. 旧记录是失败状态允许重新发起 if (existing.status FAILED) { await dao.markProcessing(existing.id); return callUpstreamWithRetry(dao, provider, existing); } } else { return callUpstreamWithRetry(dao, provider, { id: inserted.id, spec: req.spec }); } } async function callUpstreamWithRetry(dao, provider, record) { const deadline Date.now() GLOBAL_TIMEOUT_MS; let lastError; for (let attempt 1; attempt MAX_RETRY; attempt) { try { const result await provider.generate(record.spec); await dao.markSucceeded(record.id, result); return result; } catch (e) { lastError e; if (!canRetry(e) || Date.now() BACKOFF_MAX deadline) break; await sleep(backoffWithJitter(attempt)); await dao.incrementRetry(record.id); } } await dao.markFailed(record.id, lastError.message); throw lastError; }这段代码的要点是幂等插入和状态更新统一走数据库重试只发生在callUpstreamWithRetry内部每次重试都会更新retry_count。这里有个我反复强调的细节——provider.generate本身必须是可重试的。如果上游是同步接口且支持幂等通过requestId重试是安全的如果不支持重试前要先查状态例如用queryStatus确认没有重复创建任务。5.4 健康检查与熔断网关的自我防护Gateway不能只做转发还要有自我保护。我给每个上游服务挂了两个东西健康检查每隔10秒发送一个轻量级探测请求比如查询任务状态的接口连续3次失败后标记为不健康熔断器统计最近1分钟内的失败率超过50%则快速失败Fast Fail不再发起上游调用而是直接返回上游繁忙。熔断状态机分三态关闭正常、打开快速失败、半开放少量流量试探。图像生成场景中熔断的恢复要特别谨慎因为一个慢服务在恢复初期的压力承受能力很低。半开状态下我建议只放1个测试请求成功后再逐步放大流量。如果测试请求又失败立刻回到打开状态不要反复试探。6. 我踩过的几个坑以及现在会提前做的事6.1 参数的隐式类型转换有一个印象很深的线上问题业务方传了image_count: 1字符串JSON反序列化到int时很多库会宽松转换但参数从Gateway转发到供应商时重新序列化又变成了1。表面看起来没问题但某个供应商对参数类型极其敏感直接返回400。排查了半天最后发现是Gateway对外API层用一个宽松的MapString, Object接收参数类型信息在传递中丢失了。现在我的习惯是对外API的DTO用强类型字段类型严格定义Gateway内部统一用规范化的GenerationSpec对象任何外部传入的Map或JsonNode必须在入口做一次显式转换和校验不转换不清算。这条规则看起来很简单但它能避免一类特别隐蔽的偶发400问题尤其是在多个语言、多个端对接时。6.2 重试风暴到底有多可怕有次压测环境里一个上游的GPU服务因为显存不足开始返回500业务服务没做熔断只是每个请求都重试3次。结果就是上游CPU被打满原本只需要30秒恢复的故障硬生生拖了15分钟。事后看日志同一个提示词在1秒内被重试了7次。那次之后我把重试策略改成了全局并发令牌熔断双重限制进入重试逻辑前先看当前对该上游的并发请求数如果已经超过阈值比如100直接放弃重试走快速失败。熔断是保护上游并发令牌是保护Gateway自己两者缺一不可。如果只有一个熔断器没有并发限制Gateway自己也可能被大量堆积的等待请求拖垮。6.3 幂等键的过期问题如果幂等记录永久保留表会无限膨胀如果过早清理用户几天前生成的图片想重新获取时Gateway又会调用上游再生成一次既多花钱又可能出现图与预期不一致。我的做法是成功状态幂等记录保留30天因为用户可能还要查询旧图失败状态记录保留24小时过了24小时同键重试视为新请求处理中状态记录保留48小时并配合一个兜底任务把所有卡住的请求置为超时。过期清理通过定时任务在低峰期执行顺便统计业务侧的重复率。如果你发现幂等键重复率异常高往往说明前端防抖没做好或者业务层有隐性的多次调用这时候就要去查调用方的代码而不只是看Gateway本身。6.4 可观测性Gateway一定要有日志和追踪最后说一个最容易忽略的事。Gateway处于中间层调试难度天然比直连更大。如果没有可观测性出了问题只能靠猜。我的最低标准是每个请求记录idempotency_key、upstream_name、retry_count、upstream_request_id每次上游调用记录开始时间、结束时间、耗时、状态码、错误信息错误日志必须包含完整的请求参数摘要避免打全量prompt太长且可能涉及隐私有条件的团队建议接入分布式追踪把业务服务、Gateway、上游服务之间的调用链串起来。有了这几条排查为什么这次生成很慢为什么同一个请求被重试了为什么上游扣了两次费这种问题效率会高非常多。图像生成Gateway这层抽象本质上是在复杂异构的上游服务和多样化的业务诉求之间划出一道清晰边界边界划好了后续无论换供应商、调策略还是加新业务都是在边界两侧各自演进不会互相拖累。
