FastAPI on 武成龙

给 RAG Agent 加流式输出：SSE 从设计到落地

Fri, 07 Aug 2026 00:00:00 +0000

给一个基于 FastAPI + LangChain/LangGraph 的 RAG Agent 加上"打字机"式流式输出。本文按自顶向下的顺序记录：从方案选型、协议设计，到后端/前端实现，最后是一段曲折的踩坑——dev 代理的 gzip 压缩会把流式悄悄变成一次性响应。

先说结论：

流式对话用 SSE（Server-Sent Events）就够了——方案一（SSE 专用接口）成本可控、标准通用、能满足"打字机效果"的核心诉求。关键实现要点有三个：后端用 agent.astream(stream_mode="messages") 逐 token 产出、前端用原生 fetch + ReadableStream 解析（不能用 EventSource，因为要 POST + Authorization）、以及必须让响应头带 Cache-Control: no-cache, no-transform，否则开发代理的 gzip 会把流缓冲成一大块。

一、为什么需要流式

LLM 生成一段回复通常要 3~10 秒，Agent 场景还会先调工具检索，首字延迟更明显。如果没有流式，用户点击发送后只能盯着转圈，体验很差；而流式下首个 token 往往几百毫秒就到了，后续内容逐字出现，感知延迟大幅下降。

在动手前先明确约束：

现有接口 POST /chat 一次性返回 JSON，前端 await 后整段渲染；
后端已有 create_react_agent(llm, tools) 的 ReAct Agent（含 RAG 检索工具和 MCP 工具）；
前端是 React + umi（axios 封装），需要增量渲染能力。

二、方案选型：SSE / WebSocket / NDJSON

维度	SSE（方案一）	WebSocket（方案二）	NDJSON（方案三）
实现成本	中	高	低
前端改动	中（换 fetch）	大（WS 客户端）	小（axios 参数）
标准性 / 通用性	高	中	低
双向交互（停止 / 确认）	否	是	否
代理 / 负载均衡兼容	好	需要特殊支持	好（但怕压缩）
适用场景	通用聊天流式，首选	需要 Agent 交互控制	快速验证 / 最小改动

选择 SSE 的决定性理由：

单向流正是聊天场景需要的——服务端推，客户端收，不需要上行通道；
HTTP 协议、任何代理/CDN 都能透传，生产部署成本最低；
保留原有 POST /chat 不动，新端点并行存在，向后兼容；
把事件对象设计成与传输协议解耦（{"type", "content", ...}），未来要升级 WebSocket 或加"停止生成"功能时，只换传输层即可。

一个容易踩的坑：EventSource（浏览器原生 SSE API）只支持 GET，而我们的接口需要 POST + Authorization 请求头，所以前端必须用 fetch + ReadableStream 手动解析 SSE 帧。

三、后端设计：事件协议

流式接口把原来的一次性 JSON 响应拆成一串事件，每个事件一行：

data: {"type": "text", "content": "地理信息系统（GIS"} # 增量文本，前端追加渲染

data: {"type": "tool", "name": "info_retriever"} # 工具调用，可展示"正在检索…"

data: {"type": "done", "response": "...", "session_id": "...", "message_count": 6} # 结束

data: {"type": "error", "code": 5010, "message": "聊天调用超时"} # 出错

SSE 帧格式是 data: <JSON>\n\n，一次连接推多个事件，最后自然结束。

四、后端实现

4.1 服务层：async generator 产出事件

核心是 LangGraph 的 agent.astream(..., stream_mode="messages")，它逐 token 产出 (message_chunk, metadata)。这里有个非常优雅的特性：工具调用阶段产出的 AIMessageChunk 内容为空（只有 tool_calls），自然被 elif content: 过滤掉；ToolMessage 单独透出为 tool 事件；最终答案逐 token 到达。这样"文本流"和"工具事件流"自动分离。

