TransformerLens

生成式语言模型的机制可解释性库。由 Bryce Meyer 和 Jonah Larson 维护；由 Neel Nanda 创建

这是一个用于对 GPT-2 风格语言模型进行机制可解释性研究的库。机制可解释性的目标是获取一个训练好的模型，并从其权重中逆向工程出模型在训练过程中学习到的算法。

TransformerLens 允许您加载 140 多个架构家族的 15,000 多个开源语言模型，并向您公开模型的内部激活值。您可以缓存模型中的任何内部激活值，并添加函数来在模型运行时编辑、移除或替换这些激活值。

快速开始

安装

pip install transformer_lens

Python 3.8 或 3.9

pip install 'transformer_lens~=2.0'

用途

from transformer_lens.model_bridge import TransformerBridge

# Load a model (eg GPT-2 Small)
bridge = TransformerBridge.boot_transformers("gpt2", device="cpu")

# Run the model and get logits and activations
logits, activations = bridge.run_with_cache("Hello World")

门控模型（Llama、Mistral、Gemma 等）要求环境中设置 HF_TOKEN。完整列表请参见环境变量。

TransformerBridge 是推荐的使用方式，支持 140 多个架构系列的 15,000 多种模型（完整清单见 supported_models.json）。默认情况下，它保留原始的 HuggingFace 权重——输出 logits 和激活值与 HF 模型匹配，而非旧版 HookedTransformer（后者默认折叠 LayerNorm 并对权重进行中心化处理）。启动后调用 bridge.enable_compatibility_mode() 可获得与 HookedTransformer 等效的数值结果。旧版 HookedTransformer.from_pretrained API 仍可使用，但已弃用——请参见迁移至 TransformerLens 3 指南。

核心教程

• 库与机制可解释性简介
• TransformerLens 主要功能演示

研究成果展示

使用 TransformerLens 开展的研究：

• 通过机制可解释性衡量 Grokking 进展（ICLR 亮点论文，2023）作者：Neel Nanda、Lawrence Chan、Tom Lieberum、Jess Smith、Jacob Steinhardt
• 大海捞针：稀疏探针案例研究 作者：Wes Gurnee、Neel Nanda、Matthew Pauly、Katherine Harvey、Dmitrii Troitskii、Dimitris Bertsimas
• 迈向机制可解释性的自动化电路发现 作者：Arthur Conmy、Augustine N. Mavor-Parker、Aengus Lynch、Stefan Heimersheim、Adrià Garriga-Alonso
• 实际上，Othello-GPT 具有线性涌现的世界表征 作者：Neel Nanda
• 4 层纯注意力 transformer 中的 Python 文档字符串电路 作者：Stefan Heimersheim 与 Jett Janiak
• 普适性的玩具模型（ICML，2023）作者：Bilal Chughtai、Lawrence Chan、Neel Nanda
• N2G：量化大型语言模型中可解释神经元表征的可扩展方法（2023，ICLR 研讨会 RTML）作者：Alex Foote、Neel Nanda、Esben Kran、Ioannis Konstas、Fazl Barez
• 使用 Tuned Lens 从 Transformer 中提取潜在预测 作者：Nora Belrose、Zach Furman、Logan Smith、Danny Halawi、Igor Ostrovsky、Lev McKinney、Stella Biderman、Jacob Steinhardt

用户贡献的库实际应用示例：

• 归纳头相变复现：Connor Kissane 对上下文学习与归纳头的部分复现
• 决策 Transformer 可解释性：一组用于训练决策 Transformer 的脚本，使用 TransformerLens 查看中间激活、执行归因和消融实验。初始工作的说明可参见此处。

更多 TransformerLens 实际应用示例，请查看我们的演示文件夹。

机制可解释性入门

机制可解释性是一个非常年轻且规模较小的领域，存在大量未解决的问题。这意味着该领域既有许多低垂的果实（容易实现的目标），也意味着入门门槛较低——如果你想提供帮助，不妨尝试解决其中一个问题！对于“为什么还没有人做这件事”，标准答案往往就是：人手不足！核心资源：

