# softmax_focal_loss

Python API: `luxonis_train.attached_modules.losses.softmax_focal_loss`

Softmax 焦点损失，它降低了简单样本的权重。

## 类

### SoftmaxFocalLoss

多类预测的 softmax 输出上的焦点损失。

损失在类别维度上应用 softmax。焦点因子降低了目标类别已具有高概率的元素的损失。

 * `输入:`: * `predictions` (`Tensor`): `[B, C, ...]` logits，其中 C ≥ 2
    * `targets` (`Tensor`): 相同形状，one-hot
 * `输出:`: * `Tensor`: 标量，或当 `reduction` 为 `"none"` 时为 `[B, ...]`
 * `公式:`: 在一个元素上，pc 是类别 c 的 softmax 概率，yc 是其目标。对于平滑因子 s > 0，损失首先将每个目标裁剪到 [s ⁄ (C − 1), 1 − s]。然后元素的损失为 pt = ∑cyc pc + s，ℓ = − αt
   (1 − pt)γlogpt 浮点数 `alpha` 是每个元素的 αt。列表 `alpha` 从目标类别的条目（目标的 `argmax`）给出 αt。然后 `reduction` 对所有元素取平均值或求和，或保留每个元素的损失。

> **参考**
> * 来源: 本项目。
 * 许可证: Apache-2.0 (本项目)

> **注意**
> 损失在 `float32` 中运行，并关闭了自动转换，也在混合精度运行中。当 `alpha=1`、`gamma=0` 和 `smooth=0` 时，损失是交叉熵。

> **示例**
> 附加到 `model.nodes` 中的 `DDRNetSegmentationHead`：

```yaml
- name: DDRNetSegmentationHead
  inputs: [DDRNet]
  losses:
    - name: SoftmaxFocalLoss
```

 * `兼容:`: * 节点: *
   [BiSeNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [SegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### 方法

##### init

```python
def __init__(alpha: float | list[float] = 0.25, gamma: float = 2.0, smooth: float = 0.0, reduction: Literal['none', 'mean', 'sum'] = 'mean', **kwargs):
```

初始化损失并检查平滑因子。

参数

 * `alpha` (`float | list[float]`): 类别权重
   αt。浮点数以相同因子缩放每个元素的损失，因此它不偏向某个类别。列表按类别顺序为每个类别保留一个权重。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
   然后检查列表是否为每个类别包含一个条目。
 * `gamma` (`float`): 焦点因子 (1 − pt) 的指数。`0` 关闭焦点因子。
 * `smooth` (`float`): 标签平滑因子 s，在 `[0, 1]` 中。类别公式显示了它如何改变目标和 pt。
 * `reduction` (`Literal['none', 'mean', 'sum']`): 如何减少元素的损失： * `"none"`: 返回每个元素的损失。
    * `"mean"`: 返回所有元素的平均值。
    * `"sum"`: 返回所有元素的总和。
      [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
      将任何其他值视为 `"none"`。
 * `**kwargs`: 转发给
   [BaseLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md)
   的关键字参数，例如 `final_loss_weight` 和 `node`。

引发

 * `ValueError`: 当 `smooth` 超出 `[0, 1]` 时。

##### forward

```python
def forward(predictions: Tensor, targets: Tensor) -> Tensor:
```

计算 logits 和 targets 之间的 softmax 焦点损失。

> **示例**
> 当 `alpha=1` 和 `gamma=0` 时，损失是交叉熵：

```pycon
>>> import torch
>>> import torch.nn.functional as F
>>> logits = torch.tensor([[2.0, 0.0, -1.0]])
>>> target = torch.tensor([[1.0, 0.0, 0.0]])
>>> loss = SoftmaxFocalLoss(alpha=1.0, gamma=0.0)
>>> ce = F.cross_entropy(logits, target)
>>> torch.allclose(loss(logits, target), ce)
True
```

一个类别不足：

```pycon
>>> loss(torch.zeros(1, 1), torch.ones(1, 1))
Traceback (most recent call last):
    ...
ValueError: SoftmaxFocalLoss is not suitable for binary tasks. Please use SigmoidFocalLoss instead.
```

参数

 * `predictions` (`Tensor`): 形状为 `[B, C, ...]` 的 logits，至少包含两个类别。节点的主要输出。
 * `targets` (`Tensor`): 与 `predictions` 形状相同的 one-hot 目标。

返回

 * `Tensor`: 对于 `"mean"` 和 `"sum"` 归约，返回 `float32` 标量。对于任何其他 `reduction`，返回每个元素的损失，形状为 `[B, ...]`。

引发

 * `ValueError`: 当 `predictions` 的类别少于两个时，当形状不同时，或者当列表 `alpha` 没有为每个类别包含一个条目时。

#### 属性

##### supported_tasks
