MNIST 多层感知机可视化工具

这是一个交互式的网页可视化工具，用于展示在 MNIST 手写数字数据集上训练的一个紧凑型多层感知机模型。您可以绘制一个数字，观察激活值在三维网络中的传播，并实时查看预测概率。

开发中

目前该项目仍处于初步阶段，正在积极开发中。如果您希望将其用于博物馆等场所，请稍后再来查看。我计划添加一些功能（例如连接平板电脑直接书写数字），以使其成为一款优秀的教育类可视化工具。

仓库结构

• index.html / assets/ – 静态的 Three.js 可视化工具及 UI 资源。
• exports/mlp_weights.json – 默认权重文件，包含时间线快照（由最近一次训练生成）。
• training/mlp_train.py – PyTorch 脚本，用于训练 MLP 模型（在可用时利用 Apple Metal 加速），并导出前端所需的权重文件。

快速开始

1. （仅限训练）安装 Python 依赖（PyTorch + torchvision）：

   python3 -m pip install torch torchvision
   

2. 从仓库根目录启动静态文件服务器（任何服务器均可；此处以 Python 为例）：

   python3 -m http.server 8000
   

3. 在浏览器中打开 http://localhost:8000。您可以在 28×28 的网格上绘图（左键画笔，右键橡皮擦），并使用鼠标或触控板探索三维网络。

训练与导出新权重

training/mlp_train.py 脚本会训练一个小型 MLP 模型于 MNIST 数据集，并将权重导出为前端可消费的 JSON 文件。在 Apple Silicon 设备上，脚本会自动使用 Metal (MPS) 加速；否则则回退到 CUDA 或 CPU。

典型用法如下：

python3 training/mlp_train.py \
  --epochs 5 \
  --hidden-dims 128 64 \
  --batch-size 256 \
  --export-path exports/mlp_weights.json

主要选项说明：

• --hidden-dims: 隐藏层大小（默认为 128 64）。请保持网络规模适中，以确保可视化流畅。
• --epochs: 最小训练轮数（默认为 5）。脚本会自动延长训练，直到达到处理 50 倍数据量的里程碑。
• --batch-size: 小批量大小（默认为 128）。
• --device: 强制指定使用 mps、cuda 或 cpu。默认情况下，脚本会选择最佳可用后端。
• --skip-train: 直接导出随机初始化的权重，而不进行训练（适用于调试流程）。

训练完成后，如果导出路径或文件名发生变化，请更新 assets/main.js 中的 VISUALIZER_CONFIG.weightUrl。刷新浏览器即可加载新权重。

训练时间线导出

每个导出的 JSON 文件现在都包含一个 timeline 数组，涵盖 35 个检查点：早期密集采样的快照（约 50、120、250、500、1k、2k、3.5k、5.8k、8.7k、13k、19.5k、28.5k、40k 张图像），随后是数据集倍数的里程碑，从 1 倍逐步到 50 倍。JSON 清单文件本身很小；每个快照的权重会单独存储为 float16 编码的文件，位于 exports/<stem>/NNN_<id>.json 下，前端会按需流式加载这些权重，因此您可以自由浏览时间线，而无需预先下载整个 50 倍运行的数据。使用更新后的脚本重新导出权重，即可为您的训练生成新的时间线数据。

注意事项与提示

• 可视化工具会突出显示每个神经元最强的前 N 条输入连接（可配置），以保持场景清晰易读。
• 颜色编码了激活值的符号和幅度：冷色调表示负值或低激活，暖色调表示强正值贡献。
• 默认导出的权重文件（exports/mlp_weights.json）已包含多次训练的时间线里程碑。如果您想展示不同的训练过程，请重新训练并导出权重。
• 如果您调整了网络架构，请确保导出的 JSON 文件反映新的层大小；前端会根据这些元数据动态构建场景。

部署

生产环境文件应放置在仓库本地的 releases/ 目录下（适合部署到新主机上的 /srv/server/nn-vis）：

• releases/current/ – 由 nginx 提供服务的文件。
• releases/backups/<timestamp>/ – 不可变的备份快照，用于快速回滚（每个快照都会在 .commit 文件中记录提交哈希）。
• releases/.deploy_tmp/ – 部署过程中使用的暂存区域。

从仓库根目录运行以下命令：

./deploy.sh [commit-ish]

如果不指定提交，则部署 HEAD 分支。该脚本会导出指定的提交，暂存至 .deploy_tmp/，然后通过 rsync 同步到 releases/current/ 和一个带时间戳的备份目录。最后，将 nginx 配置指向 current 目录，例如：

server {
    server_name nn-vis.noelith.dev;
    root /srv/server/nn-vis/releases/current;
    index index.html;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

站点启用后，可通过 certbot --nginx -d nn-vis.noelith.dev 申请 TLS 证书。

Neural-Network-Visualisation 快速上手指南

环境准备

本工具包含前端可视化与后端训练两部分，请根据需求准备环境。

• 操作系统：macOS (推荐 Apple Silicon)、Linux 或 Windows。
• 运行时依赖：
  • 浏览器：现代浏览器（Chrome, Firefox, Edge 等），需支持 WebGL。
  • Python：版本 3.8+（仅当需要重新训练模型或导出新权重时需要）。
• Python 库（仅训练用）：
  • torch (PyTorch)
  • torchvision
  • 注：Apple Silicon 用户将自动使用 MPS 加速，NVIDIA 显卡用户自动使用 CUDA，其余使用 CPU。

安装步骤

1. 获取源码

克隆仓库到本地：

git clone https://github.com/DFin/Neural-Network-Visualisation.git
cd Neural-Network-Visualisation

2. 安装 Python 依赖（可选）

如果您只想体验默认的可视化效果，可跳过此步。若需重新训练模型或导出自定义权重，请执行：

python3 -m pip install torch torchvision

(国内用户如遇下载缓慢，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源)

基本使用

启动可视化服务

无需编译，直接通过静态文件服务器启动即可。在项目根目录执行：

python3 -m http.server 8000

交互操作

1. 打开浏览器访问：http://localhost:8000
2. 绘制数字：在左侧 28×28 网格中，左键绘制手写数字，右键擦除。
3. 观察网络：
   • 查看激活值如何在 3D 多层感知机（MLP）中传播。
   • 使用鼠标或触控板旋转、缩放 3D 视图。
   • 实时查看预测概率分布。
4. 时间轴回溯：如果加载了包含时间线的权重文件，可拖动进度条观察模型从随机初始化到训练完成的学习过程。

（进阶）训练并导出自定义权重

若要使用自定义架构或展示不同的训练阶段，运行训练脚本：

python3 training/mlp_train.py \
  --epochs 5 \
  --hidden-dims 128 64 \
  --batch-size 256 \
  --export-path exports/mlp_weights.json

训练完成后，刷新浏览器即可加载新生成的权重数据。如需修改权重文件路径，请更新 assets/main.js 中的 VISUALIZER_CONFIG.weightUrl 配置。