Penzai

盆 ("pen", 托盘) 栽 ("zai", 种植) - 一种将树木和景观微缩化的古老中国艺术，也称为盆景，是日本盆景艺术的祖先。

Penzai 是一个 JAX 库，用于将模型编写为可读的、函数式的 pytree 数据结构（一种树形数据结构），并提供可视化工具、修改和分析它们的工具。Penzai 专注于在模型训练后轻松进行操作，使其成为涉及逆向工程或消融模型组件、检查和探测内部激活、执行模型手术、调试架构等的绝佳选择。（但如果你只是想构建和训练一个模型，也可以这样做！）

有了 Penzai，你的神经网络可能看起来像这样：

Penzai 被结构化为一系列模块化工具的集合，它们共同设计但可独立使用：

• 一个功能强大的交互式 Python 美化打印机：

  • Treescope (pz.ts)： 它是普通 IPython/Colab 渲染器的即插即用替代品，最初是 Penzai 的一部分，但现在作为独立包可用。它旨在帮助理解 Penzai 模型和其他深层嵌套的 JAX pytrees，内置支持可视化任意维度的 NDArrays（多维数组）。

• 一组 JAX 树和数组操作实用工具：

  • penzai.core.selectors (pz.select)：一个 pytree 瑞士军刀，将 JAX 的 .at[...].set(...) 语法推广到任意类型驱动的 pytree 遍历，使得对 Penzai 模型和其他数据结构进行复杂重写或即时修补变得容易。

  • penzai.core.named_axes (pz.nx)：一个轻量级的命名轴系统（named axes），它将普通的 JAX 函数提升为按命名轴向量化，并允许你在命名和位置编程风格之间无缝切换，而无需学习新的数组 API。

• 一个基于声明式组合器的神经网络库，其中模型表示为易于修改的数据结构：

  • penzai.nn (pz.nn)：这是 Flax、Haiku、Keras 或 Equinox 等其他神经网络库的替代方案，它使用声明式组合器暴露模型前向传播的完整结构。与 Equinox 一样，模型表示为 JAX PyTrees，这意味着你可以通过美化打印看到模型所做的所有事情，并使用 jax.tree_util 注入新的运行时逻辑。然而，penzai.nn 模型也可以在树的叶子节点包含可变变量，使它们能够跟踪可变状态和参数共享。

• 常见 Transformer 架构的模块化实现，以支持可解释性、模型手术和训练动态的研究：

  • penzai.models.transformer：参考 Transformer 实现，可以加载 Gemma、Llama、Mistral 和 GPT-NeoX / Pythia 架构的预训练权重。使用模块化组件和命名轴构建，以简化复杂的模型操作工作流。

Penzai 的文档可在 https://penzai.readthedocs.io 找到。

[!IMPORTANT] Penzai 0.2 包含神经网络的许多破坏性更改。这些更改旨在通过引入对可变状态和参数共享的一等支持并移除不必要的样板代码来简化常见工作流。你可以在 "Changes in the V2 API" 概述中阅读旧版 "V1" API 与当前 "V2" API 之间的差异。

如果你目前正在使用 V1 API 且尚未转换为 V2 系统，你可以通过从 penzai.deprecated.v1 子模块导入来保留旧行为，例如：::

from penzai.deprecated.v1 import pz
from penzai.deprecated.v1.example_models import simple_mlp

入门指南

如果你还没有安装 JAX，你应该先安装，因为安装过程取决于你的平台。你可以在 JAX documentation 中找到说明。之后，你可以使用以下命令安装 Penzai：

pip install penzai

并使用以下方式导入：

import penzai
from penzai import pz

(penzai.pz 是一个别名命名空间，这使得引用常见的 Penzai 对象更加容易。)

当在 Colab 或 IPython 笔记本中工作时，我们建议还将 Treescope（Penzai 的配套美化打印机）配置为默认的美化打印机，并启用一些交互使用的实用工具：

import treescope
treescope.basic_interactive_setup(autovisualize_arrays=True)

以下是初始化和可视化简单神经网络的方法：

from penzai.models import simple_mlp
mlp = simple_mlp.MLP.from_config(
    name="mlp",
    init_base_rng=jax.random.key(0),
    feature_sizes=[8, 32, 32, 8]
)

