LangGraph 怎麼可視化與調試:Mermaid 導出、debug 流式日誌與 LangGraph Studio 用法

搜「langgraph 如何可視化」和「如何 debug」有三套官方方法:導出 Mermaid 結構圖、開 stream_mode="debug" 看節點狀態增量,以及運行 langgraph dev 免 Docker 打開 Studio 單步調試。

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

結論先說

  1. 只看圖連沒連對(靜態可視化):編譯後直接調 graph.get_graph().draw_mermaid() 拿純文本流程圖,或調 draw_mermaid_png() 直接存成 PNG 圖片。
  2. 在命令行快速查錯(輕量 Debug):把 graph.invoke(...) 換成 graph.stream(..., stream_mode="debug"),終端會按步打印每個節點的進入、工具入參和返回的狀態字典。
  3. 重度排錯與中途改狀態重跑(圖形化 Studio):安裝 langgraph-cli[inmem] 後運行 langgraph dev,無需安裝 Docker 就能在瀏覽器裏打開 LangGraph Studio,實時看節點高亮、加斷點攔截並回放歷史檢查點。
  4. 注意斷網環境的小細節:draw_mermaid_png() 預設會把圖結構發給外部 mermaid.ink 接口生成圖片;內網保密項目請改用純本地字符串導出 draw_mermaid()。

LangGraph 三種可視化與調試手段

圖:本站根據 LangGraph 官方文檔 Studio 與 Visualization 整理的示意圖

本文根據 LangChain / LangGraph 官方可視化與 LangGraph Studio 文檔整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 官方網站。

適用於誰

  • 搜「langgraph 如何可視化」「langgraph 如何 debug」「langgraph studio 怎麼用」的人;
  • 剛把幾個節點和條件邊連起來(基礎寫法見 /guides/langgraph-quickstart-install-first-graph),結果運行時走錯分支或卡在循環裏,光看最後一句返回根本不知道中間哪一步出了錯的開發者;
  • 以為用 LangGraph Studio 必須先裝厚重的 Docker Desktop、想知道怎麼純本地輕量跑起來的人。

一、第一層:兩行代碼導出靜態拓撲圖(核對連線邏輯)

寫完 add_edge 和 add_conditional_edges 後,甚至不需要消耗任何大模型 Token,就能先把編譯後的圖畫出來肉眼檢查「有沒有孤島節點」「條件邊虛線是不是指到了預期分支」。

python
# 假設 graph = builder.compile() 已經編譯完成

# 做法 A:純離線輸出 Mermaid 語法字符串(可貼進 Markdown、GitHub PR 或 VS Code 預覽)
mermaid_code = graph.get_graph().draw_mermaid()
print(mermaid_code)

# 做法 B:直接把流程圖儲存為本地 PNG 文件(預設需聯網調 Mermaid.ink)
png_bytes = graph.get_graph().draw_mermaid_png()
with open("my_graph.png", "wb") as f:
    f.write(png_bytes)

在導出的圖裏,實線箭頭代表無條件固定跳轉(add_edge),虛線箭頭代表條件分支(add_conditional_edges)。如果你在圖裏嵌套了子圖(Subgraph),還可以傳入 xray=True(即 graph.get_graph(xray=True))把子圖內部的節點一併展開顯示。

二、第二層:終端 stream_mode 與檢查點歷史(代碼級排錯)

當連線沒問題,但運行時大模型傳錯了參數或狀態字段被意外覆蓋時,最快的命令行調試辦法是打開流式輸出與狀態快照檢查:

  1. stream_mode="updates":每跑完一個節點,只打印「這個節點剛剛往 State 裏返回了什麼增量」,最清爽易讀;
  2. stream_mode="debug":打印完整的內部調度任務 ID、節點輸入快照與異常堆棧,適合抓隱蔽的類型轉換報錯;
  3. graph.get_state_history(config):只要編譯時掛了檢查點儲存器(如 InMemorySaver),跑完後就能傳入同一個 thread_id 遍歷每一步的歷史快照,看清第 2 步和第 3 步之間 State 字段到底是怎麼變的。
