把千问 3.5 Flash 接入国内服务时，卡住你的往往不是模型本身，而是鉴权头、超时设置和流式解析这三件小事。本文按排查顺序拆开讲，帮你把问题定位到具体那一行配置。

开始之前，先把三个变量对齐

大部分“接入失败”的报错，追到根上都是三个值不一致：API Key、Base URL、模型名称。这三项只要有一项是从旧文档里复制来的，就会出现各种看似玄学的现象。所以在写代码之前，建议先做一次手工核对。

• API Key：确认它属于当前环境（测试 Key 和线上 Key 不要混用），并且没有多余的空格、换行或不可见字符。
• Base URL：确认它指向的是你正在使用的服务端地址，末尾是否带 /v1 取决于服务商的约定，不要凭记忆拼。
• 模型名称：这是最容易被忽略的一项。模型名称必须与控制台或模型广场中展示的名称完全一致，大小写、版本后缀、短横线都可能影响结果。

如果你用的是统一接入方式，比如在 通联AI中转站 这类 AI 聚合平台上调用，通常可以在控制台里直接看到当前可用的接口地址、兼容协议与模型列表。做国内 API 接入时，先照着控制台显示的内容抄一遍到本地配置文件，比在代码里反复试错要快得多。

鉴权失败：401 和 403 说的不是同一件事

先看状态码，再动手改代码

401 Unauthorized 几乎都和凭证本身有关：Key 写错、Key 被删除或重置、请求头格式不对、环境变量没读到。最常见的一种情况是本地用 export 设置了变量，但服务是通过 systemd、Docker 或 IDE 启动的，根本没继承到那个变量，程序读到的其实是空字符串。

403 Forbidden 则更偏向权限与调用范围：Key 有效，但当前账号、项目或额度状态下不允许访问该模型。这类问题改请求头没用，需要回到控制台确认余额、权限分组和模型可见范围。

排查鉴权问题时，第一步永远是打印出你实际发出的请求头（记得对 Key 做脱敏），而不是反复修改文档里的示例代码。看到真实请求，问题基本就现形了。

几个高频细节

• 请求头应当是 Authorization: Bearer ${API_KEY}，中间是一个空格，不要写成 Bearer: xxx。
• 不要把 Key 写进 URL 查询参数，多数接口不接受这种传法。
• 从网页控制台复制 Key 时，注意末尾是否被截断，尤其是长 Key 在多行文本框里复制。
• 如果用了网关或反向代理，确认它没有把 Authorization 头过滤掉。

可以用一段最小请求先验证凭证，排除业务代码的干扰：

curl -sS -X POST "你的BaseURL/v1/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台中显示的模型名称", "messages": [{"role":"user","content":"ping"}], "stream": false }'

这条命令能通，说明鉴权、地址、模型名称三件事都对齐了，问题就在你的业务代码里；这条命令不通，就别再往下写业务逻辑了，先解决凭证问题。

超时问题：分清连接超时和读超时

“请求超时”是个笼统的报错，实际至少有两种：一种是连不上，TCP 或 TLS 握手阶段就失败，通常是 DNS、网络出口或地区访问策略的问题；另一种是连上了但迟迟没有返回，属于读超时，往往和输入长度、生成长度、并发排队有关。

区分方法很直接：看报错出现得有多快。几百毫秒内就失败的，多半是连接层；等到几十秒才失败的，基本是读超时。两者的处理方向完全不同。

• 连接层：检查 DNS 解析、代理配置、防火墙出站规则，以及客户端是否支持当前 TLS 版本。
• 读超时：给客户端设置一个合理的总超时，同时把长文本任务拆小，或者改用流式返回，让数据尽早开始传输。
• 重试策略：只对幂等的、非流式的请求做有限次重试，并加退避；流式请求中途断开时盲目重试，容易出现内容重复。

这里有个常见误区：很多人以为把超时设成 300 秒就能解决一切。实际上长超时会把问题从“报错”变成“页面一直转圈”，用户体验反而更差。更稳妥的做法是把单次生成控制在可预期范围内，超时阈值略高于正常耗时，而不是无限放大。

流式输出问题：从 SSE 解析到网关缓冲

服务端返回了，客户端却看不到

流式输出（stream: true）出错时，现象通常有三种：一个字都不出、一次性全部返回、内容中间断裂或出现乱码。逐个看。

一个字都不出，优先检查中间是否有多层反向代理在做缓冲。Nginx 默认会缓冲上游响应，需要在对应 location 上关闭缓冲并设置不缓存，同时确认响应头里的 Content-Type 是 text/event-stream。如果你用的是云函数或某些 PaaS，也可能存在平台级的响应缓冲，需要查平台文档。

一次性全部返回，一般是客户端读取方式的问题。必须按行迭代读取，而不是等整个响应体下载完再解析。

for raw in resp.iter_lines(): if not raw: continue if raw.startswith(b"data: "): payload = raw[6:] if payload.strip() == b"[DONE]": break chunk = json.loads(payload) # 取出 delta 中的增量文本，逐段拼接

内容断裂或乱码，多数是分块边界踩在了多字节字符中间。SSE 的每一行不一定对应一个完整的 UTF-8 字符边界，所以一定要先累积字节、再解码，而不是对每个网络分片单独做解码。同时记得跳过空行和心跳行，它们不代表内容结束。

还要注意这几个边界

• 结束标志 [DONE] 之后不要再继续解析，否则可能抛出 JSON 解析异常。
• 每个数据行前面通常是 data: ，注意冒号后有一个空格，直接切片位置要算准。
• 流式结束后，把累积的文本拼接一次再做后处理，不要在增量阶段做标点补全，容易破坏上下文。
• 前端展示时，建议加节流刷新，避免每个 token 都触发一次重渲染。

一张表看清排查路径

把排查经验固化成模板

千问 3.5 Flash 国内 API 接入踩的坑，八成集中在这三处：凭证没传对、超时没分层、流式没按事件流解析。把这三处做成一份可复用的配置模板——环境变量集中管理 Key，Base URL 与模型名称写成配置项而不是硬编码，请求层统一处理超时、重试和流式解析——以后再换模型或换服务端地址，只需要改配置，不用改业务代码。

如果你同时要对接多个模型，与其在每个项目里各维护一套地址和 Key，不如考虑用统一接入的方式，把接口地址、Key 与调用配置集中管理。需要查看具体的模型列表、兼容协议和接入说明时，可以直接到 通联AI中转站官网 对照控制台信息核对，再决定用哪种调用方式接入。