🏠 总目录📚 本教程 05 · 流式输出 ← →

AI 全栈 / 05 · 从症状找缓冲位置

本地逐字正常,
为什么上线后
一次性出现?

应用产生事件,不代表中间链路已经把它交给客户端。

沿缓冲位置逐层核对,再处理流内错误与断连回收。

产生事件与客户端收到事件之间,可能在哪里攒住? 应用已经逐次产生事件。代理、压缩中间件、平台网关或CDN都可能缓冲;这些位置可以叠加,顺序依部署。客户端可能因此较晚才收到一批输出。 应用逐次产生事件写出事件 ≠ 客户端已经收到 可能缓冲的位置 · 可以叠加 反向代理:攒一批再转发 压缩中间件:等待压缩块 平台 / 网关 / CDN:整体缓冲 客户端较晚才看到一批输出
这是一张排查地图,三类位置可叠加、顺序依部署;不是抓包、测时或本次故障判定。事件与传输分帧的边界仍按正文区分。
📑 本页目录(点开跳转)

05 · 流式输出

⏱ 64 分钟 | ⭐ 只管后端到 HTTP 这一半 | ⚠️ 本章一半篇幅在讲「代码没错但流式还是坏了」


🎯 一句话

让字一个一个出来,难的不是「怎么吐」,而是「一路上有三个地方会悄悄把它攒起来」。 本章管后端 → HTTP 这一段:怎么吐、怎么在流里报错、怎么在用户关掉页面时停止烧钱。浏览器那一半在第 10 章。


🌊 一、为什么必须流式(一节就够)

一次长回答生成几十秒是常态。非流式下,页面等整段生成并返回后才能显示内容;流式下,第一段内容到了就能显示。首段仍要等排队、模型生成和链路转发,不能按一次网络往返来估算。流式改善的是等待中的反馈,整段生成耗时仍需单独测量。用户因长时间没反馈而重发时,还可能多触发一次生成。

⭐ 「为什么要流式」「护栏怎么和流式配合」在 智能体工程 16c 讲过,那边是产品视角。 这一章接着往下讲工程链路:报文怎么编、被谁吃掉了、错了怎么办、断了怎么办。


🔀 二、三种通道,为什么 LLM 场景通常选 SSE

通道 方向 代价 什么时候选它
⭐ SSE(text/event-stream) 服务器 → 客户端单向 沿用 HTTP 响应;仍需处理断连、缓冲和资源占用 默认选它。LLM 输出天然是单向的
WebSocket 双向 建立 WebSocket 会话;需处理心跳、重连、鉴权和代理兼容 真的需要边说边打断:语音、协同编辑、实时打断生成
自定义流式响应体 单向 ⚠️ 自行定义消息边界;HTTP/1.1 chunk 边界不能代替它 你确实只吐纯文本、且不打算加任何元信息时

⭐ SSE 规定的是 HTTP 响应体里的事件格式:媒体类型是 text/event-stream,用 UTF-8 文本和空行分隔事件。HTTP/1.1 的 chunked 是另一层的消息分帧;一个事件可以跨多个 chunk,一个 chunk 也可以装多个事件。换成 HTTP/2 后,内容由 DATA 帧承载,不能使用 Transfer-Encoding: chunked,SSE 事件格式仍可保留。

⚠️ WebSocket 提供双向消息通道,适合确实需要持续双向交换的场景。本章的生成请求用一次 POST 发起、后续主要接收输出,先用流式 HTTP 即可;是否换通道要看交互需求。

同样是 HTTP,承载与复用不同

可跳过:从HTTP/1.0到1.1,默认连接与消息长度改了什么?

连接:HTTP/1.0通常一次请求/响应后关闭连接;部分历史实现能显式协商Keep-Alive扩展,不能说1.0绝不支持长连接。HTTP/1.1默认允许持久连接,Connection: close可声明本次响应后不再复用;默认持久也不保证永不超时。

目标主机:HTTP/1.1每个请求必须带合法的Host字段,用于区分同一地址上的目标主机。1.0原规范没有这项强制要求,后来一些1.0客户端也实现了Host;历史支持与1.1的强制规则要分开。

响应长度:对含正文的普通1.0响应,可用Content-Length给出字节数,否则靠关闭连接定界。1.1可用Content-Length,未知长度的持续正文常用chunked,让接收方识别结束并保留连接;若仍靠关闭连接定界,该连接就不能继续复用。HEAD、204、304等无正文响应按各自语义处理。

Transfer-Encoding在1.1引入,不能把chunked响应发给仅表明1.0的请求;发送Transfer-Encoding时不能同时发送Content-Length。chunked分帧与SSE事件格式仍是两层。下面继续对照1.1/2/3的承载与复用。

依据:RFC1945 §7.2.2、RFC9112 §9.3 / C.2(含Host与Transfer-Encoding差异)、RFC9110 §7.2。

版本承载与响应体复用的边界
HTTP/1.1TCP;无预知长度的持续响应常用 chunked 编码默认允许持久连接复用多次请求;流水线的响应仍须按请求顺序返回,并发常靠多个连接
HTTP/2TCP;HEADERS / DATA 帧一条连接交错多个流;TCP 丢包仍可能阻塞其上的多个流,不等于消除所有队头阻塞
HTTP/3QUIC(基于 UDP);HTTP 帧映射到 QUIC 流由 QUIC 提供可靠流与复用,避免 TCP 的跨流队头阻塞;仍有拥塞、资源与应用依赖

HTTP 管方法、状态码和字段等请求/响应语义;HTTPS 为通信增加身份验证、机密性与完整性保护。常见 HTTP/1.1、HTTP/2 的 HTTPS 使用 TLS,HTTP/3 的 QUIC 集成 TLS 1.3。加密不替代应用鉴权,也不保证响应及时、不重试或不丢业务结果。证书与握手机制见 证书与 TLS 原节。

把响应、连接和心跳分别看

对象它解决什么不能由它推出什么
持续响应(SSE)同一次请求的响应体持续产生事件一次请求结束不必关闭承载连接;持续响应也要占用并发与内存资源
持久连接连接可供多次请求复用;HTTP/1.1 默认支持不自动推送事件,也不承诺永不超时
连接池客户端管理可复用连接及并发上限,减少反复建连不是持久化消息队列;流占用连接/流配额仍受客户端实现限制
应用心跳例如 SSE 注释 : ping\n\n,帮助应对空闲超时不是 TCP keepalive,也不证明某条业务消息已落库或已被用户消费

因此,关闭标签、取消请求、结束 HTTP 流、关闭底层连接是不同事件。HTTP/2 连接可能还承载其他流;后端应依赖框架的断连/取消通知并清理本次生成资源,不能根据「用户关页」推断某条 TCP 必然立刻关闭。第六节继续处理取消与上游收尾。

WebSocket:一段最小状态轨迹

下面的 Upgrade / 101 仅指 HTTP/1.1 握手:客户端发送带 Upgrade: websocket、Connection: Upgrade、Sec-WebSocket-Key 和版本字段的请求;服务端验证请求并返回 101 与正确的 Sec-WebSocket-Accept,客户端核验后进入 OPEN。HTTP/2 不使用这个 101 路径;双方协商支持 RFC 8441 时,可用扩展 CONNECT 在一个流内建立 WebSocket。

CONNECTING → 握手成功 → OPEN
OPEN ↔ 文本/二进制消息(一个消息可拆成多个帧)
OPEN → Ping → 对端 Pong(控制帧;不是业务确认)
OPEN → Close ↔ Close → CLOSED
异常断开 → CLOSED → 应用退避后重新握手 → 新会话

