circuit-tracer

该库实现了用于基于（跨层）MLP transcoders 的特征寻找电路的工具，该方法最初由 Ameisen et al. (2025) 和 Lindsey et al. (2025) 提出。

本库主要完成以下三项任务。

1. 给定一个具有预训练 transcoders 的模型，它可找到电路 / 归因图；也就是说，它计算每个非零 transcoder 特征、transcoder 误差节点以及输入 token 对其他每个非零 transcoder 特征和输出 logit 的直接影响。
2. 给定一个归因图，它可以可视化该图，并允许你标注这些特征。
3. 利用从归因图获得的信息，可对模型的 transcoder 特征进行干预；也就是说，你可以将特征设置为任意值，并观察模型输出如何变化。

快速上手

一种快速开始的方式是试用我们的教程 notebook！

你也可以通过以下三种方式之一来寻找并可视化电路：

1. 在 Neuronpedia 上使用 circuit-tracer——无需安装！只需点击 + New Graph 即可创建你自己的图，或使用下拉菜单选择一个现有图。
2. 通过 Python 脚本或 Jupyter notebook 运行 circuit-tracer。可先从我们的教程 notebook 开始。在 Colab 上，使用其默认免费提供的 GPU 资源即可运行——只需点击 Colab 徽章！更多教程可参见下文 Demos 部分。你也可以使用自己的计算资源，在本地运行这些演示 notebook。
3. 通过命令行界面运行 circuit-tracer。这只能在你自己的计算资源上进行。有关更多操作方法，见 Command-Line Interface。

在相对有限的 GPU 资源下，使用 Gemma-2 (2B) 也是可行的；Colab GPU 拥有 15GB 显存。更充足的 GPU 显存可以减少 offloading，并支持更大的 batch size。

目前，针对你在图中发现的 transcoder 特征对模型进行干预，既可以在脚本或 notebook 中使用 circuit-tracer 时完成，也可以在 Neuronpedia 上针对 Gemma-2 (2B) 完成。要在 Neuronpedia 上执行干预，请确保至少固定了一个节点，然后在子图中点击 “Steer”。

安装

安装此库时，请先克隆它，并在其目录下运行命令 pip install .。

演示

我们在 demos 文件夹中提供了一些演示，用于展示如何使用本库。主演示是 demos/circuit_tracing_tutorial.ipynb，它使用 Gemma 2 (2B) 复现了 这篇论文 中的两项发现。除 Llama 演示外，所有演示均可在 Colab 上运行。

我们还提供了两个简单的归因与干预演示，供希望进一步了解如何使用本库的读者参考：

• demos/attribute_demo.ipynb：演示如何查找电路并对其进行可视化。
• demos/attribution_targets_demo.ipynb：演示如何通过指定归因目标来查找电路，即你希望从中进行归因的特定 logits（或相关量）。
• demos/intervention_demo.ipynb：演示如何在模型上执行干预。

最后，我们提供了一些演示，用于深入探索特定的、已预先计算并预先标注的归因图，并通过执行干预来验证标注图的正确性：

• demos/gemma_demo.ipynb：探索来自 Gemma 2 (2B) 的归因图。
• demos/gemma_it_demo.ipynb：探索来自指令微调 Gemma 2 (2B) 的归因图，并使用基础模型中的 transcoders。
• demos/llama_demo.ipynb：探索来自 Llama 3.2 (1B) 的归因图。Colab 不支持。

我们还为这两个模型提供了多组标注好的归因图，可以在对应的两个演示 notebook 顶部找到。

用法

可用转码器

HuggingFace 上可用

以下转码器可用于 circuit-tracer；这意味着转码器权重与特征均可用（因此在运行可视化服务器时，特征可以正常加载）。你可以将 HuggingFace 仓库名（例如 mntss/gemma-scope-transcoders）用作 ReplacementModel.from_pretrained 的 transcoders 参数，或用作 CLI 中 --transcoder_set 的参数。

• Gemma-2 (2B)：PLTs（最初来自 GemmaScope）以及两种特征数量的 CLTs：426K 和 2.5M
• Llama-3.2 (1B)：PLTs 和 CLTs
• Qwen-3 PLTs：适用于 Qwen-3 0.6B、1.7B、4B、8B 和 14B
• GPT-OSS (20B) CLT
• Gemma-3 PLTs（最初来自 GemmaScope-2）可在此处（270M、1B、4B、12B 和 27B 规模模型，PT 和 IT）找到。它们需要使用 nnsight 后端。
• Llama 3.1 (8B) Instruct：TopK PLTs

本地保存的转码器

使用 ReplacementModel.from_pretrained 加载本地保存的转码器时，需在 transcoders 参数中提供完整根路径（而非相对路径），例如 /path/to/local_transcoders/。在此情况下，若要启用特征可视化，必须将可视化服务器指向本地特征数据，方法是把 serve 中的可选参数 features_dir 设置为同一目录；例如：

serve(data_dir=graph_path, port=port, features_dir='/path/to/local_transcoders/')

选择后端

默认情况下，circuit-tracer 会创建一个继承自 TransformerLens 的 HookedTransformer 类的 ReplacementModel。不过，TransformerLens 并不支持所有 HuggingFace 模型；它仅支持已在 TransformerLens 中实现的模型。

