适用人群：

• 使用 LangGraph / LangChain
• 本地 Ollama（qwen2.5 / llama）
• Debian / Ubuntu / testing / unstable
• 想把 LangGraph 流程 导出为 PNG 图片

---

一、教程目标

完成本教程后，你将能够：

• ✅ 正确运行 LangGraph Agent
• ✅ 正确生成 ASCII / Mermaid / PNG 图
• ✅ 理解 Graphviz / dot / libgraphviz-dev 的真实区别
• ✅ 避免 Debian 系统中最常见的 Graphviz 依赖大坑
• ✅ 明白「哪些方案是走投无路时才尝试的」

---

二、环境说明（非常重要）

本文环境为 真实踩坑环境，而不是“理想干净系统”：

• Debian 12
• testing / unstable（存在混源）
• Python ≥ 3.10
• Ollama 已安装
• graphviz 未预装

---

三、第一步：准备 Python 依赖

1️⃣ 安装 Python 包

pip install -U \
  langgraph \
  langchain \
  langchain-core \
  langchain-ollama

⚠️ 注意：
此时不需要安装 pygraphviz，也不需要装 libgraphviz-dev

---

四、第二步：编写 LangGraph 示例代码

将下面代码保存为 langgraph_demo.py

from typing import Annotated
from typing_extensions import TypedDict

from langchain_core.messages import HumanMessage, AnyMessage
from langchain_core.tools import tool
from langchain_ollama import ChatOllama

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition


# =========================
# 1. 状态定义
# =========================
class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]


# =========================
# 2. 工具定义
# =========================
@tool
def multiply(a: int, b: int) -> int:
    """将两个整数相乘"""
    return a * b


tools = [multiply]
tool_node = ToolNode(tools)


# =========================
# 3. LLM（Ollama）
# =========================
llm = ChatOllama(
    model="qwen2.5:7b",
    temperature=0,
)

model_with_tools = llm.bind_tools(tools)


# =========================
# 4. Agent 节点
# =========================
def agent(state: State):
    response = model_with_tools.invoke(state["messages"])
    return {"messages": [response]}


# =========================
# 5. 构建 LangGraph
# =========================
builder = StateGraph(State)

builder.add_node("agent", agent)
builder.add_node("tools", tool_node)

builder.add_edge(START, "agent")
builder.add_conditional_edges(
    "agent",
    tools_condition,
    {"tools": "tools", END: END},
)
builder.add_edge("tools", "agent")

graph = builder.compile()


# =========================
# 6. 图可视化
# =========================
print("=== ASCII ===")
print(graph.get_graph().draw_ascii())

print("\n=== Mermaid ===")
print(graph.get_graph().draw_mermaid())

print("\n=== PNG ===")
try:
    png_bytes = graph.get_graph().draw_png()
    with open("langgraph.png", "wb") as f:
        f.write(png_bytes)
    print("✅ 已生成 langgraph.png")
except Exception as e:
    print(f"PNG 生成失败（可忽略）：{e}")


# =========================
# 7. 执行测试
# =========================
input_messages = {
    "messages": [
        HumanMessage(content="请计算 12345 * 54321，并解释步骤")
    ]
}

for step in graph.stream(input_messages, stream_mode="values"):
    step["messages"][-1].pretty_print()

---

五、第三步：第一次运行（必然失败）

python langgraph_demo.py

你将看到类似输出：

PNG 生成失败（可忽略）：Program dot not found in path.

解释（非常关键）

• LangGraph 的 PNG 导出
• 本质是调用系统命令：dot
• 当前系统中 没有 Graphviz

---

六、第四步：错误做法（真实踩坑过程）

❌ 错误尝试 1：直接安装 libgraphviz-dev

sudo apt install libgraphviz-dev

真实报错如下（必须贴出来，很多人就是卡在这里）：

无法满足的依赖关系：
 libgraphviz-dev : 依赖: libpathplan4 (= 2.42.2-7+deb12u1)
                   但是 2.42.4-3 正要被安装
                   依赖: libxdot4 (= 2.42.2-7+deb12u1)
                   但是它将不会被安装
                   依赖: liblab-gamut1 (= 2.42.2-7+deb12u1)
                   但是 2.42.4-3 正要被安装
                   依赖: libgvc6-plugins-gtk (= 2.42.2-7+deb12u1)
                   但是它将不会被安装

👉 原因：
系统中已有 graphviz 2.42.4
而 libgraphviz-dev 强制锁死 2.42.2

---

❌ 错误尝试 2：手动指定旧版本依赖（高风险）

sudo apt install \
  libpathplan4=2.42.2-7+deb12u1 \
  libxdot4=2.42.2-7+deb12u1 \
  liblab-gamut1=2.42.2-7+deb12u1 \
  libgvc6-plugins-gtk=2.42.2-7+deb12u1

⚠️ 说明：

• 在 stable 单源 环境下可能成功

• 在 testing / unstable / 混源环境下：

  • 极易失败
  • 或强制降级大量系统库

👉 不推荐在宿主机使用

---

❌ 错误尝试 3：使用 aptitude 自动解决

sudo apt install aptitude
sudo aptitude install libgraphviz-dev

aptitude 通常会给出：

• 降级方案
• 移除 GTK / graphviz 组件

👉 对非容器环境风险极高

---

七、核心真相：你根本不需要 libgraphviz-dev

LangGraph PNG 的真实依赖链

LangGraph → graphviz → dot → PNG

各包真实用途对照表

包名	是否需要	用途
graphviz	✅ 必须	提供 dot
libgraphviz-dev	❌ 不需要	C/C++ 开发
pygraphviz	❌ 非必须	可选 Python 绑定
libpathplan4	❌ 不应手动装	内部依赖

---

八、第五步：正确且唯一推荐的做法 ✅

安装 graphviz（不是 -dev）

sudo apt update
sudo apt install graphviz
pip install pygraphviz

验证：

dot -V

输出示例：

dot - graphviz version 2.42.4

---

九、第六步：再次运行脚本（成功）

python langgraph_demo.py

输出：

✅ 已生成 langgraph.png

打开图片：

xdg-open langgraph.png

---

十、常见疑问解答

Q1：终端里为什么不显示图片？

终端不支持渲染 PNG，只能保存文件。

Q2：Jupyter 可以直接显示吗？

可以，用 IPython.display.Image

Q3：一定不能装 libgraphviz-dev 吗？

只有你 要用 C/C++ 编译 Graphviz 时才需要。

---

十一、最终总结（一定要看）

一句话总结

LangGraph 导出 PNG 失败 ≠ Python 问题
≠ LangGraph 问题
≠ 模型问题
而是 Graphviz 安装方式错误

牢记三点

• ✅ 只装 graphviz
• ❌ 不装 libgraphviz-dev
• ❌ 不强制降级系统库