decoderesearch/circuit-tracer

# circuit-tracer 本库实现了相关工具，用于利用（跨层）MLP transcoder 的特征来寻找电路，该方法最初由 [Ameisen et al. (2025)](https://transformer-circuits.pub/2025/attribution-graphs/methods.html) 和 [Lindsey et al. (2025)](https://transformer-circuits.pub/2025/attribution-graphs/biology.html) 提出。 我们的库主要执行三项任务： 1. 给定一个带有预训练 transcoder 的模型，它能找到电路 / 归因图；即计算每个非零 transcoder 特征、transcoder 误差节点和输入 token 对其他每个非零 transcoder 特征及输出 logit 的直接效应。 2. 给定一个归因图，它能将此图可视化，并允许你对这些特征进行标注。 3. 利用从归因图中获得的洞察，对模型的 transcoder 特征进行干预；即你可以将特征设置为任意值，并观察模型输出的变化。 ## 入门指南 一个快速开始的方法是尝试我们的[教程笔记本](https://github.com/safety-research/circuit-tracer/blob/main/demos/circuit_tracing_tutorial.ipynb)！ 你还可以通过以下三种方式之一来寻找电路并将其可视化： 1. 在 [Neuronpedia](https://www.neuronpedia.org/gemma-2-2b/graph?slug=gemma-fact-dallas-austin&pinnedIds=27_22605_10%2C20_15589_10%2CE_26865_9%2C21_5943_10%2C23_12237_10%2C20_15589_9%2C16_25_9%2C14_2268_9%2C18_8959_10%2C4_13154_9%2C7_6861_9%2C19_1445_10%2CE_2329_7%2CE_6037_4%2C0_13727_7%2C6_4012_7%2C17_7178_10%2C15_4494_4%2C6_4662_4%2C4_7671_4%2C3_13984_4%2C1_1000_4%2C19_7477_9%2C18_6101_10%2C16_4298_10%2C7_691_10&supernodes=%5B%5B%22state%22%2C%226_4012_7%22%2C%220_13727_7%22%5D%2C%5B%22preposition+followed+by+place+name%22%2C%2219_1445_10%22%2C%2218_6101_10%22%5D%2C%5B%22Texas%22%2C%2220_15589_10%22%2C%2220_15589_9%22%2C%2219_7477_9%22%2C%2216_25_9%22%2C%224_13154_9%22%2C%2214_2268_9%22%2C%227_6861_9%22%5D%2C%5B%22capital+%2F+capital+cities%22%2C%2215_4494_4%22%2C%226_4662_4%22%2C%224_7671_4%22%2C%223_13984_4%22%2C%221_1000_4%22%2C%2221_5943_10%22%2C%2217_7178_10%22%2C%227_691_10%22%2C%2216_4298_10%22%5D%5D&pruningThreshold=0.6&clickedId=21_5943_10&densityThreshold=0.99) 上使用 `circuit-tracer` —— 无需安装！只需点击 `+ New Graph` 来创建你自己的图表，或使用下拉菜单选择现有的图表。 2. 通过 Python 脚本或 Jupyter 笔记本运行 `circuit-tracer`。从我们的[教程笔记本](https://github.com/safety-research/circuit-tracer/blob/main/demos/circuit_tracing_tutorial.ipynb)开始。这可以在默认免费提供的 GPU 资源的 Colab 上运行——只需点击 Colab 徽章！查看下方的 **Demos** 部分以获取更多教程。你也可以在本地使用自己的算力运行这些演示笔记本。 3. 通过命令行界面运行 `circuit-tracer`。这只能在你自己的算力上完成。有关如何执行此操作的更多信息，请参阅 **Command-Line Interface**。 在 GPU 资源相对有限的情况下，也可以处理 Gemma-2 (2B) 模型；Colab GPU 拥有 15GB 的 RAM。更多的 GPU RAM 将允许你减少卸载，并使用更大的 batch size。 目前，无论你是在脚本或笔记本中使用 `circuit-tracer`，还是在 Neuronpedia 上处理 Gemma-2 (2B)，都可以针对你在图中发现的 transcoder 特征对模型进行干预。要在 Neuronpedia 上执行干预，请确保至少固定一个节点，然后点击子图中的“Steer”。 ### 安装 要安装此库，请克隆它并在其目录中运行命令 `pip install .`。 ### 示例 我们在 `demos` 文件夹中包含了一些演示，展示了如何使用我们的库。主要演示是 [`demos/circuit_tracing_tutorial.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/circuit_tracing_tutorial.ipynb)，它使用 Gemma 2 (2B) 复现了[这篇论文](https://transformer-circuits.pub/2025/attribution-graphs/biology.html)中的两项发现。除了 Llama 演示外，所有演示均可在 Colab 上运行。 我们还提供了两个关于归因和干预的简单演示，供希望进一步了解如何使用该库的用户参考： - [`demos/attribute_demo.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/attribute_demo.ipynb)：演示如何寻找电路并将其可视化。 - [`demos/attribution_targets_demo.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/attribution_targets_demo.ipynb)：演示如何通过指定归因目标（即你希望从其进行归因的特定 logit 或相关量）来寻找电路。 - [`demos/intervention_demo.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/intervention_demo.ipynb)：演示如何对模型执行干预。 最后，我们提供了深入研究特定的、预计算和预标注归因图的演示，通过执行干预来证明所标注图表的正确性： - [`demos/gemma_demo.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/gemma_demo.ipynb)：探索 Gemma 2 (2B) 的图表。 - [`demos/gemma_it_demo.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/gemma_it_demo.ipynb)：使用基础模型的 transcoder，探索经过指令微调的 Gemma 2 (2B) 的图表。 - [`demos/llama_demo.ipynb`](https://github.com/safety-research/circuit-tracer/blob/main/demos/llama_demo.ipynb)：探索 Llama 3.2 (1B) 的图表。Colab 不支持此演示。 我们还为这两个模型提供了大量带标注的归因图，可以在它们各自的两个演示笔记本的顶部找到。 ## 用法 ### 可用的 Transcoder **在 HuggingFace 上** 以下 transcoder 可用于 `circuit-tracer`；这意味着 transcoder 的权重和特征均可用（因此当你运行可视化服务器时，特征将正确加载）。你可以使用 HuggingFace 仓库名称（例如 `mntss/gemma-scope-transcoders`）作为 `ReplacementModel.from_pretrained` 的 `transcoders` 参数，或在 CLI 中作为 `--transcoder_set` 的参数。 - Gemma-2 (2B)：[PLTs](https://huggingface.co/mntss/gemma-scope-transcoders)（最初来自 [GemmaScope](https://huggingface.co/google/gemma-scope)）以及具有 2 种特征数量的 CLT：[426K](https://huggingface.co/mntss/clt-gemma-2-2b-426k) 和 [2.5M](https://huggingface.co/mntss/clt-gemma-2-2b-2.5M) - Llama-3.2 (1B)：[PLTs](https://huggingface.co/mntss/transcoder-Llama-3.2-1B) 和 [CLTs](https://huggingface.co/mntss/clt-llama-3.2-1b-524k) - Qwen-3 PLT：适用于 Qwen-3 [0.6B](https://huggingface.co/mwhanna/qwen3-0.6b-transcoders-lowl0), [1.7B](https://huggingface.co/mwhanna/qwen3-1.7b-transcoders-lowl0), [4B](https://huggingface.co/mwhanna/qwen3-4b-transcoders), [8B](https://huggingface.co/mwhanna/qwen3-8b-transcoders) 和 [14B](https://huggingface.co/mwhanna/qwen3-14b-transcoders-lowl0) - [GPT-OSS (20B) CLT](https://huggingface.co/mntss/clt-131k) - Gemma-3 PLT（最初来自 [GemmaScope-2](https://huggingface.co/google/gemma-scope-2)）可在[此处找到大小为 270M、1B、4B、12B 和 27B 的 PT 及 IT 模型](https://huggingface.co/collections/mwhanna/gemma-scope-2-transcoders-circuit-tracer)。这些需要使用 `nnsight` 后端。 - Llama 3.1 (8B) Instruct：[TopK PLTs](https://huggingface.co/facebook/crv-8b-instruct-transcoders) **本地保存的 Transcoder** 通过使用 `ReplacementModel.from_pretrained` 并将完整的根路径（而非相对路径）作为 `transcoders` 参数（例如 `/path/to/local_transcoders/`），可以加载本地保存的 transcoder。在这种情况下，要启用特征可视化，你必须通过将 `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`，它继承自其 `LanguageModel` 类；这支持大多数 HuggingFace 模型。也就是说，你可以使用 `ReplacementModel.from_pretrained(model_name, backend='nnsight')` 来创建一个 `nnsight` `ReplacementModel`。但请注意，`nnsight` 后端仍处于实验阶段：它的速度较慢，内存效率较低，并且可能无法提供 `TransformerLens` 版本的所有功能。 ### 缓存 为了在 transcoder 上使用 `lazy_decoder` 和 `lazy_encoder` 选项，它们必须以 `circuit-tracer` 兼容的格式存储。虽然许多 transcoder 已经以该格式上传到 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 步流程： ### 3 步流程 1. **归因**：运行归因算法以寻找电路/归因图，计算 transcoder 特征、误差节点、token 和输出 logit 之间的直接效应。 2. **创建图表文件**：修剪归因图以移除低效应的节点和边，然后将其转换为适合可视化的 JSON 格式。 3. **本地服务器**：启动本地 Web 服务器，以便在你的浏览器中可视化图表并与之交互。 ### 基本用法 要寻找电路、创建图表文件并启动本地服务器，请使用以下命令： ``` 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`)：用于归因的 transcoder 集合。选项： - HuggingFace 仓库 ID（例如 `mntss/gemma-scope-transcoders`、`username/repo-name@revision`） - 方便的快捷方式：`gemma`（GemmaScope transcoder）或 `llama`（ReLU transcoder） - 本地保存的 transcoder 的路径：`/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 logit 的累积概率阈值 - `--batch_size`（默认值：256）：反向传递的 batch size - `--max_feature_nodes`：特征节点的最大数量（默认为 7500） - `--dtype`：加载模型/transcoder 的数据类型（允许的值：`float32/fp32`、`float16/fp16`、`bfloat16/bf16`） - `--offload`：内存优化选项（`cpu`、`disk` 或 `None`） - `--verbose`：显示详细的进度信息 **图表修剪参数：** - `--node_threshold`（默认值：0.8）：保留累积影响 ≥ 阈值的最少节点 - `--edge_threshold`（默认值：0.98）：保留累积影响 ≥ 阈值的最少边 **服务器参数：** - `--port`（默认值：8041）：本地服务器的端口 - `--features_dir`（默认值：None）：如果使用本地 transcoder，包含本地服务器特征文件的目录路径 ### 示例 **包含可视化的完整工作流：** ``` 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` 选项时，你的浏览器将打开一个本地可视化界面。该界面与[原论文](https://transformer-circuits.pub/2025/attribution-graphs/methods.html)中的相同（前端可在[此处](https://github.com/anthropics/attribution-graphs-frontend)获取）。 - **选择节点**：点击一个节点。 - **将节点固定/取消固定到子图窗格**：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} } ``` 或在此处[引用该论文](https://aclanthology.org/2025.blackboxnlp-1.14/)。

标签：DLL 劫持, 人工智能, 凭据扫描, 大语言模型, 归因分析, 模型可解释性, 用户模式Hook绕过, 稀疏自编码器, 逆向工具