Claude/GPT API 流式输出断流、超时、乱码全排查（2026 实战）

2026 年随着 Agent、长上下文和深度推理模型普及，单次 API 响应越来越长，流式输出（streaming / SSE）几乎成了刚需——没人愿意盯着光标等三十秒才看到第一个字。但流式也是报错重灾区：调用 Claude、GPT API 时，最常见的吐槽就是「stream: true 一开就中途断流」「跑到一半 504 超时」「输出的中文变成一堆乱码」。这篇把这三类问题从客户端、网络代理一直排到中转服务，逐层给你能直接抄的解法。

一、流式输出到底是怎么断的？先分清三种症状

排查前先对号入座，三种症状根因完全不同，别一股脑去改超时时间：

二、客户端：90% 的乱码和「假流式」死在这一层

很多人用 requests 同步库硬读流，结果要么乱码要么根本不流式。流式响应必须按字节读、按 UTF-8 边界解码，并显式开启 stream=True。下面是 Python 的标准吃法：

import json, requests

resp = requests.post(
    "https://api.aisafa.xyz/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx", "Accept": "text/event-stream"},
    json={
        "model": "claude-opus-4-8",
        "messages": [{"role": "user", "content": "写一首关于海的诗"}],
        "stream": True,
    },
    stream=True,          # 关键：不开这个就是假流式
    timeout=(10, 300),    # (连接超时, 读超时) 读超时要给够
)
for line in resp.iter_lines(decode_unicode=True):  # 按行读 SSE
    if not line or not line.startswith("data: "):
        continue
    chunk = line[6:]
    if chunk == "[DONE]":
        break
    delta = json.loads(chunk)["choices"][0]["delta"].get("content", "")
    print(delta, end="", flush=True)   # flush 很重要，否则终端看着像没流式

三个最常踩的坑：① 忘了 stream=True，整段攒完才返回，看着像超时；② print 不加 flush=True，输出被行缓冲攒住，误以为断流；③ 自己手动 resp.content.decode() 整块解码，遇到分包切断的多字节汉字必乱码——交给 iter_lines 或按字节增量解码即可。

三、网络与代理：断流和 504 的真凶往往在这

国内直连官方 API 走 http://127.0.0.1:7890 这类本地代理时，流式最容易被「缓冲」掉。两个高频元凶：

• 代理开启了响应缓冲：Clash/V2Ray 一般没问题，但若中间加了 nginx 反代，必须关掉缓冲，否则它会攒齐整个响应再转发，流式直接退化成一次性返回甚至 504。
• 空闲超时太短：模型「思考」时 SSE 可能几秒没数据，被中间层判定空闲而断开。

如果你自建了 nginx 转发层，务必加这几行：

location /v1/ {
    proxy_pass http://upstream;
    proxy_buffering off;          # 关闭缓冲，流式才能逐字转发
    proxy_cache off;
    proxy_read_timeout 600s;      # 给长响应留足时间
    proxy_set_header Connection "";
    chunked_transfer_encoding on;
}

另一个隐蔽坑：部分企业网关/CDN 会强制缓冲 text/event-stream。如果你怎么调本地都正常、一上线就断流，先怀疑这一层。

四、中转服务这一层：稳定流式的「地基」

把客户端和自家代理都调对了，仍有人三天两头断流——问题出在最上游：你接的那条 API 链路本身就不稳。免费/廉价中转为了省成本常做激进缓冲、连接复用过度、甚至偷偷降级模型，流式体验自然忽好忽坏。

这也是Safa API被很多国内开发者拿来当默认入口的原因——它是 AI 模型 API 中转站，官方直连不降智，全链路对 stream: true 做了透传不缓冲，长响应也不会被中途掐断；一个接口同时接入 Claude / GPT / Gemini，国内免翻墙、人民币付费，省去自己折腾代理和超时调参的功夫。无论你用 Cursor、Claude Code 还是自己写脚本，把 base_url 换成它的端点、填好 Key 就能跑，流式开箱即用。

一句话给你省时间：如果客户端代码和本地代理都按上面调好了还断流，别再死磕自己这端——换一条透传流式、不缓冲不降智的稳定中转链路，往往一步到位。

五、30 秒自检清单

• 请求体确认带了 "stream": true，客户端也开了流式读取（如 requests 的 stream=True）
• 读超时（read timeout）≥ 300s，别用默认的几十秒
• 输出用 iter_lines / 按字节增量解码，别整块 decode（防乱码）
• 打印加 flush=True，排除「看着像断流」的假象
• 自建 nginx 反代关掉 proxy_buffering、调大 proxy_read_timeout
• 以上都对仍断流 → 换一条透传不缓冲的稳定中转链路