# 当你从 Colab/IPython 笔记本单元格输出模型和数组时，它们会自动可视化：
mlp

以下是捕获和提取逐元素非线性变换之后的激活值的方法：

@pz.pytree_dataclass
class AppendIntermediate(pz.nn.Layer):
  saved: pz.StateVariable[list[Any]]
  def __call__(self, x: Any, **unused_side_inputs) -> Any:
    self.saved.value = self.saved.value + [x]
    return x

var = pz.StateVariable(value=[], label="my_intermediates")

# 创建一个保存其激活值的模型副本：
saving_model = (
    pz.select(mlp)
    .at_instances_of(pz.nn.Elementwise)
    .insert_after(AppendIntermediate(var))
)

output = saving_model(pz.nx.ones({"features": 8}))
intermediates = var.value

要了解如何使用 Penzai 构建和操作神经网络，我们建议从 "How to Think in Penzai" tutorial 开始，或者查看 Penzai documentation 中的其他教程。

引用

如果你发现 Penzai 对你的研究有用，请考虑引用以下文章（也可在 arXiv 上获取）：

@article{johnson2024penzai,
    author={Daniel D. Johnson},
    title={{Penzai} + {Treescope}: A Toolkit for Interpreting, Visualizing, and Editing Models As Data},
    year={2024},
    journal={ICML 2024 Workshop on Mechanistic Interpretability}
}

---

这不是官方支持的 Google 产品。

Penzai 快速上手指南

Penzai 是一个基于 JAX 的库，用于将模型编写为可读性高、功能性的 PyTree 数据结构。它专注于模型训练后的操作（如逆向工程、组件消融、内部激活探测、模型手术等），同时也支持构建和训练模型。

[!NOTE] 版本提示: Penzai 0.2 包含神经网络的 V2 API 重大变更。如果您正在使用旧版 V1 API，可通过 penzai.deprecated.v1 导入以保持兼容。建议直接采用最新的 V2 系统。

1. 环境准备

在使用 Penzai 之前，请确保您的开发环境满足以下要求：

• Python: 推荐 Python 3.9 或更高版本。
• JAX: Penzai 依赖 JAX，请先完成 JAX 的安装。
  • 根据操作系统选择 CPU 或 GPU 版本，具体安装指令请参考 JAX 官方文档。

2. 安装步骤

通过 pip 安装 Penzai 及其依赖项：

pip install penzai

安装完成后，在 Python 脚本或 Notebook 中导入核心模块：

import penzai
from penzai import pz

penzai.pz 是常用对象的别名命名空间，方便后续调用。

3. 基本使用

配置交互式可视化

在 Jupyter Notebook 或 Google Colab 环境中，建议配置 Treescope（Penzai 的配套 pretty-printer）以优化显示效果：

import treescope
treescope.basic_interactive_setup(autovisualize_arrays=True)

初始化并可视化模型

以下示例展示了如何创建一个简单的多层感知机（MLP）并在 Notebook 单元格中自动可视化其结构：

from penzai.models import simple_mlp
mlp = simple_mlp.MLP.from_config(
    name="mlp",
    init_base_rng=jax.random.key(0),
    feature_sizes=[8, 32, 32, 8]
)

# 在 Colab/IPython notebook 单元格中输出模型时会自动可视化
mlp

进阶：提取中间层激活

Penzai 的核心优势在于对模型结构的灵活修改。以下是利用 pz.select 在推理过程中捕获中间激活值的示例：

@pz.pytree_dataclass
class AppendIntermediate(pz.nn.Layer):
  saved: pz.StateVariable[list[Any]]
  def __call__(self, x: Any, **unused_side_inputs) -> Any:
    self.saved.value = self.saved.value + [x]
    return x

var = pz.StateVariable(value=[], label="my_intermediates")

# 复制模型并在特定层后插入保存逻辑
saving_model = (
    pz.select(mlp)
    .at_instances_of(pz.nn.Elementwise)
    .insert_after(AppendIntermediate(var))
)

output = saving_model(pz.nx.ones({"features": 8}))
intermediates = var.value

更多高级用法和教程，请访问 Penzai 官方文档。