# transformer_classification_head

Python API: `luxonis_train.nodes.heads.transformer_classification_head`

Transformer 主干网络 CLS token 上的分类头。

## 类

### TransformerClassificationHead

Transformer 主干网络 CLS token 的分类头。

[DinoV3](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/dinov3.md)
在其 `return_sequence` 参数为 `True` 时提供 CLS token。

 * `输入:`: * `inputs` (`Tensor`): [B, C] CLS token
 * `输出:`: * `classification` (`Tensor`): [B, nclasses] logits

> **参考**
> * 来源：本项目。
 * 许可证：Apache-2.0（本项目）

> **注意事项**
> 该头部对 CLS token 应用 dropout 和一个线性层。它没有池化，因为 CLS token 没有空间维度。dropout 仅在训练模式下起作用。该模式不改变输出键或形状。这包括导出模式。

 * `变体:`: 无。通过 `params` 配置节点。

> **示例**
> 配置中 `model.nodes` 部分的节点条目：

```yaml
- name: TransformerClassificationHead
  inputs: [DinoV3]
```

 * `兼容:`: * 附加索引：`-1`，输入节点的最后一个输出
    * 所需标签：`classification`
    * 损失： *
      [BCEWithLogitsLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/bce_with_logits.md)
       * [CrossEntropyLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/cross_entropy.md)
       * [OHEMLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/ohem_loss.md)
       * [SigmoidFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/sigmoid_focal_loss.md)
       * [SmoothBCEWithLogitsLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/smooth_bce_with_logits.md)
       * [SoftmaxFocalLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/softmax_focal_loss.md)
    * 指标： *
      [Accuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
       * [F1Score](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [JaccardIndex](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [Precision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
       * [Recall](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/torchmetrics.md)
    * 可视化工具：[ClassificationVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/classification_visualizer.md)
    * 导出解析器：`ClassificationParser`

#### 方法

##### init

```python
def __init__(dropout_rate: float = 0.2, **kwargs):
```

构建 dropout 和线性层。

线性层将
[in_channels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
值映射到 `n_classes` logits。

参数

 * `dropout_rate` (`float`): 在训练模式下，dropout 层将 CLS token 值设置为零的概率，范围为 `[0, 1]`。该层将其他值按 1 ⁄ (1 − p) 缩放，其中 p 是 `dropout_rate`。默认为
   `0.2`。
 * `**kwargs`:
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。它们必须通过 `input_shapes` 或 `in_sizes` 包含输入大小，并通过 `n_classes` 或 `dataset_metadata` 包含类别计数。

##### forward

```python
def forward(x: Tensor) -> Tensor:
```

从 CLS token 计算类别 logits。

该方法应用 dropout，然后应用线性层。dropout 仅在训练模式下起作用。

> **示例**
> ```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import TransformerClassificationHead
>>> head = TransformerClassificationHead(
...     n_classes=5,
...     input_shapes=[{"features": [Size([2, 384])]}],
... )
>>> head.in_channels
384
>>> head(torch.zeros(2, 384)).shape
torch.Size([2, 5])
```

参数

 * `x` (`Tensor`): 形状为 `[B, C]` 的 CLS token，其中 `C` 是嵌入大小。

返回

 * `Tensor`: 形状为 `[B, n_classes]` 的 logits。[BaseNode.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 将它们放在 `"classification"` 键下。

##### get_custom_head_config

```python
def get_custom_head_config(self) -> Params:
```

返回 NN Archive 的头部特定元数据。

子类重写该方法以向其解析器提供更多值。[get_head_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_head.md) 将结果合并到 `"metadata"` 字典中。基本实现返回一个空字典。

返回

 * `Params`: 附加元数据键及其值。

#### 属性

##### attach_index

##### dropout

##### fc

##### in_channels

CLS token 的嵌入大小。

它是 [BaseNode.in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 的最后一个维度，即输入形状 `[B, C]` 中的 `C`。它取代了 [BaseNode.in_channels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)，后者从末尾读取第三个维度。

引发

 * `TypeError`: 当 [BaseNode.in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 是大小列表时。这发生在 `attach_index` 为 `"all"` 或范围时。构造函数读取该属性，因此它也会引发错误。

##### parser