async def chat_stream(self, prompt, query, chat_model_name, ...):
 tools, messages = self._build_tools_and_messages(
 prompt=prompt, query=query, use_memory=use_memory,
 history=history, db_name=db_name, mcp_tools=mcp_tools,
 user_id=user_id,
 )
 llm = self._create_llm(chat_model_name)

 if tools:
 agent = create_react_agent(llm, tools)
 async for msg_chunk, _meta in agent.astream(
 {"messages": messages},
 config={"callbacks": [handler]}, # 工具审计回调不变
 stream_mode="messages",
 ):
 msg_type = getattr(msg_chunk, "type", "")
 content = getattr(msg_chunk, "content", "") or ""
 if msg_type == "tool": # ToolMessage → 工具事件
 yield {"type": "tool",
 "name": getattr(msg_chunk, "name", None) or "tool"}
 elif content: # AIMessageChunk → 增量文本
 yield {"type": "text", "content": content}
 else:
 async for chunk in llm.astream(messages): # 纯对话直接流式
 content = getattr(chunk, "content", "") or ""
 if content:
 yield {"type": "text", "content": content}

顺带一个重构收益：把"构建工具 + 消息列表"抽成 _build_tools_and_messages()，普通 /chat 和流式 /chat/stream 共享，避免两套逻辑漂移。

4.2 路由层：StreamingResponse + 完整生命周期

流式不能牺牲原有保障，所以生命周期和一次性接口完全对齐：

先落库：用户消息、ChatRun 审计记录在流开始前写入（超时/断线也能恢复用户输入）；
流转：把 generator 包进 StreamingResponse(media_type="text/event-stream")；
流结束落库：AI 回复、会话标题、记忆、finish_chat_run("succeeded")；
超时：用 asyncio.wait_for(iterator.__anext__(), timeout=...) 对每个 chunk 设超时，超时发 error 事件并记 timed_out；
断线/取消：except asyncio.CancelledError / finally 兜底记 cancelled，防止审计记录永远卡在 running。

def _sse_payload(event: dict) -> str:
 return f"data: {json.dumps(event, ensure_ascii=False)}\n\n"

@router.post("/chat/stream")
async def chat_stream(request: ChatRequest, ...) -> StreamingResponse:
 # ... 会话校验、先落库用户消息、create_chat_run ...
 return StreamingResponse(
 event_generator(), # 内部 while 循环 + asyncio.wait_for 逐块消费
 media_type="text/event-stream",
 headers={
 "Cache-Control": "no-cache, no-transform", # 关键！见踩坑部分
 "X-Accel-Buffering": "no",
 "Connection": "keep-alive",
 },
 )

五、前端实现

5.1 用 fetch 解析 SSE

为什么不用 EventSource：它只支持 GET，且无法自定义 Authorization 头。用 fetch + ReadableStream：

export async function chatStream(body, onEvent, signal?) {
 const headers: Record<string, string> = { 'Content-Type': 'application/json' };
 const token = localStorage.getItem('token');
 if (token) headers['Authorization'] = `Bearer ${token}`;

 const resp = await fetch('/llm/v1/chat/stream', {
 method: 'POST', headers, body: JSON.stringify(body), signal,
 });
 if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
 if (!resp.body) throw new Error('响应体不可用');

 const reader = resp.body.getReader();
 const decoder = new TextDecoder('utf-8');
 let buffer = '';

 while (true) {
 const { done, value } = await reader.read();
 if (done) break;
 buffer += decoder.decode(value, { stream: true });

 let sepIdx: number;
 while ((sepIdx = buffer.indexOf('\n\n')) >= 0) { // 按空行切分 SSE 帧
 const frame = buffer.slice(0, sepIdx);
 buffer = buffer.slice(sepIdx + 2);
 for (const line of frame.split('\n')) {
 if (!line.startsWith('data: ')) continue;
 const payload = line.slice(6).trim();
 if (!payload || payload === '[DONE]') continue;
 onEvent(JSON.parse(payload)); // 交给 React 增量渲染
 }
 }
 }
}

