流式响应生命周期:字节、事件、参数完成与背压
用真实本地HTTP把UTF-8拆成小块,解析SSE并缓冲工具参数,解释取消传播、重连和慢客户端处理。
服务端一次写出一个token,不代表客户端一次读取也得到一个token。TCP、TLS、代理和HTTP库都可能重新分块:一次read可能拿到半个UTF-8字符,也可能拿到多个事件。流式客户端首先要恢复字符与事件边界,之后才能讨论文本展示和工具执行。
连接、事件和业务完成是三层状态
SSE使用HTTP响应传输文本事件流,常见内容类型为text/event-stream。一条事件可以有event、data、id等字段,空行表示事件结束;多行data按规则拼接。以冒号开始的注释常用于心跳。SSE并不规定模型事件的业务含义,[DONE]之类标记属于某些API约定,不是SSE标准的一部分。
WebSocket提供双向消息通信,适合客户端在连接中持续发送控制或音频等数据;SSE主要沿服务端到客户端方向发送,客户端控制通常另走请求。浏览器原生EventSource的请求能力与使用fetch读取POST响应流不同,不能因为都看到data字段就认为认证、重连和取消行为相同。
网络EOF也不等于模型成功。连接断开时可能还缺最后一段参数、终止事件或usage。应用应区分连接已关闭、生成已完成、工具参数已完成和业务已提交。每一层都有自己的状态,而不是一个done=true通吃所有含义。
运行一个真实本机HTTP事件流
以下程序启动一个绑定127.0.0.1随机端口的临时服务,再用标准库客户端读取;服务与客户端都按3字节分块,刻意让中文字符跨块。最后自动关闭服务。事件内容是固定夹具,没有调用模型。
解析器处理此服务采用的LF/CRLF行结束、event与多行data;忽略注释。它不是完整SSE客户端:未实现单独CR行结束、id/retry重连语义或所有供应商事件。连接结束时残留未完成事件会按本应用要求报错,而不是把截断内容当完整结果。实际产品应使用符合所需协议的成熟解析器,并测试异常路径。
保存为streaming.py,运行python -X utf8 streaming.py。
"""真实本地 HTTP 传输 + 小块 UTF-8/SSE 解析;固定事件,不调用模型。"""
import codecs
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.request import urlopen
def parse_sse(chunks, max_chars=8192):
decoder=codecs.getincrementaldecoder('utf-8')()
buffer=''
data=[]
event='message'
size=0
for chunk in chunks:
buffer+=decoder.decode(chunk)
if len(buffer)+size>max_chars:
raise ValueError('未完成事件超过上限')
while '\n' in buffer:
line,buffer=buffer.split('\n',1)
line=line.removesuffix('\r')
if not line:
if data:
yield event,'\n'.join(data)
data,event,size=[],'message',0
elif line.startswith(':'):
continue
else:
field,_,value=line.partition(':')
if value.startswith(' '):value=value[1:]
if field=='event':event=value
if field=='data':
data.append(value);size+=len(value)
decoder.decode(b'',final=True)
if buffer or data:
raise ValueError('连接结束时存在未完成事件')
def frame(event, value):
return ('event: '+event+'\ndata: '+json.dumps(value,ensure_ascii=False)+'\n\n').encode()
class Handler(BaseHTTPRequestHandler):
def log_message(self,*args):pass
def do_GET(self):
self.send_response(200)
self.send_header('Content-Type','text/event-stream; charset=utf-8')
self.end_headers()
payload=(frame('text.delta',{'text':'你好'})+
frame('tool.delta',{'id':'c1','fragment':'{"city":"'})+
frame('tool.delta',{'id':'c1','fragment':'杭州"}'})+
frame('tool.done',{'id':'c1'}))
try:
for index in range(0,len(payload),3):
self.wfile.write(payload[index:index+3]);self.wfile.flush()
except (BrokenPipeError,ConnectionResetError):
pass # 客户端取消时结束本地写入;真实上游还应取消生成。
def run_demo():
server=ThreadingHTTPServer(('127.0.0.1',0),Handler)
thread=Thread(target=server.serve_forever,daemon=True);thread.start()
arguments={};outputs=[]
try:
with urlopen(f'http://127.0.0.1:{server.server_port}/',timeout=5) as response:
chunks=iter(lambda:response.read(3),b'')
for event,data in parse_sse(chunks):
value=json.loads(data)
if event=='text.delta':outputs.append('文本:'+value['text'])
elif event=='tool.delta':
key=value['id'];arguments[key]=arguments.get(key,'')+value['fragment']
outputs.append('参数片段已缓冲,尚未执行')
elif event=='tool.done':
args=json.loads(arguments.pop(value['id']))
outputs.append('完整参数待校验:'+str(args))
if arguments:raise ValueError('连接结束但工具参数未完成')
return outputs
finally:
server.shutdown();server.server_close();thread.join()
if __name__=='__main__':
for line in run_demo():print(line)文本:你好
参数片段已缓冲,尚未执行
参数片段已缓冲,尚未执行
完整参数待校验:{'city': '杭州'}增量解码器保存尚不足以组成字符的字节,收到后续字节再完成解码。行缓冲只在得到换行后处理,事件缓冲只在空行后发布。工具参数按c1累积,收到tool.done才解析为JSON;解析成功后仍显示“待校验”,没有直接调用天气工具。
删除最后一个tool.done事件,客户端会发现连接结束时仍有未完成参数。把杭州的UTF-8字节截掉一半,会在最终解码校验报错。把单个未完成事件扩大到配置上限之外,会触发缓冲限制。三个失败分别对应业务完成、编码完整性和资源约束,不应归为同一个“网络异常”。
并行工具参数要按ID或索引分别组装
供应商可能在一个流中交替发送多个工具调用的名称、ID和参数片段,有些字段只在首次片段出现。适配器要按协议规定的index或ID维护各自状态,避免把c1的城市和c2的日期拼到同一个对象里。需要等相应调用的完成信号与整体验证,而不是看到第一个右括号就执行。
文本输出也可能混有推理摘要、工具事件、拒绝、状态通知或最终使用量,不能把所有data直接拼成用户可见字符串。事件类型白名单与未知事件策略应显式定义;遇到新类型可以记录并安全忽略或报不支持,不能默默当普通文本展示敏感内部字段。
慢客户端为什么会拖累整个服务
如果上游持续生成,而浏览器消费慢,应用层无限列表会把整个回答积在内存。设计有界队列后,队列满时应暂停读取上游、限速或终止请求,并记录原因。仅让队列丢掉随机事件会破坏工具JSON或完整文本;若做展示合并,也应只合并可合并的文本delta,保留控制事件顺序。
暂停读取未必立即暂停模型计算:远端服务可能还在生成并计费,中间代理可能缓冲。需要了解供应商取消机制和网络库行为。客户端断开后,应用要取消上游读取与生成任务,关闭连接,释放并发槽、临时文件和缓存引用;在finally清理本地资源,但不要宣称这必然撤销已经完成的工具副作用。
反向代理缓冲可能让服务端明明逐段写出,浏览器却最后一次性收到。排查时分别记录上游首事件、本服务转发、代理和浏览器收到的时间,并检查内容类型、flush、压缩及代理缓冲配置;不能只修改模型的stream参数。
重连必须知道从哪里恢复
SSE标准提供事件ID和Last-Event-ID机制,但服务端必须保存可重放事件并定义恢复语义,它才有用。模型API不一定支持从任意token继续同一次生成。重新发送请求可能产生不同回答、重复费用或重复工具调用,不能把网络自动重连当成业务幂等保证。
对用户界面,应区分“回答中断,可重试”与“已完成”。服务端保存请求ID、最后已确认事件及工具执行状态;恢复时可以重放已持久化事件,或明确开始一次新生成。若usage终帧丢失,使用量应标为未知并通过后续账单/接口对账,不能记为零。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
一次read就是一个token或一个SSE事件吗?
参考思路与常见误区
不是。传输层可拆分或合并字节块,甚至切开UTF-8字符。需增量解码、按行解析并等空行完成SSE事件,随后按业务事件类型处理。token边界与网络块边界无固定关系。
常见误区:对每个网络块直接json.loads或单独UTF-8解码。
SSE与WebSocket如何选择?原生EventSource与fetch流相同吗?
参考思路与常见误区
SSE主要服务端向客户端推送HTTP事件,WebSocket支持双向消息。EventSource的请求、认证与自动重连能力和fetch读取POST响应流不同。选择取决于双向控制需求及协议支持,不能只看都能逐段显示。
常见误区:认为SSE一定支持任意POST头,或WebSocket自动提供业务恢复。
客户端收到半个工具参数,何时可以执行?
参考思路与常见误区
按ID或协议索引分别缓冲,等该调用明确完成并确认未截断,再解析、schema校验和授权。并行调用可能交错,不能共用一个字符串缓冲,也不能看到第一个右括号就执行。
常见误区:把所有delta拼一起并尽早执行可解析片段。
慢客户端造成内存增长,为什么随机丢事件不可取?
参考思路与常见误区
随机丢失可能破坏JSON参数、控制顺序或正文。应使用有界队列,暂停上游读取、限速或终止,只有明确可合并文本才合并。停止读取未必停止远端计费,取消需传播并释放资源。
常见误区:用无限列表缓冲,或只关闭浏览器而保留后台生成。
SSE连接断开后自动重连,是否保证继续同一次模型生成?
参考思路与常见误区
不保证。Last-Event-ID需要服务器有可重放事件和恢复约定,模型API可能不支持恢复。重发可能变成新生成和新费用,已有工具副作用需独立记录。终帧usage丢失应标未知,不能记零。
常见误区:把传输重连等同于业务幂等和无损续传。