协议 Ping/Pong 由端点实现处理,浏览器 JavaScript 的 WebSocket API 不直接暴露这些控制帧;需要应用可见的探活时,可以另约定消息与超时。重连不会自动重放业务消息:例如客户端最后处理到序号 42,断开后重新建连时,43 是否已写入、是否需从 42 之后补拉,要由服务端保留记录与客户端游标/去重约定决定。这个轨迹只是协议与业务边界说明,未执行真实网络或规模压测;稳定业务标识的作用见 幂等原节。

可选:在线文档怎样合并编辑,而不只传送消息?

以服务端权威的纯文本为例:每次编辑带文档ID、基础版本和稳定操作ID;服务端核对当前编辑权限及接受条件,经所选OT类型转换后应用、提交新版本,再发应用确认并广播。WebSocket只负责双向消息,TCP ACK/Pong不代表编辑获准或冲突已合并;服务端排序和版本号本身也不会合并意图。实际转换应交给成熟且有文档的OT类型;ShareDB的OT类型边界与纯文本类型说明可帮助区分这些职责。

下面只手算ASCII、从0起算的不同位置插入:双方从版本7的ab出发,A插入X后本地为Xab、待确认A1;B插入Y后为abY、待确认B1。直接套旧坐标会出现两种结果;校正坐标后,本例两种顺序才得到同一文本,不能把“加1”当完整OT或一般收敛证明。

v7: "ab"; A1=ins(0,"X"), local="Xab"; B1=ins(2,"Y"), local="abY"
naive A1,B1: "XaYb"; naive B1,A1: "XabY"
A1 -> v8 "Xab"; transform B1: 2->3 -> v9 "XabY"
B1 -> v8 "abY"; transform A1: 0->0 -> v9 "XabY"

本地立即回显只是暂存编辑;远端更新也须经过OT处理,例如B保留待确认B1时将远端A1作用于abY,得到XabY。只有应用成功确认才推进本次编辑的服务端确认版本(见submitOp契约);确认丢失后以同一操作ID重试并去重,不能再应用一次。重连先补已确认历史,再由所选OT机制重定基准并重发待确认操作;历史有缺口时显式快照/重新同步,同时保留并处理待确认编辑,不能静默丢弃。If-Match/412只能发现整资源写入的旧版本,不能自动合并文本。相同位置插入、删除、富文本、撤销及真实同步延迟不在这个有限例子内。

依据:RFC 9112 §9.3、RFC 9113 §2/8.1、RFC 9114 §2、RFC 9110 §4.2.2、RFC 6455 §5/7、RFC 8441 §4、WebSockets 标准 §5。

本章流式主线可直接继续第三节。想定位“半条消息、连接没关或超时后结果未知”,再看 可跳过的传输深入。

可选深入:事件下面的字节流与连接状态

先问故障在哪一层:应用事件没结束、HTTP响应被缓冲、还是传输连接出了问题?以下序号、时刻与报文轨迹都是教学手算,不是抓包、真实内核测试或网络压测;先前的 HTTP/SSE/WebSocket 主线继续成立。

把教学分层用于定位,不当作严格实现图

本章观察对象TCP/IP模型OSI教学对应与边界
JSON/SSE事件;HTTP请求/响应;FTP文件传输命令应用层OSI应用层(7);表示(6)、会话(5)的序列化/会话职责常由库或应用承担,不必各有独立协议进程
TCP字节流、UDP数据报传输层主要对应传输层(4)。QUIC在UDP之上整合可靠流、加密与复用,不能强画成每层一个协议的一一映射
IP地址与跨网络转发网际层网络层(3);尽力交付,不保证顺序或到达
相邻节点间的以太网/Wi-Fi帧链路层数据链路层(2);逐跳帧不等于端到端应用事件
电/光/无线信号常合并进底层网络接入讨论物理层(1)。OSI七层与TCP/IP四层是不同教学划分

以HTTP over TCP为例:应用把事件编码成响应体→HTTP定义消息语义/边界→TCP把字节按序号分段传送→IP跨网络路由→每跳用本地链路承载;对端逐层接收并解析。TCP段、一次 recv 返回和一个SSE事件的边界可以完全不同。HTTP/3走QUIC/UDP路径,不是“下面也必有TCP”。

可选:这一跳的MAC,和ARP/RARP各解决什么?

普通以太网使用48位MAC作为本链路的接口地址;它不是远端IP、用户ID或已认证身份。地址有单播/组播及全局/本地管理等位语义,也可由本地管理,不能概括成每个MAC都永久不变、全球唯一。假设无NAT,A向另一子网B发送IP包:先选路由,首跳帧的目的MAC是网关;路由器在下一链路重新封装帧,IP源/目的仍是A/B。普通二层交换转发不意味着每过一台交换机都改写MAC。

机制方向与适用范围
ARP在IPv4以太网上,将已选下一跳的IPv4地址解析为链路地址;远端B不在本链路时解析网关。请求广播限于本链路相应广播域,不跨路由器寻找B的MAC。
RARP已知硬件地址,向维护映射的服务器查询协议地址;这是RFC903描述的历史引导机制,不是反向DNS,也不据此断言当前系统采用它。

IPv6邻居解析使用基于ICMPv6的邻居发现(ND),不沿用ARP/RARP。依据:RFC9542 §2.1、RFC826、RFC903、RFC4861 §3.1。

TCP可靠字节流与UDP数据报,分别承诺什么

TCP在连接内提供可靠、有序的字节流,不保留一次send的消息边界。应用仍需分隔符/长度等消息格式;连接失败时也可能无法知道对端处理到哪里。UDP保留数据报边界,但本身不保证到达、去重或顺序;丢失、乱序、重复均需按应用语义处理。UDP少一些协议机制不等于在所有负载下必定更快。

完整文件/文本请求通常希望按序得到全部字节;实时音视频可能更重截止时间、愿意丢掉过期数据,但也要做速率/拥塞控制。若在UDP上自建可靠交付,就要承担业务消息ID、确认、丢失检测/重传、排序去重、拥塞控制、缓冲与安全等职责;QUIC是已有的标准化可靠流方案之一。没有这些设计,不能因“加了ACK”便宣称等价TCP。

可跳过:用10个不同问题对照原生TCP与UDP

下列比较原生传输协议;UDP上的QUIC可另加可靠流、拥塞控制与加密,不能把它的能力算作UDP自带。

  1. 连接状态:TCP要建立并维护连接、按状态结束;UDP没有对应握手/关闭状态机,socket的connect不等于增加UDP握手。
  2. 应用消息边界:TCP是字节流,一次send不对应一次recv;UDP保留数据报边界,应用仍须处理接收缓冲不足等情况。
  3. 丢失与重复恢复:TCP用序号、确认和重传恢复丢失并识别重复;UDP本身不提供。TCP连接失败仍可能留下业务结果未知。
  4. 交付顺序:TCP按序交付,前方缺口可挡住后续字节;UDP不保证报文顺序,应用可选择直接处理、重排或丢弃过期报文。
  5. 接收流控:TCP通告rwnd约束发送;UDP没有原生接收窗口反馈,接收方变慢时要另做背压或丢弃策略。
  6. 网络拥塞:TCP发送受拥塞算法约束;UDP自身没有,使用UDP的应用/上层协议仍须控制拥塞,不能任意满速发送。
  7. 分发形态:TCP提供单播连接;UDP可用于单播、IP组播和IPv4广播,受网络支持与权限限制;IPv6没有广播。
  8. 基础首部:TCP最少20字节,普通UDP首部8字节;不计IP、TCP选项及上层协议开销,不能据此推出UDP必快。
  9. 发送分段责任:TCP按MSS/路径条件把字节流分段;UDP应用需选择合适报文大小,UDP不自动补出TCP式分段重组,勿依赖IP分片。
  10. 校验策略:TCP校验和必须使用;UDP在IPv4允许零值表示未启用,IPv6默认必须校验,特定隧道例外见下文。校验和都不等于认证或加密。

