流式输出慢,先别急着把锅甩给远端模型。Claude Code 是一个命令行前端,你的终端、本地 CLI 进程、操作系统管道、网络代理和 API 服务端都可能让一个本来正常的流式响应变慢。建议把问题拆成“首包之前”和“首包之后”两个阶段,然后再对照原始 API 做一次实验。
先把首 Token 延迟和 Token 间延迟分开看
流式输出延迟要拆成首 Token 延迟和 Token 间延迟分开看。如果首 Token 明显慢,而后续 Token 正常,问题多半在网络请求建立或服务端推理排队;如果 Token 间间隔大,则是数据传输或客户端处理阶段。一个实用的判断方法是用 curl 直接请求底层 API 并观察原始流,再对比 Claude Code 的表现。若两者都慢,说明瓶颈在上游,若只有 Claude Code 慢,就要检查本地命令行的处理逻辑。注意不要只统计总耗时,要分段计时才能定位环节。
这里的限制是:curl 和 Claude Code 的请求参数、认证方式、路径都不完全一致,所以它只用来判断上游是否有明显放大效应。建议固定在同一网络环境,连续跑两三次取中间值,不要用单次结果下结论。如果 curl 的首字节时间明显短于 Claude Code,下一步就从本地 CLI 的日志、插件加载和缓存入手。
先排除终端渲染,再怀疑网络或服务端
优化时可以先把输出重定向到文件或空设备,排除终端渲染的影响。比如命令后加 > /dev/null,如果耗时明显下降,说明是终端高亮和滚动拖慢了速度。此时可以改用无样式输出或管道方式,让 stdout 直接通过,减少中间层消耗。此外,尽量避免在每次收到 chunk 时做同步日志写盘,可以把日志改成异步,或者只在结束时写汇总。这样能让流式数据不被 IO 操作堵住。
这个测试只适合非交互式调用,因为输出被丢弃后,Claude Code 的交互界面可能会收到 SIGPIPE 或直接退出。如果你在管道里使用,需要给命令补上 `2>&1` 或 `--output-format json` 这类参数,保证能通过文件观察结果。要注意的是,`> /dev/null` 只能排除终端绘制,不能排除终端驱动本身的影响;真正要排除 Pty 开销,可以用 `script -q /dev/null` 包裹一层。
在客户端逐个 chunk 打时间戳
想分清“首 Token 慢”和“后续 Token 慢”,最好在客户端记录每个 chunk 的到达时间,而不是只看总耗时。简单做法是在管道入口加一层时间戳,例如:
claude -p '...' | while IFS= read -r line; do printf '%s|%s\n' "$(date +%s.%N)" "$line"; done这个方式会额外 fork date 进程,所以它适合观察间隔规律,不适合当精确基准。如果发现间隔有规律地突然拉大,优先检查网络代理或服务端批处理;如果是随机抖动,重点看本地 CPU 占用、终端渲染或磁盘 IO。更细的抓包可以用 tcpdump -n -tt 看 TCP 段到达时间,但要注意 TCP 段和应用层 chunk 并不是一一对应,需要配合客户端日志交叉验证。
后端别攒响应,超时设置要留余量
流式输出时不要在后端把整个响应先攒起来再一次性返回,否则会丢失流式效果,还会显著增加内存占用。同时要注意超时设置:如果客户端读超时设得太短,正常生成的长时间思考可能被误判为无响应;设得太长又会让用户感觉卡死。合理的做法是设定一个比首 Token 预期时间更长的连接超时,而读超时则考虑允许较长时间无 Token 产出。另外,取消和中断操作要能及时关闭底层连接,避免服务端继续浪费资源。
如果你维护的是中间层网关或 SDK,这个原则尤其重要。检查点有两个:一是看响应体是否在内存里被收集后再统一写出,正确做法是每收到一个 chunk 就调用一次写方法并 flush;二是看超时参数是否区分了 connection timeout 和 read timeout。建议把 read timeout 设置得明显长于“预计最长的思考间隔”,并在超时后记录当时收到的字节数,方便判断是上游卡住还是链路断了。
缓冲和输出原语:容易漏掉的坑
如果上面的时间戳显示 raw stream 正常,只有 Claude Code 慢,那要回头检查工具链的缓冲行为。常见的是 curl 不带 `-N --no-buffer` 时数据会在终端前被缓冲;Node.js 的 `for await` 若没有处理背压,数据会在内存里堆积;还有直接用 `console.log` 打印 chunk,不仅会有额外格式化,还会在行尾加换行,实际上相当于每段输出都做了两次写操作。先把这些输出原语改成 `process.stdout.write` 或等价的非缓冲写法,再跑一遍时间戳测试,通常能排除掉大量“伪延迟”。
这里需要提醒:不要为了减少延迟而把 swap、临时缓存这类止血措施当成正式优化。缓存的命中率、内存占用都要重新观察。可以把优化分成两步:先消除明显缓冲和终端渲染,再回到首 Token 和 Token 间隔两个指标做对比。改完后至少看三个信号:首 Token 时间是否下降、Token 间间隔是否变均匀、内存/CPU 是否稳定。若其中一个指标恶化,说明改动方向反了,应当回滚。