lyramakesmusic/neuron-explorer

它是什么

一个用于探索大型语言模型（Qwen3.5-4B）内部“神经元”的工具。它系统地测试在文本生成过程中人为增强或抑制每个神经元时会发生什么，保存每个实验，并在模型的交互式 3D 视图中显示结果。

工作原理

该项目分为两部分：

1. 扫描 — 在 GPU 服务器上运行的批处理流水线。它按测量量上下推动层中的每个神经元，生成文本，并记录输出。
2. 探索器 — 一个本地 Web 应用，在您自己的机器上加载模型，让您浏览所有扫描结果、运行实时实验，并与 AI 助手讨论您的发现。

探索器（Web 应用）

运行在 localhost:8791。它读取扫描的输出文件并在本地加载模型（Apple silicon、NVIDIA GPU 或 CPU）以进行实时交互。它有五个面板：

• 地图 — 模型层的 3D 视图；每个神经元是一个点。悬停显示该神经元转向什么以及它预测什么 token；点击打开其详细信息。内部结构相似的神经元彼此相邻放置。
• 列表 — 神经元按它们围绕特定单词聚类的强度排名，与随机基线进行比较。您可以搜索 token，或运行自己的文本并查看哪些神经元被激活。
• 神经元 — 针对单个神经元：不同剂量的转向文本生成、三方聊天（向下转向 / 中性 / 向上转向）、与其他神经元的连接以及名称。
• 嵌入 — 层实验的 UMAP 投影，按神经元、提示、剂量或种类着色。
• Claude — 使用 claude 命令行工具（如果已安装并登录）的聊天，探索器充当工具服务器。Claude 可以读取神经元数据、运行实时模型（转向、激活、下一个 token 概率、消融）、导航地图和列表，并使用文件和 shell 工具。它只在您自己的机器上回答。

扫描（数据流水线）

使用修改版 vLLM 推理引擎在 CUDA GPU pod 上运行。关键步骤：

• 设置 — 安装修改版 vLLM、依赖项和模型。
• 神经元统计 — 计算每个神经元的统计信息：激活极值、下投影列、残差范数。
• 主扫描 — 对于每个神经元，在向上或向下推动神经元的情况下生成文本。剂量是离开层的残差范数中位数的分数：三个提示（“who”、“snake”、“orange”）各三个剂量（−0.7、+0.5、+0.8），一个 +3 的“自由”条件，以及每个提示一个未转向的基线。
• 深度扫描 — 跨多个层的随机子集扫描。

支持脚本生成排名（独特单词、聚类质量与对照）、“转向透镜”（每个神经元如何改变下一个 token 概率）、每层深度报告、词移分数、合并分片、两个推理引擎之间的等价性检查、吞吐量基准，以及探索器使用的缓存数据（嵌入、布局、连接 — 每个神经元的 24 个最强上下链接）。

备注

research_log.md 保存项目的发现和推理；NOTES.md 保存源代码注释。