流式输出下的客户端超时，通常不该只留一个数。建议拆成连接超时、首字节超时（或块间读超时）、整体超时三处，各自只负责一段链路；一次性返回的调用则主要看整体耗时。界面长时间空白，未必是服务端没返回，也可能是 HTTP 客户端在攒包、压缩层在合并数据，或者读超时太短、流还没吐出首块就被掐断。判断顺序建议是：先用逐块打印确认服务端是否真的在分块发，再看客户端有没有缓冲，最后才调超时值。

处理方向：先验证是不是真流式，再动超时参数。服务端逐块到达但界面不动，优先查客户端缓冲与服务端压缩；确认是流式后，把连接、首字节、整体三段超时分开配置，并记录首字节耗时与总耗时，用两个数据区分瓶颈在网络还是模型生成。边界：本文不给可直接照搬的超时默认值，取值需结合链路往返、首 token 生成时间和网关行为确认后再回归验证。

把连接超时、首字节超时、整体超时拆成三个参数

三个参数混成一个，出问题时无法对号入座：到底是连不上、还是服务端迟迟不出首块、还是输出太长把总时长耗尽了，只能靠猜。拆开后每段链路各自兜底，日志里也更容易定位。

取值关系的保守建议是：连接超时 < 首字节超时 < 整体超时；首字节超时按“正常首 token 生成时间再留一截余量”来定，整体超时按“最长输出所需时间”来定。是否给出具体秒数要结合环境确认，不同模型、不同网络路径差异很大，先记录再定值比先定值再调更稳。另外要留意：Python requests 的 read 超时管的是每次读的等待间隔，不等于整体超时；Node 生态里 AbortController 的计时器则更像整体超时。用哪个参数表达整体上限，取决于客户端库本身，接入前建议翻一眼库的行为说明或写个小用例验证。

按块读取并逐块打印，确认是不是真的流式

下面的骨架放在本地脚本里跑，URL 和请求体按实际接口替换。关键点是 stream=True 与 iter_content(chunk_size=None)，让数据按底层到达情况返回，而不是攒够一定长度再给。

import time, requests

URL = 'http://127.0.0.1:8000/v1/chat/completions'  # 替换成实际地址
BODY = {'stream': True, 'messages': [{'role': 'user', 'content': '写一段 200 字说明'}]}

t0 = time.monotonic()
first = None
total = 0
with requests.post(URL, json=BODY, stream=True,
                   timeout=(5, 30)) as r:   # 占位值：(连接, 块间读)，需按环境确认
    print('status', r.status_code, 'at', round(time.monotonic() - t0, 3))
    for chunk in r.iter_content(chunk_size=None):
        now = time.monotonic()
        if first is None:
            first = now
        total += len(chunk)
        print(f'chunk at={now - t0:.3f}s len={len(chunk)} acc={total} head={chunk[:40]!r}')
        if now - t0 > 120:      # 整体上限自己兜，requests 的 timeout 不负责这段
            print('total timeout hit, bytes=', total)
            break
print('first_byte', None if first is None else round(first - t0, 3), 'bytes', total)

判读方法：每块长度不大、到达时间戳均匀分布，说明服务端确实在逐段发；如果第一块很晚才到、且一次给出很大的长度，多半是中间有缓冲，或者服务端根本没有流式返回；如果只打印出一块就结束，先怀疑网关或客户端把响应体读完了再交给你。可以用 curl -N 对同一个地址做对照，curl 里逐行刷出而脚本里一次性到达，问题就在脚本或中间的代理层。

检查客户端缓冲设置

数据已经到了客户端进程，界面却不更新，通常不是超时参数的事。按下面几类依次排查：

