AI 内容检测这类接口,几乎没有同步的。一次推理动辄几秒到十几秒,同步等结果会把 HTTP 连接一直占着,扛不住并发。所以主流的做法都是「提交拿 task_id,然后轮询」。
但轮询这件事,看着简单,做起来全是坑。这一篇把轮询、超时、退避、续查四件事一次性讲透。
一、先建立正确的心智模型
提交和查结果是两个独立动作,中间隔着一层「任务状态机」:
text
POST /v1/text/classify → { task_id, status: "pending", cost: "0.0600" }
↓ 后台执行
GET /v1/tasks/{task_id} → { status: "pending" | "running" | "succeeded" | "failed" }
四个状态里,pending 和 running 是中间态,succeeded 和 failed 是终态。只有到了终态,这一单才算结束。
要理解的最关键一句话是:查询拿不到结果,不代表任务没在做。任务在服务端队列里排队、在上游推理,这些过程你的轮询是看不见的,你看到的只是「还没好」。
二、轮询间隔怎么定
轮询间隔不是越小越好,它受两个约束:
- 查询接口有独立的 QPS 上限(默认 10 次/秒,按账号)。
- 轮询换不来更快的推理。推理耗时由上游决定,你 0.5 秒查一次和 1.5 秒查一次,拿到终态的时间几乎一样,只是前者多烧了查询配额。
所以间隔的合理下限是 1 秒。更实用的做法是按任务耗时预估一个首查延迟:
python
FIRST_POLL_DELAY = 1.0 # 先等 1 秒再查,别提交完立刻查
POLL_INTERVAL = 1.5 # 常规间隔
一张表看清楚间隔和查询压力的关系(查询 QPS ≈ 在途任务数 / 间隔):
| 在途任务数 | 间隔 | 查询 QPS |
|---|---|---|
| 10 | 1.0s | 10(打满) |
| 10 | 2.0s | 5(安全) |
| 30 | 1.0s | 30(持续 429) |
并发上去了,间隔就得跟着拉长,否则查询先被限流。这条比「轮询勤快点」重要得多。
三、退避:固定、线性还是指数
任务耗时是不确定的,短文本可能 1 秒就出,长文本或高峰时段可能拖到十几秒。固定间隔在两种情况下都不合适:快的任务被白等,慢的任务被密集空查。
推荐带上限的指数退避:间隔从 1 秒开始,每次翻倍,封顶在 5 秒左右。
python
import time
def poll_with_backoff(client, task_id, *, base=1.0, cap=5.0, deadline=180.0):
start = time.monotonic()
interval = base
while True:
if time.monotonic() - start > deadline:
raise TimeoutError(f"task {task_id} not finished in {deadline}s")
task = client.get_task(task_id)
if task.status in ("succeeded", "failed"):
return task
time.sleep(interval)
interval = min(interval * 2, cap)
为什么用指数而不是线性:多数任务在前几秒就出结果,指数退避让「快的任务」少空查,「慢的任务」也不会被频繁打断。封顶是为了保证慢任务最终能被查到,而不是退避到一个小时查一次。
四、超时:最大的坑在这里
轮询超时 ≠ 任务失败。这是最容易造成资损的认知错误,值得单独加粗。
你的轮询循环设了 3 分钟超时,3 分钟到了任务还是 running,于是你把它当失败处理------重试,重新提交。结果就是重新扣了一次费 ,而上一次的任务其实还在跑,稍后就 succeeded 了。
正确的做法是两层:
- 等待超时,只放弃「等待」,不放弃「任务」 。把
task_id存下来,稍后用另一个线程、另一轮对账去续查。 - 重试必须复用同一个幂等键 。超时后重新提交时带上原来的
Idempotency-Key,服务端会返回同一个task_id,而不是新建一个任务再扣一次钱。
python
# 超时后:不要重新提交,继续查同一个 task_id
task = client.get_task(saved_task_id) # 续查
# 而不是:
# client.submit_text(text) # ← 这是重新扣费
五、续查:异步任务的生命周期管理
一个健壮的客户端,必须把「任务 ID」当成可持久化的资源来管,而不是一次循环里的临时变量。
典型的做法是任务落库,状态由后台 job 推进:
text
提交 → 写 task 表(status=pending, idempotency_key 唯一索引)
↓
轮询 job 每 N 秒扫一批 pending/running → 查到终态 → 更新状态 + 记结果
↓
对账 job 把「超时未推进」的 task 捞出来 → 续查 or 标记失败(走幂等退款判定)
这套结构的好处是:进程重启、网络抖动、跨天执行,都不会丢任务。丢了也能从库里捞回来续查。
六、一个完整的轮询实现(Go)
给一个 Go 版本,带超时和退避,可以直接抄:
go
func PollUntilDone(ctx context.Context, c *Client, taskID string, deadline time.Duration) (*Task, error) {
deadlineAt := time.Now().Add(deadline)
interval := time.Second
for {
if time.Now().After(deadlineAt) {
return nil, fmt.Errorf("poll deadline exceeded, task=%s", taskID)
}
t, err := c.GetTask(ctx, taskID)
if err != nil {
// 网络错误别直接放弃,退避后重试查询(GET 幂等,重查无副作用)
interval = min(interval*2, 5*time.Second)
time.Sleep(interval)
continue
}
if t.Status == "succeeded" || t.Status == "failed" {
return t, nil
}
interval = min(interval*2, 5*time.Second)
time.Sleep(interval)
}
}
注意查询是幂等的 GET,查多少次都没有副作用,所以查询失败(网络抖动)可以放心重试。这和「重新提交」是完全不同的事。
七、小结
异步检测的轮询,本质是三句话:
- 间隔别贪快,1 秒起步、指数退避、5 秒封顶,查询配额比你想的容易打满。
- 超时不是失败 ,拿
task_id续查,绝不重新提交。 - 重试靠幂等键,超时重试复用同一个键,才是「重试」,否则是「重买」。
把这三句话落实成代码,异步检测接起来就稳了。
示例基于文识云(sbnew.top)的检测接口约束(提交 2 QPS、查询 10 QPS、日配额 1000)。具体数值以你的账号档位为准,轮询与超时的逻辑不变。