依据:RFC9293 §2.2/3、RFC768、RFC8085 §3/4。消息边界回答“怎样分消息”,分段回答“谁控制发送单元大小”;丢失恢复与按序交付也分别核对。

三次握手:先把双方序列空间对齐

# 常见一主动、一监听的无丢包路径;序号仅为手算
A CLOSED → SYN-SENT:     A → B  SYN     seq=100
B LISTEN → SYN-RECEIVED: B → A  SYN,ACK seq=700 ack=101
A收到后 → ESTABLISHED:   A → B  ACK     seq=101 ack=701
B收到最后ACK → ESTABLISHED

SYN占用一个序号,所以确认100的SYN用101;另一方向也独立确认。序号主要计字节,不是“第几个包”;纯ACK不消耗序列空间,FIN也消耗一个序号。最后一次确认让B知道自己的初始序号已被A收到,并配合初始序号选择等规则降低旧重复报文的歧义。握手不是服务业务请求已经完成的证据。

SYN/SYN-ACK丢失会触发相应重传/超时;最后ACK丢失时,B可重发SYN-ACK,A再确认,不必把纯ACK想成有独立重传计时器的业务消息。实际包数可能因重传、同时打开或数据携带而不同,不能把“三次”当任意抓包都只有三包的断言。

可选:socket调用、握手和等待accept的队列怎样对齐?
普通TCP路径此时由谁推进
服务端 socket → bind → listen建立监听fd;收到SYN后可有未完成握手的请求状态,俗称“半连接队列”。这是Linux实现教学,不是TCP规范固定的队列结构。
客户端 socket → connect;内核推进握手握手完成后,服务端连接等待accept,俗称“全连接队列”;应用尚未accept不等于握手未完成。非阻塞connect可能返回EINPROGRESS,须等就绪并核验SO_ERROR等实际完成结果。
服务端 accept → 新连接fd取出一个已完成连接;监听fd继续监听,accept不是第三次握手。双方在连接fd上循环send/recv,按应用格式组帧,处理短读/短写、EOF和错误,最后close。

按Linux man-pages 6.19的listen说明,自Linux2.2起,TCP的backlog指已完成、等待accept的队列长度,传入值受somaxconn上限约束;已accept的活动连接不占这个等待队列,backlog不是总活动连接数或每端口容量。未完成请求的tcp_max_syn_backlog限制另看;SYN cookies可减少提前分配,此时不能机械套用同一队列图或把两个限制相加。队列满时的行为受内核版本、策略与状态影响,不能断言必然RST或固定丢弃;cookies也不使资源无限。

普通被动打开需要有效监听端点(也可能继承已有监听fd),单有bind不等于在监听;本进程暂不调用accept时,只要队列等条件允许,内核仍可完成握手。主动客户端不需要listen/accept;RFC9293的同时主动打开是另一条状态路径,仍有端点/网络条件,不能据此保证NAT打洞。API边界见accept、connect及tcp;本页没有运行内核队列或吞吐测试。

可选读字段:把首部和上面的轨迹对起来

可选:IP版本、首部字段与1500字节预算一起读

只问“IP首部”而未给版本时,应分别说明IPv4和IPv6;下面按用途归组,不用TCP字段替代IP字段。

用途IPv4IPv6基本首部
版本、首部长短与流量标记Version、IHL;最少20字节,选项/填充使其可变。历史ToS字节如今按DSCP/ECN解释。Version、Traffic Class、Flow Label;基本首部固定40字节,扩展首部另计。
长度、分片与下一协议Total Length含IP首部和数据;Identification、Flags、Fragment Offset关联分片;TTL限制存活,Protocol指示上层协议。Payload Length不含40字节基本首部,但包含扩展首部;Next Header指出紧随的首部,Hop Limit限制转发跳数。分片由发送端使用Fragment扩展首部,路由器不沿途分片。
地址与校验源/目的地址各32位;Header Checksum只校验IPv4首部,不是整包数据校验。源/目的地址各128位;没有基本首部校验和,不代表没有TCP/UDP等上层校验。

沿用路径MTU=1500、TCP首部20字节,且两者均无选项、IPv6无扩展首部、无隧道或其他封装的前提,IPv4数据预算仍是1500−20−20=1460,IPv6则为1500−40−20=1440字节;这不是任意实际路径的MSS保证。共存时还要核对DNS的A/AAAA、监听地址、路由与防火墙,见现有部署网络链路,不能仅由版本推断更快或更安全。依据:RFC791 §3.1、RFC2474 §3、RFC3168 §5、RFC8200 §3/4.5。

普通UDP首部固定8字节:源端口16位|目的端口16位;长度16位|校验和16位。长度包含首部和数据。校验和也关联IP伪首部中的地址/协议/长度,检查误码与误投递,不是加密或身份认证。IPv4可用零表示未启用UDP校验;IPv6默认必须校验,计算结果为零时按规范编码为FFFF,零校验仅有满足额外要求的特定隧道例外,不能直接沿用IPv4规则。IPv6巨型报文等扩展另有长度规则,不由这张普通首部示意覆盖。

TCP基础首部最少20字节:端口各16位;序号/确认号各32位,对应前面按字节推进的两条序列空间;Data Offset是首部长度的32位字数,值5对应20字节。控制位SYN/FIN/RST/ACK分别用于同步、结束方向、复位与确认号有效性;PSH不把字节流变成消息协议,URG/紧急指针也不是另建一条业务通道。通告窗口参与接收流控;校验和覆盖首部/数据并结合IP伪首部。选项可承载MSS、窗口扩大、SACK许可/块、时间戳等,不是每个包都带全部选项。CWR/ECE与拥塞通知有关,不替代应用状态码。

MSS、MTU与分片分别看:MSS是TCP数据段大小的限制,MTU约束链路可承载的IP包大小,TCP分段与IP分片不是同一层。假设路径MTU=1500字节、IPv4/TCP都没有选项或封装,1500−20−20=1460字节是一个数据预算示例;加选项、换IP版本或隧道都要重算,还要服从对端MSS及路径限制。IPv4在条件允许时可分片;IPv6路由器不沿途分片,发送端应按路径条件处理,不能靠“设置MSS”就宣称所有IP分片已消失。

必要分片只要仍有缺失,就不能完整重组原IP包,路径设备也可能直接丢弃分片;TCP按MSS与路径预算分段可减少这类风险。IP本身不负责可靠重传,MSS也不等于路径MTU探测,更不保证绝无分片。

前面100/700是教学ISN,不是生产生成法。RFC9293描述时钟项M加上连接四元组与秘密键的不可外推伪随机函数F,兼顾序列空间推进、旧报文隔离和盲猜注入风险;不能给所有连接固定从0开始,也不能只以“有一个随机数”代替协议条件。ISN不可预测不等于TLS加密,旁路防猜不保护已被观察的应用明文。

SYN洪泛针对未完成握手的状态资源。SYN cookies将部分状态编码到SYN-ACK序号,待最终ACK核验后再重建,减少提前分配;它有选项协商/实现与算力代价,也不是身份验证或无限抗压保证。还应结合入口过滤、网络边界防护及队列/资源监测。RFC4987是2007年的机制讨论,不能照搬其中旧内核默认值;实际部署配置和效果须针对当前系统核验,本页没有执行攻击或防护测试。

依据:RFC9293 §3.1/3.4.1/3.7.1、RFC768、RFC8200 §4.5/8.1/8.3、RFC4987。

一个缺口如何触发ACK、SACK与重传

假设接收方正等待字节1000,发送方依次发四段,每段100字节;接收方有足够缓冲并保留乱序段,半开区间右端不包含:

