TransformerLens 是面向 GPT 风格语言模型机制可解释性研究的标准库，创建者为 Neel Nanda，维护者为 Bryce Meyer。它在 GitHub 上由 TransformerLensOrg/TransformerLens 维护，获得 2900 以上星标。库的核心价值是为模型的每一处激活提供干净的检查与操纵接口（HookPoint），从而支持逆向分析训练中学到的算法。
【用途】 当你需要逆向工程模型在训练中习得的算法、执行激活修补或因果追踪实验、研究注意力模式与信息流、分析电路（如归纳头 induction heads、IOI 电路）、缓存并检查中间激活、进行直接 logit 归因时，适合使用 TransformerLens。 需要在以下情况时考虑替代方案：处理非 Transformer 架构时使用 nnsight 或 pyvene；训练或分析稀疏自编码器时使用 SAELens；需要在超大模型上远程执行时使用 nnsight 配合 NDIF；需要更高层因果干预抽象时使用 pyvene。
【安装】 标准安装：pip install transformer-lens 开发版安装：pip install git+https://github.com/TransformerLensOrg/TransformerLens
【核心概念】 HookedTransformer 是主类，包装 Transformer 模型并在每处激活上放置 HookPoint。加载模型示例： from transformer_lens import HookedTransformer model = HookedTransformer.from_pretrained("gpt2-small") 对于门控模型（LLaMA、Mistral），需设置 HF_TOKEN 环境变量后再加载，例如 meta-llama/Llama-2-7b-hf。
支持的模型超过 50 个，包括 GPT-2 系列（gpt2、gpt2-medium、gpt2-large、gpt2-xl）、LLaMA 系列（llama-7b、llama-13b、llama-2-7b、llama-2-13b）、EleutherAI 系列（pythia-70m 至 pythia-12b、gpt-neo、gpt-j-6b）、Mistral 系列（mistral-7b、mixtral-8x7b），以及 phi、qwen、opt、gemma 等。
【主要能力】 激活缓存：使用 model.run_with_cache(tokens) 运行模型并缓存全部中间激活。可通过 cache["resid_post", 5] 访问第 5 层残差流，cache["pattern", 3] 访问第 3 层注意力模式，cache["mlp_out", 7] 访问第 7 层 MLP 输出。可用 names_filter 参数筛选需要缓存的激活以节省内存。缓存键包括 resid_pre、resid_mid、resid_post、attn_out、mlp_out、pattern、q、k、v 等，各自具有明确的形状与含义。
工作流一：激活修补（因果追踪）。通过将干净激活修补到损坏运行中，识别哪些激活对模型输出有因果影响。步骤包括：定义仅微小差异的干净与损坏提示；缓存干净激活；定义度量（如 logit 差值）；系统地对每个（层，位置）组合进行修补；将结果可视化为热图并识别因果热点。
工作流二：电路分析（间接宾语识别 IOI）。复现论文《Interpretability in the Wild》中的 IOI 电路发现。步骤包括：设置具有明确 IO/S token 的任务；计算基线 logit 差值；按注意力头分解贡献；识别关键电路组件（name movers、S-inhibition、induction）；通过消融实验验证。
工作流三：归纳头检测。寻找实现 [A][B]...[A] → [B] 模式的归纳头。通过检查最终 [A] 位置对第一个 [B] 位置的注意力分数，找出高分注意力头。
【常见问题与解决方案】 钩子残留：调试后旧钩子可能仍然生效，应始终在运行前调用 model.reset_hooks()。 tokenization 陷阱：不同单词可能被切分为不同 token 数量（如 "Neel" 会变成 "Ne" + "el"），应使用 model.to_str_tokens 显式检查。 LayerNorm 被忽略：分析时需包含 LayerNorm，例如使用 model.blocks[layer].ln2(residual) 而非直接对残差做投影。 大模型内存爆炸：使用选择性缓存（names_filter）并将缓存放在 CPU 上。
【关键类】 HookedTransformer（带钩子的主模型包装）、ActivationCache（字典式激活缓存）、HookedTransformerConfig（模型配置）、FactoredMatrix（高效因子矩阵运算）。
【与 SAELens 集成】 TransformerLens 可与 SAELens 集成进行稀疏自编码器分析，例如加载 gpt2-small-res-jb 的 blocks.8.hook_resid_pre 并对残差激活进行编码。
【参考资料】 references/ 文件夹包含 README（概览与快速开始）、api.md（HookedTransformer、ActivationCache、HookPoints 的完整 API 参考）、tutorials.md（激活修补、电路分析、logit lens 的分步教程）。外部资源包括主演示 Notebook、激活修补演示、ARENA 机制可解释性课程（200 小时以上教程），以及相关论文与官方文档。
【版本说明】 v2.0 移除了 HookedSAE（迁移至 SAELens）；v3.0（alpha）引入 TransformerBridge 以加载任意 nn.Module。