python
for event in graph.stream(
    {"messages": [("user", "查一下庫存並生成補貨建議")]},
    stream_mode="updates",
):
    for node_name, state_patch in event.items():
        print(f"=== 剛執行完節點: {node_name} ===")
        print(state_patch)

用 langgraph dev 啟動本地 Studio

圖:本站根據 LangChain 官方文檔 LangGraph Studio 整理的示意圖

三、第三層:用 langgraph dev 打開 LangGraph Studio(交互式斷點與時間旅行)

早期版本的 Studio 桌面客戶端依賴 Docker 容器構建,現在官方提供了純 Python 內存運行模式,幾分鐘就能搭起來。

第一步:安裝帶內存模式的 CLI

在你的項目虛擬環境裏執行:

bash
pip install -U "langgraph-cli[inmem]"

第二步:在項目根目錄放一份最小 langgraph.json

假設你的狀態圖定義在 src/agent.py 文件裏,編譯後的圖變量名叫 graph(注意:交給 Studio 運行的圖變量在 builder.compile() 裏不要自己傳 checkpointer,本地伺服器會自動掛載持久化層):

json
{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./src/agent.py:graph"
  },
  "env": ".env"
}

第三步:啟動本地熱重載調試並打開畫布

在根目錄終端敲:

bash
langgraph dev

終端會啟動本地開發伺服器(預設地址 http://127.0.0.1:2024),並直接打印出一行指向網頁端 Studio 畫布的本地連接地址。用瀏覽器打開後,你可以做三件純命令行很難做的事:

  • 實時點亮執行路徑:發一條測試輸入,看着畫布上的節點隨着推理和工具調用逐個變亮(包括通過 MCP 掛載的外部工具節點,配置見 /guides/langgraph-mcp-integration-guide);
  • 加前置斷點(Interrupt):在危險寫操作節點前勾上斷點,圖跑到此處會自動掛起等你點確認;
  • 在線改狀態與時間旅行(Fork / Replay):如果第 4 步大模型理解偏了,不用從第 1 步重跑燒前序額度,直接點開第 3 步的快照手動改掉裏面那句消息或業務變量,從第 3 步分叉繼續往後跑。

在本地零成本反覆驗證調試鏈路時,你也可以把節點臨時切到本機離線模型(見 /guides/langgraph-local-model-ollama-guide),或者對比其他 SDK 的追蹤面板思路(見 /guides/openai-agents-sdk-guardrails-tracing)。日常配合網頁端 Claude 或 ChatGPT 分析長報錯堆棧時,個人訂閱方案說明可參考 /chongzhi/claude-pro。

常見問題

Q:打開終端給的 Studio 網頁連結提示連不上本地 127.0.0.1:2024 怎麼辦?

部分私隱增強瀏覽器(如 Safari 或開啟了嚴格本地網絡攔截的瀏覽器)會阻止公網 HTTPS 前端頁面直接請求本機迴環 HTTP 端口。優先換成 Chrome 打開該連結,或按官方 CLI 提示附加支持隧道的參數重新啟動。

Q:在 Studio 裏改了本地 .py 源碼,需要關掉 langgraph dev 重啟嗎?

不需要。langgraph dev 預設開啟了文件監聽熱重載(Hot Reload),儲存 Python 文件後本地服務會自動重新加載新節點邏輯,直接在網頁畫布開一個新線程測試即可。

相關教學

參考資料

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

Nathaniel 的更多內容

  1. 01

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

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

    其他 AI 工具0
  2. 02

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

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

    其他 AI 工具0
  3. 03

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

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

    其他 AI 工具0
  4. 04

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

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

    其他 AI 工具0
  5. 05

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

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

    其他 AI 工具0
  6. 06

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

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

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

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

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

    Claude其他 AI 工具0
  2. 02

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

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

    Claude其他 AI 工具0
  3. 03

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

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

    Claude其他 AI 工具0
  4. 04

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

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

    Gemini其他 AI 工具0
  5. 05

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

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

    ChatGPT其他 AI 工具0
  6. 06

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

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

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~