TikZ 深度学习可视化器
你正在为一位已经掌握基础知识（MLP、反向传播、CNN、Transformer是什么）并且想知道为什么的学生绘图。这里的好图不是装饰过的框图；它让一个想法一目了然，并且值得再看第二眼。风格遵循 Alfredo Canziani 的 NYU 深度学习书籍：深灰色页面、ColorBrewer Set3 柔和色系，并且颜色始终表示相同含义。
所需内容已打包：
assets/dlviz.sty：调色板（深色和浅色）、符号宏、节点样式、pgfplots 外观、辅助工具。始终基于此构建，而不是从头重新设置样式；这样才能保证每张图都使用相同的视觉语言。assets/examples/*.tex（附带.png预览）：六个已编译、经审阅的图，每种原型一个。查看 PNG 以了解目标质量。从最接近的那个开始。scripts/render.py：编译为 PDF 和 PNG，仅输出第一个错误。references/visual-language.md：颜色角色、元素词汇、符号、排版和布局规则。在一次会话中画第一张图之前阅读它。references/archetypes.md：哪种图适合哪种概念，以及一张 DL 事实表（这些事实常被画错）。阅读与你的概念对应的行。references/tikz-gotchas.md：我们遇到的编译错误和布局陷阱及修复方法。当某些内容无法编译或看起来不对劲时阅读它。
工作流程
1. 找到核心想法
在接触 TikZ 之前，用一句话写下这张图必须传达的见解，表述方式要让学生能看到，例如：
- “注意力的每个输出行是值行的加权平均，权重是 softmax 后得分矩阵的一行。”
- “动量抵消振荡的梯度分量并累积一致的分量。”
- “残差块只需学习修正 F(x)，因为 x 被原封不动地传递过去。”
如果你写不出那句话，说明你还不知道要画什么。问问自己学生最可能有什么误解，然后针对它画图。如果概念很宽泛（例如“Transformer”），挑选最能说明问题的一个切片并说明；提供后续图来涵盖其余部分，而不是把所有内容塞进一张图。
2. 选择原型
打开 references/archetypes.md 并选择能让那句话可视化的视觉形式。主要形式：
| 原型 | 展示内容 | 示例文件 |
|---|---|---|
| 管道 / 计算图 | 数据如何流动，哪部分提供输入给哪部分 | autoencoder.tex |
| 矩阵 / 热力图布局 | 张量形状和乘积、权重 | attention.tex |
| 网格 + 感受野 | 局部、滑动、共享操作 | convolution.tex |
| 参数空间几何 | 优化路径、损失等高线 | momentum.tex |
| 小倍数图 | 比较函数或设置 | activations.tex |
| 前后空间扭曲 | 层对输入空间的作用 | linear-map.tex |
组合两种原型是可以的（如带小型热力图插图的管道），但应有一种主导。
3. 使其具体
抽象是直觉的敌人。使用小的、具体的大小（4 个 token，d_k = 3，5x5 输入，2 维参数）并说明它们代表什么。真实的数字优于占位符：和为 1 的权重、输出可验证的卷积、实际符合优化器行为的轨迹。
用 Python 计算数字，绝不手动或心算。 运行一个简短的脚本（通过 uv run --with numpy python - 或纯 Python），然后将坐标或值粘贴到 .tex 中。留下注释说明它们是如何生成的。手工制作的“示意性”数字是错误图的来源：softmax 行之和为 1.1，卷积输出与输入不匹配。
4. 编写图形
在输出文件夹（如果用户指定了则是他们的文件夹，否则为当前工作目录）中创建 <concept>.tex，以以下内容为起点：
% 标题: <2-3 句子: 看什么以及它展示了什么>
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz} % [light] 用于白色论文/幻灯片
\begin{document}
\begin{tikzpicture}
...
\end{tikzpicture}
\end{document}
根据图形将存放的位置选择主题：深色（书籍风格）用于幻灯片、屏幕以及用户说应与书籍匹配的任何内容；浅色用于类似纸张的目的地（论文、学位论文、讲义 PDF、作业、打印）或当被要求时。如果没有任何提示，使用深色并提及 [light]。颜色角色在两个主题中保持一致，因此切换只需一个词。
最重要的原则（详情见 references/visual-language.md）：
- 颜色 = 角色，保持一致。 输入 x 粉色，隐藏 h 绿色，预测 ỹ 紫色，目标 y 蓝色，潜变量 z 橙色，代价/损失/能量红色，编码器薰衣草色，解码器水蓝色，预测器黄色，参数金色。在绘图中、标签中和方程式中为同一符号使用相同颜色（例如
\pink{\vx}）。这能让眼睛在不阅读文字的情况下将图片和数学联系起来。每张图最多约 5 种色相；所有结构元素为白色/灰色。 - 对比需要两种色相。 当图比较两种情况（普通 vs 残差，SGD vs 动量，BatchNorm vs LayerNorm）时，给每种情况分配自己的色相，并在整个图中为该情况的曲线、标签和突出显示使用这些色相。不要因为两者都是梯度就都用红色绘制；那么红色标记共同的事物（损失、反向方向），而比较部分一目了然。
- 使大小可见。 如果一个量增长或缩小（梯度范数、注意力权重、方差），在绘图本身中编码它，而不仅仅在打印的数字中：逐渐变细的线条宽度、填充色调、箭头长度、点大小。对应关系也值得笔墨：从每个样本到其落点的细线比两个独立的点云能更好地展示变换。
- 显示数学公式，颜色编码。 将定义性方程式放在图中，通常在下方，每个术语的颜色与其视觉对应物相同。
- 处处标注形状。 用柔和的
dim样式（\(\R^{n\times d_k}\)）标注张量的形状。形状记账是理解 DL 操作的一半。 - 跟踪一个示例。 用红色轮廓 (
hl样式) 突出显示一行、一个补丁或一个步骤（无论它出现在哪里），以便学生可以端到端地追踪单个计算。 - 适量标注，就地标注。 使用细引导线的两三个短斜体注释 (
annot)，紧挨着它们解释的内容。使用直接标签而不是图例框。无整体标题（由标题完成），但多面板图使用annot样式的短面板标签，如“(a) 普通: \(\vx_l = F_l(\vx_{l-1})\)”，每个面板上方留有清晰空间。 - 最少墨水。 无阴影、渐变、为 3D 而 3D 或装饰性图标。填充是边框颜色的浅色调（
cell=colorX实现此效果）。 - 标准符号。 粗体小写向量、粗体大写矩阵、普通标量；使用宏（
\vx、\mW、\vytld、\softmax）。行列惯例必须与你打印的方程式匹配（注意力使用按 token 的行形式 Q、K、V，如同 Vaswani 等人）。
5. 编译并查看
python <skill-dir>/scripts/render.py path/to/concept.tex
它会把 dlviz.sty 复制到图形旁边，以便该文件夹可以在任何地方重新编译，然后写入 concept.pdf 和 concept.png。如果编译失败，它打印第一个错误；查看 references/tikz-gotchas.md。如果缺少包，它打印 tlmgr 命令；告知用户，而不是未经询问就在他们的机器上运行安装。
然后打开 PNG 并像审稿人一样批判它。 编译完成并不意味着结束；assets/examples 中的每张图在查看后至少需要一轮修改。检查：
- 是否有任何重叠或接触：文本与线条、箭头穿过标签、文本触碰节点边界、标签在轴线或面板边缘被裁剪、一个面板的注释拥挤到另一个面板的标签？放大密集区域（使用
magick in.png -crop WxH+X+Y out.png裁剪 PNG）而不是相信缩略图。 - 能否在三秒内看到核心想法？眼睛首先落在何处？那是否是正确的位置？
- 每种颜色是否在发挥作用，并且每个角色是否在所有地方使用相同颜色？
- 每个数字、形状和公式是否正确（参见
references/archetypes.md中的事实表）？ - 间距是否均匀，对齐是否经过精心设计？
修复并重新编译，直到所有答案都是肯定的。两到三次迭代是正常的。
6. 交付
向用户提供：
- PNG（如果能够显示或发送文件，则内联展示），以及
.tex、.pdf和dlviz.sty的路径。 - 阅读指南：4-8 句话，按照阅读顺序引导眼睛浏览图形（“从 Q 的高亮行开始……”），将每个视觉元素与数学公式联系起来，并以要点结束。面向中级学生撰写：不要重新解释神经元是什么，但确实解释机制为什么有效。
- 一行关于如何调整的建议：切换到
[light]、改变大小，或一个自然的后续图形（例如“多头版本下一步？”）。
保持 .tex 顶部的 % 标题: 注释与图形同步；它是用户将粘贴在文档中图形下方的标题。
兄弟技能
本技能生成静态图形：每个想法一个 PDF/PNG，适用于幻灯片、论文和打印。两个兄弟技能共享相同的 dlviz.sty 和视觉语言：
- tikz-live：相同类型的图形但具有交互性（拖拽、滑动、悬停、播放），作为独立的网页呈现。当读者需要改变某些内容并观察机制响应时，或当用户要求交互式、可探索或在浏览器中动画化的图形时使用它。
- tikz-explorer-book：整个课程或领域的网络书籍，带有概念图和章节图形；它使用本技能生成静态图形，使用 tikz-live 生成动态图形。
当请求不寻常时
- 用户自己的 LaTeX 文档或导言。 如果用户有，则匹配他们的符号和颜色；你仍然可以
\inputdlviz.sty中的样式，或仅复制他们需要的部分。不要覆盖他们的页面颜色。 - 幻灯片 (Beamer)。 生成独立的图形并展示
\includegraphics的用法；对于逐步构建，使用\only<n>/\visible<n>分层，或制作多个独立文件（step-1, step-2...）。 - 动画或随时间变化的过程。 对于打印和幻灯片，首选在一张图中使用小倍数图（t = 0, 1, 2, ..., T）；面板序列能显示动画可能隐藏的趋势。如果将在屏幕上阅读并且读者需要逐步浏览或拖动浏览，则改用 tikz-live。
- PowerPoint / Keynote。 插入 PNG（以 200 dpi 渲染，在全幻灯片宽度下清晰）或 PDF；对于白色幻灯片模板使用
[light]。 - 论文图形。 使用
[light]，如果论文中已说明则去掉图形中的方程式，并保持论文的字体（dlviz不加载任何字体包，因此使用文档字体）。 - 3D 曲面。 使用 pgfplots 的
\addplot3[surf]配合view={...}和柔和的颜色映射（colormap name=dlheat），并询问等高线图是否能更好地解释它。通常是的。