neuronscope

NeuronScope

询问大模型“你为什么这么说”，即可通过命令行或 MCP 上的 Agent，以 JSON 格式获取真正导致该输出的注意力头和神经元。

安装

pip install neuronscope-cli

这会安装 neuronscope 命令。若要从源代码安装（用于开发或跟踪 main），请改用：

git clone https://github.com/RudrenduPaul/NeuronScope
cd NeuronScope
pip install -e .

说明

首次运行任何命令时，都会从 HuggingFace Hub 下载所请求的模型（gpt2 约为 500MB），并向 stderr 输出两行预期信息，而非错误：如果你没有 CUDA GPU，会显示 CPU 回退提示；还会显示未经身份验证的 HF Hub 速率限制提示。这两条信息都不表示出了问题。

快速入门

neuronscope trace gpt2 "The capital of France is Paris. The capital of Japan is" --top-k 5

以下是运行此命令的实际输出（stderr 中仅保留了上文提到的两条预期警告）：

Prompt: The capital of France is Paris. The capital of Japan is
Predicted next token: ' Tokyo'
Top attention heads (by direct logit
            attribution)
┏━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Layer ┃ Head ┃ Logit attribution ┃
┡━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│     9 │    8 │            4.0679 │
│     8 │   11 │            2.9028 │
│    10 │    7 │           -1.4782 │
│     8 │   10 │           -1.3999 │
│    10 │    0 │            1.1424 │
└───────┴──────┴───────────────────┘
Top MLP neurons (by activation
          magnitude)
┏━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
┃ Layer ┃ Neuron ┃ Activation ┃
┡━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
│    10 │     97 │     7.8394 │
│    11 │    611 │     4.6954 │
│    11 │   2997 │     4.6468 │
│    10 │   1793 │     4.5443 │
│     9 │   1460 │     4.4196 │
└───────┴────────┴────────────┘

gpt2 正确预测了 Tokyo，而头 L9H8 是对该预测贡献最大的单个因素。添加 --json，即可获取相同结果的机器可读版本：

neuronscope trace gpt2 "The capital of France is Paris. The capital of Japan is" --top-k 3 --json

{
  "schema_version": 1,
  "operation": "trace",
  "model": {
    "requested_name": "gpt2",
    "resolved_name": "gpt2",
    "backend": "transformer_lens",
    "device": "cpu",
    "n_layers": 12,
    "n_heads": 12,
    "d_model": 768,
    "d_mlp": 3072
  },
  "prompt": "The capital of France is Paris. The capital of Japan is",
  "predicted_token": " Tokyo",
  "predicted_token_id": 11790,
  "top_neurons": [
    { "layer": 10, "neuron_index": 97, "activation": 7.839381217956543 },
    { "layer": 11, "neuron_index": 611, "activation": 4.695372581481934 },
    { "layer": 11, "neuron_index": 2997, "activation": 4.646785736083984 }
  ],
  "top_heads": [
    { "layer": 9, "head_index": 8, "logit_attribution": 4.067923545837402 },
    { "layer": 8, "head_index": 11, "logit_attribution": 2.9028172492980957 },
    { "layer": 10, "head_index": 7, "logit_attribution": -1.4781968593597412 }
  ]
}

功能介绍

NeuronScope 是一个 CLI 和 MCP 服务，基于 TransformerLens 构建。TransformerLens 负责实际的模型加载、钩子设置和激活值计算；NeuronScope 则在此基础上提供稳定的 CLI、 有版本号的 JSON 架构和 MCP 服务，让脚本或 Agent 无需直接编写 TransformerLens 代码， 就能询问“哪些组件推动了这段输出”。

• trace：将提示词输入模型，并根据对预测 token 的直接 logit 归因对注意力头进行排序， 同时按提示词最后一个位置的激活值大小对 MLP 神经元进行排序。
• activations：输出每一层残差流、MLP 神经元激活值和注意力模式的形状、均值、标准差、 最小值/最大值，以及激活值最大的序列位置。
• patch：在指定层对一个组件（resid_pre、resid_mid、resid_post、 attn_out、mlp_out 或 mlp_post）进行置零消融，并报告预测 token 及其 logit 的变化。
• circuit：尽力生成自动化电路草图。先按 logit 归因对候选注意力头/神经元排序， 再通过单组件消融测量每个组件的单独因果效应。这并非使用干净/损坏提示词对进行的完整路径修补， 也无法捕捉组件间的交互效应。--json 输出会在 method 字段中明确说明这一点。
• 每条命令都支持 --json，可输出带有 schema_version 标记的文档，而非表格；同样的四种操作 也作为 MCP 工具提供，并通过 .model_dump() 返回相同结构。因此，对于相同输入，CLI 调用和 MCP 工具调用会生成相同的文档。
• 支持哪些模型，取决于 transformer_lens.HookedTransformer.from_pretrained 支持哪些模型。 当前安装 neuronscope-cli 会拉取 TransformerLens 3.6.0，它支持 249 个预训练检查点及别名 （OFFICIAL_MODEL_NAMES），涵盖 GPT-2、Pythia、Llama、Gemma、Qwen 等模型。像 gpt2 这样的小型 模型可在 CPU 上轻松运行。