[1000,1100) 丢失
[1100,1200) 到达 → 累计ACK=1000,若启用SACK则报告[1100,1200)
[1200,1300) 到达 → 累计ACK=1000,SACK可合并为[1100,1300)
[1300,1400) 到达 → 累计ACK=1000,SACK可合并为[1100,1400)
重传[1000,1100)补齐 → 累计ACK=1400,连续字节可交给应用

累计ACK是“下一个期望字节”,不能因收到后面一段就越过缺口。SACK需协商支持,额外报告已收到的块以减少盲目重传,不替代累计ACK。重复段由序号识别,不应作为新字节再交付;但应用重新发一次完整业务请求仍是另一回事,必须另做幂等。

RFC5681的经典快速重传用三个符合条件的重复ACK推断缺口,未等RTO便重传;不是所有现代实现都只有这一种丢失检测规则,少量数据或ACK丢失时也不一定凑够三个重复ACK。超时重传则依赖RTO:RFC6298按RTT及其变动估计,超时后退避,重传报文的RTT采样还存在歧义。RTO不是调用层的connect/read超时,更不是任何系统固定几秒;内核版本、算法及配置会影响实际行为。

滑动窗口:接收能力与网络容量分开

接收方通告的 rwnd 限制未被应用及时取走的数据量,避免撑爆接收缓冲;累计ACK和通告窗口变化,让可发送区间向前滑动。发送方的 cwnd 根据网络拥塞反馈控制在途量,保护网络路径。它们分别是流量控制和拥塞控制;经典慢启动/拥塞避免调的是cwnd,不是接收端把rwnd“调快”。

忽略恢复期等细节,若rwnd=1200字节、cwnd=800字节,已有500字节未确认,则剩余可新增约 min(1200,800)-500=300 字节,不是再发800。实际拥塞算法可以不同,窗口上限也不能换算成固定业务QPS;接收方或应用变慢还要配合本章后续的有界缓冲与取消策略。

可跳过:rwnd怎样更新,经典Reno怎样换阶段?

接收流控的四步:①接收缓存有多少可接收空间,形成通告rwnd;②随ACK把下一期望字节与窗口告诉发送方;③发送方结合cwnd和未确认量限制新增发送;④应用取走缓存后,接收方通告更新的窗口,允许发送继续推进。TCP确认收到不等于应用已经取走。

小窗口轨迹:假设接收缓存4000字节、起初为空且下一期望序号1000,通告rwnd=4000;收到连续2000字节而应用未读,ACK=3000、rwnd=2000。应用再读走1000字节,可通告ACK=3000、rwnd=3000,右边界由5000前移到6000。这里只忽略窗口扩大等实现细节。

零窗口另看:rwnd=0时暂停普通新数据发送,TCP仍支持零窗探测,避免窗口重开通知丢失后双方永远等待。它不是应用心跳,也不因零窗就把cwnd按拥塞丢包规则重置;连接资源与超时仍有实现边界。

下面只走RFC5681的经典Reno教学路径。SMSS是发送端最大段数据字节数;cwnd、ssthresh与FlightSize都按字节计,FlightSize是已发未确认量。假设rwnd足够、一直有数据、每整段新数据都获ACK,初始cwnd=2×SMSS、ssthresh=8×SMSS仅为算例,不是当前系统默认值。

  1. 慢启动→拥塞避免:cwnd低于ssthresh时,对确认新数据的ACK按确认字节数增长,每个ACK最多增1×SMSS;上述理想假设下可按RTT看2→4→8段。阈值相等时本例选拥塞避免(规范允许两者);之后按约每RTT增1段而非继续倍增,ACK节奏和应用供给会改变实际轨迹。
  2. 3个符合条件的重复ACK→快速恢复:推断缺口后快速重传,不等RTO;本例把ssthresh取为max(FlightSize/2,2×SMSS),规范要求不超过该上界,并排除limited-transmit额外发送量。cwnd暂设ssthresh+3×SMSS,后续每个重复ACK再增1×SMSS;有新数据且窗口允许才发送。
  3. 新ACK→退出恢复:在本例单处丢失被修复、ACK确认此前未确认数据时,cwnd收回到ssthresh,进入拥塞避免。例如FlightSize=10段,阈值取5段,快速恢复暂为8段,再收回5段;这不代表任何ACK都增加窗口。
  4. RTO超时→回慢启动:对尚未因计时器重传过的该段,按同一FlightSize规则降低阈值,cwnd降到至多1×SMSS,重传后慢启动;再次超时重传同段时阈值保持,计时器退避另依RTO规则。不能把这条路径简写成“任何丢包都减半继续线性增长”。

多处丢失、SACK/现代恢复、延迟ACK与初始窗口版本会改变细节;CUBIC、BBR不是这条Reno增长轨迹。任何阶段仍受前文min(rwnd,cwnd)与在途量约束,不能由窗口数字保证吞吐。

依据:RFC9293 §3.8.6、RFC5681 §2/3.1/3.2。以上为教学状态/算术,没有执行真实连接或压测。

两个方向分别关闭,为什么不总是四包

# 接握手、无数据的教学序号;A先关闭发送方向
A → B FIN,ACK seq=101 ack=701   A:FIN-WAIT-1;B收到后:CLOSE-WAIT
B → A ACK     seq=701 ack=102   A收到后:FIN-WAIT-2
B本地应用也关闭 → A FIN,ACK seq=701 ack=102   B:LAST-ACK
A → B ACK     seq=102 ack=702   A:TIME-WAIT;B收到后:CLOSED
A等待后:CLOSED

FIN表示本端不再发送新字节,不代表另一方向也停止发送;B可能先确认A的FIN,继续把剩余数据发完再FIN。若B立即关闭,第二、三行的ACK/FIN可以合并;同时关闭时又有CLOSING等路径。TCP区分正常FIN关闭与经校验接受的RST复位,“四次挥手”不是所有连接固定四个网络包。

状态/现象含义及排查线索不能直接得出的结论
TIME_WAIT保留终止相关状态,使对方重发FIN时还能再ACK,并隔离旧连接延迟报文;常见由最后确认FIN的一端进入,双方同时关闭时也可能都有规范路径用2×MSL描述,不能把某操作系统秒数当跨平台常量;不等于应用文件描述符仍一直打开
CLOSE_WAIT已收到对端FIN,等待本地应用关闭发送方向。持续积累时检查本地资源收尾不是和TIME_WAIT同一种“等网络冷却”,也不能仅据状态断定远端有bug
RST可能来自不存在的连接/监听端口、状态失配或主动中止等情形;接收方还要做序号/状态校验不是任意一个RST必定终止连接,也不是对端断电必然会发RST

若上例最后ACK丢了,B会重传未确认的FIN,TIME_WAIT中的A能再ACK并按规范处理计时;FIN丢失也需重传,达到失败策略可能结束连接,不能承诺网络最终一定恢复。客户端突然断电通常来不及通知;进程崩溃后内核可能关闭或复位socket,但具体结果仍取决于状态/缓冲/选项,不能写成“服务端立即知道”。

TIME_WAIT重开与已建立连接收到SYN,要分别判断。RFC9293 §3.6.1允许(MAY)从TIME_WAIT接受新化身,条件包括:本端为新连接分配的本端ISS高于本端旧化身用过的最大序号,并在识别为旧重复SYN时返回TIME_WAIT;这不是要求收到的对端SYN.SEQ超过这个门槛。时间戳优化路径另有条件,不能据此推断某Linux配置或实际默认行为。

对已建立连接的SYN,若采用RFC5961 §4.2缓解,无论SYN序号在窗口内外,都发送challenge ACK,然后丢弃该段并停止处理,不能解释为开启新握手。RFC9293 §3.10.7.4另列未采用该缓解的历史路径:窗口内SYN触发复位,窗口外在先前序号检查处回复ACK。两条处理分支不能拼成唯一固定流水线,也不能与TIME_WAIT重开混为一谈;实际内核实现及ACK节流仍需另核。

