先从一个普通聊天接口开始。客户端提交问题后,服务器调用模型,等模型生成完整答案,再一次性返回 JSON:
客户端发出请求后,服务器先等待模型生成完整答案,再一次性返回响应头和完整响应体;客户端此时才开始显示答案。
FLOW / RELATIONSHIP
客户端请求
等待完整生成
服务器调用模型
返回完整响应
响应头 + 完整响应体
显示答案
客户端开始渲染
假设模型用 20 秒生成答案,那么用户在前 20 秒里什么也看不到。即使服务器一直在工作,页面看起来也像是没有响应。
流式响应改变了返回答案的方式。服务器拿到第一小段内容后就立即发送,后续内容生成一段、发送一段:
客户端请求后,服务器先返回响应头,在同一份响应体中依次发送第一段、第二段和第三段内容,最后结束响应。客户端可以边接收边渲染,无需等待完整生成。
返回响应头
同一个 HTTP 响应
第 1 段内容
接收并显示
第 2 段内容
继续追加正文
第 3 段内容
响应结束
完成一次请求
这里要区分两个时间:
流式响应主要缩短的是用户感知到的首块时间,不一定能缩短模型生成完整答案的时间。它让用户更早看到结果,也允许页面边接收边渲染,并为停止生成、进度提示和工具调用状态提供了基础。
不过,流式响应也带来了新的问题:客户端如何知道一段内容从哪里开始、在哪里结束?流已经开始后发生错误怎么办?用户关闭页面后,服务器如何停止模型?网络断开后能不能继续?这正是后面要重点学习 SSE 的知识内容。
阅读流式代码时,经常会看到响应、数据块和事件这三个词。它们不是同一个概念:
一次流式请求仍然只有一个 HTTP 响应。服务器不会为每个模型片段重新创建一次响应,而是在同一个响应体中持续写入数据。
网络数据块的边界也没有业务含义。一次 yield 可能被底层拆成多个网络块,多次 yield 也可能合并后才到达客户端。一个 UTF-8 汉字、一个 JSON 对象,甚至 SSE 中的一行文本,都可能跨越两个网络块。因此,客户端不能对每次 reader.read() 得到的内容直接执行 JSON.parse(),而要先按照协议重新拼出完整事件。
yield
reader.read()
JSON.parse()
FastAPI 的 StreamingResponse 可以把普通迭代器或异步迭代器产生的内容持续写入响应体。我们先看一个不涉及模型和 SSE 的最小示例:
StreamingResponse
01# src/fastapi/api/stream/text_stream.py 02import asyncio 03from collections.abc import AsyncIterator 04 05from fastapi import APIRouter 06from fastapi.responses import StreamingResponse 07 08router = APIRouter() 09 10 11class TextStreamingResponse(StreamingResponse): 12 media_type = "text/plain" 13 14 15# 请求路径:GET /api/v1/stream/text/stream 16@router.get( 17 "/text/stream", 18 response_class=TextStreamingResponse, 19) 20async def stream_text() -> AsyncIterator[str]: 21 for chunk in ("FastAPI", " 可以", " 流式", " 输出"): 22 await asyncio.sleep(0.2) 23 yield chunk
这段代码的执行过程如下:
/api/v1/stream/text/stream
TextStreamingResponse
text/plain
FastAPI
yield 的作用是产生一段值并暂停函数,await 的作用是暂停当前协程并把执行机会交还事件循环。二者解决的问题不同。真实模型的 astream() 内部通常包含异步网络读取,所以自然会到达 await;如果自定义异步生成器只有长时间的 CPU 计算,即使不断 yield,取消信号也可能无法及时执行
await
astream()
启动本地服务之后,我们可以通过下面这个案例来感受一下这个接口的调用过程
浏览器拿到的是连续的 text/plain 字节流,并不知道 Python 端一共执行了几次 yield。页面最后显示为一段完整文本,也不代表浏览器恰好执行了四次 reader.read();服务器生成边界和网络读取边界仍然是两回事
TextStreamingResponse 把媒体类型固定为 text/plain。因为它属于文本类型,响应层还会补充 UTF-8 字符集。我们也可以显式创建响应对象:
01# src/fastapi/api/stream/text_stream.py 02from collections.abc import AsyncIterable 03 04from fastapi.responses import StreamingResponse 05 06async def generate_text() -> AsyncIterable[str]: 07 yield "第一段" 08 yield "第二段" 09 10 11async def stream_text() -> StreamingResponse: 12 return StreamingResponse( 13 generate_text(), 14 media_type="text/plain; charset=utf-8", 15 ) 16 17# GET /api/v1/stream/text/response 18@router.get( 19 "/text/response", 20 summary="显式创建纯文本流响应", 21) 22async def stream_text_response() -> StreamingResponse: 23 """在运行时显式传入迭代器、媒体类型和字符集。""" 24 25 return StreamingResponse( 26 generate_text(), 27 media_type="text/plain; charset=utf-8", 28 )
显式返回 StreamingResponse 适合在运行时决定响应头、状态码或媒体类型。直接 yield 更简洁,也能让 FastAPI 根据返回类型进行文档生成和数据处理。两种形式最终都要把一个可迭代对象交给响应层。
StreamingResponse 同时支持同步生成器和异步生成器,但选择时要看数据来源:
async def
async for
def
不要在异步生成器里直接调用耗时的同步 SDK。它会占住事件循环,使同一进程中的其他请求、心跳和取消处理一起停下来。如果供应商只提供同步流式接口,应使用同步生成器,让框架在线程池中迭代,或者把阻塞调用明确放到线程中执行。
LangChain 的 astream() 会返回异步迭代器,可以直接接入 StreamingResponse:
01# src/fastapi/api/stream/langchain_stream.py 02from collections.abc import AsyncIterator 03from typing import Annotated 04 05from fastapi import APIRouter, Depends 06from fastapi.responses import StreamingResponse 07 08from .common import ChatRequest, DemoChatService, get_chat_service 09 10router = APIRouter() 11 12# POST /api/v1/stream/langchain 13@router.post("/langchain") 14async def stream_chat( 15 payload: ChatRequest, 16 service: Annotated[DemoChatService, Depends(get_chat_service)], 17) -> StreamingResponse: 18 async def generate() -> AsyncIterator[str]: 19 async for chunk in service.astream(payload.question): 20 yield chunk 21 22 return StreamingResponse( 23 generate(), 24 media_type="text/plain; charset=utf-8", 25 )
真实 LangChain 模型的 chunk 通常是消息块,chunk.content 才是模型产生的内容。一个消息块不保证恰好对应模型分词器中的一个 token,也不保证是一句话,所以后文虽然沿用常见的 token 事件名,客户端仍应把它理解为文本增量。当前项目的 DemoChatService.astream() 已经把消息块转换为字符串,路由可以直接转发。
chunk
chunk.content
token
DemoChatService.astream()
不同模型集成返回的 content 结构可能不同。有的返回字符串,有的返回内容块列表,有的还会混入工具调用参数。真实项目要先确认当前模型的消息类型,再决定如何提取文本,不能无条件执行 str(chunk.content),否则结构化工具信息也可能被错误地显示给用户。
content
str(chunk.content)
还要注意,调用了 astream() 不等于整条链一定能够逐步产出。链中的模型、解析器和自定义节点都要支持流式处理;只要中间某个步骤必须等待完整结果,客户端就可能在那一步暂时收不到新内容。
下面这个案例中,客户端的输入会作为 {"question":"..."} 发送给 POST /api/v1/stream/langchain。接口仍然返回纯文本,所以客户端只负责逐块解码和追加,不会出现 event、id 或 data 等 SSE 字段
{"question":"..."}
POST /api/v1/stream/langchain
event
id
data
你可以把这个案例与后面的 /chat 放在一起比较:两者使用同一个 DemoChatService.astream(),但 /langchain 只返回正文,/chat 还会返回开始、结束、错误和事件 ID 等协议信息
/chat
/langchain
关于 langchain 更详细的使用,我们会在后续章节中深入学习
前面的案例没有请求真实的 LLM 模型。这个案例,我们使用 deepseek 的 SSE 接口来对接流式响应
所有的配置,我们都配置在项目根目录的 .env 文件中:
.env
1DEEPSEEK_MODEL=deepseek-chat 2DEEPSEEK_BASE_URL=https://api.deepseek.com 3DEEPSEEK_API_KEY=your-api-key
下面是案例和对应的代码实现
001# src/fastapi/api/stream/deepseek_sse.py 002"""使用 .env 中的 DeepSeek 配置调用真实模型的 SSE 接口。""" 003 004import asyncio 005import logging 006from collections.abc import AsyncIterator 007from typing import Annotated 008from uuid import uuid4 009 010from fastapi import APIRouter, Depends, HTTPException 011from fastapi.sse import EventSourceResponse, ServerSentEvent 012from langchain_openai import ChatOpenAI 013 014from app.core.config import Settings, get_settings 015from app.model import create_model 016 017from .common import ConversationRequest 018 019logger = logging.getLogger(__name__) 020router = APIRouter() 021 022 023def get_deepseek_model( 024 settings: Annotated[Settings, Depends(get_settings)], 025) -> ChatOpenAI: 026 """在流启动前创建模型,缺少密钥时返回普通 HTTP 错误。""" 027 028 try: 029 return create_model(settings) 030 except RuntimeError as exc: 031 raise HTTPException( 032 status_code=503, 033 detail="DeepSeek 模型配置不完整", 034 ) from exc 035 036 037# POST /api/v1/stream/deepseek 038@router.post( 039 "/deepseek", 040 response_class=EventSourceResponse, 041 summary="DeepSeek 流式聊天", 042) 043async def stream_deepseek( 044 payload: ConversationRequest, 045 model: Annotated[ChatOpenAI, Depends(get_deepseek_model)], 046) -> AsyncIterator[ServerSentEvent]: 047 """调用 DeepSeek,并把 LangChain 消息块转换成 SSE 生命周期事件。""" 048 049 message_id = f"msg_{uuid4().hex}" 050 sequence = 0 051 usage: dict[str, object] | None = None 052 053 yield ServerSentEvent( 054 event="message_start", 055 id=f"{message_id}:{sequence}", 056 retry=3_000, 057 data={ 058 "message_id": message_id, 059 "model": model.model_name, 060 }, 061 ) 062 063 try: 064 async for chunk in model.astream(payload.to_langchain_messages()): 065 if chunk.usage_metadata is not None: 066 usage = dict(chunk.usage_metadata) 067 068 # ``text`` 会从字符串或标准文本内容块中提取可展示文本。 069 if not chunk.text: 070 continue 071 072 sequence += 1 073 yield ServerSentEvent( 074 event="token", 075 id=f"{message_id}:{sequence}", 076 data={"text": chunk.text}, 077 ) 078 except asyncio.CancelledError: 079 # 客户端断开时让取消信号继续传播,以便终止上游读取。 080 raise 081 except Exception: 082 logger.exception("DeepSeek streaming request failed") 083 sequence += 1 084 yield ServerSentEvent( 085 event="stream_error", 086 id=f"{message_id}:{sequence}", 087 data={ 088 "code": "model_unavailable", 089 "message": "模型暂时不可用,请稍后重试", 090 }, 091 ) 092 return 093 094 sequence += 1 095 yield ServerSentEvent( 096 event="message_end", 097 id=f"{message_id}:{sequence}", 098 data={ 099 "finish_reason": "stop", 100 "usage": usage, 101 }, 102 )
最终请求路径是 POST /api/v1/stream/deepseek:
POST /api/v1/stream/deepseek
01curl -iN -X POST \ 02 http://127.0.0.1:8000/api/v1/stream/deepseek \ 03 -H 'Content-Type: application/json' \ 04 -d '{ 05 "messages": [ 06 {"role":"system","content":"你是 Python 学习助手。"}, 07 {"role":"user","content":"什么是 FastAPI?"}, 08 {"role":"assistant","content":"FastAPI 是一个 Python Web 框架。"}, 09 {"role":"user","content":"它支持异步吗?"} 10 ] 11 }'
这个案例与前面的单轮 /chat 案例最重要的区别,在于请求体:每次提问都会把当前 UI 组件中已经完成的 user 和 assistant 消息连同新问题一起提交。
user
assistant
可以先发送“请记住:我正在学习 FastAPI”,等回答结束后再问“我刚才说我在学习 什么?”。第二轮请求不是只发送最后一个问题,而是发送类似下面的完整数组:
1{ 2 "messages": [ 3 {"role": "user", "content": "请记住:我正在学习 FastAPI。"}, 4 {"role": "assistant", "content": "好的,我记住了。"}, 5 {"role": "user", "content": "我刚才说我在学习什么?"} 6 ] 7}
纯文本流只能表达正文。如果服务器还要告诉客户端 消息开始了、正在执行工具、已经结束 、或者 生成失败,就需要在文本之上再约定一种格式
常见方案如下:
AI 聊天通常是客户端先提交一次问题,随后服务器持续返回结果。这个过程仍然符合普通 HTTP 的请求与响应模型,SSE 已经能够表达正文、状态、错误和恢复信息。WebSocket 功能更多,但也会增加连接管理、心跳、鉴权、重连和跨进程广播的复杂度,不应该成为默认选择。
运行真实异步生成器,编码 message_start、token 与 message_end 三类 SSE 事件。文本来自请求参数,不调用模型。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
1from fastapi import FastAPI 2 3from event_stream import router 4 5app = FastAPI(title="FastAPI 流式响应") 6app.include_router(router) 7
01import asyncio 02import json 03from collections.abc import AsyncIterator 04 05from fastapi import APIRouter, Query 06from fastapi.responses import StreamingResponse 07 08router = APIRouter() 09 10def encode_event(event: str, sequence: int, data: dict[str, object]) -> str: 11 payload = json.dumps(data, ensure_ascii=False) 12 return f"event: {event}\nid: {sequence}\ndata: {payload}\n\n" 13 14async def generate(text: str, delay_ms: int) -> AsyncIterator[str]: 15 try: 16 yield encode_event("message_start", 0, {"length": len(text)}) 17 for index, character in enumerate(text, start=1): 18 await asyncio.sleep(delay_ms / 1000) 19 print(f"生成文本增量 {index}:{character}") 20 yield encode_event("token", index, {"text": character}) 21 yield encode_event("message_end", len(text) + 1, {"finish_reason": "stop"}) 22 finally: 23 print("流式生成器已清理") 24 25@router.get("/events") 26async def events( 27 text: str = Query(default="你好", min_length=1, max_length=40), 28 delay_ms: int = Query(default=20, ge=5, le=50), 29) -> StreamingResponse: 30 return StreamingResponse(generate(text, delay_ms), media_type="text/event-stream", 31 headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}) 32
打开在线案例,点击运行,等待环境就绪,再发送默认 GET /events?text=你好&delay_ms=20。本篇不需要模型密钥或外部服务。
GET /events?text=你好&delay_ms=20
默认响应类型为 text/event-stream,正文包含开始事件、两个 token 事件和结束事件;每条事件以空行结束,data 是 JSON。日志会逐项记录生成过程,并在最后记录清理。
当前浏览器工作区使用 HTTPX ASGITransport 汇总完整响应,因此响应预览在生成结束后一次展示,不代表客户端已经逐块收到网络数据。下载后运行服务,再执行 curl -N "http://127.0.0.1:8000/events?text=hello&delay_ms=50",才能观察真实 HTTP 分段到达。text 最多 40 字符、间隔最多 50 毫秒,事件序号只属于当前请求,不提供断线持久化恢复。
curl -N "http://127.0.0.1:8000/events?text=hello&delay_ms=50"
下载项目后,在项目目录执行:
1uv run fastapi dev main.py
再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。
http://127.0.0.1:8000/docs
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 概述
先从一个普通聊天接口开始。客户端提交问题后,服务器调用模型,等模型生成完整答案,再一次性返回 JSON:
客户端发出请求后,服务器先等待模型生成完整答案,再一次性返回响应头和完整响应体;客户端此时才开始显示答案。
FLOW / RELATIONSHIP
客户端请求
等待完整生成
服务器调用模型
返回完整响应
响应头 + 完整响应体
显示答案
客户端开始渲染
假设模型用 20 秒生成答案,那么用户在前 20 秒里什么也看不到。即使服务器一直在工作,页面看起来也像是没有响应。
流式响应改变了返回答案的方式。服务器拿到第一小段内容后就立即发送,后续内容生成一段、发送一段:
客户端请求后,服务器先返回响应头,在同一份响应体中依次发送第一段、第二段和第三段内容,最后结束响应。客户端可以边接收边渲染,无需等待完整生成。
FLOW / RELATIONSHIP
客户端请求
返回响应头
同一个 HTTP 响应
第 1 段内容
接收并显示
第 2 段内容
继续追加正文
第 3 段内容
继续追加正文
响应结束
完成一次请求
这里要区分两个时间:
流式响应主要缩短的是用户感知到的首块时间,不一定能缩短模型生成完整答案的时间。它让用户更早看到结果,也允许页面边接收边渲染,并为停止生成、进度提示和工具调用状态提供了基础。
不过,流式响应也带来了新的问题:客户端如何知道一段内容从哪里开始、在哪里结束?流已经开始后发生错误怎么办?用户关闭页面后,服务器如何停止模型?网络断开后能不能继续?这正是后面要重点学习 SSE 的知识内容。
2. 响应、数据块与事件
阅读流式代码时,经常会看到响应、数据块和事件这三个词。它们不是同一个概念:
一次流式请求仍然只有一个 HTTP 响应。服务器不会为每个模型片段重新创建一次响应,而是在同一个响应体中持续写入数据。
网络数据块的边界也没有业务含义。一次
yield可能被底层拆成多个网络块,多次yield也可能合并后才到达客户端。一个 UTF-8 汉字、一个 JSON 对象,甚至 SSE 中的一行文本,都可能跨越两个网络块。因此,客户端不能对每次reader.read()得到的内容直接执行JSON.parse(),而要先按照协议重新拼出完整事件。3. StreamingResponse
FastAPI 的
StreamingResponse可以把普通迭代器或异步迭代器产生的内容持续写入响应体。我们先看一个不涉及模型和 SSE 的最小示例:这段代码的执行过程如下:
/api/v1/stream/text/streamTextStreamingResponse,响应类型是text/plainyield,把FastAPI交给响应层yield的作用是产生一段值并暂停函数,await的作用是暂停当前协程并把执行机会交还事件循环。二者解决的问题不同。真实模型的astream()内部通常包含异步网络读取,所以自然会到达await;如果自定义异步生成器只有长时间的 CPU 计算,即使不断yield,取消信号也可能无法及时执行启动本地服务之后,我们可以通过下面这个案例来感受一下这个接口的调用过程
浏览器拿到的是连续的
text/plain字节流,并不知道 Python 端一共执行了几次yield。页面最后显示为一段完整文本,也不代表浏览器恰好执行了四次reader.read();服务器生成边界和网络读取边界仍然是两回事TextStreamingResponse把媒体类型固定为text/plain。因为它属于文本类型,响应层还会补充 UTF-8 字符集。我们也可以显式创建响应对象:显式返回
StreamingResponse适合在运行时决定响应头、状态码或媒体类型。直接yield更简洁,也能让 FastAPI 根据返回类型进行文档生成和数据处理。两种形式最终都要把一个可迭代对象交给响应层。StreamingResponse同时支持同步生成器和异步生成器,但选择时要看数据来源:async def+async fordef+yield不要在异步生成器里直接调用耗时的同步 SDK。它会占住事件循环,使同一进程中的其他请求、心跳和取消处理一起停下来。如果供应商只提供同步流式接口,应使用同步生成器,让框架在线程池中迭代,或者把阻塞调用明确放到线程中执行。
4. 接入 LangChain
LangChain 的
astream()会返回异步迭代器,可以直接接入StreamingResponse:真实 LangChain 模型的
chunk通常是消息块,chunk.content才是模型产生的内容。一个消息块不保证恰好对应模型分词器中的一个 token,也不保证是一句话,所以后文虽然沿用常见的token事件名,客户端仍应把它理解为文本增量。当前项目的DemoChatService.astream()已经把消息块转换为字符串,路由可以直接转发。不同模型集成返回的
content结构可能不同。有的返回字符串,有的返回内容块列表,有的还会混入工具调用参数。真实项目要先确认当前模型的消息类型,再决定如何提取文本,不能无条件执行str(chunk.content),否则结构化工具信息也可能被错误地显示给用户。还要注意,调用了
astream()不等于整条链一定能够逐步产出。链中的模型、解析器和自定义节点都要支持流式处理;只要中间某个步骤必须等待完整结果,客户端就可能在那一步暂时收不到新内容。下面这个案例中,客户端的输入会作为
{"question":"..."}发送给POST /api/v1/stream/langchain。接口仍然返回纯文本,所以客户端只负责逐块解码和追加,不会出现event、id或data等 SSE 字段你可以把这个案例与后面的
/chat放在一起比较:两者使用同一个DemoChatService.astream(),但/langchain只返回正文,/chat还会返回开始、结束、错误和事件 ID 等协议信息关于 langchain 更详细的使用,我们会在后续章节中深入学习
5. 对接 deepseek
前面的案例没有请求真实的 LLM 模型。这个案例,我们使用 deepseek 的 SSE 接口来对接流式响应
所有的配置,我们都配置在项目根目录的
.env文件中:下面是案例和对应的代码实现
最终请求路径是
POST /api/v1/stream/deepseek:这个案例与前面的单轮
/chat案例最重要的区别,在于请求体:每次提问都会把当前 UI 组件中已经完成的user和assistant消息连同新问题一起提交。可以先发送“请记住:我正在学习 FastAPI”,等回答结束后再问“我刚才说我在学习 什么?”。第二轮请求不是只发送最后一个问题,而是发送类似下面的完整数组:
6. 选择流式协议
纯文本流只能表达正文。如果服务器还要告诉客户端 消息开始了、正在执行工具、已经结束 、或者 生成失败,就需要在文本之上再约定一种格式
常见方案如下:
data、event、id等字段AI 聊天通常是客户端先提交一次问题,随后服务器持续返回结果。这个过程仍然符合普通 HTTP 的请求与响应模型,SSE 已经能够表达正文、状态、错误和恢复信息。WebSocket 功能更多,但也会增加连接管理、心跳、鉴权、重连和跨进程广播的复杂度,不应该成为默认选择。
20. 在线实验
运行真实异步生成器,编码 message_start、token 与 message_end 三类 SSE 事件。文本来自请求参数,不调用模型。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
GET /events?text=你好&delay_ms=20。本篇不需要模型密钥或外部服务。默认响应类型为 text/event-stream,正文包含开始事件、两个 token 事件和结束事件;每条事件以空行结束,data 是 JSON。日志会逐项记录生成过程,并在最后记录清理。
当前浏览器工作区使用 HTTPX ASGITransport 汇总完整响应,因此响应预览在生成结束后一次展示,不代表客户端已经逐块收到网络数据。下载后运行服务,再执行
curl -N "http://127.0.0.1:8000/events?text=hello&delay_ms=50",才能观察真实 HTTP 分段到达。text 最多 40 字符、间隔最多 50 毫秒,事件序号只属于当前请求,不提供断线持久化恢复。下载项目后,在项目目录执行:
再通过
http://127.0.0.1:8000/docs发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。