自定义TensorFlow Metric必须继承tf.keras.metrics.Metric并实现__init__、update_state、result三个方法，状态变量须用self.add_weight注册，update_state中仅用tf.*运算，result必须返回标量tf.Tensor。
TensorFlow自定义Metric必须继承tf.keras.metrics.Metric
直接写个普通函数或类是无效的——Keras训练循环只认继承自tf.keras.metrics.Metric的实例。它要求你显式实现三个核心方法：__init__、update_state和result，缺一不可。漏掉reset_state（虽然有默认实现）也可能在多轮验证时出错，建议显式重写。
常见错误现象：AttributeError: 'MyMetric' object has no attribute 'count'，本质是没在__init__里用self.add_weight注册可累积的变量。所有中间状态（如TP、FP、累计和、计数）都必须通过self.add_weight创建，不能用普通Python属性。
示例关键骨架：
class F1Score(tf.keras.metrics.Metric):
def __init__(self, name='f1_score', **kwargs):
super().__init__(name=name, **kwargs)
self.precision = self.add_weight(name='precision', initializer='zeros')
self.recall = self.add_weight(name='recall', initializer='zeros')
# 注意：这里不直接存TP/FN/FP，而是按需拆解更新逻辑
update_state里必须用tf.math运算，不能用NumPy或Python内置函数
因为update_state会在图模式（graph mode）下被追踪编译，混入np.sum或len()会导致TypeError: Cannot convert Python object to Tensor或静默失败。所有张量操作必须走tf.* API。
立即学习“Python免费学习笔记（深入）”；
使用场景：比如计算二分类F1，你需要从y_true和y_pred中提取TP、FP、FN。别用np.where，改用tf.where；别用sum()，改用tf.reduce_sum；布尔索引要用tf.boolean_mask或tf.cast转0/1后点乘。
容易踩的坑：
-
y_pred通常是logits或概率，需先tf.argmax或tf.greater二值化，否则比较会出错 - 维度不匹配：确保
y_true和y_predshape一致，必要时tf.squeeze或tf.expand_dims - 数据类型：
tf.equal要求同dtype，tf.cast(y_pred > 0.5, tf.int32)比直接比较更稳
多类别F1要小心sample_weight和轴向约简
官方tf.keras.metrics.F1Score（TF 2.10+）支持average='macro'，但自定义时若想复现macro-F1，不能简单对每个类算F1再取均值——因为update_state是逐batch调用的，必须在result里统一计算。更稳妥的做法是分别累积每个类的TP、FP、FN，最后在result中按类计算再平均。
参数差异：
-
sample_weight参数必须显式接收并参与加权计算，否则验证集带权重时指标失真 - 多维
y_true（如one-hot）需用tf.argmax转label ID，再用tf.one_hot还原为逐类mask，避免tf.math.confusion_matrix的维度陷阱 - macro平均要在
result里做，micro平均可直接累加全局TP/FP/FN
性能影响：逐类统计会增加add_weight数量（如100类就要100个TP变量），内存占用上升，但精度可控；用tf.math.confusion_matrix一次性生成矩阵再分解，图构建稍慢但变量少。
调试自定义Metric时优先检查result()返回值类型和形状
训练中Keras会把result()返回值传给日志和回调，如果它返回tf.Tensor但shape不是标量（如[1]），可能触发InvalidArgumentError: Input must be a scalar；如果返回Python float，会丢失梯度上下文且无法在分布式策略下同步。
正确做法：result()必须返回单个tf.Tensor，dtype通常为tf.float32，shape为()（标量）。常用收尾操作：
- 用
tf.reduce_mean而非tf.reduce_sum保证标量输出 - 用
tf.clip_by_value防除零（如precision分母为0） - 调试时可在
result()开头加tf.print('debug:', self.tp)，但上线前删掉——tf.print有副作用且影响性能
最容易被忽略的是：当Metric用于model.evaluate()时，它会被重置；但用于model.fit()的validation_data时，每个epoch末会自动reset_state()。如果你手动调用reset_state()位置不对，会导致指标清零过早。
