把语音转文字能力接进业务系统,大多数工程师踩的第一个坑是拿同步接口的思维去调长音频转写:上传一个 90 分钟的会议录音,等接口返回,30 秒超时,任务失败。本文给出一套经过实战验证的接入架构,核心是四个字:异步优先。
转写一小时的音频,服务端处理时间以分钟计。任何同步 HTTP 调用在这个量级下都不现实——网关超时、连接不稳、客户端重试风暴,每一个都是事故源。所以主流转写服务(包括算邻坊这类聚合服务平台)对长音频一律采用任务模型:
客户端 服务端
│── POST /submit (音频/URL) ──→│ 创建任务,返回 task_id
│←───────── task_id ───────────│
│ │ 异步处理(分钟级)
│── GET /poll?task_id=xxx ────→│ 轮询:processing
│←───────── processing ────────│
│←── 回调 webhook(可选)───────│ 完成时主动通知
│── GET /result?task_id=xxx ──→│
│←───────── 转写全文 ───────────│架构设计的重点,全在客户端这一侧怎么把任务管稳。
音频超过 50MB 就别走 multipart 直传了:先把文件传对象存储,把 URL 交给转写服务。好处有三——上传失败与转写失败解耦、服务端拉取自带重试、同一音频可以被多个任务复用。
def poll_task(task_id):
interval = 5
while True:
status = api.get_task(task_id)
if status.state in ("success", "failed"):
return status
interval = min(interval * 1.5, 60) # 5s → 60s 封顶
time.sleep(interval)一分钟级处理时长的任务,轮询间隔从 5 秒起步指数拉长到 60 秒封顶,足够灵敏又不浪费配额。
只依赖 webhook 会在网络抖动时丢通知;只依赖轮询又浪费。生产上正确的姿势是双轨:回调到了就立即处理,同时保底轮询兜底——回调是加速器,轮询是安全网。两条通道先到先处理,这就引出下一节。
回调与轮询可能交付同一结果两次,落库必须幂等。以 task_id 为唯一键做 upsert,处理逻辑先查后写:
INSERT INTO transcripts (task_id, text, status, updated_at)
VALUES (%s, %s, 'success', NOW())
ON CONFLICT (task_id) DO UPDATE SET text = EXCLUDED.text, updated_at = NOW();没有幂等设计的接入层,上线第一周就会看到重复入库的脏数据。
失败位置 | 处理策略 |
|---|---|
提交失败 | 立即重试(3 次),仍失败进死信队列告警 |
转写失败(服务端) | 区分错误码:参数错不重试;内部错退避重试 2 次 |
轮询超时 | 不代表任务失败——转查询回调记录,双通道都无结果才标记失联 |
回调丢失 | 保底轮询在 deadline 后补刀 |
关键认知:轮询超时 ≠ 任务失败。多少系统把「轮询器重启」误判成「转写失败」然后重复提交,制造出一堆重复任务。
长音频转写接入的架构骨架就这四件事:URL 优先的提交、指数退避的轮询、双轨并行的回调补偿、task_id 幂等的落库。这套骨架不只适用于转写——视频处理、大规模 OCR、文档解析,所有分钟级异步任务的服务都是同一个模型。把这套接口形态固化成内部的统一任务客户端,后面每接一个新能力都是填空题。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。