可视化

📚 学习目标

学完这篇文章后，你将能够：

• 使用 Mermaid 生成图结构与执行流程图
• 理解不同可视化方式的适用场景
• 使用 drawMermaid() 调试复杂图结构
• 把结构快照纳入回归检查

前置知识

在开始学习之前，建议先阅读：

• 并行处理

你需要了解：

• 基本的 Flowchart 概念
• 图结构中的节点与边

1 为什么需要可视化？

LangGraph 的图结构可能非常复杂，尤其是包含条件分支、子图和并行处理时。代码逻辑很难直观看出实际执行流。

可视化可以帮助我们：

1. 验证设计：确认图连接是否符合预期。
2. 调试逻辑：检查条件分支指向是否正确。
3. 文档沟通：向团队展示 Agent 的架构。

2 生成 Mermaid 图表

Graph 和 CompiledGraph 都提供 getGraph() 方法，它返回的 Graph 对象包含 drawMermaid()。

代码示例

import { StateGraph, START, END } from '@langchain/langgraph';

type State = {
  input: string;
};

const workflow = new StateGraph<State>({
  channels: {
    input: { default: '' },
  },
});

workflow.addNode('normalize', async (state) => ({ input: state.input.trim() }));
workflow.addEdge(START, 'normalize');
workflow.addEdge('normalize', END);

const app = workflow.compile();

const mermaidChart = app.getGraph().drawMermaid();
console.log(mermaidChart);

输出预览

打印出来的字符串如下所示：

%% drawMermaid() 的输出示例（内容会随版本变化）
graph TD;
  __start__([<p>__start__</p>])
  normalize(normalize)
  __end__([<p>__end__</p>])
  __start__ --> normalize;
  normalize --> __end__;

你将得到 Mermaid 源码，可粘贴到 Mermaid Live Editor 或直接在 Markdown 中渲染。

3 自定义样式

drawMermaid() 可以接收配置对象，用来定制输出样式。

const chart = app.getGraph().drawMermaid({
  curveStyle: 'basis',
  firstNodeColor: '#ffcc80',
  lastNodeColor: '#a5d6a7',
});

建议把可视化当作调试输出：

• 先用默认输出确认“结构对不对”
• 再加样式突出关键路径

4 可视化方式怎么选？

你可以把它类比成前端开发：

• Mermaid ≈ 一张架构图
• Studio ≈ DevTools
• 自定义 UI ≈ 你的业务页面

5 可视化类型概览

6 LangGraph Studio

除了静态图表，LangGraph 还提供 LangGraph Studio（云服务或本地 Docker）。它支持：

• 交互式图表：可点击节点查看状态
• Replay：回放 Agent 的每一步操作
• 状态编辑：手动修改状态进行测试

一个务实的调试流程：

1. 先用 invoke 跑通（不流式）
2. 再切换 stream/streamEvents（确保 UI 能接住 event）
3. 最后用 Studio 看“哪里慢、哪里卡、状态怎么变”

7 把可视化变成回归测试：结构快照

当图越来越复杂时，结构变更很容易引入回归。可以把 Mermaid 源码当成快照写入文件：

import { writeFileSync } from 'node:fs';

const mermaid = app.getGraph().drawMermaid();
writeFileSync('artifacts/graph.mmd', mermaid, 'utf-8');

你甚至可以在 CI 里做简单校验：

if (!mermaid.includes('tools')) {
  throw new Error('Graph snapshot missing tools node');
}

8 执行流程可视化（事件流）

静态结构图解决“结构对不对”，执行流程回答“运行顺序对不对”。

const stream = app.streamEvents({ input: 'hello' }, { version: 'v2' });

for await (const event of stream) {
  console.log(event.event, event.name);
}

事件流可以帮助你定位“哪一步变慢、哪一步未触发”。

9 条件边与多图对比技巧

条件边容易看不懂，建议：