• HTTP 客户端缓冲：确认没有使用会读完整个响应体的方法（例如先取 text 再处理），也没有在读取前套一层会聚合的解码逻辑。排查动作：在读到第一块时立刻打日志，看日志出现的时间是否早于界面刷新。
• 服务端压缩：响应带 gzip、br 等压缩时，压缩库通常要攒一批数据才输出，流会被合并成几大块。排查动作：请求头里显式关闭压缩，或在服务端对流式接口不启用压缩，再对比块的数量和间隔。
• 前端渲染批次：把每个块 append 到数组后，框架可能合并多次更新再渲染。排查动作：临时改成每块到达直接改写一个 DOM 文本节点，观察是否还“卡住”；若立刻刷新，问题在渲染层而不是网络层。
• 中间层缓冲：反向代理或网关可能启用响应缓冲。排查动作：看网关日志里响应发出的时间点，与客户端收到的首块时间比对。

这类问题不要用“调大超时”掩盖，超时调大只是让等待变得更久，缓冲依旧存在。

把超时值做成可配置项并构造慢响应场景

超时值写死在代码里，换环境就要改代码，也不方便做对照。建议从环境变量读取，并在启动日志里打印实际生效值。

import os

TIMEOUTS = {
    'connect': float(os.getenv('LLM_CONNECT_TIMEOUT', '5')),   # 占位值，按环境确认
    'read':    float(os.getenv('LLM_READ_TIMEOUT', '30')),
    'total':   float(os.getenv('LLM_TOTAL_TIMEOUT', '120')),
}
assert TIMEOUTS['connect'] < TIMEOUTS['read'] < TIMEOUTS['total']
print('timeouts in effect:', TIMEOUTS)   # 让日志能证明配置生效

验证是否真的生效，可以本地起一个逐块慢速返回的服务，人为把间隔拖到超过读超时：

# slow_server.py：验证客户端超时用，不要对外暴露
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        self.send_response(200)
        self.send_header('Content-Type', 'text/event-stream')
        self.send_header('Cache-Control', 'no-cache')
        self.end_headers()
        for i in range(5):
            self.wfile.write(f'data: chunk {i}\n\n'.encode())
            self.wfile.flush()
            time.sleep(2)   # 改成能跨过客户端读超时的值
        self.wfile.write(b'data: [DONE]\n\n')
        self.wfile.flush()

HTTPServer(('127.0.0.1', 8000), H).serve_forever()

先用 python slow_server.py 起服务，再把客户端读超时设得比 2 秒小，重跑第二节的脚本。预期看到读超时异常、已读字节数和持续时间；如果把读超时设大，则应完整打印 5 块并在块之间留下约 2 秒的间隔。触发超时时日志至少要包含：异常类型、已读块数与字节数、从发请求到报错的耗时、当前生效的超时配置。日志里没有这些字段，后面区分“超时触发”和“服务端断开”会很困难。

记录首字节耗时与总耗时

两个埋点位置就够：发起请求前后记一次，收到第一块数据时记一次，读完时再记一次。日志建议固定成可 grep 的键值格式，便于按接口和是否流式分组对比。

t_req = time.monotonic()
# ... 发起请求、进入读循环 ...
# 第一块到达时：
first_byte_ms = int((now - t_req) * 1000)
# 读完之后：
total_ms = int((time.monotonic() - t_req) * 1000)
print(f'stream=true first_byte_ms={first_byte_ms} total_ms={total_ms} '
      f'chunks={n_chunks} bytes={n_bytes} timeout_kind={timeout_kind} path=/v1/chat/completions')

两类耗时的差异对应不同的下一步：首字节耗时接近总耗时、块数很少，说明数据是在末尾一次性到达，重点查服务端是否真的流式、以及中间层缓冲；首字节正常但总耗时偏长、块之间间隔大，重点查生成速度和单块大小，必要时看服务端输出节奏；首字节就超时，说明请求还没进到生成阶段，重点查建连、鉴权与排队；总耗时超限而首字节正常，通常是输出太长，先缩短最大输出或放宽整体超时，不要动读超时。把这些数据按时间排一遍，哪一段变长就查哪一段，比反复改超时参数更省时间。