poloclub/transformer-explainer · 上手攻略

  • 仓库：poloclub/transformer-explainer
  • 链接：https://github.com/poloclub/transformer-explainer
  • 分类：ai（AI / 大模型可视化与教学）
  • 作者：spark
  • 更新：2026-07-14

是什么

poloclub/transformer-explainer 是佐治亚理工 Polo Club of Data Science 维护的交互式 Transformer 教学工具。在浏览器里跑一个完整的 GPT-2 模型（@xenova/transformers v2.17.1 + onnxruntime-web v1.23.0 + onnx），用户输入任意文本，工具实时可视化整条前向链路：嵌入、Q/K/V 矩阵拆分、注意力权重热力图、logits → softmax → 下一个 token 采样。论文已被 CHI 2026 接收（DOI: 10.1145/3772318.3791725），同时拿了 arXiv:2408.04619 的扩展版。

技术栈是 SvelteKit 2 + Svelte 5 + Vite 5 + TypeScript 5 + D3 v7 + GSAP v3 + KaTeX，2025-2026 教学类交互页面的典型组合。MIT 协议。

解决什么问题

对 LLM 好奇但又怕打开《Attention is All You Need》直接劝退的人：

  • "Q、K、V 到底是什么"——动一动文本，看到 attention 矩阵每一格都跟着变。
  • "概率怎么从 logits 变到下一个 token"——softmax + 温度 + top-k 都在右侧面板里直接拨。
  • "为什么有时模型会选一个不是 argmax 的词"——看采样分布。
  • "124M 参数跑在浏览器不卡吗"——可以在 DevTools 里看到 transformers.js 走的是 ONNX Runtime Web + WASM。

快速安装

环境要求来自仓库 package.json 的 engines 段：Node ≥ 20，npm ≥ 10。

git clone https://github.com/poloclub/transformer-explainer.git
cd transformer-explainer
npm install
npm run dev
# 默认在 http://localhost:5173

零配置即可运行：vite dev 会自动加载 ONNX 模型的 Web Worker，首次访问要下载 ~200MB 模型权重（GPT-2），耐心等 30 秒 - 2 分钟，浏览器会缓存。生产构建：

npm run build       # 产物在 build/
npm run preview     # 本地预览静态站
npm run deploy      # 用 gh-pages 发布到 GitHub Pages

核心用法

演示视角

打开 http://localhost:5173，左侧是文本输入框（默认 "I ate a banana because it was"），右侧是三栏面板：

  • Top：上下文 token 列表和温度/top-k 滑块。
  • Middle：Sankey 图展示 GPT-2 的层 / 头 / 残差流；点击节点高亮其对应计算。
  • Bottom：softmax 后 top-5 候选词，可逐个 hover 看概率。

输入框打字 → debounce 300ms → 调 transformers.js 的 model.generate → 把中间张量（Q、K、V、attention、logits）走 D3 + GSAP 动效回放。

改造成自己的演示

最常见的二次开发是换成别的 GPT-2 变体或自己蒸馏的模型。仓库用 Svelte 的响应式变量，文件结构大致是：

src/
  lib/
    components/   # 各类 D3 可视化组件
    inference/    # 封装 transformers.js 调用
    state.svelte.ts  # 全局状态机

例如换模型：

// src/lib/inference/model.svelte.ts
import { AutoTokenizer, AutoModelForCausalLM } from '@xenova/transformers';

export async function loadModel() {
  const tokenizer = await AutoTokenizer.from_pretrained('Xenova/distilgpt2');
  const model = await AutoModelForCausalLM.from_pretrained('Xenova/distilgpt2');
  return { tokenizer, model };
}

distilgpt2 权重更小（~80MB），适合课堂演示。

嵌入到课堂

CHI 论文里给的建议：教师把笔记本接投影，学生用手机扫码打开 GitHub Pages 上的同一 URL，互动时全员同步推进。教学场景里效果比静态 PPT 好 5-10 倍。

典型适用场景

  • CS 入门课（NLP / DL）：教师演示注意力机制的标准教具。
  • 技术博客 / 知乎专栏：截 GIF / 录视频做素材。
  • 研究入门者：想做 mechanistic interpretability 但不想装 PyTorch + CUDA 的人，可以先在这里理解前向推理每一步的形状。
  • 招聘 / 科普讲座：现场让听众自己打几个字看概率分布，比讲"softmax"高到不知道哪里去。

坑与注意

  1. 首次加载慢：GPT-2 原始 int4 模型约 200MB，移动端 / 校园网可能不友好。CHI 论文和 issue 都有推荐加 loading 动画。
  2. Node 版本：低于 20 会因 Svelte 5 / Vite 6 报 TypeError，nvm use 20 即可。
  3. Safari 16 以下：onnxruntime-web 的 SIMD 支持有限，可能退回到 WASM，跑模型会慢约 3-5x。
  4. 移动端小屏：sankey 图默认按 1080p 排版，375px 视口会重叠；项目里有响应式断点，但极致窄屏仍建议横屏。
  5. CORS：本地 dev 用 vite 自带代理，问题不大；放到自己的服务器上要给 /models/ 配置 Access-Control-Allow-Origin。
  6. 教学纪律：现场让同学"试试输入奇怪文本"很快乐，但请提前提示 NSFW 词会触发 ONNX 内部 filter，结果可能不直观。

与同类对比

工具 类型 跑模型 交互深度 适合人群
Transformer Explainer 单页 Svelte 应用 是（GPT-2） Token → logits 全链路 教学、入门者
3blue1brown 视频 视频 无 高（概念） 零基础
BertViz Jupyter notebook 后端 注意力矩阵 研究者
The Illustrated Transformer 静态博客 无 中 自学者
OpenAI Playground Web 是（云） 仅结果 工程人员
TransformerLens Python 库 本地 高 机制解释研究者

差异化：Transformer Explainer 是少有的"真的在浏览器里跑 GPT-2 + 全链路可视化"教学工具。BertViz 更偏研究者、3blue1brown 偏纯概念、Playground 不暴露中间量。

一句话推荐结论

Transformer Explainer 是给"想看 GPT 内部到底在干嘛"的人准备的最友好交互教具——10 行命令跑起来，输入即反馈，能直接把注意力机制从抽象概念变可观察现象。