请求超时是客户端主动断连所致，主因是网络、服务延迟或超时配置过短；应设timeout=(10,30)、分块处理长文本、启用指数退避重试并验证网络与密钥有效性。

调用千问AI API时请求超时，意味着客户端在等待响应过程中主动中断连接，常见表现为requests.exceptions.Timeout、HTTP 504或Connection timed out错误，这通常不是代码写错，而是网络链路、服务端延迟或客户端配置失配导致的可干预问题。

延长超时阈值

默认HTTP超时（如requests库的3秒）远低于千问模型实际推理耗时，尤其在生成长文本或高负载时段极易误判为失败。显式设置合理超时是第一步。

在Python requests调用中，将timeout参数设为元组形式：【timeout=(10, 30)】，其中第一个数值为连接超时（秒），第二个为读取超时（秒）。连接超时设5–10秒足够，读取超时必须≥25秒——qwen-plus处理万字摘要平均耗时18秒，留出冗余才能避免提前断连。

若使用aiohttp，需同步调整client_timeout，且read_timeout不得低于25秒；在Dify或FastAPI等中间层调用时，检查其HTTP客户端是否继承了全局超时配置，必要时覆盖为timeout=30.0。

检查并分块处理长文本

超时常是静默卡顿而非报错，根源往往是输入超出模型token上限却未被拦截：qwen-turbo上限6144，qwen-plus为32768，超过后服务端可能持续等待直至超时。

方法一：用transformers.AutoTokenizer精确计数。加载tokenizer后对input文本执行encode，len(tokenizer.encode(text))即真实token数。

方法二：字符长度粗筛。若messages中所有role-content字符串总长度＞15000，直接触发预分块流程——这不是绝对阈值，但能覆盖90%超长误判场景。

方法三：语义切块重试。将文档按段落拆成≤4096 token的子块，逐块调用并拼接结果。注意保留前一块末尾两句话作为下一块的上下文锚点，否则逻辑断裂。

添加指数退避重试

瞬时网络抖动或服务端临时拥塞会导致偶发超时，无重试机制等于放弃一次成功机会。但盲目重试会加重服务压力，还可能重复计费。

第一步：仅对超时类异常启用重试——requests.exceptions.Timeout、HTTPStatus.GATEWAY_TIMEOUT（504）、ReadTimeout。严禁对4xx错误重试，比如401（密钥失效）重试只会连续扣费。

第二步：使用tenacity库配置策略，示例：@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))。三次尝试间隔分别为2秒、4秒、8秒，避免雪崩式请求洪峰。

第三步：禁用SDK内置重试。dashscope.init()中显式设置【max_retries=0】，防止业务层自定义重试与SDK底层重试叠加，造成请求翻倍。

验证网络与认证有效性

很多“超时”本质是请求根本没发出去。先确认基础链路是否通畅。

执行ping tongyi.aliyun.com和curl -I https://dashscope.aliyuncs.com，若均超时，说明本地DNS或防火墙阻断了访问。临时关闭杀毒软件，特别放行对dashscope.aliyuncs.com和auth.aliyuncs.com的HTTPS请求。

检查API Key是否完整粘贴——开头漏掉sk-、末尾多一个空格、复制时混入不可见Unicode字符，都会导致鉴权失败并返回超时假象。登录DashScope控制台，在“API密钥管理”页确认该Key状态为“启用”，且未达配额上限。

确认Base URL结尾含/v1路径，例如https://dashscope.aliyuncs.com/v1，缺失将返回404，部分客户端会误报为超时。