使用 Mermaid.js 绘制 Transformer 架构图：轻量级可视化与 TensorFlow 开发环境的融合实践
在深度学习模型日益复杂的今天，如何清晰、高效地表达模型结构，已经成为科研与工程实践中不可忽视的一环。尤其是在 Transformer 架构主导 NLP、CV 和多模态任务的当下，一张准确且可维护的架构图，往往比千行代码更能快速传达设计思想。
然而，传统的绘图方式——无论是 PowerPoint 拖拽图形，还是用 Visio 精调布局——都面临一个根本性问题：它们是“静态资产”，难以版本化、不易协作、更新成本高。当你修改了模型层数或注意力机制的设计，是否还要重新打开 PPT 手动画一遍？显然不是理想的工作流。
有没有一种方式，能让架构图像代码一样被编写、被提交、被审查、被复用？
答案是肯定的：用文本定义图表，用 Mermaid.js 实现“代码即图”。
Mermaid 正是以极简 Markdown 风格语法生成 SVG 图表的利器，特别适合绘制神经网络结构、训练流程和数据管道。结合如今广泛使用的容器化开发环境（如 TensorFlow-v2.9 Jupyter 镜像），我们完全可以构建一个“模型代码 + 架构图 + 实验记录”三位一体的技术文档体系。
Transformer 的核心在于其编码器-解码器结构与自注意力机制。要准确表达这一架构，不仅需要展示模块之间的连接关系，还要体现信息流动的方向、关键组件的类型以及层次化的组织逻辑。
Mermaid 的graph语法天然支持这些需求。通过-->定义流向，subgraph划分功能模块，style标注语义颜色，我们可以从零开始构建一个既美观又语义清晰的 Transformer 架构图。
先看一个基础示例：
graph TD A[输入序列] --> B(Embedding层) B --> C{多头注意力} C --> D[前馈网络] D --> E[输出序列]这段代码虽然简单，但已经体现了 Transformer 的基本数据流：输入经过嵌入、注意力、前馈网络最终输出。更重要的是，它完全是文本形式，可以放进 Git 跟踪每一次变更——比如把“前馈网络”改成“FFN + Dropout”，只需修改一行代码即可。
而当我们转向完整的 Transformer 模型时，Mermaid 的表达能力依然游刃有余。以下是其标准架构的 Mermaid 实现：
graph LR %% 输入部分 subgraph Input I1[Input Sequence] --> EMB[Token Embedding] EMB --> PE[Positional Encoding] end %% 编码器部分 subgraph Encoder PE --> MHA1[Multi-Head Attention] MHA1 --> LN1[Layer Norm] LN1 --> FFN1[Feed-Forward Network] FFN1 --> LN2[Layer Norm] end %% 解码器部分 subgraph Decoder O1[Target Sequence] --> EMB_D[Token Embedding] EMB_D --> PE_D[Positional Encoding] PE_D --> MHA2[Masked Multi-Head Attention] MHA2 --> LN3[Layer Norm] LN3 --> MHA3[Encoder-Decoder Attention] MHA3 --> LN4[Layer Norm] LN4 --> FFN2[Feed-Forward Network] FFN2 --> LN5[Layer Norm] end %% 连接关系 Encoder -->|Key, Value| MHA3 LN2 -->|Output| MHA3 LN5 --> LOGITS[Linear Projection] LOGITS --> SOFTMAX[Softmax] %% 输出 SOFTMAX --> Output[Output Sequence] style I1 fill:#f9f,stroke:#333 style O1 fill:#bbf,stroke:#333 style Output fill:#dfd,stroke:#333 style MHA1 fill:#ffe4b5,stroke:#333 style MHA2 fill:#ffe4b5,stroke:#333 style MHA3 fill:#ffe4b5,stroke:#333 style FFN1 fill:#e0ffff,stroke:#333 style FFN2 fill:#e0ffff,stroke:#333这个脚本有几个值得强调的设计细节：
- 使用
graph LR明确指定从左到右的数据流方向，更符合阅读习惯； subgraph将输入、编码器、解码器分组，提升视觉层次感；- 通过
|Label|在连接线上标注“Key, Value”等关键信息，增强了对 encoder-decoder attention 的解释力； style指令为不同模块赋予语义化颜色：黄色代表注意力机制，浅蓝代表前馈网络，粉/蓝分别标识输入输出，形成统一的视觉语言。
这样的图表不仅可以嵌入 Markdown 文档，还能直接放入 Jupyter Notebook 中，与模型实现代码并列展示，真正实现“图文同源”。
那么，在实际开发中，这套方案该如何落地？
最理想的环境之一就是TensorFlow-v2.9 的官方 Jupyter 镜像。这个镜像预装了 Python、TensorFlow 2.9、Keras、NumPy、Matplotlib 和 Jupyter Lab，开箱即用，尤其适合作为教学、实验或原型开发的基础环境。
启动命令极为简洁：
docker run -it -p 8888:8888 tensorflow/tensorflow:2.9.0-jupyter容器启动后，浏览器访问http://localhost:8888即可进入交互式开发界面。你可以在.ipynb文件中一边写模型代码，一边用 Markdown 单元格插入 Mermaid 图表，实时呈现你的设计思路。
不过需要注意的是，默认的 Jupyter 环境并不支持 Mermaid 渲染。这是因为 Mermaid 是一个前端 JavaScript 库，而 Jupyter 的 Markdown 渲染引擎不会自动加载外部脚本。
解决方法有两种：
方法一：安装 Jupyter 插件
使用jupyterlab-markup或ipython-mermaid等扩展来启用 Mermaid 支持：
pip install jupyterlab-markup jupyter lab build重启 Jupyter Lab 后，即可在 Markdown 单元格中正常使用`mermaid块。
方法二：手动注入 Mermaid.js
如果无法安装插件（例如受限于权限），可以直接在 Notebook 中插入 HTML 单元格，加载 CDN 上的 Mermaid 模块：
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>这种方法无需额外依赖，适用于临时演示或 CI/CD 环境中的文档渲染。
此外，对于需要远程协作的团队，还可以通过 SSH 登录容器进行高级操作。例如，在镜像内创建docs/transformer_arch.md文件，用 Vim 编辑 Mermaid 脚本，并通过 SFTP 下载到本地 Typora 或 VS Code 中查看渲染效果。这种模式特别适合撰写技术白皮书或论文附录。
从系统架构角度看，Mermaid 与 TensorFlow 镜像的结合，实际上构成了一个“双层开发范式”：
+-------------------+ | 用户终端 | | (Typora / VS Code) | +-------------------+ ↑ (查看/编辑 .md) | +---------------------------+ | TensorFlow-v2.9 容器环境 | | - Jupyter Notebook | | - Python/TensorFlow | | - Mermaid 图表嵌入 | +---------------------------+ ↑ (Docker 启动) | +----------------------------+ | 宿主机（Linux / Windows） | | - Docker Engine | | - GPU 驱动（可选） | +----------------------------+在这个体系中：
- TensorFlow 容器提供稳定、可复现的执行环境；
- Mermaid 提供轻量、可版本控制的表达层；
- 两者共同支撑起“代码 + 文档一体化”的现代 AI 工程实践。
典型工作流如下：
1. 启动容器，进入 Jupyter；
2. 创建新 Notebook，编写模型构建代码；
3. 在 Markdown Cell 中插入 Mermaid 图，说明整体架构；
4. 分段实现编码器、解码器逻辑，并辅以子图说明；
5. 训练模型，记录指标；
6. 导出为 HTML 或 PDF，用于汇报或归档。
这一流程带来的好处是实实在在的：
-减少重复劳动：不再需要将 Jupyter 截图粘贴到 PPT；
-避免文档滞后：模型改了，图也跟着改，始终保持同步；
-提升协作效率：同事可以通过 Git 查看图表变更历史，甚至提出修改建议；
-支持自动化输出：配合 Sphinx、MkDocs 等工具，可自动生成项目文档网站。
当然，在实际应用中也有一些经验性的设计考量需要注意：
- 控制复杂度：不要试图在一个图中画出所有细节。对于深层堆叠的编码器，建议只画一层作为代表，注明“N layers”即可；
- 保持语义一致：比如始终用黄色表示注意力模块，蓝色表示 FFN，帮助读者建立视觉记忆；
- 注意兼容性：GitHub 原生支持 Mermaid，但某些 CI 工具链可能需要额外配置渲染器；
- 准备降级方案：对于不支持 Mermaid 的场景（如 Word 报告），应提前导出 SVG 或 PNG 备用。
最终我们会发现，这项技术组合的价值远不止“画张图”那么简单。它反映了一种更深层次的趋势：AI 开发正在从“手工作坊”走向“工程化”。
过去，模型设计靠口述、靠草图、靠零散的笔记；而现在，我们有能力将整个知识链条——从思想到代码，从结构到文档——全部纳入版本控制系统，形成可追溯、可复用、可协作的技术资产。
而 Mermaid 正是这条链路上的关键一环。它让架构图不再是“一次性消耗品”，而是成为项目代码库中的一部分，随迭代而演进，随团队而共享。
当我们在 TensorFlow 镜像中写下这样一段 Mermaid 脚本时，我们不仅是在画图，更是在构建一种新的表达语言——一种属于现代 AI 工程师的语言。
