LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. 新版 LangGraph 原生支持用數組同時訂閱多種流模式(如 stream_mode=["updates", "messages", "custom"]),不再需要去啃繁瑣難記的舊版事件過濾。
  2. 想要聊天框逐字打字機效果,開 stream_mode="messages":每次產出 (message_chunk, metadata),並且可以用 metadata["langgraph_node"] 精準過濾只把最終答覆節點的字推給用戶。
  3. 想要頂部步驟條顯示「剛跑完哪個節點」,開 stream_mode="updates"。
  4. 想在耗時工具函數內部主動往外報進度(比如「已抓取第 3/10 篇文檔」),開 stream_mode="custom",並在節點或工具裏調 get_stream_writer() 推送任意字典。

LangGraph 四種 stream_mode 對照

圖:本站根據 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 文檔 整理的示意圖

二、生產接流式時最常踩的三個坑

  1. 節點裏用了同步調用或非流式包裝導致整段一次性蹦出來:在異步 astream 模式下,節點內部請盡量使用異步的 await llm.ainvoke(...)。在 Python 3.11 及以上版本中,LangGraph 會自動攔截節點內部 ainvoke 的底層流分片餵給 "messages" 通道;如果在低版本 Python 遇到不逐字吐詞,顯式將 config: RunnableConfig 透傳進 await llm.ainvoke(..., config=config) 即可修復;
  2. 多 Agent 嵌套子圖期間流突然中斷幾秒沒動靜:當你的主圖把任務派給了嵌套子圖(寫法見 /guides/langgraph-multi-agent-supervisor-subgraph-guide)時,預設外層只發頂層節點事件。只需在 graph.astream(..., subgraphs=True) 加上 subgraphs=True,就能把子圖內部的進度和 Token 透傳出來;
  3. 前置 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: 判斷,就能天然過濾掉底層的工具參數拼裝碎片。

相關教學

參考資料

  • LangChain / LangGraph 官方文檔:Streaming — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多內容

  1. 01

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  2. 02

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  3. 03

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  4. 04

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  5. 05

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0
  6. 06

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  3. 03

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0
  6. 06

    CrewAI 入門教學:Agent 角色、Task 任務、執行流程(Process)與第一個團隊示例

    CrewAI 是主打「擬人化角色分工」的 Python 多智能體開源框架。本文按官方文檔講清安裝要求、Agent(角色/目標/背景)、Task(任務描述與預期輸出)和 Process(順序接力與經理層級模式)的配合邏輯,並給出最小可運行代碼。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~