
本文详解如何在 Flax NNX 中精准冻结指定参数(如 kernel)并仅优化其余参数(如 bias),核心在于正确使用 nnx.DiffState 配合 nnx.value_and_grad 的 argnums 参数,避免梯度状态不匹配错误。
本文详解如何在 flax nnx 中精准冻结指定参数(如 `kernel`)并仅优化其余参数(如 `bias`),核心在于正确使用 `nnx.diffstate` 配合 `nnx.value_and_grad` 的 `argnums` 参数,避免梯度状态不匹配错误。
在 Flax NNX 的迁移学习实践中,常需冻结预训练子模块的权重(如线性层的 kernel),仅对特定参数(如 bias 或新增分类头)进行微调。然而,直接通过 wrt= 指定可优化参数并不足以完成梯度计算——NNX 的自动微分机制要求显式声明“哪些变量参与求导”,这必须通过 nnx.DiffState 实现,而非仅依赖优化器的 wrt 过滤。
? 关键原理:nnx.DiffState 是梯度传播的“开关”
nnx.value_and_grad 默认对所有可微变量(Param、BatchStat 等)计算梯度。若仅希望对部分变量求导(例如仅 bias),必须:
- 提前定义参数过滤规则(如
nnx.All(nnx.PathContains("bias"))); - 将其封装为
nnx.DiffState(diff_index, filter),其中diff_index=0表示对第一个函数参数(即model)应用该过滤; - 将该
DiffState传给argnums=,而非wrt=(后者仅控制优化器更新范围,不影响梯度生成)。
否则将触发 ValueError: Mismatch custom node data —— 因为 grads 包含了全量参数结构,而 optimizer.update() 期望的梯度结构与 wrt 定义不一致。
✅ 正确实现步骤(附代码)
以下是最小可运行示例,聚焦核心逻辑:
import jax.numpy as jnp
import jax.random as random
from flax import nnx
import optax
# 1. 构建模型并加载预训练权重
rngs = nnx.Rngs(123)
model = nnx.Linear(1, 1, rngs=rngs)
model.kernel.value = jnp.array([[2.0]]) # 冻结 kernel
# 2. 定义参数过滤:仅对 bias 求导
transfer_params = nnx.All(nnx.PathContains("bias"))
diff_state = nnx.DiffState(0, transfer_params) # ← 关键!声明 model 的第 0 个参数按此规则求导
# 3. 使用 diff_state 构造梯度函数
loss_grad = nnx.value_and_grad(compute_loss, argnums=diff_state, has_aux=True)
# 4. 创建优化器(wrt 控制更新范围,需与 diff_state 语义一致)
optimizer = nnx.Optimizer(model, optax.adamw(1e-3), wrt=transfer_params)
# 5. 训练循环(注意:grads 现在只含 bias 的梯度)
@nnx.scan(in_axes=(nnx.Carry, None, None), out_axes=(nnx.Carry, 0), length=123)
def train_step(optimizer, x, y):
(loss, _), grads = loss_grad(optimizer.model, x, y)
optimizer.update(grads) # grads 结构与 wrt 严格匹配
return optimizer, loss
optimizer, losses = train_step(optimizer, x_train, y_train)⚠️ 注意事项与最佳实践
-
顺序不可颠倒:
diff_state必须在nnx.value_and_grad调用前创建,且transfer_params需复用同一对象(避免重复构造导致路径匹配失效)。 -
wrt与DiffState必须一致:二者过滤逻辑应完全相同,否则optimizer.update()会因梯度缺失或冗余而报错。 -
调试技巧:打印
grads结构验证——成功时仅含{'bias': ...};若出现kernel字段,说明DiffState未生效。 -
扩展场景:冻结多层时,可用
nnx.And(nnx.PathContains("encoder"), nnx.PathContains("kernel"));冻结整个子模块则用nnx.PathPrefix("backbone")。
通过 nnx.DiffState 显式控制微分范围,Flax NNX 实现了比传统 Flax 更精细、更安全的参数冻结机制。掌握这一模式,是构建高效迁移学习、LoRA 微调及混合精度训练的基础。

