例如监听本地192.0.2.10:443,连接四元组可分别为(192.0.2.10,443,198.51.100.20,51000)与(192.0.2.10,443,203.0.113.30,51000)(依次为本地IP/端口、远端IP/端口):它们共用本地端口,仍是不同连接。四元组候选空间不是实际容量;还要预算文件描述符、内存、NAT、地址分布和负载,不能用IPv4地址数乘端口数得出生产容量,也不要混入监听backlog。

大量短连接会消耗内核状态、内存和可用连接元组等资源;先看是否能复用连接、是否有本地未关闭资源、瓶颈究竟在句柄/端口/内存/NAT哪一层。不要无条件缩短等待或开启TIME_WAIT重用。收到新SYN怎样处理、何时可安全重用、最大连接数是多少,必须给出系统/内核/地址与端口范围/远端分布/配置;缺这些条件的来源题仍保留需澄清,不能用一个“65535”代替所有连接容量。

send成功、TCP确认、业务提交是三种证据

你看到了什么支持什么结论还没证明什么
Linux send返回n>0本次有n字节被本地发送路径接受;可能少于请求长度没有证明所有字节已到对端、应用已读或已处理
TCP ACK推进对端TCP确认收到相应连续字节没有证明对端应用已消费、校验或提交事务
应用成功响应/持久结果记录按该接口契约解释处理结果响应丢失时,本地超时仍不能推出“对端没提交”

连接fd的来源与循环读写见上面的socket/队列轨迹;服务端提速先测accept积压、CPU、下游I/O及慢客户端背压,再结合I/O就绪与GIL边界判断,不能用加线程或加backlog保证更快。

TCP keepalive 是可选的传输探活;应用心跳可检查应用约定的存活点;业务deadline决定等多久并如何取消。三者互不替代,HTTP持久连接只是复用能力。Fetch取消可能只终止本次HTTP/2流(RST_STREAM),不必关闭承载其他流的TCP;与HTTP/1.x连接复用/关闭也有不同处理。取消后还要按第六节回收本次上游资源,不能从浏览器关页推导供应商已经停止计费。未知业务结果仍按 稳定业务ID与重放契约 查询/重试。

依据:RFC9293 TCP基本规范、RFC6298 RTO、RFC5681拥塞/经典快速重传、RFC2018 SACK、RFC768 UDP、RFC1122分层与保活、Linux send / tcp选项、Fetch规范与HTTP/2 RST_STREAM。

可跳过的应用轨迹:万人在线、每秒十万条弹幕意味着什么?
直播中的角色协议例子与边界
编码器 → 接入服务按具体服务选择RTMP/RTMPS等;例如Amazon IVS低延迟接入文档说明支持RTMPS等接入(具体支持与安全配置按服务文档),不能外推所有直播服务。
向观众分发媒体HLS以播放列表描述媒体分段;这里只用RFC8216所述version7作基础例,不推断其他版本或低延迟扩展。
实时双向音视频WebRTC是一组协作协议,不是只选TCP或UDP就能替代的单一协议。

这些角色可以共存,并非互斥或穷尽的协议分类;按终端、交互方向、可容忍延迟与CDN/规模条件选择,弹幕和控制消息再按本章WebSocket/SSE边界选择,媒体协议本身不证明下述扇出能力。

这是已观察题干条件的有限设计推演,不搭直播平台。输入吞吐与扇出必须分开:若教学假设每条负载100字节,10万条/秒约10MB/秒输入;若全部通过过滤、同一房间且1万人每人都收到每条,则是每秒10亿次消息投递、约100GB/秒负载输出,尚未计协议/复制开销。不能把10MB/秒当全部网络预算,也不能假设每个客户端能展示这么多条。

入口先鉴权、限制请求量并核对房间;实时敏感词规则应有版本,规则匹配/规范化失败怎样拒绝或暂缓要明示。通过过滤后分配稳定消息ID、房间序号并持久记录,再给出“已接受”语义。按房间分区保持该房间顺序,不承诺跨房间全局时序;客户端本地钟不应成为可信排序依据。规则变更后的历史内容要定义重新审核/撤回策略,不能因缓存旧过滤结果就永远放行。

广播队列与每客户端缓冲有界;慢客户端可按明确策略采样/降级、断开后带游标补拉,并给出丢弃/缺口提示。若业务要求每条可靠接收,就必须为补传、保留和确认预算资源,不能静默丢弃后仍宣称不丢。重连的重复消息按ID去重,服务端接受、设备收到、画面显示是不同证据。

离线弹幕要保存在连接之外:记录视频/片段ID、经定义和校验的媒体时间偏移、房间序号及审核版本;回放按媒体时间范围分批加载,同一偏移的并列按序号处理。重试/补拉不能重复显示,缺失/已撤回要有策略;不能拿“当前WebSocket内存列表”当历史库。可靠投递与恢复基础见 队列确认轨迹。本例没有真实过滤延迟、万人网络或十万条/秒压测证据,不自动闭合全题。


📦 三、SSE 报文长什么样

服务端发送事件(Server-Sent Events,SSE)为持续到来的响应体规定了事件边界。先记住本章用到的三点:data: 是内容、空行结束一帧、冒号开头的行是注释(前端会忽略,正好拿来做心跳)。

⭐ 本板块的统一帧格式:每帧一行 data: {JSON},帧间空一行,帧的类型放在 JSON 负载的 type 字段里。

要点

data: {"type":"delta","text":"你"}

data: {"type":"delta","text":"好"}

data: {"type":"usage","in":120,"out":8}

失败分支用 error 报错,仍可用 done 结束发送,完整轨迹见第五节。

data: {"type":"done"}

⚠️ SSE 协议本身还有一个 event: 行可以给帧起名字,但本板块不用它 —— 这是「跟着消费方走」的选择。第 10 章会讲:浏览器原生的 EventSource 带不了 Authorization header,所以前端一律用 fetch + ReadableStream 手动解析。手动解析器也可以支持 event:、多行 data:、id: 和 retry:,只是本板块选择单行 JSON 的子集,不能把它称为完整 SSE 解析器。原生 EventSource 按规范自动重连,并可携带 Last-Event-ID;fetch 手动消费不会自动获得这些行为,补发还要求服务端保留事件。详见 HTML 标准 §9.2 与 第 10 章的消费约定。

⭐ 把类型放进 JSON 负载,换来的是「一行 JSON.parse 拿到全部信息」:解析路径只有一条。

同理结束帧写 {"type":"done"} 而不是 [DONE] —— ⚠️ [DONE] 不是合法 JSON,会让统一的 JSON.parse 当场抛 SyntaxError,逼前端在解析前先加一次特判。

⚠️ 错误帧的字段名统一用 message(不是 code):前端拿它是要显示给人看的,需要一句话,不是一个枚举值。

⭐ 但错误帧必须多带一个 trace_id —— 第 3 章立的原则是「每个错误带 trace_id 并同时写进日志」,⚠️ 流式这条路上最容易把它漏掉:非流式出错时 trace_id 在那个 500 的 JSON 里,而流式的状态码早已是 200、那个 JSON 根本不会发出来。漏了的后果很具体:用户说「刚才回答到一半崩了」,你手上什么都没有 —— 而这恰恰是本板块最常见的一种失败。

done 是应用约定的结束标记。客户端要结合此前的事件判断结果,有 error 的回复仍然失败。注释心跳、用量事件和 HTTP 响应体结束都不能代替这项判断。

⚠️ 注意 message 和 trace_id 的分工,两者缺一不可:message 是给人看的一句人话(⚠️ 别塞异常原文,上游报错常带着密钥前缀、内网 IP、SQL 片段);trace_id 是给你查的,它在日志里对应着完整细节。一句人话 + 一个能报的号,就是这一对的全部用意。

