nnterp：统一大语言模型可解释性研究的接口标准

nnterp 基于 NNsight 构建，为所有 Transformer 模型提供标准化接口，解决不同模型命名混乱问题，让机械可解释性研究代码能够跨模型复用。

背景：Transformer 模型命名的混乱现状\n\n在大语言模型的机械可解释性研究中，研究者经常需要深入模型内部，访问特定的层、注意力头或 MLP 模块。然而，一个长期困扰研究者的问题是：每个 Transformer 模型都使用不同的命名约定。\n\nGPT-2 使用 transformer.h 作为层的前缀，LLaMA 使用 model.layers，OPT 又使用完全不同的结构。这意味着当你想从 GPT-2 切换到 LLaMA 进行实验时，不能简单地修改模型名称，而必须重写大量代码来适配新的命名体系。这种碎片化严重阻碍了可解释性研究的进展，也让代码复用变得异常困难。\n\n## nnterp 的解决方案\n\nnnterp 基于 NNsight 框架构建，提供了一种全新的解决思路。它不像 transformer_lens 那样重新实现 Transformer 模型，而是通过 NNsight 的重命名功能，在保持原始 HuggingFace 实现不变的情况下，为所有模型建立统一的标准化接口。\n\n这种设计带来了两个关键优势：一是完美兼容原始模型，避免了重新实现可能引入的微妙错误；二是研究者可以在不同模型间无缝切换，代码几乎无需修改。\n\n## 标准化的模型结构\n\nnnterp 将所有模型统一到接近 LLaMA 的命名规范：\n\n\nStandardizedTransformer\n├── layers\n│ ├── self_attn\n│ └── mlp\n├── ln_final\n└── lm_head\n\n\n无论你加载的是 GPT-2、LLaMA、Gemma 还是其他模型，都可以使用相同的代码访问内部组件。例如，model.layers_output[5] 在任何模型中都表示第 5 层的输出，model.attentions_output[3] 都表示第 3 层的注意力输出。\n\n## 内置的可解释性工具\n\n除了标准化接口，nnterp 还集成了多种常用的机械可解释性研究方法：\n\nLogit Lens 可以解码每一层隐藏状态对应的词表概率分布，帮助研究者理解模型在中间层是如何"思考"的。\n\nPatchscope 支持跨提示的隐藏状态修补，研究者可以将一个提示中的表示注入到另一个提示中，观察模型行为的变化。\n\n激活引导（Activation Steering） 允许在特定层注入自定义向量，实现对模型行为的精细控制。可以针对特定 token 位置或批次元素进行引导，灵活性很高。\n\n## 实际使用示例\n\n加载模型后，研究变得异常简洁。以下代码展示了如何访问模型内部并获取 logits：\n\npython\nfrom nnterp import StandardizedTransformer\n\nmodel = StandardizedTransformer(\"gpt2\")\n\nwith model.trace(\"The Eiffel Tower is in the city of\"):\n # 统一接口，适用于所有模型\n attention_output = model.attentions_output[3]\n mlp_output = model.mlps_output[3]\n layer_5_output = model.layers_output[5]\n \n # 内置工具\n logits = model.logits.save()\n\n\n更复杂的干预也变得直观。比如将第 3 层的残差直接加到第 10 层：\n\npython\nwith model.trace(\"Hello world\"):\n layer_3_output = model.layers_output[3]\n model.layers_output[10] = model.layers_output[10] + layer_3_output\n\n\n## 模型验证与可靠性\n\nnnterp 包含自动测试机制，确保每个模型都被正确标准化。加载模型时会运行快速验证检查，如果验证失败会及时报错。这种设计让研究者可以确信他们使用的接口是可靠的，不会因为命名错误导致实验结果偏差。\n\n## 社区与扩展性\n\n项目维护者积极欢迎社区贡献。目前列出的待实现功能包括梯度获取辅助、vLLM 支持、KV 访问接口等。如果你在自己的研究中实现了新功能，提交 PR 可以让整个社区受益。\n\n## 总结\n\nnnterp 解决了 Transformer 可解释性研究中长期存在的命名混乱问题。通过标准化接口和内置工具，它大大降低了跨模型研究的门槛。对于从事大语言模型内部机制探索的研究者来说，这是一个值得关注和尝试的工具。

