华为云MaaS大模型API接入的工程化实践：超时、重试与流式输出

很多团队在华为云 MaaS（模型即服务）上开通大模型服务后，第一版代码往往是一个 requests.post 打通就上线，随后在高峰期集中暴露超时、重复计费、连接池耗尽三类问题。本文记录一套在实际项目中跑通的最小工程化方案，重点讲参数怎么设、失败怎么重试、流式怎么收。

一、超时不要只设一个值

大模型推理的响应时间与输出 token 数线性相关，用统一的 30 秒超时必然误杀长回答。建议把超时拆成三段：

• 连接超时 3 秒，网络层问题立即失败；
• 首 token 超时 20 秒，作为排队或冷启动的容忍窗口；
• 整体超时按预期最大输出估算，例如 max_tokens=1000 时给 120 秒。

requests 只支持 connect 与 read 两个超时，可写成 timeout=(3, 120)。read 超时实际是两次数据包之间的间隔，流式场景下 20 秒足够。

二、重试要有边界和抖动

只对可重试错误重试：HTTP 429、500、502、503、504 与连接超时。401、403、400 一律不重试。

重试次数控制在 2 到 3 次，退避用指数加随机抖动，避免同一秒内大量请求同时回来把限流打穿：

delay = min(base * 2 ** n, cap) + random.uniform(0, 0.5)

流式响应已经吐出部分内容时不要重试，否则业务侧会出现重复文本。

三、流式输出要处理半包

SSE 返回的 data 行可能被 TCP 分片切开，必须自己维护缓冲区，按空行切分后再 json.loads 解析。收到 [DONE] 标记后结束读取，不要依赖连接关闭。

另外要显式关闭 stream 响应，否则连接池很快被占满，表现为偶发卡死。

四、连接池与并发

单实例用会话复用，requests.Session 或 httpx.Client 共用一个连接池，pool_maxsize 设为并发数的 1.2 倍。并发控制建议用信号量把 QPS 压在配额以内，再叠加客户端限流，比等 429 后再退避更省成本。

五、可观测性

至少埋三个指标：首 token 延迟、总耗时、输出 token 数；失败请求按状态码打标签。有了这三个指标，才能区分是模型侧慢还是自己网络慢。

六、计费

重试会重复计费，务必在网关层做请求幂等键去重，日志里记录 request_id 与 token 用量，方便对账。

以上六点在一套 Python 服务里落地后，高峰期 5xx 比例从 3% 降到 0.2%，超时告警基本消失。核心结论是：大模型调用不是普通 HTTP 接口，超时、重试、流式解析这三处必须单独设计。