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

圖:本站根據 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 與檢查點歷史(代碼級排錯)
當連線沒問題,但運行時大模型傳錯了參數或狀態字段被意外覆蓋時,最快的命令行調試辦法是打開流式輸出與狀態快照檢查:
stream_mode="updates":每跑完一個節點,只打印「這個節點剛剛往 State 裏返回了什麼增量」,最清爽易讀;stream_mode="debug":打印完整的內部調度任務 ID、節點輸入快照與異常堆棧,適合抓隱蔽的類型轉換報錯;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)

圖:本站根據 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 文件後本地服務會自動重新加載新節點邏輯,直接在網頁畫布開一個新線程測試即可。
相關教學
- /guides/langgraph-quickstart-install-first-graph:LangGraph Python 安裝與第一個狀態圖
- /guides/langgraph-mcp-integration-guide:LangGraph 接入 MCP 工具伺服器
- /guides/langgraph-local-model-ollama-guide:LangGraph 對接本地 Ollama 離線調試
- /guides/openai-agents-sdk-guardrails-tracing:智能體護欄與鏈路追蹤對比
參考資料
- LangChain / LangGraph 官方文檔:Studio 與 Visualization — https://docs.langchain.com/
langchain-ai/langgraph官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph
0 條評論
還沒有評論,來搶沙發~