llm-neuron-atlas 詳細教學

Live demo: https://charenix.com/qwen3b-atlas Repo: https://github.com/norika1207-lab/llm-neuron-atlas 作者: Norika Oda (ORCID 0009-0006-6816-9891) License: MIT

1. 專案定位

llm-neuron-atlas 屬於 mechanistic interpretability (機械式可解釋性) 工具範疇，但與既有工具有結構性的差異：

核心定位：把整個 transformer 的「神經元城市」(neuron-as-city / weight-as-road) 一次性渲染出來，讓使用者用空間導航的方式探索 LLM 的內部結構。

適用情境：

• LLM internals 教學示範 (對學生 / 跨領域研究者)
• Mechanistic interpretability paper 的 supplementary material
• Cross-architecture 保守性 (cross-Qwen-family / Phi-3 / Mistral) 視覺對照
• Mercury MCP observability 觀測結果的視覺化驗證

不適用情境：

• 即時 inference 觀測 (Phase 2 才要做的 live forward-pass overlay)

• 70B 模型 (output JSON 預計 300MB+，瀏覽器吃緊)

• MoE 架構 (尚未支援 expert 聚合)

2. 安裝指南

2.1 前置需求

• Python ≥ 3.10
• ~10 GB 磁碟空間 (Qwen 2.5 3B 權重 ~6 GB + 輸出 ~117 MB JSON + 中間 cache)
• 任何現代瀏覽器 (Chrome / Safari / Firefox 都可)
• 純 CPU 即可，不需要 GPU

2.2 完整 Pipeline

 1# 1. clone repo
 2git clone https://github.com/norika1207-lab/llm-neuron-atlas
 3cd llm-neuron-atlas
 4
 5# 2. 安裝依賴 (建議在 venv / uv 環境內)
 6pip install -r requirements.txt
 7# requirements.txt:
 8#   safetensors>=0.4.0
 9#   numpy>=1.24
10#   torch>=2.0
11#   huggingface_hub>=0.20
12
13# 3. 下載 Qwen 2.5 3B 權重 (~6 GB)
14huggingface-cli download Qwen/Qwen2.5-3B --local-dir weights/Qwen2.5-3B
15
16# 4. bake graph (CPU 純運算，~1-3 分鐘視 CPU 而定)
17python bake/extract_graph.py \
18  --weights weights/Qwen2.5-3B \
19  --out viewer/graph
20
21# 5. 本地啟動 viewer
22cd viewer && python -m http.server 8000
23# 瀏覽器開 http://localhost:8000

2.3 推薦的隔離環境

依本專案 CLAUDE.md 規範，避免汙染原生 Python：

1# 用 uv (推薦)
2uv venv .venv
3source .venv/bin/activate
4uv pip install -r requirements.txt
5
6# 或用標準 venv
7python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

2.4 預覽不下載權重 (offline preview)

examples/ 目錄含 qwen3b-meta.json / qwen3b-hotness.json / qwen3b-highways.json 三個 tiny sample，可在不下載 6GB 模型的情況下先看 viewer 樣貌 (但完整 nodes/edges 仍需 bake)。

3. 核心架構解析

3.1 整體架構圖