NeuronScope 不会取代 TransformerLens、nnsight、 SAELens、Anthropic 的 circuit-tracer 或 Neuronpedia。它封装 TransformerLens，用于一项范围更窄的工作： 针对单个提示词，快速、可脚本化且可由 Agent 调用地追踪组件。更深入的机制研究（SAE 训练、 基于 transcoder 的电路图、托管式特征浏览）则交由这些工具完成。

CLI 参考

每条命令都将 MODEL（HookedTransformer.from_pretrained 接受的任意名称，例如 gpt2 或 EleutherAI/pythia-70m）和 PROMPT 作为位置参数。

命令	额外标志	功能
neuronscope trace MODEL PROMPT	--top-k INTEGER（默认值为 10）、--json	为预测的下一个 token 对注意力头（logit 归因）和 MLP 神经元（激活幅度）进行排名
neuronscope activations MODEL PROMPT	--json	输出每层的激活摘要统计（残差流、MLP、注意力模式）
neuronscope patch MODEL PROMPT	--layer INTEGER（必填）、--component [resid_pre|resid_mid|resid_post|attn_out|mlp_out|mlp_post]（必填）、--json	将一个组件归零消融，并报告 logit／预测变化量
neuronscope circuit MODEL PROMPT	--top-k INTEGER（默认值为 10）、--json	通过单组件消融排名，尽力绘制电路草图
neuronscope mcp-server	无	通过 stdio 启动 MCP 服务

全局选项：neuronscope --version、neuronscope <command> --help。退出代码：0 表示成功， 1 表示运行时错误（提示词超出模型的上下文窗口、--layer 超出范围等），2 表示 Click 用法错误（标志无效），3 表示不支持的模型名称。

MCP 服务

NeuronScope 附带一个 Model Context Protocol 服务，让 AI Agent（Claude、Cursor 或任何兼容 MCP 的客户端）可以直接追踪、检查、消融并绘制 电路草图，无需人工手动调用 CLI。

安装附加项：

pip install "neuronscope-cli[mcp]"

将其添加到 MCP 客户端的配置中（对于 Claude Desktop，配置文件为 claude_desktop_config.json）：

{
  "mcpServers": {
    "neuronscope": {
      "command": "uvx",
      "args": ["--from", "neuronscope-cli", "neuronscope-mcp"]
    }
  }
}

该服务提供四种工具：trace、activations、patch 和 circuit。每种工具都通过 .model_dump() 返回与 CLI 的 --json 标志输出完全相同的 pydantic 模型格式 JSON，因此，调用此服务的 Agent 和调用 CLI 的脚本针对相同输入会获得相同文档。一次实际的 trace 调用及其响应如下：

trace(model="gpt2", prompt="The capital of France is Paris. The capital of Japan is", top_k=3)

{
  "schema_version": 1,
  "operation": "trace",
  "predicted_token": " Tokyo",
  "predicted_token_id": 11790,
  "top_neurons": [
    { "layer": 10, "neuron_index": 97, "activation": 7.839381217956543 }
  ],
  "top_heads": [
    { "layer": 9, "head_index": 8, "logit_attribution": 4.067923545837402 }
  ]
}

错误不会越过工具边界向外抛出：每个处理器都会捕获异常，并返回结构化的 ErrorResponse 字典，因此调用 Agent 始终能获得可解析的结果。

警告

NeuronScope 限制了模型大小（默认最多 2B 个参数，NEURONSCOPE_MAX_MODEL_PARAMS） 以及可同时加载的模型数量（默认 1 个，NEURONSCOPE_MAX_CONCURRENT_LOADS）， 但不会为模型加载或前向传递设置超时。如果将此 MCP 服务暴露给不受信任的 Agent 调用， 仍应在进程周围设置资源限制（cgroup、ulimit 或容器的内存／CPU 上限），作为纵深防御， 而不要仅依赖这些进程内限制。

传输方式为 stdio，因此无需托管：MCP 客户端会将服务作为本地子进程启动。源文件：neuronscope/mcp_server.py。