注意：SSE 帧可能跨网络分块到达，所以必须用 buffer 拼接后按 \n\n 切分，不能假设一次 read() 就是一个完整事件。

5.2 增量渲染

状态更新只改最后一条 AI 消息：首个 text 事件创建消息（标记 streaming），后续事件原地追加内容。配合一个闪烁光标，就是完整的打字机效果。

let streamedText = '';
let streamMsgId: string | null = null;

await chatStream(requestData, (ev) => {
 if (ev.type === 'text' && ev.content) {
 streamedText += ev.content;
 if (streamMsgId === null) {
 streamMsgId = String(Date.now() + 1);
 setMessages(prev => [...prev,
 { id: streamMsgId!, type: 'ai', content: streamedText, streaming: true }]);
 } else {
 setMessages(prev => prev.map(m =>
 m.id === streamMsgId ? { ...m, content: streamedText } : m));
 }
 }
 // ev.type === 'tool' 可展示"正在检索…"；ev.type === 'error' 提示错误
});

六、踩坑记录：gzip 把流式变成一次性响应

这是本次最值得记录的一环。

现象

后端直连、甚至通过 dev 代理用 curl 测试，事件都是逐块到达的（实测 31 个事件分布在 10~16 秒内）。但浏览器里就是等全部回复结束后一次性渲染，流式完全没有效果。

定位

在浏览器 Network 面板看 chat/stream 响应头，发现两个可疑项：

Content-Encoding: gzip
X-Powered-By: Express

X-Powered-By: Express 说明请求经过了 Umi dev 代理（Express 中间件）。Express 的 compression 中间件默认对接受 gzip 的客户端启用压缩——浏览器请求头带 Accept-Encoding: gzip, deflate, br，而 curl 不带，所以 curl 正常、浏览器异常，就是这个差异造成的假象。

为什么 gzip 会破坏流式？compression 中间件把响应包进 zlib 流，zlib 默认攒够一个块（约 16KB）才输出。对一段几百字的回复，数据会在流结束时一次性 flush，浏览器拿到的就是一整块压缩数据，解压后一次性渲染。

修复：`Cache-Control: no-cache, no-transform`

Umi 3 的 dev CLI 把 compress: true 写死，devServer.compress = false 覆盖不掉。最稳妥的方案是让后端对这个响应显式声明"不可转换"：

headers={
 "Cache-Control": "no-cache, no-transform",
 ...
}

no-transform 是 RFC 7234 §5.2.2.4 定义的标准指令。Express compression 中间件的 shouldTransform() 正是检查它：

var cacheControlNoTransformRegExp = /(?:^|,)\s*?no-transform\s*?(?:,|$)/

function shouldTransform(req, res) {
 var cacheControl = res.getHeader('Cache-Control')
 // Don't compress for Cache-Control: no-transform
 return !cacheControl || !cacheControlNoTransformRegExp.test(cacheControl)
}

命中后中间件直接跳过压缩，流就能原样逐块透传给浏览器。实测对比：同一代理，请求 /umi.js（普通资源）带 Accept-Encoding: gzip 返回 Content-Encoding: gzip；而 SSE 响应带 no-transform 后不再被压缩。

顺带说明：X-Accel-Buffering: no 是 nginx 的概念，对 Express 代理无效；真正让压缩中间件退场的是 no-transform。

七、验证方法

不要靠"感觉"，用带时间戳的实测脚本验证流是否真的逐块到达：

import time, json, urllib.request

req = urllib.request.Request(url, data=body, method="POST", headers=auth_headers)
t0 = time.time()
with urllib.request.urlopen(req, timeout=120) as r:
 for raw in r: # 逐行读取，天然带到达时间信息
 line = raw.decode().strip()
 if line.startswith("data: "):
 ev = json.loads(line[6:])
 print(f"+{(time.time()-prev)*1000:6.0f}ms {ev['type']}")
 prev = time.time()