flowchart LR
  HF["HuggingFace Hub
Qwen/Qwen2.5-3B"]
  W["weights/Qwen2.5-3B/
*.safetensors"]
  Bake["bake/extract_graph.py
(~250 lines Python)"]
  G["viewer/graph/
nodes.json + edges.json
+ highways.json + meta.json"]
  V["viewer/index.html
(self-contained, three.js)"]
  B["Browser
3D atlas, 60 fps"]
  CDN["esm.sh
three@0.160.0 importmap"]

  HF -->|huggingface-cli download| W
  W -->|safetensors mmap| Bake
  Bake -->|json dump| G
  G -->|python -m http.server| V
  V -->|fetch JSON| B
  CDN -.->|importmap CDN| V

3.2 Bake Pipeline (9 步)

flowchart TD
  S1["1. mmap-load safetensors shards"] --> S2["2. 每層讀 7 個 weight tensor
q/k/v/o + gate/up/down"]
  S2 --> S3["3. 計算有效 MLP 轉移矩陣
M[D',D] = down @ gate (2048x2048)"]
  S3 --> S4["4. 每個 src dim 取 top-10 outgoing edges
by abs(weight)"]
  S4 --> S5["5. 標 8 個 Mercury named anchors
715/758/279/382/476/11/25/481"]
  S5 --> S6["6. 標 300 個 Tier-B hot neurons"]
  S6 --> S7["7. emit 4 JSON
nodes + edges + highways + meta"]
  S7 --> S8["8. 任意 HTTP server 對外靜態服務"]
  S8 --> S9["9. Viewer fetch 全部 → InstancedMesh + bloom"]

3.3 為什麼 M = down @ gate 是核心抽象？

這是整個 repo 的數學核心，bake script 第 73–118 行的關鍵段落。直觀解讀：

• gate_proj 形狀 (INTERMEDIATE=11008, HIDDEN=2048)：把 layer L 的 residual (2048,) 投到 MLP 中間層 (11008,)
• down_proj 形狀 (HIDDEN=2048, INTERMEDIATE=11008)：把 MLP 中間層 (11008,) 投回 residual (2048,)
• 合成矩陣 M = down @ gate 形狀 (2048, 2048)：M[D', D] = 「layer L 第 D 維對 layer L+1 第 D’ 維」的有效線性貢獻

這是 Phase 1 簡化 — 忽略 attention 路徑、忽略 SiLU 非線性，僅取 MLP 線性骨架。但這已足以呈現「resi cascade」的結構美感，且 2048×2048 矩陣每層只算一次，CPU 上 <2 秒。

3.4 視覺化 (viewer/index.html)

• 845 行 single-file HTML，無 build step
• 從 esm.sh importmap 拉 three@0.160.0 + OrbitControls + EffectComposer + UnrealBloomPass
• 用 THREE.InstancedMesh 一次渲染 73,728 個球體
• 透過 7 個非同步 fetchJSON() 取 meta / hotness / match-phi3 / match-mistral / nodes / highways / edges，並用 weight 比例顯示載入進度
• 5 個 layer region 用不同顏色 (blue / green / yellow / pink / orange) 分區
• Bloom post-processing 讓 named anchors 自帶光暈感

4. Helper Scripts 詳細用法

本 repo 僅一個關鍵 script：

4.1 bake/extract_graph.py

輸出檔案：

呼叫範例：

1# 最小 top-K (適合 demo / 教學)
2python bake/extract_graph.py --weights weights/Qwen2.5-3B --out viewer/graph --top-k 5
3
4# 較密集視覺 (適合研究)
5python bake/extract_graph.py --weights weights/Qwen2.5-3B --out viewer/graph --top-k 20

Mercury named anchors 對照 (寫死在 MERCURY_NAMES dict 第 42–51 行)：

5. 應用場景

5.1 教學示範

• 課程：transformer internals 教學單元，把抽象的「2048-dim residual stream」變成可指可點的 3D 物件
• 工作坊：在 1 小時內讓學員體會 LLM 不是黑盒、而是有空間結構的網絡

5.2 研究輔助

• Paper supplementary material — 把「我們發現 dim 715 是 inhibitor」直接做成 reviewer 可點開的 3D 連結
• Cross-architecture 比對 — Qwen 3B 中央塔 vs Phi-3 / Mistral 7B 側塔，視覺驗證 conservation 假說

5.3 觀測結果驗證

• Mercury MCP v0.1 (Paper A + B) 的 8 個 named anchor 可在 atlas 內逐一檢視，作為「研究主張的可視化證據」

5.4 不適合用本工具的場景

• 即時 inference 行為觀測 → 等 Phase 2 forward-pass overlay
• MoE / SSM / hybrid 架構 → 目前只支援 dense decoder-only
• 想看 attention head 的細節 → 用 BertViz；本工具是 neuron-level

6. 資安掃描報告

6.1 紅黃綠燈總結

🟢 整體判定：低風險 此 repo 為靜態視覺化工具，無使用者輸入、無 server 端、無秘密儲存、無 shell 注入面。bake script 是純檔案 IO + numpy 矩陣運算，無 eval / exec / subprocess。

6.2 詳細掃描結果

6.3 唯一中度提醒 🟡 — CDN 依賴

viewer/index.html 透過 importmap 從 https://esm.sh/three@0.160.0 載入 three.js。風險面：

• CDN 可用性：若 esm.sh 暫時無法存取，viewer 整個無法載入 (因 ES module import 失敗)
• CDN 完整性：importmap 未指定 SRI hash；理論上若 esm.sh 被入侵，可注入惡意 JS
• 離線使用：完全離線環境無法直接使用

緩解建議：

 1<!-- 自託管 three.js (推薦給內部分享 / 離線 demo) -->
 2<!-- 1. 下載 three.module.js + addons/ 到 viewer/vendor/three/ -->
 3<!-- 2. 把 importmap 改成相對路徑 -->
 4<script type="importmap">
 5{
 6  "imports": {
 7    "three": "./vendor/three/three.module.js",
 8    "three/addons/": "./vendor/three/addons/"
 9  }
10}
11</script>

6.4 對「整合進內部管線」的建議

• ✅ 可直接 fork 入 air-gapped 內網，無需修改即可使用 (除自託管 CDN 外)
• ✅ bake script 可直接在 internal model 上跑 (替換 --weights 與 constants)
• ⚠️ 若要把 internal model 的 atlas 公開分享，記得 sanitize meta.json 內模型路徑欄位
• ⚠️ examples/ 內含 sample JSON，若用內部模型 bake，發佈前清乾淨此目錄

7. FAQ

Q1：為什麼 bake 只看 MLP，不看 attention？ A：Phase 1 簡化。Attention 的影響受輸入 token 與位置影響，是動態 routing；MLP 的轉移矩陣是 static structure，最適合做「結構地圖」。Phase 2 加 live forward-pass overlay 時會把 attention 加進來。

Q2：73,728 個球體真的能 60 fps 嗎？ A：可以，因為用 THREE.InstancedMesh — 一次 draw call 渲染所有 instance，GPU 只算 transform，不重複建 geometry。

Q3：能用在 GPT-4 / Claude 嗎？ A：不行 — 需要 open weights。本工具靠 safetensors 直接讀權重做矩陣乘法。

Q4：viewer 開不起來，瀏覽器空白？ A：先檢查：(1) viewer/graph/ 是否有完整 4 個 JSON；(2) 是否從 python -m http.server 啟動 (file:// 會擋 fetch)；(3) DevTools console 是否有 esm.sh 403/404。

Q5：能離線使用嗎？ A：bake 階段可以；viewer 因 esm.sh CDN 依賴需自託管 three.js (見 §6.3)。

Q6：跟 Neuronpedia 差在哪？ A：Neuronpedia 是 SAE feature dashboard，每個 feature 一張 2D 卡；本工具是 raw neuron + 3D 空間結構，沒做 SAE 分解。兩者互補不互斥。

Q7：bake 跑多久？ A：作者描述 “any laptop CPU”，36 層 × 一個 2048×2048 矩陣相乘，大致 1–3 分鐘量級。

8. 進階技巧

8.1 自訂 named anchors

在 bake/extract_graph.py 第 42 行的 MERCURY_NAMES dict 加入自家研究發現：

1MERCURY_NAMES = {
2    # ... 既有 8 個 ...
3    1234: {'name': 'MY_FEATURE', 'role': 'my interpretability finding'},
4}

重 bake 後，新加的 anchor 自動會在 viewer panel 顯示 role。

8.2 移植到 Llama 3 / Mistral

requirements.txt 已支援；只需確認 tensor 命名一致即可：

1python bake/extract_graph.py --weights weights/Meta-Llama-3-8B --out viewer/graph

Llama 3 的 HIDDEN=4096 與 INTERMEDIATE=14336 不同 — 需要把 extract_graph.py 第 36–38 行的常數改成模型對應值（或 PR 一個自動推斷邏輯）。

8.3 加入 SAE feature 層

進階：對每層 intermediate (11008) 訓 SAE，把 SAE feature 當第三軸視覺化。需擴展 nodes.json schema 加 sae_feature_ids 欄位，viewer 端增加 toggle。

8.4 加大 top-K 看完整 connectivity

--top-k 50 會把 edges.json 放大到 ~500MB，viewer 載入慢但圖更密。研究用 OK，demo 用建議維持 10。

9. 整合進其他工作流

9.1 與 paper-tutorial / research-pipeline-v2 整合

• 在 Mercury MCP paper 的 supplementary material 區段，直接嵌入 atlas iframe + 截圖
• research-pipeline-v2 Stage 7 (final tutorial) 可把 atlas live demo 連結放進 HTML 上方

9.2 與 graphify / gitnexus 對照

• graphify 對 codebase 建知識圖；本工具對 model weights 建神經元圖 — 兩者結構相似但 domain 不同
• 可作為 graphify wiki 內「LLM internals」章節的可視化外掛

9.3 與 patent-creator 邊界

• ⚠️ Atlas 若以內部 model weights bake，視覺化內容可能含 trade secret — bake 結果不可公開
• 若進入 patent-creator 流程：禁止把 internal bake 結果上 Discord / 公開 demo site

9.4 與 ai-notebooklm 整合

• 把 paper-A / paper-B PDF + atlas screenshot 一起餵 NotebookLM，建立「research + visualization」雙模態筆記本

10. 重點摘要 Checklist

• 確認本機已有 Python ≥ 3.10 + 10GB 磁碟
• 用 uv venv 或 python -m venv 建獨立環境，不要污染系統 Python
• pip install -r requirements.txt
• huggingface-cli download Qwen/Qwen2.5-3B --local-dir weights/Qwen2.5-3B (6GB)
• python bake/extract_graph.py --weights weights/Qwen2.5-3B --out viewer/graph
• cd viewer && python -m http.server 8000
• 開 http://localhost:8000 確認 atlas 顯示 + 自動跳 dim 715
• 若內部分享：自託管 three.js (見 §6.3) 取代 esm.sh
• 若內部模型 bake：清乾淨 examples/ + 確認 meta.json 無敏感路徑

11. 進一步閱讀

• Mercury MCP v0.1 — Zenodo DOI 10.5281/zenodo.20352085
  • Paper A: cross-architecture conservation (anchor dims 跨 Qwen 0.5B–72B 保留)
  • Paper B: functional control via single-dim subspace rescue (715 INHIBITOR + 758 CONTROLLER)
• Qwen 2.5 3B model card — https://huggingface.co/Qwen/Qwen2.5-3B
• three.js InstancedMesh 文件 — https://threejs.org/docs/#api/en/objects/InstancedMesh
• esm.sh (CDN 機制) — https://esm.sh
• 相關 interpretability tools：
  • BertViz: https://github.com/jessevig/bertviz
  • Neuronpedia: https://www.neuronpedia.org
  • TransformerLens: https://github.com/neelnanda-io/TransformerLens
• 作者其他連結：
  • ORCID 0009-0006-6816-9891
  • Google Scholar
  • GitHub @norika1207-lab

Tutorial 生成於 2026-05-28，by AI-Knowledge Template gh-tutorial-qd workflow。