• Claude Code 会读取仓库根目录中的项目级 .mcp.json，也可以通过 claude mcp add neuronscope -- neuronscope-mcp 添加。
• Claude Desktop 会读取其 claude_desktop_config.json（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json， Windows 上的路径为 %APPDATA%\Claude\claude_desktop_config.json），配置位于相同的 "mcpServers" 键下。
• neuronscope mcp-server CLI 子命令仍可用作本地的非 uvx 替代方案，从现有安装启动同一个 stdio 服务。

对比情况

这五个项目都是真实存在且积极维护的项目，但各自承担不同的任务。此表对比的是 CLI／JSON Agent 输出能力和模型覆盖范围，而非可解释性研究的深度；在这方面，TransformerLens、nnsight、SAELens、circuit-tracer 和 Neuronpedia 都比 NeuronScope 更成熟。以下星标数、版本发布信息和最近推送日期均来自各项目在 2026-08-03 的 GitHub API 数据，之后可能会有变化；如需最新数据，请直接查看各项目仓库。

项目	星标数	最近活动	CLI	可供 Agent 调用的结构化输出	模型覆盖范围
TransformerLens	3,750	v3.6.0 于 2026-07-28 发布，2026-08-03 推送	否（Python 库）	否	249 个预训练检查点／别名（其官方列表）
nnsight	1,014	v0.7.0 于 2026-05-05 发布，2026-07-30 推送	否（Python 库）	否（返回张量／Python 对象）	通用支持任何 HuggingFace 或 PyTorch 模型，无固定列表
circuit-tracer（由 Anthropic 编写，已从 safety-research/circuit-tracer 移出）	2,882	v0.5.2 于 2026-07-18 发布，2026-07-18 推送	是	JSON 归因图导出；无 MCP 服务	固定的转码器允许列表：Gemma-2（2B）、Gemma-3（270M-27B）、Llama-3.2（1B）、Llama-3.1（8B Instruct）、Qwen-3（0.6B-14B）、GPT-OSS（20B）
SAELens	1,492	v6.47.0 于 2026-07-28 发布，2026-07-28 推送	否（Python 库）	否	通用支持任何 PyTorch 模型；与 TransformerLens 的集成最深入
Neuronpedia	1,093	持续部署，标签为 v1.0.795	否（托管 Web 应用 + REST API）	REST API 返回 JSON；仅可通过非官方的第三方封装访问 MCP，官方仓库不提供此功能	可通过 TransformerLens 的模型表加载的模型（GPT-2、Gemma-2、Llama、DeepSeek 等）
NeuronScope（本项目）	1	本次提交	是	是：每条命令都支持 --json，另有原生 MCP 服务返回相同的模式	TransformerLens 的 HookedTransformer.from_pretrained 支持的所有模型：249 个检查点／别名

客观而言，NeuronScope 的差异化范围很窄：在这些项目中，只有它在同一个软件包中同时提供 CLI、原生 MCP 服务和有版本号的 JSON 模式；而且它能通用支持 TransformerLens 支持的模型，不像 circuit-tracer 那样限定于固定的转码器允许列表。它并不比这些项目中的任何一个功能更强大、更成熟或使用更广泛。

NeuronScope 是什么？它为何存在？

TransformerLens 提供了用于加载模型和运行带钩子的前向传递的 Python API。这是研究笔记本的合适接口，但并不适用于需要调用子进程并获取 JSON 文档的脚本，也不适用于需要通过 MCP 调用工具的 Agent。NeuronScope 的目的就是提供后一种接口：底层计算保持不变，但经过封装后，CLI 调用或 MCP 工具调用返回的是具有模式版本号的文档，而不是 Python 对象图。

常见问题

这是 TransformerLens、nnsight、SAELens、circuit-tracer 或 Neuronpedia 的替代品吗？ 不是。NeuronScope 直接构建在 TransformerLens 之上，无法完成任何 TransformerLens 本身不能在更底层完成的事情。它不会训练 SAE（SAELens）、使用转码器进行完整的路径修补电路发现（circuit-tracer）、为任意 PyTorch 模型提供原生 Python 的追踪上下文管理器（nnsight），也不会托管可浏览的特征数据库（Neuronpedia）。它是一个 CLI 和 MCP 封装，只覆盖 TransformerLens 一部分功能。

支持哪些模型？ 支持 transformer_lens.HookedTransformer.from_pretrained 支持的所有模型，目前共有 249 个检查点和别名，涵盖 GPT-2、Pythia、Llama、Gemma、Qwen 等。在自己的环境中运行 python -c "from transformer_lens.loading_from_pretrained import OFFICIAL_MODEL_NAMES; print(len(OFFICIAL_MODEL_NAMES))" 即可获取你所安装版本的准确数量，因为 TransformerLens 会持续添加模型。

