语音识别接口调用的可靠性设计：超时、重试与幂等

把语音识别这类 AI 能力接进生产系统，功能跑通只是第一晚的事，第二晚开始就要面对真实世界的网络抖动、服务限流和半夜告警。这篇整理成可靠性设计清单，全部条目来自实际故障复盘。

一、先想清楚：调用为什么失败

外部接口的失败可以分成三类，处理策略完全不同：

把这张表刻进代码里的意思是：重试逻辑必须按错误类别分支，而不是 try-catch 里无脑 for 循环三次。

二、超时设置的三个层次

见过不少系统的超时是一个全局常量，这在语音接口上是错的。正确的做法是按调用阶段分别设置：

连接超时：3s（连不上就是连不上，等再久也没用）
读超时（提交）：30s（上传音频的合理窗口）
读超时（轮询）：10s（查状态本来就该快）

轮询接口的超时设得比提交还长，是常见的资源浪费——它在白白占着连接等一个不会来的包。

三、重试的纪律

哪些错误码可以重试

• 连接类：Connection reset / broken pipe——立即重试
• 限流类：429——读响应头里的 Retry-After，没有就指数退避
• 服务端类：500/502/503——退避重试，连续失败超过阈值就熔断，别把下游打得更死

重试必须带抖动

多实例同时退避，会在同一个时间点集体重试（惊群）。退避间隔加随机抖动：

delay = base * (2 ** attempt) + random.uniform(0, 1)

一行代码，避免重试风暴。

重试要有总闸

设置最大重试次数与总耗时预算（比如 5 分钟），超了就走降级路径——语音场景的降级可以是「保留音频，标记待转，人工或延后处理」，而不是让用户的请求挂在半空。

四、幂等：重试安全的前提

一旦重试，同一请求就会到达服务端多次。两种幂等手段：

1. 客户端幂等键：提交任务时带上业务侧生成的 request_id，服务端据此去重——首选，前提是服务支持
2. 自然幂等：以音频内容哈希+业务单号做任务标识，提交前先查是否已有同名任务——服务不支持幂等键时的兜底

我在实践里用的是后者的变体：以「音频文件 MD5 + 场景标签」作为任务指纹，重复提交在客户端就被拦下。上线以来再没出现过重复转写任务。

五、可观测性：失败要能被看见

可靠性设计的最后一环是让故障无处藏身。三个最低配置：

• 调用日志：每次调用记录 task_id、耗时、错误码——排查时限流和超时一眼区分
• 成功率看板：按小时聚合，成功率跌破阈值自动告警
• 对账任务：定时核对「业务侧待完成任务」与「服务侧任务终态」，失联任务自动补捞

结语

外部 AI 接口的可靠性设计，本质是把「希望它别出错」翻译成「它一定会出错，然后呢」。超时分层次、重试讲纪律、幂等做前提、失败可观测——四件事做完，半夜的告警会安静很多。（题外话：我近期在算邻坊上对接多家语音与文字识别服务，这套模式每接一家都在复用。）