LangGraph 多智能体架构深度解析:DeepDiagram 如何实现实时 AI 绘图
LangGraph 多智能体架构深度解析:DeepDiagram 如何实现实时 AI 绘图
DeepDiagram 是一款开源的 AI 可视化绘图工具,它利用 LangGraph 多智能体编排,将一句自然语言实时转化为思维导图、Mermaid 图表、ECharts 统计图与 Draw.io 架构图。本文将用通俗的方式拆解它的后端架构:从请求进入 FastAPI 开始,到 LangGraph 状态图中"路由器"节点如何挑选智能体,再到 SSE 事件流如何把每一个 token 实时推送到浏览器画布,让你理解实时 AI 绘图背后的完整链路。
一、整体架构:三个模块各司其职
在深入 LangGraph 之前,先看 DeepDiagram 的整体布局。整个项目由三大块组成:
| 模块 | 技术栈 | 职责 |
|---|---|---|
后端 backend/ |
FastAPI + LangGraph + PostgreSQL | 智能体编排、LLM 调用、会话存储 |
前端 frontend/ |
React + TypeScript + Vite | 对话面板、SSE 事件消费、图表实时渲染 |
官网 website/ |
Next.js | 介绍页、文档与博客 |
依赖清单(pyproject.toml)中能看到核心引擎:
langgraph>=1.0.4:多智能体状态图编排fastapi>=0.124.0:HTTP 与 SSE 流式接口sqlmodel+asyncpg:会话与消息的异步持久化
上面这张图展示了多智能体系统的精髓:用户在第二句话输入 @mermaid 用 timeline 复原这个图,路由器把请求从 mindmap 智能体"移交"给 mermaid 智能体,上一轮生成的内容被自动带入上下文,直接转换输出——这正是后文要讲的"上下文感知路由"。
二、LangGraph 状态图:多智能体编排的骨架
2.1 定义共享状态
所有智能体共享一份状态,定义在 state.py:
class AgentState(TypedDict):
messages: Annotated[List[Any], operator.add] # 消息累积
active_agent: Optional[str] = None
intent: Optional[str] = None
model_config: Optional[Dict[str, str]] = None
两个设计值得注意:
Annotated[..., operator.add]:LangGraph 的 reducer 机制,节点返回新消息时会自动"追加"而非覆盖历史,天然支持多轮对话;intent字段:由路由器写入、被条件边读取,是整张图的"调度信号"。
2.2 组装一张"星型"图
图的实际组装只有几十行,全部在 graph.py 中完成:
- 节点:1 个
router入口节点 + 7 个智能体节点(mindmap_agent、flow_agent、mermaid_agent、charts_agent、drawio_agent、infographic_agent、general_agent) - 边:
router通过add_conditional_edges连接条件路由函数route_decision,根据intent把请求分发给对应智能体;每个智能体节点执行完直接连END
这种"星型拓扑"(一个路由节点 + N 个末端智能体)是 LangGraph 中处理"意图分类 + 专家执行"场景的经典模式:结构扁平、易扩展——新增一种图表类型,只需要加一个节点和一条边。
三、路由器节点:@ 快捷路由 + LLM 意图识别双通道
dispatcher.py 中的 router_node 是整个系统的"大脑",它用双通道策略决定请求去向。
3.1 通道一:@ 显式路由(零 LLM 成本)
用户在输入框键入 @mindmap、@chart 等关键词时,直接命中映射表(dispatcher.py):
@mindmap → mindmap
@flow → flowchart
@mermaid → mermaid
@chart → charts
@drawio → drawio
@infographic → infographic
命中后会用正则把关键词从原句中擦除,再交给下游智能体——这样智能体看到的提示词是干净的,且整个过程不需要调用 LLM,毫秒级完成。这也是为什么前端输入框提示"Type @ to select agent"。
3.2 通道二:LLM 意图分类(带上下文感知)
没有显式标记时,路由器会构造一个精心设计的 Prompt,让 LLM 只输出一个意图关键词。它的"聪明"来自三类上下文注入:
- 历史执行轨迹:从对话历史中提取所有
### Execution Trace:块(dispatcher.py),让路由器知道上一轮用了哪个智能体、调用了什么"工具"; - 最后活跃智能体:通过正则
agentName:找到最近一次执行者(dispatcher.py),并写入规则——若用户请求是"继续、修复、微调",优先沿用上一位智能体; - 画布视觉上下文规则:例如"当前画布是 Chart 且用户说修改数据 → 必须路由到 charts"(dispatcher.py),保证"在图上加个节点"这类修改指令不会跑错智能体。
route_decision 函数(dispatcher.py)最后把意图字符串映射到图节点名,兜底一律落到 general_agent 处理闲聊,确保任何输入都有出口。
四、七个智能体:各守一域的"专家系统"
每个智能体都是一个"节点函数",结构高度统一,以思维导图智能体 mindmap.py 为例,核心就三步:
- 从历史中提取当前图代码(
extract_current_code_from_messages),支持"在现有图上修改"; - 拼装专属 System Prompt:思维导图智能体的提示词要求 LLM 扮演"知识架构师",输出 4~5 层深度、按
#/##/-层级组织的 Markmap Markdown; llm.astream流式生成,返回给状态图。
所有绘图类智能体的输出都遵循统一的双标签协议:
<design_concept>设计思路:1~3 句话说明如何组织这张图</design_concept>
<code>图表代码(Markdown / Mermaid / JSON / ECharts / Draw.io XML)</code>
这个约定是前后端协作的关键——前端正是靠这两个标签把"思路"和"可执行代码"分开发送、分别渲染。
七个智能体及产出格式一览:
| 智能体 | 源码 | 输出格式 | 擅长场景 |
|---|---|---|---|
| Mindmap | mindmap.py | Markmap Markdown | 脑暴、知识梳理 |
| Flow | flow.py | React Flow JSON | 标准流程图 |
| Mermaid | mermaid.py | Mermaid 语法 | 时序图、甘特图、ERD |
| Charts | charts.py | ECharts 配置 | 统计、趋势数据 |
| Draw.io | drawio.py | Draw.io XML | 云架构、复杂 UML |
| Infographic | infographic.py | 信息图 | 数据海报、可视化叙事 |
| General | general.py | 纯文本 | 问候、闲聊、问答 |
五、实时 AI 绘图的关键:SSE 事件流逐块推送
"实时"二字全部由 routes.py 中的 event_generator 兑现。该函数监听 LangGraph 的 astream_events,把底层事件翻译成一套面向前端的 SSE 事件协议:
| SSE 事件 | 含义 |
|---|---|
session_created |
新会话已建立 |
agent_selected |
路由器选定智能体(前端立刻高亮"Active Agent") |
design_concept_start / design_concept / design_concept_end |
设计思路流式输出 |
tool_start / tool_code / tool_end |
图表代码逐块流式输出 |
agent_end |
智能体执行完成 |
error |
异常上报 |
5.1 流式标签解析器:边收边拆
难点在于 <design_concept> 和 <code> 标签会横跨多个 token 片段(比如一个标签可能被切成三块到达)。StreamingTagParser 用一个四状态机(INIT → DESIGN_CONCEPT → CODE → DONE)维护缓冲区:每次 feed(chunk) 追加到 buffer、扫描标签位置、只把新增部分作为事件吐出。效果是 LLM 吐出每个 token 的同一毫秒,前端就能收到对应片段。
5.2 健壮性细节
- 容错落盘:即使连接中断,
finally块会用asyncio.shield保存已生成的部分内容(routes.py); - Draw.io XML 消毒:
sanitize_drawio_xml自动移除会导致解析失败的<Array>元素(routes.py); - 整轮解析失败兜底:若流式解析器没提取到代码,回退用正则对完整响应做一次全量提取(routes.py)。
六、前端:把事件流变成会"生长"的画布
前端 ChatPanel.tsx 用 switch 逐个消费 SSE 事件:agent_selected 点亮右侧"Active Agent"徽章,design_concept 事件滚动输出设计思路,tool_code 事件驱动画布区边生成边渲染——流程图节点逐个出现、思维导图分支逐条展开。
各图表类型由独立组件负责渲染:CanvasPanel.tsx 统一调度,frontend/src/components/agents/ 目录下每个智能体对应一个渲染组件(如 ChartsAgent.tsx 解析 ECharts 配置、DrawioAgent.tsx 内嵌 Draw.io 编辑器)。右侧对话区还内置 Process Trace 面板,把 agent_select、Design Concept、Calling: create_xxx、Result 四步轨迹可视化,让用户随时看懂"AI 现在在干什么"。
七、动手跑起来
本地开发可以直接 docker compose up(编排文件见 docker-compose.yml),或分别构建前端(frontend/Dockerfile)与后端(backend/Dockerfile)镜像。更完整的部署说明与 API 参考可阅读:
- 部署指南:deployment.mdx
- 快速上手:getting-started.mdx
- API 参考:api-reference.mdx
- 后端说明:README.md
结语:这套架构的四个可借鉴点
- 星型状态图:router + N 个专家节点,新增图表类型只需一个节点、一条边,扩展成本极低;
- 双通道路由:
@显式标记免 LLM 调用,LLM 分类兜底并注入历史轨迹与画布上下文,兼顾速度与准确; - 统一双标签输出协议:
<design_concept>+<code>让"思考过程"与"执行产物"天然可分离,前端可分别流式呈现; - 事件驱动 UI:SSE 事件流 + 状态机解析器,使"AI 正在画图"成为可观察、可中断、可落盘的实时过程。
理解了这四层,你就掌握了 LangGraph 多智能体编排 + 实时 AI 绘图的核心设计思路——这正是 DeepDiagram 用几百行核心代码撑起"一句话出图"体验的秘密。