需要 GPU 吗？ 不需要。像 gpt2 这样的小型模型在 CPU 上也能正常运行；上文的测试套件和快速入门使用的就是 CPU。大型模型在 CPU 上运行会比较慢。即使 Apple Silicon 的 MPS 后端可用，NeuronScope 也不会自动选择该后端，因为对于本项目的激活修补数学运算所依赖的精确结果，PyTorch 的 MPS 后端可能会悄无声息地给出错误值。如果你仍想使用它，可以在自己的代码中显式传入 device="mps"。

将 MCP 服务暴露给不受信任的 Agent 安全吗？ 只有在设置资源限制的情况下才安全。请参阅下文的已知限制。

NeuronScope 与此列表中的另一个 CLI 工具 circuit-tracer 有何不同？ circuit-tracer 可进行更深入的电路分析（基于训练好的转码器生成完整归因图），但只支持固定允许列表中的模型：Gemma-2、Gemma-3、Llama-3.1/3.2、Qwen-3 和 GPT-OSS。NeuronScope 以分析深度换取适用范围：它支持 TransformerLens 的全部 249 个检查点，无需训练转码器，并内置 MCP 服务，供 Agent 直接调用。代价是，NeuronScope 执行的是单组件 logit 归因和零消融，而不是基于转码器的路径修补。

已安装的版本始终与 PyPI 上的版本一致吗？ 安装后运行 neuronscope --version 进行检查。pip install neuronscope-cli 会安装 PyPI 最新发布的版本；两次发布之间，此仓库 main 分支上的代码可能会更新得更早。通过源码安装（pip install -e .）则始终与 main 完全同步，包括尚未发布的内容。

NeuronScope 采用什么许可证？可以用于商业用途吗？ MIT。你可以在商业和闭源项目中使用、修改和重新分发，但须注明出处并保留许可证声明。它引入的依赖（TransformerLens、PyTorch、mcp 包）各自采用不同许可证；如果你要重新分发捆绑产品，而不只是将 neuronscope-cli 作为依赖调用，请分别检查这些许可证。

已知限制

• **circuit 是一种近似分析。**它根据 logit 归因对组件进行排名，并通过在一个提示词上对单个组件进行零消融来衡量各组件的独立因果效应。它不会使用干净/损坏的提示词对进行完整的路径修补，也无法捕捉组件之间的交互效应。--json 输出会在 method 字段中说明这一点，调用方无需相信文字描述也能了解这一限制。
• **模型加载和前向传播没有超时。**请求通过下文的资源上限检查后，NeuronScope 会执行加载和前向传播直至完成，不设内置的运行时间上限。如果在不受信任的 Agent 可以调用 MCP 服务的环境中运行它，请对进程设置资源限制（cgroup、ulimit 或容器内存/CPU 上限），作为纵深防御。
• 模型大小和加载并发数设有上限，但仅在进程内生效。neuronscope/core/limits.py 会在下载任何权重前，拒绝超过 NEURONSCOPE_MAX_MODEL_PARAMS（默认 2B 参数）的模型；如果已有 NEURONSCOPE_MAX_CONCURRENT_LOADS（默认 1）个其他加载任务正在进行，也会拒绝加载。两种情况都会返回结构化错误，而非挂起或崩溃。大小检查尽力而为：如果无法确定模型的参数数量（例如，完全离线且尚无缓存），检查会默认放行，而不会阻止合法请求，因此它本身并非硬性保障——在不受信任的部署中，应同时设置进程级资源限制。
• **上游已弃用 HookedTransformer.from_pretrained。**TransformerLens 3.6.0 会发出 DeprecationWarning，指出替代方案是 TransformerBridge.boot_transformers。目前它仍可正常使用，本 README 中展示的每条命令也都在其上运行过，但 NeuronScope 的后端尚未迁移。此项已列为待办事项；迁移只需修改 neuronscope/backends/transformer_lens.py，无需改动任何 CLI 命令或 MCP 工具签名。

参与贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md，了解开发环境设置、代码位置，以及 PR 合并前需要满足的条件。简要说明如下：

pip install -e ".[dev,mcp]"
pytest -v

每次向 main 推送或提交拉取请求时，CI 都会在 Python 3.10、3.11 和 3.12 上运行同一套测试。测试套件覆盖了 neuronscope/ 的 87%（pytest --cov=neuronscope）；主要未覆盖部分是 MCP 服务中较少执行的路径（特定错误分支）。

许可证

MIT。请参阅 LICENSE。