背景：Transformer 模型命名的混乱现状\n\n在大语言模型的机械可解释性研究中，研究者经常需要深入模型内部，访问特定的层、注意力头或 MLP 模块。然而，一个长期困扰研究者的问题是：每个 Transformer 模型都使用不同的命名约定。\n\nGPT-2 使用 transformer.h 作为层的前缀，LLaMA 使用 model.layers，OPT 又使用完全不同的结构。这意味着当你想从 GPT-2 切换到 LLaMA 进行实验时，不能简单地修改模型名称，而必须重写大量代码来适配新的命名体系。这种碎片化严重阻碍了可解释性研究的进展，也让代码复用变得异常困难。\n\nnnterp 的解决方案\n\nnnterp 基于 NNsight 框架构建，提供了一种全新的解决思路。它不像 transformer_lens 那样重新实现 Transformer 模型，而是通过 NNsight 的重命名功能，在保持原始 HuggingFace 实现不变的情况下，为所有模型建立统一的标准化接口。\n\n这种设计带来了两个关键优势：一是完美兼容原始模型，避免了重新实现可能引入的微妙错误；二是研究者可以在不同模型间无缝切换，代码几乎无需修改。\n\n标准化的模型结构\n\nnnterp 将所有模型统一到接近 LLaMA 的命名规范：\n\n\nStandardizedTransformer\n├── layers\n│ ├── self_attn\n│ └── mlp\n├── ln_final\n└── lm_head\n\n\n无论你加载的是 GPT-2、LLaMA、Gemma 还是其他模型，都可以使用相同的代码访问内部组件。例如，model.layers_output[5] 在任何模型中都表示第 5 层的输出，model.attentions_output[3] 都表示第 3 层的注意力输出。\n\n内置的可解释性工具\n\n除了标准化接口，nnterp 还集成了多种常用的机械可解释性研究方法：\n\nLogit Lens 可以解码每一层隐藏状态对应的词表概率分布，帮助研究者理解模型在中间层是如何"思考"的。\n\nPatchscope 支持跨提示的隐藏状态修补，研究者可以将一个提示中的表示注入到另一个提示中，观察模型行为的变化。\n\n激活引导（Activation Steering） 允许在特定层注入自定义向量，实现对模型行为的精细控制。可以针对特定 token 位置或批次元素进行引导，灵活性很高。\n\n实际使用示例\n\n加载模型后，研究变得异常简洁。以下代码展示了如何访问模型内部并获取 logits：\n\npython\nfrom nnterp import StandardizedTransformer\n\nmodel = StandardizedTransformer(\"gpt2\")\n\nwith model.trace(\"The Eiffel Tower is in the city of\"):\n 统一接口，适用于所有模型\n attention_output = model.attentions_output[3]\n mlp_output = model.mlps_output[3]\n layer_5_output = model.layers_output[5]\n \n 内置工具\n logits = model.logits.save()\n\n\n更复杂的干预也变得直观。比如将第 3 层的残差直接加到第 10 层：\n\npython\nwith model.trace(\"Hello world\"):\n layer_3_output = model.layers_output[3]\n model.layers_output[10] = model.layers_output[10] + layer_3_output\n\n\n模型验证与可靠性\n\nnnterp 包含自动测试机制，确保每个模型都被正确标准化。加载模型时会运行快速验证检查，如果验证失败会及时报错。这种设计让研究者可以确信他们使用的接口是可靠的，不会因为命名错误导致实验结果偏差。\n\n社区与扩展性\n\n项目维护者积极欢迎社区贡献。目前列出的待实现功能包括梯度获取辅助、vLLM 支持、KV 访问接口等。如果你在自己的研究中实现了新功能，提交 PR 可以让整个社区受益。\n\n总结\n\nnnterp 解决了 Transformer 可解释性研究中长期存在的命名混乱问题。通过标准化接口和内置工具，它大大降低了跨模型研究的门槛。对于从事大语言模型内部机制探索的研究者来说，这是一个值得关注和尝试的工具。