# adaptive_detection_loss

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

YOLOv6 检测损失，以及它用于分类的变焦损失。

## 类

### AdaptiveDetectionLoss

YOLOv6 的边界框损失，带有锚点分配的预热。

 * `输入:`: * `features` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]
    * `class_scores` (`Tensor`): [B, N, nclasses] sigmoid 分数
    * `distributions` (`Tensor`): [B, N, 4]，步幅单位的 `(l, t, r, b)`
    * `target` (`Tensor`): [M, 6]，`[batch, class, x, y, w, h]`，`xywh` 归一化
 * `输出:`: * `Tensor`: 标量总损失
    * `dict[str, Tensor]`: 子损失 `class` 和 `iou`，不带损失权重
 * `公式:`: 在每次调用时，分配器将 N
   个锚点与目标框匹配。[ATSSAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/atss_assigner.md)
   在 epoch 低于 `n_warmup_epochs` 时运行，之后
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   运行。对于每个锚点 a，分配器给出类别、框和每个类别 c 的软分数 qa, c。S 是所有 qa, c 的总和： L = (λclsLcls + λiou∑a ∈ P(1 − IoUa)∑cqa, c)/(max(S, 1)) Lcls 是
   [VarifocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)，对所有锚点和类别求和。P
   是正锚点的集合，IoUa 是锚点 a 的预测框和分配框的 `iou_type` 重叠。λcls 是 `class_loss_weight`，λiou 是 `iou_loss_weight`。当没有锚点为正时，IoU 项为 `0`。

