TransformerLens

用于生成式语言模型机制可解释性的库。由 Bryce Meyer 维护，由 Neel Nanda 创建。

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

TransformerLens 允许你加载 50 多种不同的开源语言模型，并将模型的内部激活暴露给你。你可以缓存模型中的任何内部激活，并在模型运行时添加函数来编辑、移除或替换这些激活。

快速入门

安装

pip install transformer_lens

使用

import transformer_lens

# 加载一个模型（例如 GPT-2 Small）
model = transformer_lens.HookedTransformer.from_pretrained("gpt2-small")

# 运行模型并获取 logits 和 activations
logits, activations = model.run_with_cache("Hello World")

重点教程

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

作品集

使用 TransformerLens 完成的研究：

• 通过机制可解释性实现 Grokking 的进展度量（ICLR Spotlight, 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
• 一个仅含注意力机制的四层变压器中的 Python 文档字符串电路，作者：Stefan Heimersheim 和 Jett Janiak
• 普适性的一个玩具模型（ICML, 2023），作者：Bilal Chughtai、Lawrence Chan、Neel Nanda
• N2G：一种可扩展的方法，用于量化大型语言模型中的可解释神经元表征（2023, ICLR Workshop RTML），作者：Alex Foote、Neel Nanda、Esben Kran、Ioannis Konstas、Fazl Barez
• 利用调谐透镜从变压器中提取潜在预测，作者：Nora Belrose、Zach Furman、Logan Smith、Danny Halawi、Igor Ostrovsky、Lev McKinney、Stella Biderman、Jacob Steinhardt

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

• 归纳头相变复现：Connor Kissane 对 上下文学习与归纳头 的部分复现
• 决策变压器可解释性：一组用于训练决策变压器的脚本，使用 transformer lens 查看中间激活、进行归因分析和消融实验。初步工作的总结可以在这里找到 这里。

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

机制可解释性入门

机制可解释性是一个非常年轻且规模较小的领域，仍然存在大量未解决的问题。这意味着既有许多容易入手的任务，进入门槛也相对较低——如果你愿意贡献力量，不妨尝试解决其中一个！对于“为什么至今还没有人去做这件事”这个问题，标准的回答往往就是：缺乏足够的人手！以下是几个关键资源：

• 机制可解释性入门指南
• 来自 Callum McDougall 的 ARENA 机制可解释性教程。这是一份全面的实践性入门指南，基于 TransformerLens 编写，包含大量可直接复制的代码片段，并配有练习题和答案！其中一些值得关注的教程：
  • 从零开始编码 GPT-2，并附有我的配套视频教程（1、2)——这是了解 Transformer 架构的良好起点。
  • 机制可解释性与 TransformerLens 简介：通过研究归纳头来介绍 TransformerLens 和机制可解释性，涵盖了该库的基础概念。
  • 间接宾语识别：这是一个对现有可解释性研究的复现，覆盖了机制可解释性的标准技术，例如 直接 logits 归因、激活插补与路径插补。
• 机制可解释性论文阅读清单
• 机制可解释性中的 200 个具体开放问题
• 机制可解释性综合解释器：用于查阅你在学习过程中遇到的各种术语和陌生概念！
• Neel Nanda 的 YouTube 频道：提供了丰富的机制可解释性视频内容，包括 论文解读以及 研究过程演示。

支持与社区

如果你遇到问题、有疑问、功能需求或 bug 报告，请先在 issue 列表中搜索是否已有解答；如果没有，请提交一个新的 issue！

你也可以加入开源机制可解释性社区的 Slack 讨论组：Slack 链接。请将关于软件包的具体讨论放在 issue 中，而将更高带宽的交流（例如支持重要的新用例，或希望对库做出重大贡献并征求维护者意见）留在 Slack 上。我们也非常欢迎你在 Slack 上分享你的项目进展！

:exclamation: HookedSAETransformer 已移除

Hooked SAE 已在 TransformerLens 2.0 版本中被移除。其功能现已迁移到 SAELens。有关此次发布的更多信息，请参阅随附的 公告，了解新功能及 TransformerLens 的未来发展方向。

致谢

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

TransformerLens 的核心功能深受 Anthropic 优秀工具 Garcon 接口的启发（Garcon 工具页面）。感谢 Nelson Elhage 和 Chris Olah 打造了 Garcon，并展示了良好的基础设施对于推动探索性研究的重要性！

作者注（Neel Nanda）

我曾就职于 Anthropic 的可解释性团队（transformer-circuits.pub），离开后尝试独立开展研究时，我对当前开源工具的状态感到极为沮丧。虽然像 HuggingFace 和 DeepSpeed 这样的框架为模型的使用和训练提供了优秀的基础设施，但用于深入挖掘模型内部机制、反向工程其工作原理的工具却少之又少。本库正是为了解决这一问题而设计的，旨在让即使没有大型基础设施的企业背景的人也能轻松进入这一领域！机制可解释性的优势之一在于，它并不需要庞大的模型或大量的计算资源。许多重要的开放问题仅需一台小型模型和一个 Colab 笔记本即可解决。

引用方式

请按以下格式引用本库：

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

TransformerLens 快速上手指南

TransformerLens 是一个用于对生成式语言模型（如 GPT-2 风格）进行**机械可解释性（Mechanistic Interpretability）**研究的开源库。它允许用户加载 50+ 种开源模型，访问、缓存、编辑或替换模型内部的激活值，从而逆向工程模型学到的算法。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
• Python 版本：建议 Python 3.8 及以上版本。
• 前置依赖：需安装 PyTorch。TransformerLens 将自动处理其他依赖（如 transformers, einops 等）。
• 网络环境：首次运行加载预训练模型时需要访问 Hugging Face。国内用户若遇到下载缓慢问题，建议配置 Hugging Face 镜像源：

  export HF_ENDPOINT=https://hf-mirror.com
  

安装步骤

使用 pip 直接安装最新稳定版：

pip install transformer_lens

若需加速下载，可指定国内镜像源（如清华源）：

pip install transformer_lens -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的使用示例，展示如何加载预训练模型（以 GPT-2 Small 为例），运行前向传播并缓存内部激活值。

import transformer_lens

# 加载预训练模型 (例如: gpt2-small)
model = transformer_lens.HookedTransformer.from_pretrained("gpt2-small")

# 运行模型并获取 logits 和所有内部激活值
logits, activations = model.run_with_cache("Hello World")

# 查看输出维度
print(logits.shape) 
# 查看特定层的激活值 (例如: 第 0 层的残差流)
print(activations["hook_resid_post", 0].shape)

核心功能说明：

• from_pretrained: 一键加载支持的开源模型。
• run_with_cache: 执行推理并自动记录所有中间层的激活状态，返回的 activations 字典可用于后续的分析、干预或可视化。