判读标准：事件间隔呈几十到几百毫秒的分布、且总耗时接近模型生成时长（而不是第一帧就 0ms、最后一帧才全部出现）→ 流式生效。

八、小结与后续优化

这套实现的三个关键决策，值得带走：

协议选 SSE：单向聊天场景下，比 WebSocket 少 90% 的复杂度，且代理友好；
stream_mode="messages" 让文本流与工具事件自动分离，Agent 的"思考-调用-作答"过程对前端透明化；
no-transform 是流式接口的"免死金牌"——任何中间件只要尊重标准，就不会吃掉你的流。

后续可选优化方向：

取消生成：加一个 AbortController + 后端取消信号（这需要双向通道，届时再考虑 WebSocket 或独立的 cancel 端点）；
工具事件可视化：前端把 tool 事件渲染成"正在检索知识库…“的步骤条；
Agent 状态持久化：用 LangGraph Checkpointer（SQLite/Postgres）替代内存 dict，跨请求保存 Agent 状态；
重连语义：SSE 标准支持 Last-Event-ID，可配合请求 ID 实现断线续传。

后端框架选型：Fastify / FastAPI / Spring Boot / Go 怎么选？

Tue, 30 Jun 2026 00:00:00 +0000

我在为一个小型信息管理 Web 项目做后端选型，候选有 Node.js (Fastify)、Python (FastAPI)、Java (Spring Boot)、Go (Gin)。为了不被"听说"带节奏，我读了两篇风格迥异的性能对比文章，把结论提炼出来，并给出针对这类项目的明确推荐。

先说结论：对小型信息管理系统，我会首选 Python (FastAPI)；如果团队是 JS/TS 背景，选 Fastify；只有当你在意单二进制部署或预期流量会快速增长时，才需要认真考虑 Go (Gin)。Spring Boot 对这个量级偏重，除非你本来就是 Java 栈。下面是依据。

一、第一篇：Travis Luong 的单机 wrk 基准测试

来源：FastAPI vs Fastify vs Spring Boot vs Gin Benchmark

这篇是相对"实验室"式的测试：每个框架写一个接口，从 PostgreSQL 查 100 行数据返回 JSON，用 wrk 压 10 秒。作者非常坦诚，多次更新修正了"进程数不对等"等测试缺陷。它的价值不在于绝对数字，而在于揭示了配置对性能的放大效应。

代表性排名（req/sec，摘自作者的最终榜单）：

排名	配置	req/sec
1	Spring Boot + jdbc（原生）	7886
2	Go + pgx	7517
3	Go + pg + 连接池调优	7388
4	FastAPI + asyncpg + ujson + gunicorn 8w	4831
5	Fastify + pg + cluster 8w（关日志）	4622
8	Express + pg + cluster 8w	4145
10	Gin + database/sql + lib/pq	2966
12	Fastify + pg（单进程）	2184
20	Spring Boot + JPA（ORM）	844

作者自己提炼的几点，比排名本身更值得记：

FastAPI 开箱并不快——必须配上 asyncpg 异步驱动才能发挥，光这一点就能拉开数倍差距。
即使用了 asyncpg，还要换更快的 JSON 库（orjson/ujson） 才能追上 Node.js。
原生 SQL 转 JSON 远快于 ORM——最直观的证据：同样是 Spring Boot，用 jdbc 是 7886，换成 JPA 直接掉到 844，差了近 10 倍。框架的"慢"往往来自 ORM 层，而不是框架本身。
编译型语言（Java/Go）在同等配置下确实比解释型快。
日志会拖性能——Fastify 关掉日志后明显提速。

一句话总结：这篇告诉我们"配置 > 选型"——同一个框架，会不会调，性能能差一个数量级。

二、第二篇：10 亿请求下的"生存测试"

来源：五大主流 Web 框架真实性能对比：10 亿请求下谁能幸存？

这篇更"生产化"：谷歌云 4 核 16G、Docker 部署、PostgreSQL 连接池，用 wrk2 把流量从 100 RPS 一路爬到 10 万 RPS，同时观察吞吐、延迟、内存、CPU、错误率。