> **参考**
> * 来源：重新实现自 [YOLOv6: A Single-Stage Object Detection Framework for Industrial Applications](https://arxiv.org/abs/2209.02976) 和 [PP-YOLOE: An evolved version of YOLO](https://arxiv.org/abs/2203.16250)。
 * 许可证：Apache-2.0 (本项目)

> **注意**
> 第一次调用会根据 `features` 的形状构建锚点、锚点和步幅。损失将它们存储为非持久缓冲区。所有后续调用都使用这些缓冲区，即使 `features` 的形状发生变化。第一次使用 [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md) 的调用会记录分配器的更改，即使 `n_warmup_epochs` 为 `0`。

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

```yaml
- name: EfficientBBoxHead
  inputs: [RepPANNeck]
  losses:
    - name: AdaptiveDetectionLoss
```

 * `兼容:`: *
   使用者：[DetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/detection/v1/model.md)
    * 节点：[EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)

#### 方法

##### init

```python
def __init__(n_warmup_epochs: int = 0, iou_type: IoUType = 'giou', reduction: Literal['sum', 'mean'] = 'mean', class_loss_weight: float = 1.0, iou_loss_weight: float = 2.5, per_class_weights: list[float] | None = None, skip_stal: bool = False, **kwargs):
```

初始化损失、其两个分配器和
[VarifocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)。

该方法从节点读取步幅、网格单元大小、网格单元偏移量、类别数量和输入图像大小。因此，损失需要一个节点：如果没有
`node`，[BaseAttachedModule.node](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/base_attached_module.md)
会引发 `RuntimeError`。代码改编自 [PPYOLOE_pytorch](https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/models)。

参数

 * `n_warmup_epochs` (`int`): 使用
   [ATSSAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/atss_assigner.md)
   和 `topk=9` 的 epoch 数量，从 epoch `0` 开始计数。后续 epoch 使用
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   和 `topk=13`、`alpha=1.0` 和 `beta=6.0`。
 * `iou_type` (`IoUType`): 框项的 IoU 变体：`"none"` 表示普通 IoU，`"giou"`、`"diou"`、`"ciou"` 或
   `"siou"`。[luxonis_train.utils.bbox_iou](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/boundingbox.md)
   描述了这些变体。
 * `reduction` (`Literal['sum', 'mean']`): 损失不读取它。两个项始终使用类别公式的归一化和。
 * `class_loss_weight` (`float`): 分类项的因子 λcls。
 * `iou_loss_weight` (`float`): 框项的因子 λiou。
 * `per_class_weights` (`list[float] | None`):
   每个类别一个因子。[VarifocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
   将每个类别的权重乘以其因子。长度与类别数量不同的列表会记录警告，然后损失不使用因子。`None` 不使用因子。
 * `skip_stal` (`bool`): `True` 关闭
   [TaskAlignedAssigner](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/assigners/tal_assigner.md)
   的小目标感知标签分配。
 * `**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`。

##### forward

```python
def forward(features: list[Tensor], class_scores: Tensor, distributions: Tensor, target: Tensor) -> tuple[Tensor, dict[str, Tensor]]:
```

将锚点分配给目标框并计算损失。

该方法将 `target` 转换为输入图像像素中的 `xyxy` 框。它将每个图像的框填充到单个图像中最大框数。它将 `distributions` 解码为锚点周围的预测框。当前 epoch 的分配器然后将锚点与目标框匹配，该方法计算类别公式的两个项。

参数

 * `features` (`list[Tensor]`): 头部的特征图，每个尺度一个形状为 `[B, C_i, H_i, W_i]`。只有第一次调用使用它们来构建锚点。
 * `class_scores` (`Tensor`): 形状为 `[B, N, n_classes]` 的 Sigmoid 类别分数，用于所有尺度的 `N` 个锚点。
 * `distributions` (`Tensor`): 从每个锚点到其框的左、上、右和下侧的距离，形状为 `[B, N, 4]`，以步幅单位表示。
 * `target` (`Tensor`): 形状为 `[M, 6]` 的 `boundingbox` 标签。每行包含批次索引、类别以及一个框的归一化 `x`、`y`、`w` 和 `h`。`x` 和 `y` 表示左上角。

返回

 * `tuple[Tensor, dict[str, Tensor]]`: 总损失（标量）和子损失 `"class"` 和 `"iou"`。子损失是分离的项，不带因子 `class_loss_weight` 和 `iou_loss_weight`。

#### 属性

##### anchor_points

##### anchor_points_strided

##### anchors

##### atss_assigner

##### gt_bboxes_scale

##### n_anchors_list

##### node

##### stride_tensor

##### supported_tasks

##### tal_assigner

##### varifocal_loss

### VarifocalLoss

变焦损失，用于训练 IoU 感知类别分数。

该损失训练预测的类别分数以匹配软目标分数，例如预测框和分配框之间的 IoU。它对每个锚点和类别的预测分数 p 和目标分数 q 之间的二元交叉熵进行加权。对于独热标签 y：

L = ∑w⋅BCE(p, q)，w = α pγ (1 − y) + q y

负元素获得焦点权重 α**pγ，正元素获得权重 q。使用 `per_class_weights` 时，损失还会将每个类别的权重乘以该类别的因子。损失不分离 w，因此梯度也流经
pγ。[AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_detection_loss.md)
将此损失用于其分类项。

> **参考**
> * [VarifocalNet: An IoU-aware Dense Object Detector](https://arxiv.org/abs/2008.13367)
 * 该实现改编自 [PPYOLOE_pytorch](https://github.com/Nioolek/PPYOLOE_pytorch/blob/master/ppyoloe/models/losses.py) 的代码。

> **示例**
> 该示例有一个锚点，包含两个类别。第一个类别为正，目标分数为 `0.8`。两个元素的二元交叉熵均为 ln2，权重分别为 `0.8` 和 0.75⋅0.52 = 0.1875：

```pycon
>>> import torch
>>> loss = VarifocalLoss()
>>> pred_score = torch.tensor([[[0.5, 0.5]]])
>>> target_score = torch.tensor([[[0.8, 0.0]]])
>>> label = torch.tensor([[[1.0, 0.0]]])
>>> round(loss(pred_score, target_score, label).item(), 4)
0.6845
```

#### 方法

##### init

```python
def __init__(alpha: float = 0.75, gamma: float = 2.0, per_class_weights: Tensor | None = None):
```

初始化变焦损失。

参数

 * `alpha` (`float`): 负元素权重的因子 α。
 * `gamma` (`float`): 负元素权重中预测分数的指数 γ。
 * `per_class_weights` (`Tensor | None`): 每个类别一个因子，形状为 `[n_classes]`。`None` 不使用因子。

##### forward

```python
def forward(pred_score: Tensor, target_score: Tensor, label: Tensor) -> Tensor:
```

计算变焦损失，对所有元素求和。

二元交叉熵以 `float32` 运行，关闭自动转换。当 `per_class_weights` 和 `pred_score` 位于不同的设备上时，该方法会将 `per_class_weights` 替换为 `pred_score` 设备上的副本。

参数

 * `pred_score` (`Tensor`): 预测的类别分数，范围为 `[0, 1]`，形状为 `[B, N, n_classes]`。
 * `target_score` (`Tensor`): 目标分数，范围为 `[0, 1]`，形状相同。分配器为分配的类别提供软分数，为其他类别提供 `0`。
 * `label` (`Tensor`): 独热标签，形状相同。背景锚点只有零。

返回

 * `Tensor`: 对所有元素求和的损失，作为标量。