# sse.py —— SSE 报文自己编一遍。看清楚字节长什么样,坑就少一半
import json


def sse(payload):
    """把一帧编成 SSE 文本。⭐ 硬规则只有一条:一帧以【空行】结束。
    ⭐ 本板块约定:payload 永远是 dict,帧类型放在它的 "type" 字段里。"""
    body = json.dumps(payload, ensure_ascii=False)          # ⭐ 永远 JSON 包一层
    lines = ["data: %s" % ln for ln in body.split("\n")]    # 兜底:万一真有换行就拆成多行
    return "\n".join(lines) + "\n\n"         # ⭐ 两个 \n:一个收本行,一个收本帧


def comment(text=""):
    return ": %s\n\n" % text                 # ⭐ 冒号开头 = 注释帧,用来做心跳


if __name__ == "__main__":
    wire = "".join([sse({"type": "delta", "text": "退"}),
                    comment("ping"),
                    sse({"type": "delta", "text": "第一行\n第二行"}),   # ⭐ 内容里带换行
                    sse({"type": "usage", "in": 120, "out": 340}),
                    sse({"type": "done"})])
    print(wire.replace("\n", "\\n\n"))       # 把换行显示出来才看得清帧边界
    # ⭐ 看第三帧:换行已被 json.dumps 转义成 \n 两个字符,所以它仍然只占【一帧】

⚠️ 两个换行问题要分开。① 模型正文里的原始换行会破坏单行 JSON 约定,用 json.dumps 把它转义成 \n 两个字符。② SSE 的两个真实换行用来结束数据行和事件。少了最后的空行,客户端会继续等,甚至在读到响应末尾时丢掉这个未完成事件。

跟一遍请求:从「我要退货」到完整回复

用第 04 章讲过的请求与响应,来跟一遍退货对话。用户点发送后,如果第一段单独到达,页面可以先显示「请」,稍后补成「请提供订单号。」。两段也可能在同一次读取里到达。如果把整段攒在一个 JSON 里,客户端得等生成完才有完整的 JSON 可读。现在把同一条回答分成多次可独立解析的增量事件(delta),每段到达就能更新这条回答。

这条回复经过哪几站

  1. 浏览器 → 应用后端。用 POST 发送消息列表,并声明想接收事件流。
  2. 应用后端 ↔ 上游模型。校验请求,通过后启动上游生成。后端把上游的文本片段包装成本章的事件。
  3. 应用后端 → 浏览器。客户端从同一个 HTTP 响应体持续读字节,按事件顺序追加文本,最后根据结束和错误标记决定界面状态。

下面展示这个接口在应用层看到的方法、头和正文,凭证是占位值。Host、长度和传输分帧由 HTTP 实现处理。输入为一条用户消息,输出和用量数字都为演示设定。

POST /api/chat
Authorization: Bearer DEMO_TOKEN
Content-Type: application/json
Accept: text/event-stream

{"messages":[{"role":"user","content":"我要退货"}]}

请求头的 Content-Type 描述送去的 JSON,Accept 描述希望收到的格式。下面是校验通过后的响应。usage 的 in 和 out 分别是输入、输出 token 数,单独记账。页面只把两条 delta.text 接成「请提供订单号。」。

200 OK
Content-Type: text/event-stream
Cache-Control: no-cache

data: {"type":"delta","text":"请"}

data: {"type":"delta","text":"提供订单号。"}

data: {"type":"usage","in":120,"out":8}

data: {"type":"done"}

浏览器读到半个字、半个事件怎么办?

HTTP/1.1 的 chunk 和 HTTP/2 的 DATA 帧由 HTTP 实现拆装。浏览器的 reader.read() 拿到响应体的一段字节,每次读到的范围可以跨过这些传输边界。之后还有两层边界需要处理。

读到的内容解码后怎样处理界面文本
第 1 次:直到「请」的前两个字节 E8 AFUTF-8 用 E8 AF B7 编码「请」。解码器先留住未凑齐的两个字节。空
第 2 次:补到 B7,再读到 "}\n解出「请」。文本缓冲已有完整数据行,但还缺结束事件的空行。空
第 3 次:一个 \n,紧接完整的第二个 delta补齐第一条的空行。循环取出两条完整事件,各解析一次 JSON。请提供订单号。
第 4 次:完整的 usage 和 done记用量,收到结束标记。此前没有错误,可以标记完成。请提供订单号。

这里 \n 代表一个 LF 换行。每次读到字节,用同一个 TextDecoder 以 {stream: true} 解码,结果拼进文本缓冲,再按 \n\n 取出所有完整事件。读完时结束解码,未遇到空行的最后一条事件仍不能交给应用。这个切法限于本章的 LF、单行 data: JSON 子协议。完整 SSE 另支持其他换行形式和多行 data:。

对照 HTTP/1.1 分块编码、UTF-8 流式解码、SSE 事件边界。浏览器代码见 第 10 章。


⚠️⚠️ 四、一路上吃掉流式的三个地方

本章最贵的一节。 症状永远是同一句话:本地逐字正常,一上线就变成「憋很久,然后一次性全出现」——而你的代码一个字都没错。

凶手 它的默认行为 怎么修
⭐ 反向代理 Nginx 那类默认 proxy_buffering on:攒够一批再转给客户端 那一段配 proxy_buffering off;,或让后端回 X-Accel-Buffering: no 响应头
⭐ 压缩中间件 GZip/Brotli 要攒够一个压缩块才有输出 对 text/event-stream 关掉压缩(多数中间件支持按 MIME 类型排除)
⭐ 云平台 / 网关 / CDN 有的会整体缓冲响应体再返回,Serverless 形态尤其常见 换成 01 章第六节那五条判据的部署形态;CDN 上给这个路径关缓冲

⚠️ 三个凶手的共同点,才是它们难查的原因:① 不报错——没有任何日志说「我缓冲了」;② 本地永远复现不了——本地没有代理、没有 CDN;③ 症状完全一样——三个凶手长得一模一样,光看症状分不出是谁。

🔍 怎么定位:一个探针 + 从里往外逐层测

⭐ 别去读代码找 bug,代码没 bug。 做法:部署一个每秒吐一帧的探针端点,从最里面往外一层层测——直连应用进程 → 容器端口 → 反向代理 → 公网域名,对照同一探针的到达间隔,优先检查最先开始成批交付的那一段。比如应用每秒产生一帧,5 帧却在第 5 秒一起到,即使总时长与直连相近,流式体验也已经变了。实际缓冲也可能拉长总时长。

# probe.py —— 流式探针:每秒吐一帧,再自己量【帧间隔】。只用标准库,可直接跑
import http.server, socketserver, threading, time, urllib.request

N, GAP = 5, 1.0            # 吐 5 帧,每帧间隔 1 秒


