结论先说
- 新版 LangGraph 原生支持用数组同时订阅多种流模式(如
stream_mode=["updates", "messages", "custom"]),不再需要去啃繁琐难记的旧版事件过滤。 - 想要聊天框逐字打字机效果,开
stream_mode="messages":每次产出(message_chunk, metadata),并且可以用metadata["langgraph_node"]精准过滤只把最终答复节点的字推给用户。 - 想要顶部步骤条显示「刚跑完哪个节点」,开
stream_mode="updates"。 - 想在耗时工具函数内部主动往外报进度(比如「已抓取第 3/10 篇文档」),开
stream_mode="custom",并在节点或工具里调get_stream_writer()推送任意字典。

图:本站根据 LangGraph 官方文档 Streaming 整理的示意图
本文根据 LangChain / LangGraph 官方文档《Streaming》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。
适用于谁
- 搜「langgraph 流式输出」「langgraph stream_mode messages」「langgraph 怎么逐字返回」的前后端开发者;
- 用
graph.invoke()跑多节点智能体时前端转圈等待超过十秒,想做成一边显示「正在查库…」、一边逐字蹦出最终答复的工程师; - 搞不清新版原生
stream_mode="messages"和早期astream_events该用哪个、或者遇到内部路由节点把丑陋 JSON 也直接推上前端屏幕的人。
如果你熟悉单次直接调底层接口的流式写法(可对照 /guides/openai-api-streaming 与 /guides/claude-api-streaming),会发现状态图的难点在于同时流式传递「图走到哪一步了」和「当前模型吐到哪个字了」。
一、一段代码同时打通「工具内部进度 + 节点切换 + 逐字输出」
假设我们的状态图(基础结构见 /guides/langgraph-quickstart-install-first-graph)包含一个「内部意图分类节点」和一个「对外答复节点」。我们既不想让分类节点的中间 JSON 露在用户屏幕上,又想在慢工具运行期间实时汇报百分比进度:
python
import asyncio
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.config import get_stream_writer
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition
@tool
async def batch_sync_records(batch_name: str) -> str:
"""批量校验归档数据记录。"""
# 在工具内部直接获取写入器,主动向前端推送自定义进度
writer = get_stream_writer()
for step in (30, 70, 100):
await asyncio.sleep(0.3)
writer({"stage": "syncing", "batch": batch_name, "percent": step})
return f"批次 {batch_name} 共 120 条记录核验无误"
tools = [batch_sync_records]
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)
async def responder_node(state: MessagesState):
res = await llm.ainvoke(state["messages"])
return {"messages": [res]}
builder = StateGraph(MessagesState)
builder.add_node("responder", responder_node)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "responder")
builder.add_conditional_edges("responder", tools_condition)
builder.add_edge("tools", "responder")
graph = builder.compile()
async def main():
# 当传入列表订阅多路模式时,每次迭代返回 (mode_name, payload) 二元组
async for mode, chunk in graph.astream(
{"messages": [("user", "请校验批次 B2026 的数据并总结")]},
stream_mode=["custom", "updates", "messages"],
):
if mode == "custom":
print(f"\n[实时进度] {chunk}")
elif mode == "updates":
finished_nodes = list(chunk.keys())
print(f"\n[节点流转] 刚完成节点: {finished_nodes}")
elif mode == "messages":
msg_chunk, meta = chunk
# 关键过滤:只渲染 responder 节点的文本分片,忽略空内容与工具入参分片
if meta.get("langgraph_node") == "responder" and msg_chunk.content:
print(msg_chunk.content, end="", flush=True)
if __name__ == "__main__":
asyncio.run(main())
把上面三个 if / elif 分支包装成 FastAPI 的 StreamingResponse(按 SSE event: token、event: progress 格式发给浏览器),就是一套体验非常完整的现代 AI 助手流式接口。

图:本站根据 LangGraph 官方 Streaming 文档 整理的示意图
二、生产接流式时最常踩的三个坑
- 节点里用了同步调用或非流式包装导致整段一次性蹦出来:在异步
astream模式下,节点内部请尽量使用异步的await llm.ainvoke(...)。在 Python 3.11 及以上版本中,LangGraph 会自动拦截节点内部ainvoke的底层流分片喂给"messages"通道;如果在低版本 Python 遇到不逐字吐词,显式将config: RunnableConfig透传进await llm.ainvoke(..., config=config)即可修复; - 多 Agent 嵌套子图期间流突然中断几秒没动静:当你的主图把任务派给了嵌套子图(写法见 /guides/langgraph-multi-agent-supervisor-subgraph-guide)时,默认外层只发顶层节点事件。只需在
graph.astream(..., subgraphs=True)加上subgraphs=True,就能把子图内部的进度和 Token 透传出来; - 前置 Nginx 反向代理把流攒在缓冲区:后端代码明明写了
flush,网页还是等五秒才蹦一大段,九成是被网关缓存了——记得在响应头加上X-Accel-Buffering: no与Cache-Control: no-cache。
平时前后端联调 SSE 流式解析协议、借助 Claude 排查异步协程阻塞点时,个人官方订阅说明也可参考 /chongzhi/claude-pro。
常见问题
Q:那以前教程里写的 graph.astream_events(..., version="v2") 还能用吗?
依然可以使用,它属于来自 langchain_core 的通用底层回调流。但对于纯 LangGraph 项目,原生 stream_mode=["messages", "updates", "custom"] 返回的结构干净得多,而且天生支持 get_stream_writer() 自定义业务进度,新写代码建议直接用原生 stream_mode。
Q:同一张图里有三个不同的大模型节点,怎么防止内部思考节点的草稿暴露给前端用户?
除了上面代码演示的检查 meta.get("langgraph_node") == "对外节点名" 之外,你也可以在初始化内部路由所用的模型实例时加上标签(如 ChatOpenAI(..., tags=["internal_router"])),在前端推送层遇到带该标签的分片直接跳过即可。
Q:用户在网页端点了「停止生成」按钮,后端正在流式运行的状态图怎么及时中止?
在 FastAPI 等异步服务框架中,当检测到客户端断开 SSE 连接(await request.is_disconnected())或收到取消信号时,直接跳出 async for ... in graph.astream(...) 循环或取消对应的异步 Task 即可。只要编译时挂载了检查点保存器,前一个已经跑完的完整节点状态依然会安全留在库里,不会造成脏数据损坏。
Q:开启 "messages" 逐字流后,大模型发起工具调用的参数 JSON 也会被拆碎吐出来吗?
会的,模型生成工具调用入参时同样会产生带 tool_call_chunks 属性的消息分片,而此时文本字段 msg_chunk.content 通常为空字符串。因此前端只展示文字对话时,务必加上 if msg_chunk.content: 判断,就能天然过滤掉底层的工具参数拼装碎片。
相关教程
- /guides/langgraph-quickstart-install-first-graph:LangGraph Python 安装与第一个状态图
- /guides/langgraph-multi-agent-supervisor-subgraph-guide:LangGraph 多智能体与
subgraphs=True嵌套实战 - /guides/openai-api-streaming:OpenAI API 原生流式输出处理指南
- /guides/claude-api-streaming:Claude API 流式响应事件详解
参考资料
- LangChain / LangGraph 官方文档:Streaming — https://docs.langchain.com/
langchain-ai/langgraph官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph
0 条评论
还没有评论,来抢沙发~