不能直接用 update_state 返回值判断逻辑，因为其设计为状态累积式，返回 none；必须用 self.add_weight 创建状态变量，通过 assign_add 更新，并在 result 中计算结果，且 reset_state 需显式重写以确保多设备下正确重置。
为什么不能直接用 update_state 返回值判断逻辑？
因为 tf.keras.metrics.Metric 的设计是状态累积式：所有计算必须通过内部变量（如 self.total、self.count）保存中间结果，update_state 本身不返回任何值（返回 None）。如果你在 update_state 里写 return some_calculation，Keras 训练循环会静默忽略它，指标值永远为 0 或 NaN。
- 正确做法是把状态更新拆成两步：先调用
self.total.assign_add(...)这类原地更新操作，再在result方法里组合出最终值 - 所有状态变量必须用
self.add_weight创建，不能用普通 Python 变量或tf.Variable手动初始化——否则多 GPU 或 TF2.11+ 的jit_compile=True下会报ValueError: Trying to access resource from wrong worker - 注意
y_true和y_pred的 shape 默认是 batch 维度开头，但 Keras 指标默认按 sample 级别处理；若需按 batch 整体算（比如 F1 的宏平均），得在update_state里自己 reduce，不能依赖默认行为
如何安全实现带 mask 的自定义 F1 分数？
常见错误是直接对 y_pred 做 tf.argmax 后和 y_true 比较，却忽略 padding 位置（如 NLP 序列任务中 mask 为 0 的 token）。这会导致分母虚高，F1 被严重拉低。
- 必须显式接收
sample_weight参数，并在update_state开头用tf.where或tf.boolean_mask对齐 mask —— 不要试图在result里后处理 -
sample_weight类型可能是float32也可能是bool，建议统一转成tf.float32并做tf.clip_by_value(..., 0, 1)防止意外负值干扰累加 - 避免用
tf.math.confusion_matrix：它不支持动态 batch size，在 tf.function 图模式下容易触发 retracing；推荐手动算 TP/TN/FP/FN，用tf.reduce_sum+tf.cast组合
def update_state(self, y_true, y_pred, sample_weight=None):
y_pred = tf.argmax(y_pred, axis=-1)
y_true = tf.cast(y_true, tf.int64)
mask = tf.cast(sample_weight, tf.bool) if sample_weight is not None else tf.ones_like(y_true, dtype=tf.bool)
tp = tf.reduce_sum(tf.cast((y_true == 1) & (y_pred == 1) & mask, tf.float32))
fp = tf.reduce_sum(tf.cast((y_true != 1) & (y_pred == 1) & mask, tf.float32))
fn = tf.reduce_sum(tf.cast((y_true == 1) & (y_pred != 1) & mask, tf.float32))
self.true_positives.assign_add(tp)
self.false_positives.assign_add(fp)
self.false_negatives.assign_add(fn)
为什么 reset_state 必须重写且不能省略？
即使你只用了 self.add_weight，也不能依赖父类默认实现。Keras 2.9+ 中，如果子类没重写 reset_state，某些分布式策略（如 MultiWorkerMirroredStrategy）会在 epoch 切换时漏重置部分副本的权重，导致指标值持续累加，越跑越大。
SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、
- 必须显式调用每个
self.add_weight创建的变量的.assign(0)，不能只写super().reset_state() - 如果用了嵌套结构（如 per-class 的
tf.Variable列表），reset_state里要遍历重置每一项，漏掉一个就会引发隐性 bug - 测试时可用
metric.reset_state(); metric.update_state(...); print(metric.result().numpy())快速验证是否真清零，别只信文档
调试时怎么快速定位 nan 来源？
自定义指标出现 nan 通常不是除零，而是 tf.reduce_sum 在空 tensor 上运行（比如整个 batch 的 mask 全为 0），或 log(0) 类运算渗入了指标逻辑。
- 在
result方法开头加tf.debugging.check_numerics包裹每个中间变量，比 print 更早暴露问题点 - 禁用图优化临时排查：
@tf.function(jit_compile=False, autograph=False)加在update_state上，让错误堆栈指向真实行号 - 注意
tf.keras.metrics.Metric的result方法会被频繁调用（每 step 一次），避免在里面做 heavy 计算或 IO；nan往往是某次异常输入触发后，后续所有 result 都继承了 nan
最麻烦的是跨设备状态不一致——比如 CPU 上跑着正常，切到 TPU 就 nan。这时候得检查所有 tf.* 调用是否都支持 XLA，特别是 tf.where 的 condition 形状是否严格匹配。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
