直接继承tf.keras.losses.Loss最稳妥，因其能完整控制前向计算图、确保梯度正确回传、支持sample_weight及分布式训练；需重写call方法，统一y_true为one-hot，动态计算pt，并将alpha、gamma作为可训练参数参与梯度计算。
为什么直接继承 tf.keras.losses.Loss 是最稳妥的方式
因为 Focal Loss 的核心逻辑（加权交叉熵 + 动态缩放）无法用 tf.keras.losses.sparse_categorical_crossentropy 等内置函数简单组合实现，且需在训练时动态计算 pt（预测概率），必须控制前向传播的完整计算图。继承 Loss 类能确保梯度正确回传、支持 sample_weight、兼容 model.compile(loss=...) 流程。
常见错误是试图用 tf.keras.losses.Loss 的静态方法（如 __call__）直接包装一个纯函数，结果导致 sample_weight 被忽略，或在多 GPU 分布式训练中出现梯度不一致。
- 必须重写
call(self, y_true, y_pred)，不能只写__call__ -
y_true通常为 one-hot 或整数标签，要统一处理为 one-hot 才能算pt -
y_pred是 logits（未 softmax），应直接用tf.nn.softmax_cross_entropy_with_logits或手动 softplus 防溢出
如何正确处理 y_true 的 shape 和类型
Focal Loss 对输入敏感：若 y_true 是整数标签（shape=(N,)），而 y_pred 是 logits（shape=(N, C)），必须先转成 one-hot；否则 tf.gather_nd 或 tf.reduce_sum(y_true * y_pred, axis=-1) 会出错或静默失败。
典型报错：InvalidArgumentError: Incompatible shapes: [32] vs. [32,10]（广播失败）或梯度为 None（因索引越界）。
立即学习“Python免费学习笔记（深入）”；
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
- 用
tf.one_hot(y_true, depth=tf.shape(y_pred)[-1], dtype=y_pred.dtype)安全转换 - 若
y_true已是 one-hot，加tf.assert_equal(tf.reduce_sum(y_true, axis=-1), 1.0)做运行时校验 - 避免用
np.argmax或tf.argmax反推标签——这会断开梯度
alpha 和 gamma 参数怎么设才不踩坑
gamma 控制难易样本权重衰减强度，alpha 平衡正负类；但二者必须参与梯度计算，不能写成 Python float 后硬编码进公式，否则 loss 不可导。
错误写法：gamma = 2.0; pt = ... ** gamma → gamma 成为常量，autograph 不识别为可训练变量。
- 把
alpha和gamma作为__init__参数存为self.alpha、self.gamma，类型用tf.float32 - 在
call中显式转为 tensor：gamma = tf.cast(self.gamma, y_pred.dtype) -
alpha若为标量，建议用tf.where按类别维度 broadcast，而非乘以y_true后求和（易维度错位）
def call(self, y_true, y_pred):
y_true = tf.one_hot(tf.cast(y_true, tf.int32), depth=tf.shape(y_pred)[-1])
ce = tf.nn.softmax_cross_entropy_with_logits(labels=y_true, logits=y_pred)
pt = tf.exp(-ce) # 注意：这是 scalar CE 的 pt，不是 per-class
focal_weight = (1 - pt) ** self.gamma
return focal_weight * ce
多分类 vs 二分类 Focal Loss 的关键差异
二分类常用 sigmoid + binary_focal_loss，输出 shape 是 (N, 1)；多分类用 softmax + categorical_focal_loss，输出 shape 是 (N, C)。混用会导致 pt 计算错误——比如对多分类用 sigmoid，pt 就不是真实类别的预测置信度。
TensorFlow 官方没提供开箱即用的多分类 Focal Loss，所以必须自己实现 call 逻辑，且注意：
- 二分类：用
tf.nn.sigmoid_cross_entropy_with_logits，再加(1 - p_t)^gamma权重 - 多分类：必须用
tf.nn.softmax_cross_entropy_with_logits，pt是真实类别的 softmax 输出值，不是 logits - 不要复用 Keras 的
BinaryFocalLoss（第三方库）到多分类任务——它内部没做 one-hot 对齐
最难调试的是 pt 值异常（恒为 0 或 1），往往源于 y_true 类型不匹配或 softmax 被误 applied 到 logits 上两次。
