如何将LangChain的RAG结果通过Web界面流式返回?

文章导读
遇到 RAG 结果在网页里“一次性等到所有内容”,我一般不会先翻前端代码。因为流式链路断掉的点通常在后端:要么链的末端不是语言模型,要么模型没有开 streaming。先把这两件事确认完,再决定改哪端。
📋 目录
  1. 一 先确认链路末端是什么
  2. 二 容易出错的地方:实例化参数与 bind 方法
  3. 三 建议的端点封装方式:FastAPI 与 SSE
  4. 四 检索过程要不要一起流式返回
  5. 五 验证步骤、回滚边界与后续维护
A A

遇到 RAG 结果在网页里“一次性等到所有内容”,我一般不会先翻前端代码。因为流式链路断掉的点通常在后端:要么链的末端不是语言模型,要么模型没有开 streaming。先把这两件事确认完,再决定改哪端。

一个最直接的判断方法是查看你的 RAG 链路的末端是否是一个语言模型。LangChain 的 `RunnableSequence` 只有在最后一个 `Runnable` 支持流式输出时,整体 `stream()` 才会返回 token 流。如果你的链最后接的是 `Retriever` 或者自定义函数,`stream()` 往往只会输出一个完整结果。因此,在设计之初就要把检索和生成拆开:先执行 `invoke` 得到上下文,再对 `LLM` 链调用 `stream`。否则,前端拿到的就是一次性 JSON,而不是增量 token。

使用 LangChain 的 `ChatOpenAI` 或 `ChatAnthropic` 时,必须在实例化时显式开启 `streaming=True`。如果你的模型是通过 `langchain` 的 `init_chat_model` 加载,也需要在参数中传入 `streaming=True`,否则 `chain.stream()` 会退化为普通 `invoke` 的行为。一个常见的坑是:在 `RunnableSequence` 里对 `model` 加 `bind(stop=...)` 会导致部分版本失去流式能力,验证方法是直接在模型上调用 `model.stream("你好")`,看能否逐字返回。如果这一步就失败,问题不在前端,而在模型配置。

先确认链路末端是什么

一个最直接的判断方法是查看你的 RAG 链路的末端是否是一个语言模型。LangChain 的 RunnableSequence 只有在最后一个 Runnable 支持流式输出时,整体 stream() 才会返回 token 流。如果你的链最后接的是 Retriever 或者自定义函数,stream() 往往只会输出一个完整结果。因此,在设计之初就要把检索和生成拆开:先执行 invoke 得到上下文,再对 LLM 链调用 stream。否则,前端拿到的就是一次性 JSON,而不是增量 token。

这个判断方法帮我省过不少时间。很多人把检索器和模型串在一个 chain 里,然后直接对 chain 调 stream,以为这样就是流式。实际上,如果链最后一步是 Retriever 或工具函数,流式输出不会发生。稳妥的顺序是先让检索器返回上下文,再单独构造 LLM 链。这样前端可以收到两种信息:检索完成事件和生成 token。

如何将LangChain的RAG结果通过Web界面流式返回?

容易出错的地方:实例化参数与 bind 方法

使用 LangChain 的 ChatOpenAI 或 ChatAnthropic 时,必须在实例化时显式开启 streaming=True。如果你的模型是通过 langchain 的 init_chat_model 加载,也需要在参数中传入 streaming=True,否则 chain.stream() 会退化为普通 invoke 的行为。一个常见的坑是:在 RunnableSequence 里对 model 加 bind(stop=...) 会导致部分版本失去流式能力,验证方法是直接在模型上调用 model.stream("你好"),看能否逐字返回。如果这一步就失败,问题不在前端,而在模型配置。

我现场排查时,会直接在 Python 交互环境跑一下 model.stream("你好")。如果返回的是单个完整字符串,说明模型配置问题;如果能逐字返回,再回头查 chain 的组装。另一个容易忽略的地方是:在 chain 中如果对 model 添加了 bind(stop=...),需要意识到这可能让部分版本的 stream 退化。尽量把 stop 序列用其他方式控制,或者验证后再挂。

建议的端点封装方式:FastAPI 与 SSE

在 FastAPI 中,推荐用 StreamingResponse 或 EventSourceResponse 来封装生成器。生成器内部需要用 asyncio 的方式进行异步流式,保证每个 token 通过 yield f"data: {token}\n\n" 推给前端。注意,SSE 要求使用 text/event-stream 媒体类型,并且生成器必须先发送一个 retry: 3000 的消息来让客户端自动重连。如果你直接 return StreamingResponse(generator),客户端断开时生成器不会自动停止,需要监听 disconnect 事件并调用 aclose()。否则,一条断开的连接会占用一个异步任务直到超时。

StreamingResponse 足够处理简单场景。需要区分消息类型时,可以把 data 内容做成 JSON,前端用 type 字段判断。另外,SSE 连接通常要处理心跳。如果前后端之间有一层 Nginx,注意关闭缓冲,否则 token 会攒到一定量才发送。

检索过程要不要一起流式返回

如果你希望网页先显示“正在抓取文档”,再把答案流式打出来,就需要把检索从 chain 里拿出来单独执行。可以在生成器里先调用 retriever.invoke(query),把命中文档通过 type 为 source 的消息推给前端,然后再进入 LLM 的 stream。否则,一个封装好的 chain 只会在生成阶段产出 token,中间的检索状态不会自动暴露。这样设计会带来两个额外问题:一是前端需要处理两种消息类型,二是后端要管理好取消逻辑。我建议先保持两步独立,跑通后再考虑封装。

如何将LangChain的RAG结果通过Web界面流式返回?

一个可用的接口简化写法是:

return StreamingResponse(generator(), media_type="text/event-stream")

这里的 generator() 必须是异步生成器函数,并且内部要负责发送 retry 消息和监听 disconnect。不要忘记把 Cache-Control: no-cache 加到响应头,避免本地代理缓冲。

验证步骤、回滚边界与后续维护

验证时,我通常先用 curl 看原始响应,而不是打开浏览器。命令行执行 curl -N http://127.0.0.1:8000/stream?q=... 观察是否逐字出现。如果 curl 能流式输出而浏览器不行,问题大概率在前端事件解析;如果 curl 也一次性返回,问题还是在后端链路。

风险方面,这条改动涉及后端接口返回类型变化和前端事件处理。如果临时要回滚,建议在后端保留一个非流式的同名接口,前端通过 Accept 头或查询参数切换。这样不需要同时发版。后续维护要注意:模型升级、LangChain 版本升级都会影响 stream 的行为,特别是 bind 和 structured output 相关参数。可以在自动化测试里加一条极短的请求,断言返回内容不是一次性 JSON。