使用 backend='nnsight' 创建 ReplacementModel，会创建一个基于 nnsight 的 ReplacementModel，其继承自 nnsight 的 TransformersModel 类；这种方式支持大多数 HuggingFace 模型。也就是说，你可以使用 ReplacementModel.from_pretrained(model_name, backend='nnsight') 创建一个 nnsight 的 ReplacementModel。不过需要注意的是，nnsight 后端目前仍属实验性：它的速度更慢、内存效率更低，并且可能无法提供 TransformerLens 版本的全部功能。

缓存

要在 transcoders 上使用 lazy_decoder 和 lazy_encoder 选项，必须以 circuit-tracer 兼容的格式存储它们。虽然许多 transcoders 已经以这种格式上传到 HuggingFace，但这需要大量存储空间。circuit-tracer 现在也支持改为创建模型的本地缓存，例如通过调用

from circuit_tracer.utils.caching import save_transcoders_to_cache

hf_ref = "mwhanna/gemma-scope-2-27b-pt/transcoder_all/width_262k_l0_small"
cache_dir = "~/.cache/"
save_transcoders_to_cache(hf_ref, cache_dir=cache_dir)

你还可以通过 circuit_tracer.utils.caching.empty_cache 清空缓存。

命令行界面

统一的 CLI 会执行完整的 3 步流程，用于查找并可视化 circuit：

3 步流程

1. 归因：运行归因算法，以查找 circuit/归因图，并计算 transcoder 特征、误差节点、token 和输出 logits 之间的直接效应。
2. 图文件创建：对归因图进行剪枝，移除低效应节点和边，然后将其转换为适合可视化的 JSON 格式。
3. 本地服务器：启动一个本地 Web 服务器，以便在浏览器中可视化并与该图进行交互。

基本用法

若要查找 circuit、创建图文件并启动本地服务器，请使用以下命令：

circuit-tracer attribute --prompt [prompt] --transcoder_set [transcoder_set] --slug [slug] --graph_file_dir [directory] --slug [slug] --graph_file_dir [graph_file_dir] --server

它会告诉你服务器正在哪个地址提供服务（类似 localhost:[port]）。如果在远程机器上运行此命令，请确保启用端口转发，以便在本地查看这些图！

必填参数

归因

• --prompt (-p): 要分析的输入提示
• --transcoder_set (-t): 用于归因的 transcoders 集合。选项：
  • HuggingFace 仓库 ID（例如：mntss/gemma-scope-transcoders、username/repo-name@revision）
  • 便捷简写：gemma（GemmaScope transcoders）或 llama（ReLU transcoders）
  • 本地保存的 transcoders 路径：/path/to/local_transcoders/

图文件创建

如果你希望运行本地 Web 服务器进行可视化，则必须提供以下参数：

• --slug: 用于标识此次分析运行的名称/标识符
• --graph_file_dir: 保存 JSON 图文件的目录路径

你也可以保存原始归因图（以便后续在 Python 中加载和使用）：

• --graph_output_path (-o): 保存原始归因图（.pt 文件）的路径

必须设置 --slug 和 --graph_file_dir，或 --graph_output_path，或两者都设置！否则 CLI 将不会输出任何内容。

本地服务器

• --server: 启动用于图可视化的本地 Web 服务器

可选参数

归因参数：

• --model (-m): 模型架构（对 gemma 和 llama 预设自动推断）
• --max_n_logits (默认: 10): 最多用于归因的 logit 节点数
• --desired_logit_prob (默认: 0.95): top logits 的累计概率阈值
• --batch_size (默认: 256): 用于反向传播的批大小
• --max_feature_nodes: 最大特征节点数（默认为 7500）
• --dtype: 加载模型 / transcoders 时使用的数据类型（允许：float32/fp32、float16/fp16、bfloat16/bf16）
• --offload: 内存优化选项（cpu、disk 或 None）
• --verbose: 显示详细进度信息

图剪枝参数：

• --node_threshold (默认: 0.8): 保留累计影响 ≥ 阈值所需的最少节点
• --edge_threshold (默认: 0.98): 保留累计影响 ≥ 阈值所需的最少边

服务器参数：

• --port (默认: 8041): 本地服务器端口
• --features_dir (默认: None): 若使用本地 transcoders，包含本地服务器特征文件的目录路径

示例

包含可视化的完整工作流：

circuit-tracer attribute \
  --prompt "The International Advanced Security Group (IAS" \
  --transcoder_set gemma \
  --slug gemma-demo \
  --graph_file_dir ./graph_files \
  --server

仅归因（保存原始图）：

circuit-tracer attribute \
  --prompt "The capital of France is" \
  --transcoder_set llama \
  --graph_output_path france_capital.pt

图标注

使用 --server 选项时，浏览器会打开本地可视化界面。该界面与原始论文中的界面一致（前端可在这里获取）。

• 选择节点：点击节点。
• 固定 / 取消固定节点至子图面板：Ctrl+点击 / Command+点击该节点。
• 注释节点：选中节点后，点击窗口右侧的 "Edit" 按钮，编辑其注释。
• 分组节点：按住 G，然后点击节点，将它们组合成一个 supernode。按住 G，然后点击 supernode 旁边的 x，取消全部节点的组合。
• 注释 supernode / 节点组：点击 supernode 下方的标签，编辑该 supernode 的注释。

引用

你可以按以下方式引用该库：

@misc{circuit-tracer,
  author = {Hanna, Michael and Piotrowski, Mateusz and Lindsey, Jack and Ameisen, Emmanuel},
  title = {circuit-tracer},
  howpublished = {\url{https://github.com/decoderesearch/circuit-tracer}},
  note = {The first two authors contributed equally and are listed alphabetically.},
  year = {2025}
}

或引用该论文，详见此处。