• 路由节点用清晰命名（如 router_tools）
• 给关键节点加说明文本
• 先画主干流程图，再画完整图

大型图建议维护两份 Mermaid：

• 主干图：只保留核心节点
• 全图：包含所有边与条件

主干图适合文档与讨论，全图更适合调试。

10 工具与库建议

11 常见问题和解决方案

1. Mermaid 图太乱：优先用子图封装，把模块折叠成一个节点。
2. 看不出条件分支：给路由节点命名清晰，并让它成为中心节点。
3. 节点很多但不知道主路径：先画主干流程图，再用全图补细节。

12 可视化实践建议

• 先跑通结构图，再引入执行流。
• 出现回归先对比结构快照。
• 对外展示用主干图，对内调试用全图。
• 条件边多时先给路由节点加注释，避免阅读成本过高。

13 性能监控可视化

当图执行变慢时，建议把性能数据也可视化。最简单的做法是记录每个节点的耗时：

const timings: Record<string, number> = {};

const timedNode = (name: string, fn: () => Promise<unknown>) => async () => {
  const start = Date.now();
  const result = await fn();
  timings[name] = Date.now() - start;
  return result;
};

你可以把耗时结果写入日志或导出成 JSON，后续再做可视化展示。

14 团队协作与文档化

当团队需要对齐架构时，建议把主干图和执行说明放到文档中：

这样可以让团队在“结构一致、执行可复现”的基础上协作开发。

15 Studio 使用步骤（实践清单）

1. 先本地运行：用 invoke 验证逻辑正确。
2. 打开事件流：使用 streamEvents 查看实际执行顺序。
3. 导入 Studio：在 Studio 中查看节点状态与回放。
4. 定位瓶颈：观察耗时节点与状态变化。
5. 回放验证：修复后重新回放，确认流程正确。

event 字段速览

💡 练习题

1. 操作题：为你之前写的 ReAct Agent 生成 Mermaid 图，并观察条件边的呈现方式。

   点击查看答案

   先调用 app.getGraph().drawMermaid() 得到图源码，再观察 addConditionalEdges 产生的分支边。 通常会看到一个路由节点发散到多个目标节点，边标签对应路由返回值或 path map 的 key。

2. 思考题：在拥有几十个节点的大型图中，如何通过子图优化可视化效果？

   点击查看答案

   可以把稳定模块拆成子图（如检索子图、工具执行子图、总结子图），主图只保留入口/出口。 调试时先看主图定位问题区域，再单独展开子图，避免一次性阅读全部节点造成信息过载。

3. 操作题：为关键节点生成结构快照，并在 CI 中做简单校验。

   点击查看答案

   在测试里将 drawMermaid() 输出写入快照文件（例如 graph.snapshot.mmd），PR 中对比 diff。 CI 可做两步校验：结构文本是否变更、关键边（如 START -> agent）是否仍存在。

4. 思考题：什么时候应该用 Studio 而不是 Mermaid？

   点击查看答案

   Mermaid 适合静态结构评审；Studio 适合运行时问题定位。 当你需要看事件流、状态快照、节点耗时、重放某次执行时，应优先使用 Studio。

5. 操作题：为你的主干图补充一个“关键路径说明”，并写成文档备注。

   点击查看答案

   可在图下增加三部分备注：核心路径（正常流程）、分支条件（何时走异常/工具路径）、失败兜底（重试与终止点）。 这样读者不看代码也能理解“请求如何从入口走到最终输出”。

📚 参考资源

官方文档

• Mermaid Live Editor
• LangGraph Studio

建议把结构图保存为 .md 文件，方便团队协作与版本对比。 如果你在 PR 中变更了图结构，请同步更新快照。

✅ 总结

本章要点：

• app.getGraph().drawMermaid() 是最常用的可视化手段。
• 可视化是调试复杂 Agent 逻辑的有力工具。
• 结合 Studio 能更好定位运行时问题。

下一步：继续学习配置管理：配置管理与 Configurable。