中转站调用 Claude 流式输出卡住、断流、首字很慢怎么办？缓冲、超时、代理和重试的排查方法

import json, os, sys, time
import requests

BASE = os.environ["BASE_URL"]  # 中转站地址，例如 https://你的中转站域名
MODEL = os.environ.get("MODEL", "claude-sonnet-5-5")
PROMPT = sys.argv[1] if len(sys.argv) > 1 else "用三百字介绍一下 TCP 三次握手。"

def probe():
    t0 = time.time()
    st = {"events": {}, "first_event": None, "first_thinking": None, "first_text": None,
          "max_gap": 0.0, "gap_at": "", "stop_reason": None, "usage": None,
          "done": False, "error": None, "broken": None}
    last, cur_event = t0, None
    try:
        # timeout=(连接, 读取)：读取超时指两次收到数据之间的间隔，不是整个响应的时长
        r = requests.post(f"{BASE}/v1/messages", stream=True, timeout=(10, 120), headers={
            "Authorization": f"Bearer {os.environ['API_KEY']}",
            "anthropic-version": "2023-06-01", "content-type": "application/json"},
            json={"model": MODEL, "max_tokens": 1024, "stream": True,
                  "messages": [{"role": "user", "content": PROMPT}]})
        st["status"], st["headers_s"] = r.status_code, time.time() - t0
        st["request_ids"] = {k: v for k, v in r.headers.items() if "request-id" in k.lower()}
        r.encoding = "utf-8"
        if r.status_code != 200:
            st["error"] = r.text[:300]  # 非 200 时返回的是普通 JSON 错误，不是事件流
        for line in (r.iter_lines(decode_unicode=True) if r.status_code == 200 else []):
            now = time.time()
            if not line:
                continue
            if line.startswith("event:"):
                cur_event = line[6:].strip()
                st["events"][cur_event] = st["events"].get(cur_event, 0) + 1
                if st["first_event"] is None:
                    st["first_event"] = now - t0
                elif now - last > st["max_gap"]:
                    st["max_gap"], st["gap_at"] = now - last, cur_event
                last = now
            elif line.startswith("data:"):
                data = json.loads(line[5:])
                if cur_event == "content_block_delta":
                    kind = data["delta"]["type"]
                    if kind == "thinking_delta":
                        st["first_thinking"] = st["first_thinking"] or now - t0
                    elif kind == "text_delta":
                        st["first_text"] = st["first_text"] or now - t0
                elif cur_event == "message_delta":
                    st["stop_reason"], st["usage"] = data["delta"].get("stop_reason"), data.get("usage")
                elif cur_event == "message_stop":
                    st["done"] = True
                elif cur_event == "error":
                    st["error"] = data
    except requests.exceptions.RequestException as e:
        st["broken"] = f"{type(e).__name__}: {e}"
    st["total_s"] = time.time() - t0
    return st

if __name__ == "__main__":
    s = probe()
    f = lambda v: "无" if v is None else f"{v:.2f}s"
    print(f"HTTP 状态 {s.get('status')}，响应头到达 {f(s.get('headers_s'))}，请求 ID {s.get('request_ids')}")
    print(f"首个事件 {f(s['first_event'])}，首个思考片段 {f(s['first_thinking'])}，首个正文片段 {f(s['first_text'])}")
    print(f"事件间最大间隔 {s['max_gap']:.2f}s（出现在 {s['gap_at'] or '无'} 之前），总耗时 {s['total_s']:.2f}s")
    print(f"事件计数 {s['events']}")
    print(f"正常结束(message_stop) {s['done']}，stop_reason {s['stop_reason']}，usage {s['usage']}")
    if s["error"]:
        print("错误内容：", s["error"])
    if s["broken"]:
        print("连接中断：", s["broken"])
    elif not s["done"] and not s["error"]:
        print("流提前结束：没有收到 message_stop，也没有错误事件")

location /v1/ {
    proxy_pass https://你的中转站域名;
    proxy_ssl_server_name on;   # 默认 off；上游是 HTTPS 时，让 TLS 握手带上服务器名
    proxy_http_version 1.1;
    proxy_buffering off;        # 默认 on：响应先攒进缓冲区再发给客户端
    proxy_read_timeout 600s;    # 默认 60s：两次读取之间超过这个时间没数据就断开
}