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：哪種圖片適合哪個概念，並附有深度學習常見錯誤事實表。閱讀與你概念相符的那一行。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-D 參數），並說明它們代表什麼。真實數字勝過佔位符：總和為 1 的權重、你能驗證輸出的卷積、實際符合最佳化器行為的軌跡。
用 Python 計算數字，絕不要手算或心算。 執行一個簡短腳本（透過 uv run --with numpy python - 或純 Python 的 numpy），然後將座標或數值貼入 .tex。留下一則註解說明它們是如何產生的。手工製作的「示意性」數字是錯誤圖形的來源：總和為 1.1 的 softmax 列、與輸入不符的卷積輸出。
4. 撰寫圖形
在輸出資料夾（如果使用者指定了資料夾則為該資料夾，否則為當前工作目錄）中建立 <concept>.tex，從以下開始：
% Caption: <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}\)）。形狀管理是理解深度學習操作的一半。 - 追蹤一個範例。 在所有出現的地方，用
hl樣式（紅色輪廓）標記一個列、一個區塊或一個步驟，讓學生能從頭到尾追蹤單一計算。 - 簡潔且就地註解。 兩到三個簡短的斜體註解（
annot）帶有纖細的引導線，放在它們要解釋的內容旁邊。使用直接標籤而不是圖例框。沒有總標題（由標題來做），但多面板圖形會獲得簡短的面板標籤，例如 "(a) 普通: (\vx_l = F_l(\vx_{l-1}))"，使用annot樣式，每個面板上方有清晰的空間。 - 最少墨水。 沒有陰影、漸層、為效果而存在的 3D 或裝飾性圖示。填充是筆觸顏色的淺色調（
cell=colorX做到這一點）。 - 標準符號。 粗體小寫為向量、粗體大寫為矩陣、普通為純量；使用巨集（
\vx、\mW、\vytld、\softmax）。行 vs 列的慣例必須與你印出的方程式一致（注意力使用按 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 頂部的 % Caption: 註解與圖形同步；它是使用者將貼在其文件中的圖形標題。
兄弟技能
此技能生成靜態圖形：每個概念一個 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），並詢問等高線圖是否能更好地解釋它。通常是的。