Sudharsanselvaraj/Token-Print · 上手攻略
- 仓库：Sudharsanselvaraj/Token-Print
- 链接：https://github.com/Sudharsanselvaraj/Token-Print
- 分类：AI · LLM 可视化 / 可解释性
- 作者：Tom
- 更新：2026-09-14
是什么
Token-Print 是一个交互式 3D 可视化平台，用于实时探索 Transformer 架构内部运作机制：注意力头、RoPE 旋转、残差流、SwiGLU 前馈等组件在真实推理过程中以 WebGL 3D 形式动态呈现。核心理念：其他 LLM 可视化工具只提供静态架构图，或运行在假数据上；Token-Print 则直接挂钩真实模型的前向传播（forward pass），每个数值都追溯到 named_parameters()、真实推理过程或 GGUF 二进制头部。
项目定位介于研究级可解释性工具与教育级演示之间，声称所有数据有明确溯源（Provenance），并通过 CI 强制禁止假数据注入代码。
解决什么问题
- 注意力机制黑盒：传统方式只能看静态图，无法理解 GQA（分组查询注意力）中 14 个 Q 头如何共享 2 个 KV 组。Token-Print 将这些关系渲染为真实 3D 几何结构。
- 推理过程不可见：无法观察 token 生成时各层的激活值如何流动。Token-Print 提供 Generation 模式，逐 token 可视化前向传播。
- 模型结构理解门槛高：RoPE、SwiGLU、RMSNorm 等机制的概念与代码实现之间存在巨大鸿沟。点击任意组件即可获得论文引用（Vaswani et al., Su et al., Shazeer et al., Ainslie et al. 等）。
- 数据可信度问题：许多"可视化"工具用 Math.random() 填充数据。Token-Print 在 README 明确声明：构建时会触发 CI 失败，禁止任何假数据进入应用代码。
快速安装
前置：Python 3.10+，Node.js 18+，npm
# 后端（加载 Qwen2.5-0.5B-Instruct，Apple MPS / CPU 回退）
cd backend
python3 -m venv .venv --system-site-packages
source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn app.main:app --app-dir . --port 8000
# 前端
cd frontend
npm install
npm run dev # → http://localhost:3000
无本地模型文件也可运行（默认通过 HuggingFace 加载 Qwen2.5-0.5B-Instruct）。如需本地 GGUF 推理，额外安装：
pip install -r backend/requirements-gguf.txt
⚠️ 注意：首次启动会下载约 1GB 模型权重，国内网络需配置代理或提前用
huggingface-cli download缓存。
核心用法
四种可视化模式
| 模式 | 用途 |
|---|---|
| Architecture | 总览模型结构，3D 展示 GQA、SwiGLU、RoPE 等组件的空间分布 |
| Generation | 输入文本，实时观看 token 生成过程中各层激活值 |
| Walkthrough | 引导式探索，按论文逻辑逐步拆解 Transformer 组件 |
| Debugger | 设置断点，对单层或单算子做激活 ablation |
关键 API 端点（后端 :8000）
# 健康检查
GET /health
# 模型架构元数据（张量形状、层数、头数等）
GET /architecture
# 返回示例（Qwen2.5-0.5B-Instruct）：
{
"model": "Qwen/Qwen2.5-0.5B-Instruct",
"device": "mps",
"num_layers": 24,
"num_heads": 14,
"hidden_size": 896,
"attn_implementation": "eager",
"ready": true
}
# 文本前向传播分析（需传 sentence，~40 tokens 上限）
POST /analyze
Body: { "sentence": "The cat sat on the mat." }
# 流式文本生成（WebSocket）
# 客户端首帧：
{ "prompt": "Name one primary color.", "max_new_tokens": 40, "trace": true }
# 服务器按帧返回：op catalog → token frame → top-k logits
模型支持
| 模型系列 | 支持情况 |
|---|---|
| Qwen 2.5 | ✅ 实时加载（HuggingFace） |
| Llama 2/3/3.2 | ✅ |
| Gemma | ✅ |
| Mistral / Mixtral | ✅ |
| DeepSeek / MoE | ✅ |
| GPT-2 / Pythia | ✅ |
| 本地 .gguf 文件 | ✅（拖拽上传，纯客户端解析，无上传） |
⚠️ 注意：GGUF 量化推理时，llama.cpp 不暴露逐层激活，Layer 照明在该模式下自动禁用而非用假数据填充。
典型适用场景
- 学习 Transformer 机制：通过 Walkthrough 模式，按论文结构逐步理解 Attention、FFN、RoPE 的数学直觉与代码实现的对应关系。
- 教授 LLM 可解释性：Architecture 模式的 3D 展示可用于讲座或教程，直观展示 GQA 中 Q 头与 KV 头的几何关系。
- 调试模型行为：输入特定提示词，在 Generation 模式观察中间激活异常；Debugger 模式支持激活 ablation。
- 验证模型结构：用
/architecture端点核对开源模型的真实参数量（Qwen2.5-0.5B 报告 494,032,768 参数 = 290 个真实张量的精确求和）。 - LLM 工程教育：理解 prefill（完整提示一次处理）vs. decode（逐 token 自回归生成）的计算差异在实际 UI 中的表现。
坑与注意
| 坑点 | 说明 |
|---|---|
| 首次下载模型慢 | Qwen2.5-0.5B-Instruct 约 1GB，HuggingFace 下载可能超时，建议提前用 huggingface-cli download Qwen/Qwen2.5-0.5B-Instruct 缓存 |
| Apple MPS 时序精度有限 | 层间耗时测量为 wall-clock 真实时间，MPS/CUDA 下无法精确同步，UI 标记为 PROXY · NOT MS，不作为精确性能数据使用 |
| GGUF 量化无逐层激活 | llama.cpp 不暴露 per-layer activations，相关可视化功能自动降级，而非显示伪造数据 |
| 注意力 ≠ 因果证明 | 高注意力质量分是线索，不是该 token"必须需要该 token"的证据；README 明确警告不要将注意力权重误读为因果关系 |
| 句子长度限制 | /analyze 对输入句子有约 40 tokens 上限，超长文本需自行分句后多次调用 |
| CORS 限制 | 后端 CORS 仅允许 http://localhost:3000，前端开发服务器端口必须为 3000 |
与同类对比
| 工具 | 实时推理 | 3D 渲染 | GGUF 支持 | 数据溯源 |
|---|---|---|---|---|
| Token-Print | ✅ 真实 forward pass | ✅ React Three Fiber | ✅ | ✅ Provenance 标签 |
| Transformer Explainer (PMLP) | 静态模拟 | ❌ | ❌ | ❌ |
| BERT-Viz | 激活可视化 | ❌（2D） | ❌ | ❌ |
| Pinn | ✅（实验性） | ❌ | ❌ | 部分 |
| Netron | ❌（仅结构） | ✅ | ❌ | ❌ |
核心差异：Token-Print 是目前唯一将实时真实推理、3D WebGL 可视化、GGUF 本地执行和严格数据溯源四者结合的开源工具。
一句话推荐结论
如果你想真正看见一个 LLM 在推理时每一层、每个注意力头在做什么——而非看静态示意图或假数据——Token-Print 是目前最诚实的选择，数据可信度在同类工具中无出其右，适合研究者和严肃学习者使用。
⚠️ 本仓库为技术教育与可解释性研究工具，不应用于绕过模型安全策略或未授权分析闭源模型。