TensorFlow 2.x 自定义 Optimizer 必须继承 tf.keras.optimizers.Optimizer 并实现 build_step 和 update_step，不可重写 _resource_apply_dense；需用 add_weight 注册超参、add_slot 管理状态变量，并正确处理 IndexedSlices 梯度与混合精度；序列化需严格匹配 __init__ 参数名并调用 _serialize_hyperparameter。
TensorFlow 2.x 中自定义 Optimizer 必须继承 tf.keras.optimizers.Optimizer
TensorFlow 2.x（尤其是 2.11+）已弃用直接继承 tf.keras.optimizers.Optimizer 并重写 _resource_apply_dense 等底层方法的方式；官方推荐路径是继承 tf.keras.optimizers.Optimizer，并实现 build_graft 和 update_step（或更稳妥地覆盖 _update_step）。否则会触发 NotImplementedError: _resource_apply_dense is not implemented 或静默失效。
常见错误现象：照搬 TF1.x 写法，重写 _create_slots + _apply_dense，结果 optimizer 不更新变量、loss 不降、model.trainable_variables 的 grad 为 None。
- 必须调用
super().__init__(name=name, **kwargs)，否则内部状态管理崩溃 - 所有可训练参数（如学习率
self._lr）需注册为self._make_variable或self.add_weight，不能用普通 Python 属性 - 若需访问梯度缩放（如混合精度训练），必须显式检查
hasattr(grad, "values")，否则在tf.keras.mixed_precision.Policy("mixed_float16")下报AttributeError: 'IndexedSlices' object has no attribute 'values'
如何在 update_step 中安全读写变量与梯度
update_step 是核心逻辑入口，接收 grad（可能为 None）、var（tf.Variable）和 **kwargs。它运行在 @tf.function 图模式下，不能用 Python 原生控制流判断 grad is None —— 必须用 tf.cond 或提前过滤。
典型场景：实现带 warmup 的余弦退火 LR，但只对部分层生效（如仅微调 head 层）。
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
立即学习“Python免费学习笔记（深入）”；
- 用
tf.debugging.assert_all_finite(grad, message="NaN grad detected")在开发期捕获梯度爆炸 - 更新前先
var.assign_sub(lr * grad)是错的 —— 这绕过了 optimizer 的 slot 变量（如 momentum、rms），应统一通过self.add_slot(var, "momentum")创建并维护 - 若算法依赖历史二阶矩（如 AdamW 的 weight decay 分离），必须在
build_step中创建 slot：self.add_slot(var, "rms", initializer="ones")，并在update_step中用self.get_slot(var, "rms")读取
为什么 get_config() 和 from_config() 容易出错
自定义 optimizer 若用于 model.compile(optimizer=MyOpt()) 后保存/加载模型（model.save() / tf.keras.models.load_model()），必须正确定义序列化逻辑。否则加载时抛 ValueError: Unknown optimizer: MyOpt，或恢复后学习率变成默认值 0.001。
-
get_config()返回字典，键名必须与__init__参数名严格一致（包括大小写），且值必须是 JSON-serializable 类型（不能返回tf.Tensor或lambda） - 若构造函数含
learning_rate参数，get_config()中必须写"learning_rate": self._serialize_hyperparameter(self._learning_rate)，而非直接self.learning_rate—— 后者可能是tf.keras.optimizers.schedules.LearningRateSchedule实例，需用self._serialize_hyperparameter转换 -
from_config()必须调用cls(**config)，不能写成super().from_config(config)，后者不识别自定义类
调试时如何确认 optimizer 真正在更新变量
最可靠的验证不是看 loss 下降，而是直接观测变量变化。TensorFlow 不会报错当 optimizer 逻辑被跳过（比如 grad 全为零、条件分支未命中），导致“看似在训，实则冻结”。
- 在训练循环中插入：
print(f"var {var.name}: {var.numpy()[:2]} → {var_after.numpy()[:2]}")，但注意var.numpy()会强制退出图模式，仅限 debug 模式启用 - 更健壮方式：用
tf.summary.scalar记录每步tf.reduce_mean(tf.abs(grad))和tf.reduce_mean(tf.abs(var - var_old))，通过 TensorBoard 观察是否同步非零 - 关键陷阱：自定义 optimizer 若未正确处理
tf.IndexedSlices（常见于 embedding 层梯度），会导致该变量完全不更新 —— 必须在update_step开头加if isinstance(grad, tf.IndexedSlices): grad = tf.convert_to_tensor(grad)或按索引单独更新
真正难的不是写出公式，而是让每个 tensor 的 shape、dtype、device placement 和 sparse/dense 类型，在每一步都对得上。漏掉任意一个 tf.cast 或 tf.convert_to_tensor，都可能让更新无声失效。
