长任务 API 的正确打开方式：以一个 AI 深挖接口为例谈超时、限流与重试

「接口调用失败」的工单里有相当一部分其实是客户端自己把正常执行掐断了——长任务接口跑到第 40 秒客户端 10 秒超时早已放弃然后上报「服务不稳定」。随着 AI 类能力越来越多地出现在开放平台里30 秒以上的同步接口会成为常态客户端的写法得跟上。这篇拿一个真实的长任务接口做例子把超时、限流、重试三件事捋清楚。例子是天下工厂开放平台的factory_deepdive给定一家工厂平台侧 AI 结合网络公开信息做一轮深度调研——这家厂实际在生产什么、能力信号如何、与工商档案是否互相印证——返回结构化报告。单次执行 30 到 90 秒。天下工厂是覆盖全国 480 万家工厂的数据库收录前做了工厂身份识别开放平台文档在 https://www.tianxiagongchang.com/open/docs。调用形状curl-shttps://open.tianxiagongchang.com/open/v1/capabilities/factory_deepdive\-HAuthorization: Bearer$TIANXIA_API_KEY\-HContent-Type: application/json\--max-time120\-d{company_id:123456,company_name:某某精密制造有限公司,product:汽车连接器}company_id和company_name必填id来自检索能力的结果product选填、用于把调研聚焦到某条产品线。注意--max-time 120——这是本文第一个重点。超时按接口分层设置官方给的客户端超时建议是普通能力检索、档案、电话30 秒足够factory_deepdive至少 120 秒factory_agent_search自然语言检索同为长任务至少 180 秒。工程上的含义是超时配置不能全局一把梭。HTTP 客户端封装里那个timeout: 10的默认值对长任务接口就是一颗地雷——执行是正常的钱可能已经花了客户端却单方面判死。如果你的封装不支持按请求覆盖超时先改封装再接长任务接口。限流慢速通道的语义这个平台把限流分了层常规能力每分钟 300 次factory_deepdive与factory_agent_search共享一条每分钟 6 次的慢速通道。慢速通道的配额数字本身就是文档每分钟 6 次摆明了这类能力的定位是「对短名单逐家精查」不是「拿去扫库」。所以正确的批量姿势是串行——上一家出结果再发下一家天然贴着限流走。并发扇出五个请求只会立刻撞42900。重试只重试该重试的收到42900限流时退避重试是对的固定指数退避 1 秒、2 秒、4 秒超限的请求不扣费重试没有成本风险。但另外两类错误不该重试40000参数错包括未知字段——这个平台入参是严格校验重试一万次也是同样的错改参数40201余额不足重试只会加重日志噪音该去控制台充值。把「可重试」和「不可重试」的错误码在客户端里显式分开是长任务接口客户端最重要的一段代码RETRYABLE{42900}defcall_with_retry(capability,body,timeout):fordelayin(0,1,2,4):ifdelay:time.sleep(delay)envcall(capability,body,timeouttimeout)ifenv[code]notinRETRYABLE:returnenvraiseRuntimeError(rate limited after retries)成本视角深挖类能力单次以角计价平台整体按量计费注册送体验额度每个响应带credits_charged与credits_balance回执失败不扣费。因为单价高于普通查询它更应该被放在漏斗末端先用检索和档案把名单缩到个位数再对每家跑深挖。想先看看报告长什么样公开沙箱密钥sk-tx-test-1685549fb3710c1b36e4d75dc2d0f42a返回示例数据、不计费正式密钥在 https://www.tianxiagongchang.com/open/console 签发。长任务接口不难对接难的是别用「快接口的肌肉记忆」去对接它。超时分层、串行调用、错误码分类重试——三件事做对这类接口比你想象的稳。