• 机制可解释性入门指南
• Callum McDougall 的 ARENA 机制可解释性教程。这是一套全面的机制可解释性实践入门教程，使用 TransformerLens 编写，包含大量可复制的代码片段，并配有练习和解决方案！值得关注的教程：
  • 从零开始编写 GPT-2，附带我的视频教程（第一部分、第二部分）——这是了解 Transformer 的良好入门
  • 机制可解释性与 TransformerLens 简介：通过研究归纳头（induction heads）来介绍 TransformerLens 和机制可解释性。涵盖了该库的基本概念
  • 间接宾语识别（Indirect Object Identification, IOI）：一项真实场景下的可解释性复现研究，涵盖了机制可解释性的标准技术，例如 直接 logit 归因（direct logit attribution）、激活修补与路径修补（activation patching and path patching）
• 机制可解释性论文阅读清单
• 机制可解释性领域的 200 个具体开放问题
• 机制可解释性综合术语解释：用于查询你可能遇到的所有行话和不熟悉的术语！
• Neel Nanda 的 YouTube 频道：一系列机制可解释性视频内容，包括 论文解读 和 研究实践演示

支持与社区

如果您遇到问题、有疑问、需要新功能或发现错误，请先搜索相关议题，查看是否已有解答。如果没有，请创建新议题！

您也欢迎加入 Slack 上的开源机制可解释性社区。具体的软件包相关讨论请使用议题，而 Slack 则适用于更高频的交流，例如支持重要的新用例，或者您想对库进行重大贡献并希望获得维护者的意见。我们也非常期待您在 Slack 上分享您的项目！

❗ HookedSAETransformer 已移除

Hooked SAE 已在 TransformerLens 2.0 版本中移除。相关功能正在迁移至 SAELens。有关此版本的更多信息，请参阅随附的 公告，了解新增内容以及 TransformerLens 的未来规划。

Mamba / SSM 支持（实验性）

TransformerLens 包含适用于 Mamba-1（state-spaces/mamba-*-hf）和 Mamba-2（AntonV/mamba2-130m-hf、state-spaces/mamba2-* 等）的桥接适配器。这些适配器支持：

• 前向传播（与 Hugging Face 实现逐位等效）
• 基于钩子的投影激活值 introspection（Mamba-1 包括 in_proj、conv1d、x_proj、dt_proj、out_proj；Mamba-2 包括 in_proj、conv1d、inner_norm、out_proj）
• 具有缓存感知解码步骤的有状态生成
• compute_effective_attention 工具（位于 transformer_lens.model_bridge.supported_architectures.mamba2），用于生成 Mamba-2 的 SSD 派生注意力矩阵，以便与 transformer 的注意力模式进行比较

验证工作位于集成测试 tests/integration/model_bridge/test_mamba_adapter.py 和 tests/integration/model_bridge/test_mamba2_adapter.py 中（共 81 个测试），并且 verify_models 基准测试套件现在已涵盖 SSM 和混合模型系列。Mamba-1、Mamba-2、gated-delta-net（Qwen3.5 / Qwen3-Next）、NemotronH 和 GraniteMoeHybrid 均声明 applicable_phases = [1, 2, 3, 4]，因此它们的前向一致性（P1，与原始 Hugging Face 模型对比）、钩子/缓存覆盖率（P2/P3，跳过 SSM 所缺乏的 HookedTransformer 对比）以及生成质量（P4）均像其他 transformer 一样进行基准测试。

致谢

本库由**Neel Nanda** 创建，并由**Bryce Meyer** 维护。

TransformerLens 的核心功能在很大程度上受到了 Anthropic 出色的 Garcon 工具 界面的启发。感谢 Nelson Elhage 和 Chris Olah 开发了 Garcon，并展示了优质基础设施对于推动探索性研究的价值！

创建者说明（Neel Nanda）

我（Neel Nanda）曾在 Anthropic 可解释性团队 工作。离开后，当我尝试进行独立研究时，开源工具的现状让我感到非常沮丧，于是我编写了这个库。现有的优秀基础设施（如 HuggingFace 和 DeepSpeed）大多用于使用或训练模型，但很少有工具能深入模型内部并逆向工程其工作原理。本库旨在解决这一问题，即便你不在拥有完善基础设施的企业机构工作，也能轻松进入该领域！机制可解释性的一大优势在于，它不需要大型模型或大量计算资源。许多重要的开放问题都可以通过 Colab 笔记本中的小型模型来解决！

引用

请按以下格式引用本库：

@misc{nanda2022transformerlens,
    title = {TransformerLens},
    author = {Neel Nanda and Joseph Bloom},
    year = {2022},
    howpublished = {\url{https://github.com/TransformerLensOrg/TransformerLens}},
}