class Handler(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-Type", "text/event-stream")
        self.send_header("X-Accel-Buffering", "no")   # ⭐ 请 Nginx 那一层别缓冲
        self.end_headers()
        for i in range(N):
            self.wfile.write(("data: %d\n\n" % i).encode())
            self.wfile.flush()                        # ⭐ 少了这句,本机这层就先憋住了
            time.sleep(GAP)

    def log_message(self, *a):
        pass                                          # 别把访问日志混进输出


def gaps(url):
    t0, marks = time.perf_counter(), []
    with urllib.request.urlopen(url) as r:
        for line in r:                                # 逐行读,不等整体读完
            if line.strip():
                marks.append(time.perf_counter() - t0)
    return [b - a for a, b in zip(marks, marks[1:])]


if __name__ == "__main__":
    socketserver.TCPServer.allow_reuse_address = True
    srv = socketserver.TCPServer(("127.0.0.1", 8123), Handler)
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    g = gaps("http://127.0.0.1:8123/")
    print("帧间隔:", ["%.2f" % x for x in g])
    # ⭐ 间隔接近 GAP = 真流式;全接近 0 而总时长仍是 N*GAP = 中间有人在缓冲
    print("判定:", "流式正常" if g and max(g) > GAP / 2 else "有人在缓冲")
    srv.shutdown()

🔨 手上没有探针端点时的替身:curl -N <地址>(-N = 关掉 curl 自己的输出缓冲)。字一点一点出来就是通的,憋着不动就是被谁攒了。⚠️ 别用浏览器的开发者工具判断——它自己也会做缓冲和分帧展示,看到的时序不一定是真的。

💓 一个近亲问题:空闲连接被掐。 模型"想"得久一点(长上下文、工具调用中)时,连接上可能几十秒没有任何字节,而 ⚠️ 很多中间设备对空闲连接有超时(🗓️ 具体值看你那层的配置),到点直接掐断,前端只看到「流莫名其妙断了」。解法就是上面那个 comment("ping"):空闲时每隔十几秒发一个注释帧——不是数据、前端会忽略,但连接上有字节在流动。


🚨 五、流式下的错误处理:头已经发出去了

第三节的「我要退货」如果只吐出「请」就卡住,页面仍可能已经收到 200 OK。一旦最终响应头发出,状态码就已确定,即使正文还没开始。先查响应头,再看流里最后真正收到的事件。

观察到什么怎么显示与处理
401 + 普通 JSON 错误鉴权在开流前失败。按 HTTP 错误处理,不进 SSE 解析。
200 → 两条 delta → usage → done拼成完整文本,独立记用量,标为完成。
200 → delta「请」 → error → done保留「请」并标记回答失败、内容未完成。done 结束接收状态,先前的错误仍有效。
200 → delta「请」 → 读到末尾或读取失败,未收到 done保留「请」并标为中断。只凭 EOF(响应体读完)或读取异常,无法断定是上游、网络还是代理导致。
收到「请」后,用户点「停止生成」浏览器用 AbortController.abort() 中止本次请求并标为已停止。后端收到断连或取消通知后,按第六节清理上游。

第三行的失败分支仍用同一个 200 和 Content-Type。它的完整事件序列如下,假设链路还允许发出错误与结束事件。

data: {"type":"delta","text":"请"}

data: {"type":"error","message":"生成超时,请重试","trace_id":"a1b2c3d4e5f6"}

data: {"type":"done"}

把可以预先检查的事放在提交响应头前,例如鉴权、读取历史、检索和输入校验。开流后仍可能遇到上游超时,链路还可写时用 try/except 转成流内错误。已有内容到达用户后,不在同一回答里静默重试。即使服务端尝试发送了结束事件,客户端也要以实际收到的事件判断结果。

下面的接入片段沿用第三节的 sse()。真实调用层需把供应商的正常结束和异常中断区分开。示例突出预检、转译和取消,省略用量事件。第六节再用可运行的模拟检查上游收尾。

# FastAPI 接入示意,需自行提供 validate_and_prepare 和 open_model_stream。
# 使用第三节的 sse.py 编码事件。此片段不会直接连接供应商。
import asyncio
import logging
import uuid

from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from sse import sse

log, app = logging.getLogger("api"), FastAPI()


@app.post("/api/chat")
async def chat(req: Request):
    tid = uuid.uuid4().hex[:12]
    # 在提交响应头前鉴权、读 JSON、校验 messages 并准备上下文。
    messages = await validate_and_prepare(req, trace_id=tid)

    async def gen():
        try:
            # 该上下文管理器负责退出时关闭本次上游流。
            # 上游异常结束应抛错,不能当作正常遍历完成。
            async with open_model_stream(messages) as upstream:
                async for piece in upstream:
                    yield sse({"type": "delta", "text": piece})
        except asyncio.CancelledError:
            raise  # 保留取消信号,不伪装成模型报错
        except Exception:
            log.exception("stream failed trace=%s", tid)
            yield sse({"type": "error", "message": "生成失败,请重试",
                       "trace_id": tid})
        # 能发到这里时,done 只表示应用结束发送。
        yield sse({"type": "done"})

    return StreamingResponse(gen(), media_type="text/event-stream",
                             headers={"Cache-Control": "no-cache",
                                      "X-Accel-Buffering": "no"})

⚠️ message 里别塞异常原文——它会直接显示在用户屏幕上,可能带出上游地址、栈帧甚至 key 片段。给用户一句人话,把真正的异常记进日志(15 章),两边靠同一个 trace_id 对上。


🔌 六、断连:用户关了页面,你还在烧钱

浏览器关页或取消请求后,后端可能收到断连/取消通知,但这不等于底层共享连接必然关闭。⚠️ 客户端请求与上游生成的生命周期需要分别管理:本次请求没人再读,上游仍可能继续工作。两件事必须做。① 感知框架的取消/断连通知。如果仅在发送下一段前轮询,等待上游时可能迟迟发现不了断连。② 在 finally 或上下文管理器退出时关闭本次上游流,释放本次生成占用的资源。下面用假上游验证本地任务是否停止;真实供应商的停止时点与计费结果还需查其接口和用量记录,不能从此模拟推出。

# cancel.py —— 客户端断开后,上游那条流会不会跟着停?(可直接跑,对照看得见)
import asyncio


class Upstream:
    """假的上游模型流:打开后就在后台自己生成,只有 close() 能让它停。
    这里只模拟独立后台任务;真实 SDK 的取消语义需另查。"""

    def __init__(self):
        self.emitted, self._task = 0, None

    def open(self):
        async def produce():
            while True:
                await asyncio.sleep(0.05)
                self.emitted += 1          # ⭐ 每 +1 模拟产出一段,不是真实 token 计费
        self._task = asyncio.create_task(produce())
        return self

    def close(self):
        self._task.cancel()

    async def next_piece(self):            # 后端每次从上游取一段往下发
        await asyncio.sleep(0.05)
        return "块%d" % self.emitted


async def bad(up):
    """❌ 没有 finally:消费者被取消了,模拟上游仍在后台继续产出。"""
    while True:
        await up.next_piece()


async def good(up):
    """✅ finally 里关上游:取消、异常、正常结束三条路都会走到。"""
    try:
        while True:
            await up.next_piece()
    finally:
        up.close()                         # ⭐ 关闭本地模拟上游;真实取消效果需另验


async def main():
    for name, handler in (("❌ 没有 finally", bad), ("✅ finally 里 close", good)):
        up = Upstream().open()
        task = asyncio.create_task(handler(up))
        await asyncio.sleep(0.3)
        task.cancel()                      # ⭐ 模拟:消费者任务收到取消
        try:
            await task
        except asyncio.CancelledError:
            pass
        n0 = up.emitted
        await asyncio.sleep(0.5)           # 断开后再等半秒,看它还在不在生成
        print("%-18s 断开时已产出 %d 段,半秒后 %d 段" % (name, n0, up.emitted))
        up.close()


asyncio.run(main())

示例输出(具体计数随调度变化):没有 finally 的那版,断开时 5 段、半秒后变成 13 段——⭐ 多出来的 8 段是模拟后台任务继续产出的证据,不是实际计费证据;有 finally 的那版停在 5 段。⚠️ 具体数字取决于你机器的调度(每段 0.05 秒,半秒的理论上限是 10 段),要看的是方向不是数字:一边继续涨,一边不动。

⚠️ 分开记录客户端断开与上游故障。客户端断开可能来自用户操作或网络中断。后端应回收本次资源,只凭断连通知无法知道用户有没有点「停止生成」。上游故障在开流前可按第 04 章的约定决定是否重试;已有输出时,保留部分内容并明确展示错误或中断。真实供应商用量的核对方法见 第 12 章。


🔄 七、换个栈怎么对应

概念 Python / FastAPI Node(Express / Hono) Go
分批往外写 StreamingResponse(生成器) 多次 res.write() / 返回 ReadableStream w.Write() + ⭐ Flusher.Flush()
⚠️ 谁在缓冲 框架不缓冲,代理会 同左;另外 compression 中间件要按 MIME 排除 ⭐ ResponseWriter 自己就带缓冲,不 Flush 就攒着
感知客户端断开 await request.is_disconnected() req.on('close', ...) / AbortSignal ctx.Done()(r.Context())
收尾必做 finally 里关上游 finally / close 事件里关上游 defer 里关上游

⭐ 这张表真正想说的:「分批往外写」在每个栈里都要显式表达,⚠️ Go 甚至默认就在缓冲。 FastAPI 只是把它藏进了 StreamingResponse 这个名字里——不是它替你解决了这个问题。


🔗 这一章连到哪里

去哪 为什么
10 · 把流式接到界面上 ⭐ 另一半:本章把帧写进 HTTP,那一章讲浏览器怎么读回来、怎么拼、怎么显示错误帧
04 · 调用层 ⭐ 流式把调用层的三件事都改了:读取超时变成「两帧间隔」、首字后不能静默重试、流式响应不能缓存
12 · 限流、配额与成本护栏 断连后白烧的那部分 token 也要计费、也要进配额,否则你的成本账是缺口的
14 · 容器化与部署 第四节三个凶手里有两个(反向代理、平台缓冲)住在那一章
智能体工程 16c · 接进真实产品 ⭐ 分工:那边讲「为什么要流式、护栏与流式怎么配合、结构化输出和流式的冲突」,本章讲这条链路的工程细节和坑

✅ 检查点

  1. SSE 和「裸分块传输」的区别只有一点,是哪一点?换来了什么?
  2. 为什么 LLM 场景通常不需要 WebSocket?上它要额外承担哪四件事?
  3. 为什么正文内容要用 JSON 包一层再放进 data:?本板块为什么把帧类型放进 JSON 负载,而不用 SSE 的 event: 行?结束帧为什么不写 [DONE]?
  4. 吃掉流式的三个地方分别是什么?它们的共同点是什么?
  5. 定位缓冲问题的判据为什么是「帧间隔」而不是「总时长」?具体怎么一层层测?
  6. 流式下为什么不能用状态码报错?错误该怎么传、字段叫什么?没有结束帧会怎样?
  7. 哪些检查能放在响应头发出之前?发出之后又为什么仍需要流内错误?
  8. 上游流不在 finally 里关会怎样?本章那段对照跑出了什么数字?「客户端断开」和「上游断开」又为什么必须分开记?
  9. 先预测再看答案。第一次读到「请」的前两个字节,第二次补齐该字并读到行尾,第三次才读到空行。哪一次能显示「请」?随后收到 error 和 done 时,这条回答该标为什么状态?
👀 答案
  1. SSE 规定事件格式,空行结束一个事件;HTTP/1.1 chunked 和 HTTP/2 DATA 是承载层的分帧,边界不必与事件重合。换来的是「以后要加错误、用量、工具状态时不用重写前端」。
  2. 因为 LLM 输出是单向的,上行只有「用户又发了一条消息」,一个普通 POST 就够。上 WebSocket 等于把心跳、重连、鉴权、代理兼容四件事全揽到自己身上。
  3. 模型输出里有换行是家常便饭,而本章单行 data: JSON 约定中,未转义换行会破坏 JSON 行;SSE 的事件结束符是空行,规范也支持多行 data: 合并。json.dumps 把换行转义成两个字符,帧就安全了。类型放进负载是跟着消费方走:前端用 fetch 手动解析(EventSource 带不了 Authorization),手动解析器也能支持 event:,只是本课程选择忽略它、限定为单行 JSON 子集;放进负载则一行 JSON.parse 拿到全部信息,解析路径只有一条。⚠️ 同理 [DONE] 不是合法 JSON,会让统一的 JSON.parse 抛 SyntaxError,所以结束帧写成 {"type":"done"}。
  4. 反向代理缓冲(proxy_buffering on)、压缩中间件(攒够一个压缩块才输出)、云平台/网关/CDN 的响应缓冲。共同点:不报错、本地复现不了、三者症状完全一样。
  5. 总时长相近时,帧也可能从每秒到一条变成最后成批到达。用每秒产生一帧的探针从里往外测:直连应用进程 → 容器端口 → 反向代理 → 公网域名,优先检查到达间隔首次明显缩短、出现成批交付的那一段。
  6. 最终响应头发出后状态码就确定了。如果流还能写,发送 error,其中 message 给用户看,trace_id 用于查日志。收到 done 可以结束等待,但出现过 error 时内容仍不完整。缺少 done 时同样不能标记成功。
  7. 鉴权、输入校验、读取历史等可以在提交响应头前进行。这时还能用普通 HTTP 错误;开流后上游仍可能失败,只能在可写的流中报错,已有输出后不能静默重试。
  8. 没有清理逻辑时,模拟上游在消费者取消后仍继续产出。示例中从 5 段涨到 13 段;有 finally 的一侧停在 5 段。真实上游可能继续生成并计费,计费要以供应商用量为准。客户端断开与上游故障应分开记,单凭断开也不能判断用户是否主动取消。
  9. 第三次才能显示「请」。字符完整只是解码成功,空行齐了才有一条可消费的事件。随后收到 error 再收到 done,保留「请」并标为失败、内容未完成。

本节回顾

⚡ 走神救援

本章只管后端 → HTTP 这一半(浏览器那半在第 10 章)。⭐ SSE 是事件格式;HTTP/1.1 chunked、HTTP/2 DATA 是承载分帧,这点约定换来「以后加错误帧、用量帧、工具状态不用重写前端」。WebSocket 不是「更高级的 SSE」,它多的是上行,而 LLM 的上行一个普通 POST 就够。

⭐ 本板块统一帧格式:每帧一行 data: {JSON},帧类型放在负载的 type 字段里(delta / usage / error / done)。

⚠️ 不用 SSE 的 event: 行,因为前端是手动解析;结束帧写 {"type":"done"} 不写 [DONE]——后者不是合法 JSON,会让统一的 JSON.parse 抛错。

错误帧必须多带一个 trace_id,⚠️ 流式最容易漏它:状态码早已是 200,那个装着 trace_id 的 JSON 压根不发,用户只能说「回答到一半崩了」,你查无可查。

⚠️⚠️ 最贵的一节:三个地方会吃掉流式——反向代理的缓冲、压缩中间件、云平台或 CDN 的响应缓冲。难查的原因是共同的:不报错、本地永远复现不了、三者症状完全一样,都是「憋很久然后一次性全出现」,而你的代码一个字都没错。

⭐ 定位法:部署一个每秒吐一帧的探针端点,从里往外逐层测(应用进程 → 容器 → 反向代理 → 公网域名),判据是帧间隔不是总时长,第一处间隔塌成 0 的那层就是凶手。⚠️ 别信浏览器开发者工具的时序。

⭐ 可提前做的检查放在响应头发出之前。开流后,即使状态是 200,也要结合 error 与 done 判定结果。已有片段但未收到 done,就不能将回答标为完整。

💸 断连:用户关页或取消请求后,上游可能继续生成。应处理取消/断连并在 finally 里关上游;模拟只证明本地任务停止,真实计费需另验。⚠️ 最后,客户端断开和上游断开要分开记,否则你会把「大家看完就关」当成「服务在抖」。

下一节 👉 06-关系数据库.md

打卡记录保存在你的浏览器里,首页能看到总进度