NeuronScope

NeuronScope 询问语言模型“为什么这么说”，并从命令行或通过MCP代理获取实际的注意力头和神经元，作为JSON。 [](https://github.com/RudPaul/NeuronScope/actions/workflows/ci.yml) PI](https://img.shields.io/pypi/v/-cli.svg)](https://pypi.org/project/neuronscopeLicense: MIT](https://img.shields.io-MIT-blue.svg)](https://github.com/Rud/NeuronScope/blob/main/LICENSE)  ## 安装 ```bash pip install neuronscope-cli ``` 这会为您提供`neuronscope`命令。要从源代码安装（用于开发或跟踪`main`）： ```bash git clone https://github.com/RudrenduPaul/NeuronScopeScope pip install -e . ``` **首次命令**都会从HuggingFace Hub下载请求的模型（`gpt2`MB），并打印两stderr，这些是预期的：CPU降级您没有CUDA未经身份验证的HF Hub速率限制通知。两者都不问题。 ## 功能 NeuronScope是一个[MCP](https.io)服务器，构建在[TransformerLens](https://github.com/Org/TransformerLens)Lens实际完成模型加载、钩住和运算；NeuronScope添加了一个稳定的CLI、版本和MCP脚本或代理可以哪些组件驱动了此输出”，而无需直接编写。 - **`：运行一个提示，并按直接对牌的逻辑归因进行排名，按位置的激活幅度P神经元进行排名。 - **`activations`**储每层的形状、均值、标准差、最小值/最大值和最大激活序列位置，用于残差流、MLP神经元激活和注意力模式。 - **`patch`**：在给定层零消一个组件（`resid_pre`、`resid_mid`、`resid_post`、`attn_out`、`ml`或p_post`），并报告预测令牌及其- **`circuit`**：一种尽力自动化电路草逻辑归因头/神经元，然后通过单元法测量的个体因果具有干净/损坏提示对的完整补，也不捕获组件效应。`--输出在`method中明确说明。 - 每个命令都支持`--json带有`schema_version`戳的文档，相同的四个操作CP工具返回，通过()`，因此MCP为相同输入生成。 - 模型`transformer_lens.HookedTransformer`支持。截至`transformer版本，已个预训练检查名（`_MODEL_NAMES`），-2ia、LGemma、Q。像`这样的小模型上舒适地运行Scope不能取代TransformerLens、[nhttps://nnsight、[ens](https:///jbloomAusens)、Anthropic的[circuit-tracer://github.com/decoderesearch/circuit-tracer[Neuronpedia://www.neuron/)。它包装Lens，用于一项更的任务：对单个快速、可脚本代理可调用的组件跟踪。它将更深入的机械工作（SAE训练转码器的电路功能浏览）这些工具。 ##入门 ```bashcope trace gptThe capital of France is Paris. The capital of" --top-k 5 ``` 此确切命令的实际输出（stderr修剪到上述两个预期``` Prompt: of France is Paris. of Japan is : ' Tokyo 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 (by activation magnitude) ┏━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┃ Layer ┃ Neuron ┃ Activation ┃ ┡━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩ │ 97 │ 7.8394 │ │ 11 │ 611 │ 4.6954 │ │ 11 │ 2997 │ 4.6468 │ │ 10 17934.5443 │ │ 1460 │ 4. │ └───────┴────────┴────────────gpt2正确预测`Tokyo`，`L9H8`是该预测的最大。添加`--以获取相同结果可读版本：bash neuronscope trace gpt2 "The capital of France is Paris. The capital of Japan is"-k 3 --``` ```json schema_version": "operation": "trace", { " "gpt2resolved_name": "gpt2", " "transformer_lens", "device": "cpu", "n 12, _heads": 12, "d_model768, "lp": 3072 }, "The capital of. 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, 4372581481934 { "layer":, "neuron_index2997, "activation": 4.646984 } top_heads": [ { "layer, "head8, "ribution": 923545837402 }, { "layer": 8, "head_index": 11, "logit_attribution": 2.9028172492980957 }, { "layer": 10, "head_index": 7, "logit_attribution": -1.4781968593597412 } ] } ``` ## CLI参考 每个命令都接受`MODEL`（`HookedTransformer.from_pretrained`接受的任何名称，例如`gpt2`或`EleutherAI/pythia-70m`）和`PROMPT`作为位置参数。 | 命令 | 额外标志 | 功能 | |---|---|---| | `neuronscope trace MODEL PROMPT` | `--top-k INTEGER`（默认10），`--json` | 按预测下一个令牌的逻辑归因对顶部注意力头进行排名，按激活幅度对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` | 零消一个组件并报告逻辑/预测增量 | | `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服务器 ```bash neuronscope mcp-server ``` 在stdio上启动一个MCP服务器，通过`trace`、`activations``和`circuit`作为MCP与CLI的`--json`输出相同的JSON模式。 要注册到MCP主机，请添加： ```json { "mcpServers": { "neuronscope": { "command": "neuronscope", "args": ["mcp-server"] } } } ``` - **Claude Code** 从项目级别的`.mcp.json`读取，位于您的仓库根目录中，或者您可以使用`claude mcp add neuronscope -- neuronscope mcp-server`添加。 - **Cl** 从其`claude_desktop_config.json`（`~/Library/Application Support/Claude/claude_desktop_config.json`在macOS上，`%APPDATA%\Claude\claude_desktop_config.json`在Windows上）读取，在相同的`"Servers"`键下。 ## 比较 这五个都是真正的、积极维护的项目，做着。下表比较了CLI/JSON代理输出表面和模型覆盖率，而不是性研究的深度，其中TransformerLens、nnsight、SAELens、circuit-tracer和Ne都比NeuronScope更成熟。星数、发布信息和上次推送日期均于2026-07-19从GitHub API拉取，之后会随时间推移而变化；请直接查看仓库以获取当前数字。 | 项目 | 星数 | 最后活动 | CLI |可调用的结构化输出 | 模型覆盖率 | |---|---|---|---|---|---| | [TransformerLens](https://github.com/TransformerLensOrg/TransformerLens) | 3,689 | v3.5.1发布于2026-07-01，推送于2026-07-16 | 否库） | 否 | 247个预训练检查点名（列表） | nnsight://github.comif-team/nnsight) | 995 | v0.7.0发布于2026-05-05，推送于2026-07-14 | 否（Python库） | 否（返回张量/Python对象） | uggingFace或Py通用，无固定| [circuit-tracer](https://github.com/decoderesearch/circuit-tracer) （Anthropic作者，已从`safety-research/circuit-tracer`迁移） | 2,864 | v0.5.2发布于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](https://github.com/jbloomAus/SAELens) | 1,476 | v6.46.0发布于2026-07-13，推送于2026-07-13 | 否（Python库） | 否 | 任意PyTorch模型通用；与TransformerLens集成最深 | | [Neuronpedia](https://github.com/hijohnnylin/neuronpedia) | 1,070 | 持续部署，标签.0.795于2026-07-17 | 否（托管Web应用+REST API） | REST API返回JSON；MCP访问仅通过非官方第三方包装器，不在官方仓库中 | 通过TransformerLens的模型表（GPT-2，Gemma-2，Llama，DeepSeek等）加载的模型 | | **NeuronScope**（该项目） | 新，预发布 | 此提交 | 是 |每个命令的json`，加上一个本地MCP服务器模式 | TransformerLensHooked_pretrained`支持的任意模型：247点/别名 | 诚实的区分很窄：NeuronScope是这几个中唯一具有CLI、本地MCP服务器和一个包中的版本化JSON模式的包，并且它在TransformerLens支持的模型上是模型无关的，而不是像circuit-tracer那样固定在转码器允许列表上。它并不比任何这些项目更具能力、更成熟或更广泛使用。 ## 什么是NeuronScope，为什么它存在 TransformerLens为您提供了一个Python API，用于加载模型和运行钩住的前向传递。对于研究笔记本来说，这是正确的接口。对于需要子进程调用和JSON文档的脚本或代理来说，这是一个错误的接口。NeuronScope的存在是为了成为第二个接口：相同的底层计算，包装在一个CLI调用或MCP工具调用返回一个模式版本文档，而不是Python对象图。 ## 常见问题 **这是否取代了TransformerLens、nnsight、SAELens、circuit-tracer或Neuronpedia？** 不。NeuronScope直接建立在TransformerLens上，不做任何TransformerLens本身已经无法做到的事情。它不训练SAE（SAELens），不进行带有转码器的完整路径修补电路发现（circuit-tracer），不为您提供用于任意PyTorch模型的Python原生跟踪上下文管理器（nnsight），也不托管可浏览Neuronpedia）。它是围绕TransformerCLI和MCP包装器。 **模型？** `transformer_lens.H.from_pretrained`支持的任何模型，目前有247个检查点和别名，涵盖GPT-2、ia、Llama、Gemma、Qwen等。在您自己的环境中运行`python -c "from transformer_lens.loading_from_pretrained import OFFICIAL_MODEL_NAMES; print(lenIAL_MODEL_NAMES))"`，以获取您已安装版本的确切数量，因为TransformerLens时间的推移添加模型。 **是否需要GPU？** 不。像`gpt2`这样的小模型可以在CPU上运行；大型模型在CPU很慢。NeuronScope不会自动选择Apple Silicon的MPS后端，即使可用，因为PyTorch的MPS后端可能会为某些操作默默地产生不正确的值，而该项目的激活修补数学依赖于这些操作的精确性。如果您想要，可以在自己的代码中显式传递`device="mps"`。 **将MCP服务器暴露给不受信任的代理是否安全？** 仅在有资源限制的情况下。参见下面的已知限制。 ## 已知限制 - **`circuit`是一种近似。** 它按逻辑归因对组件进行排名，并通过单个组件零消元法测量每个组件的个体因果效应在一个提示上。它不进行带有干净/损坏提示对的完整路径修补，也不捕获组件之间的交互效应。 `--json`输出在其`method`字段中说明了这一点，以便调用者无需信任散文即可了解警告。 - **或前向传递没有大小限制或超时。** NeuronScope加载调用者请求的模型权重并运行前向传递直到完成，没有模型大小或时钟时间限制。如果您在MCP服务器上运行它，不受信任的代理可以调用它，请在进程周围设置资源限制（cgroup，`ulimit`或容器内存/CPU上限），而不是依赖Scope自己拒绝超大请求。 ## 欢迎提出问题和拉取请求。TRIBUTING.md](CONTRIBUTING.md)了解开发设置、代码位置以及PR合并前需要什么。快速版本： ```bash pip install -e ".[dev]" pytest -v ``` CI在每个推送和拉取请求到`main`时，在Python 3.10、3.11和3.12上运行相同的测试套件。测试套件涵盖了87％的`neuronscope/`（`pytest --cov=neuronscope`），MCP服务器的路径较少被测试（特定的错误分支是主要的## 许可证 MIT。参见[LICENSE](LICENSE)。