用 FastAPI 和 SSE 实现可中断的流式回复
浏览器用 fetch 发起 POST 请求并读取 FastAPI 返回的 SSE,用户点击停止时由 AbortController 取消请求,后端也需关闭上游模型流。文章用确定性模拟响应联调,并提醒检查代理是否缓冲事件。
AI 深度解读
让 AI 聊天逐段显示回答,可以用浏览器的 fetch 发出 POST 请求,让 FastAPI 在同一个 HTTP 响应里持续返回 SSE 事件。作者给了一套 FastAPI 和 Next.js 示例,还把「停止生成」接入了这条链路。点下 Stop 后,浏览器中止请求,服务端退出生成任务并关闭上游流。
这套示例适合先用固定输出跑通。用同一个 mock,你就能分别检查首段有没有及时到达、断流能不能被识别、取消后服务端有没有释放资源。等这些行为都能观察到,再接真实模型。
一次 POST 就能把提问和流式回答接起来
聊天请求有两个阶段。浏览器先把问题放进 POST 请求体,随后服务端沿着同一个 HTTP 响应往回发文本。第二阶段的数据主要从服务端流向浏览器,SSE(Server-Sent Events)已经够用。如果回答期间浏览器还要持续上传实时音频,WebSockets 的双向通信才有用武之地。
浏览器自带的 EventSource 只发 GET,也无法设置自定义请求头。这里用 fetch 发送 JSON,再把响应体按 text/event-stream 解析。SSE 负责事件格式,fetch 负责发请求和读响应,两件事可以分开选。
FastAPI 从 0.135.0 起在 fastapi.sse 提供 EventSourceResponse 和 ServerSentEvent。把下面这段存成 app.py,装好 FastAPI 0.135.0 或更新版本和 Uvicorn,再运行 uvicorn app:app --reload,就能用四段固定输出来验证事件顺序和流关闭。
import asyncio
import logging
from collections.abc import AsyncIterator
from contextlib import aclosing
from fastapi import FastAPI
from fastapi.sse import EventSourceResponse, ServerSentEvent
from pydantic import BaseModel, Field
app = FastAPI()
log = logging.getLogger("uvicorn.error")
class ChatIn(BaseModel):
message: str = Field(min_length=1)
async def mock_tokens(prompt: str) -> AsyncIterator[str]:
try:
for piece in ("Echo: ", prompt, "\n", "Done."):
await asyncio.sleep(0.35)
yield piece
finally:
log.info("Mock stream closed")
@app.post("/chat/stream", response_class=EventSourceResponse)
async def chat_stream(body: ChatIn) -> AsyncIterator[ServerSentEvent]:
try:
async with aclosing(mock_tokens(body.message)) as stream:
async for delta in stream:
yield ServerSentEvent(event="token", data={"token": delta})
except asyncio.CancelledError:
raise
except Exception:
log.exception("Generation failed")
yield ServerSentEvent(event="error", data={"message": "Generation failed"})
return
yield ServerSentEvent(event="done", data={})
重点看 async with aclosing(...) 和紧接着的取消处理。任务退出时,上下文负责关闭生成器,raise 则让取消继续传播。每段输出间隔 0.35 秒,token 事件里的文本增量可以是半个词、几个字符,也可以只是换行。
输入和权限应在响应开流前校验。开流后如果生成失败,就发 error 事件,只有成功走完才发 done。项目还在用旧版 FastAPI 的话,可以用 StreamingResponse 返回 text/event-stream,事件分帧和心跳需要自己处理。
前端要靠 done 事件确认回答完整
示例把 Next.js 的 /api/chat/stream 通过同源代理接到 FastAPI 的 /chat/stream,代理需要边读上游边转发。浏览器读到的每个网络块边界由传输决定,一条 SSE 记录可能跨几个块。直接对每次 read() 的结果做 JSON.parse,就可能拿到半条事件。
安装 eventsource-parser 后,下面这段先把字节解码成文本,再解析完整的 SSE 事件,最后把文本增量交给界面。
import { EventSourceParserStream } from "eventsource-parser/stream";
export async function streamChat(
message: string,
onToken: (token: string) => void,
signal: AbortSignal,
) {
const response = await fetch("/api/chat/stream", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ message }),
signal,
});
const type = response.headers.get("content-type")?.split(";")[0].trim();
if (!response.ok || !response.body || type !== "text/event-stream") {
throw new Error(`Could not start stream (${response.status})`);
}
const reader = response.body
.pipeThrough(new TextDecoderStream())
.pipeThrough(new EventSourceParserStream())
.getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) throw new Error("Stream ended before the done event");
if (value.event === "done") return;
if (value.event === "error") throw new Error("Generation failed");
if (value.event === "token") {
const { token } = JSON.parse(value.data);
if (typeof token !== "string") throw new Error("Invalid token event");
onToken(token);
}
}
} finally {
await reader.cancel().catch(() => {});
reader.releaseLock();
}
}
注意循环里两个 done。reader.read() 返回的 done 只表示传输结束,value.event === "done" 才表示生成成功。连接提前断开时,界面应显示回答中断。用户主动停止时,已经收到的文字可以留在原消息里。
每次生成都创建一个新的 AbortController,把 signal 传给 fetch,再用 ref 保存当前控制器。点击 Stop 或组件卸载时调用 abort()。还要给每轮生成分配一个运行 ID,更新界面前检查它是否仍是当前那一轮,防止旧请求的回调写进新消息。
停止要传到模型端,测试要走公网入口
abort() 发起的是浏览器侧的取消。接入真实模型后,生成任务还得按供应商 SDK 文档,用异步上下文管理器或关闭方法释放上游流。模型调用如果由独立 worker 持有,取消也要传给那个 worker。作者建议分别验证点击 Stop、浏览器断开、模型暂时没有输出时点击 Stop,检查任务退出时是否确实执行了关闭操作。至于供应商何时停止计算、已消耗的用量怎么算,要看该次请求的用量记录。
另一个常见症状是直连 FastAPI 能逐段返回,到了公网却攒到一起显示。FastAPI 原生 SSE 响应会发送空闲心跳并设置 X-Accel-Buffering: no,部署时仍要逐跳检查代理缓冲、压缩、空闲读取超时和请求总时长。Nginx 的 proxy_read_timeout 计算的是两次读取之间的静默时间,心跳可以缩短这段静默。托管平台设定的最长请求时长,要去托管层处理。用 curl -N 分别测公网入口和 FastAPI 直连,比较首条事件到达时间,可以帮助定位延迟是否出在中间链路。
我的判断
这套方案最实用的地方,是把「收到文本」「生成成功」「资源关闭」变成三个能单独验证的信号。只把响应块拼到页面上,也能很快做出逐字显示,但连接在半途结束时,界面就少了判断回答是否完整的依据。加上命名事件和固定 mock,前后端能先把边界行为约定清楚,再调模型。
原文给了可以运行的样例和排查方法,没有提供 SSE 与 WebSockets 的对照数据,也没有给出不同代理下的首段延迟或真实模型取消后的用量结果。关于 SSE 通常能穿过负载均衡器的说法,是部署经验。示例还把 Next.js 同源代理留给读者接线,是否逐段转发、下游断开能否传到 FastAPI,要在自己的部署链路上实测。
能拿来做什么
- 给 Next.js 聊天页加流式输出时,先接固定 mock,用
token追加文本,用done确认完成,并单独处理error和提前断流。 - 做 Stop 按钮时,为每轮生成保存独立的
AbortController和运行 ID,保留已收到的文字,并用服务端日志确认上游流已关闭。 - 上线前用
curl -N对比直连和公网入口的首段时间,再在模型暂时没输出时测一次停止,分别验证代理转发和取消传播。