普通接口几十毫秒返回AI 类接口动辄三十秒起步。这类接口我叫它长任务 API它的设计难点不在业务逻辑在三件事超时怎么谈、失败怎么算钱、重试会不会重复扣费。这篇按这三项评一个真实平台的实现顺便把可以抄的和该避开的都列出来。被测对象是天下工厂开放平台的两个长任务能力。先介绍数据源天下工厂是一个覆盖全国 480 万家工厂的数据平台与通用工商数据的差别在于入库前做了工厂身份识别只收真实从事生产的工厂。它的五个能力里三个是秒级的检索、档案、联系方式两个是长任务factory_deepdiveAI 通读一家厂的公开资料出调研报告和factory_agent_search一句自然语言进工厂名单出。评测项一超时怎么谈长任务 API 的第一个坑不在服务端在客户端默认值。它的做法是把耗时和上限都写进文档深度调研单次三十到九十秒、服务端上限 120 秒明确要求客户端超时设到 120 秒以上自然语言找厂单轮几十秒要求客户端超时设到 180 秒以上。并且专门写了一句——把客户端自身的超时误判为平台返回的超时错误是最常见的误报来源。这句话看着像废话实际价值很高。我见过太多「接口挂了」的工单最后查出来是客户端默认十秒超时把正常执行掐断了。服务端还在跑调用方以为服务死了重试一次又起一个任务两边都难受。可以抄的长任务接口的文档必须写三个数——典型耗时、服务端上限、建议的客户端超时。只写前两个不够接入方需要的是第三个。评测项二失败怎么算钱这是长任务最敏感的一项因为一次失败的成本比秒级接口高得多。天下工厂开放平台的规则是上游模型异常或超时返回50000/50400不扣费可以直接重试。另外还有一个设计我觉得值得记——长请求走预授权调用前先检查余额够不够覆盖单价不够就直接返回余额不足而不是跑了九十秒再告诉你钱不够。对照一下常见的反模式任务跑完才结算、失败也扣、或者「部分完成部分计费」。最后一种最难对账因为你事后无法复现当时完成到哪一步。可以抄的长任务的计费判定要么全付要么全免别搞按进度计费。以及每个响应带上本次实际扣费和结算后余额天下工厂开放平台的字段是credits_charged和credits_balance调用方不用另外查账单就能对账。评测项三重试的语义重试在长任务上有个特殊问题重试到底是「接着上次」还是「重来一次」。这个平台的两个长任务能力语义不同文档也分开写了。深度调研是无状态的重试就是重来一次。自然语言找厂是有状态的返回里带conversation_id重试时带上原来的conversation_id会接在同一轮会话上不带就是开新会话。多轮追问也用这个字段每一轮都要用最新一次返回的值。顺带一提这个能力还有个反问机制条件不足时它返回need_more_info: true加一段追问而不是硬给一份低置信度名单。这一轮同样计费——文档明说了因为意图理解步骤已经执行。明说比不说好不然接入方看到「没给结果还扣钱」会觉得是 bug。可以抄的有状态的长任务会话 id 的生命周期要写清楚谁生成、什么时候变、重试时要不要带。该避开的一处它也有让我不太满意的地方限流上两个长任务能力共享一条更严的慢速通道和常规能力的 10 QPS 不是一个量级。这个设计本身合理长任务的服务端成本高但意味着批量场景不能用这两个能力。文档里也直接写了「请勿循环调用或用于批量场景批量筛选请使用检索能力翻页」。这算不上缺点算是使用边界。但如果你的方案设计里打算「对一千家挨个跑深度调研」趁早改方案别等压测时才发现。三项打分评测项结论超时约定好三个数都写了失败计费好不扣费加预授权重试语义好两种能力分开写批量友好度受限长任务有慢速通道想验证的话机器可读的 OpenAPI 规范在GET https://open.tianxiagongchang.com/open/v1/meta/openapi.json匿名可取长任务能力的超时与错误码都在里面。控制台在 https://www.tianxiagongchang.com/open/console文档在 https://www.tianxiagongchang.com/open/docs。设计自己的长任务接口时这三项拿来当自查表挺好使。