核心数据：

框架	持续稳定 RPS	峰值内存	99% 延迟	CPU 峰值	错误率(10万RPS)
Rust (Actix-Web)	110,000	250 MB	7 ms	75%	0.01%
Go (Gin)	105,000	190 MB	10 ms	68%	0.03%
Node.js (Fastify)	60,000	650 MB	35 ms	82%	0.5%
Java (Spring Boot)	40,000	1.4 GB	50 ms	88%	0.3%
Python (FastAPI)	8,000	1.2 GB	150 ms	100%	15%

作者的"幸存者"分级：

绝对幸存者 —— Go (Gin)：性能、开发效率、生态三者最平衡，像"AK47"，易上手、耐造。
极限生存者 —— Rust (Actix)：性能天花板，但学习曲线陡，需专业团队。
主流生存者 —— Fastify / Spring Boot：覆盖大多数公司的常规战场。
限定生存者 —— FastAPI：仅在低并发"安全区"（< 1 万 RPS）表现良好，适合数据管道、AI 模型接口。

一句话总结：这篇把极限高并发的天花板拉了出来——系统级语言（Go/Rust）是降维打击，但前提是你真的有那么多流量。

三、两篇放在一起看

两篇文章结论高度一致，但视角互补：

性能天花板：Go ≈ Java(原生) > Node > Python。压到极限时，编译型语言的优势会随并发上升而放大。
资源效率：Go 最省（190MB），Java 最重（1.4GB + 启动 12 秒）。Python 在高并发下反而吃内存（1.2GB）且错误率飙升。
易用性 / 开发效率：恰好与性能排序相反——FastAPI 开发最快、自动文档最香，但抗并发最弱。

关键陷阱：别把高并发结论直接套到小项目上。 第二篇自己也写明，FastAPI 的"安全区"是 < 1 万 RPS——而一个小型信息管理系统，日常峰值大概率在几十到几百 RPS，离这个阈值有两个数量级。在这种流量下，框架本身的吞吐根本不是瓶颈，开发速度、可维护性、文档自动生成才是。

四、针对"小型信息管理系统"的推荐

信息管理系统的典型特征：以 CRUD 为主、中低并发、前后端分离、追求快速交付。这类项目的真正成本不在服务器，而在开发和对接的人力。所以选型权重应该是：开发效率 > 文档/对接 > 部署运维 > 极限性能。

按这个权重，决策如下：

你的情况	推荐	理由
想最快交付、要自动 API 文档给前端	FastAPI	类型提示 + 自动 OpenAPI 文档，信息管理系统的 CRUD 接口几乎"写模型即得文档"；<1万 RPS 安全区绰绰有余
团队是 JS/TS 背景，想前后端同语言	Fastify	比 Express 快、schema 校验内置，前后端类型可复用
追求单二进制部署、运维简单，或预期流量会涨	Go (Gin)	编译成一个可执行文件扔服务器即可，无运行时依赖；两篇文章里都是"绝对幸存者"，未来不会遇到性能墙
已有 Java 栈 / 复杂事务和权限	Spring Boot	生态最全，但启动慢、内存重，对小项目是"用航母运快递"

我的最终选择是 FastAPI。原因很实在：信息管理系统的价值在于"把数据管起来、把接口暴露清楚"，FastAPI 的 Pydantic 模型 + 自动文档把这两件事的成本压到了最低；性能上配 asyncpg + orjson（第一篇验证可到 ~4800 req/s）对小型系统完全是冗余的富余。等哪天流量真涨上来，再按第二篇的指引用 Go 重写核心接口，成本也可控——技术选型从来不是非黑即白，而是匹配当下的战场。

参考来源：

Travis Luong — FastAPI vs Fastify vs Spring Boot vs Gin Benchmark
51CTO — 五大主流 Web 框架真实性能对比：10 亿请求下谁能幸存？