# ghostfacenet_head

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

GhostFaceNet 的嵌入头。

## 类

### GhostFaceNetHead

GhostFaceNet 嵌入头。

 * `输入:`: * `inputs` (`Tensor`): [B, C, ⌈H ⁄ 32⌉, ⌈W ⁄ 32⌉]
 * `输出:`: * `embeddings` (`Tensor`): [B, D]，其中 D 是 `embedding_size`

> **参考**
> * 来源：改编自 [Hazqeel09/ellzaf_ml](https://github.com/Hazqeel09/ellzaf_ml) (MIT)。
 * 许可证：MIT

> **注意事项**
> H 和 W 是模型输入的高度和宽度。[GhostFaceNet](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/ghostfacenet/ghostfacenet.md) 主干网络的最后一个输出具有此大小。头部按顺序应用这些层：

 * 一个深度可分离
   [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)，带有批量归一化，无激活。其核大小与输入图相同，因此输出为
   `1x1`。
 * 一个 dropout 层。
 * 一个 `1x1` 卷积，无偏置，输出 D 个通道。
 * 一个展平步骤和一个 1D 批量归一化。

`forward` 不检查模式，因此导出模式也提供嵌入。**输入图必须具有上述确切大小。**其他大小的图会导致层引发 `RuntimeError`。在训练模式下，单图像批次会导致深度可分离
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
的批量归一化引发 `ValueError`。

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

> **另请参阅**
> * [ellzaf_ml 中的 GhostFaceNetsV2 代码](https://github.com/Hazqeel09/ellzaf_ml/blob/main/ellzaf_ml/models/ghostfacenetsv2.py)
 * [GhostFaceNets: Lightweight Face Recognition Model From Cheap
   Operations](https://www.researchgate.net/publication/369930264_GhostFaceNets_Lightweight_Face_Recognition_Model_from_Cheap_Operations)

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

```yaml
- name: GhostFaceNetHead
  inputs: [GhostFaceNet]
```

 * `兼容:`: * 附加索引：`-1`，输入节点的最后一个输出
    * 所需标签：`metadata/id`
    * 由以下使用：[EmbeddingsModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/embeddings/v1/model.md)
    * 损失： * `AngularLoss`
       * `CircleLoss`
       * `ContrastiveLoss`
       * `DynamicSoftMarginLoss`
       * `FastAPLoss`
       * `GeneralizedLiftedStructureLoss`
       * `HistogramLoss`
       * `InstanceLoss`
       * `IntraPairVarianceLoss`
       * `LiftedStructureLoss`
       * `MarginLoss`
       * `MultiSimilarityLoss`
       * `NCALoss`
       * `NPairsLoss`
       * `NTXentLoss`
       * `PNPLoss`
       * `RankedListLoss`
       * `SignalToNoiseRatioContrastiveLoss`
       * `SupConLoss`
       * `ThresholdConsistentMarginLoss`
       * `TripletMarginLoss`
       * `TupletMarginLoss`
    * 指标： *
      [ClosestIsPositiveAccuracy](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
       * [MedianDistances](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/embedding_metrics.md)
    * 可视化工具：[EmbeddingsVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)

#### 方法

##### init

```python
def __init__(embedding_size: int = 512, cross_batch_memory_size: int | None = None, dropout: float = 0.2, **kwargs):
```

构建头部的层。

构造函数将 `embedding_size` 和 `cross_batch_memory_size` 存储在同名属性中。嵌入损失从节点读取这两个属性。嵌入指标仅读取 `cross_batch_memory_size`。深度可分离卷积的核是 ⌈H ⁄
32⌉×⌈W ⁄ 32⌉，其中 H 和 W 来自 `original_in_shape`。

参数

 * `embedding_size` (`int`): 每个嵌入中的值数量。它是 `1x1` 卷积的输出通道数。
 * `cross_batch_memory_size` (`int | None`): 嵌入损失和指标在批次之间保留在内存中的最新嵌入的最大数量。`None` 关闭此内存。不支持 `CrossBatchMemory`
   的损失会记录警告并忽略该值。头部本身不读取该值。
 * `dropout` (`float`): dropout 层在训练模式下将值设置为零的概率，范围为 `[0, 1]`。
 * `**kwargs`:
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。它们必须包含 `original_in_shape`，以及 `input_shapes` 或 `in_sizes`。

##### forward

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

计算一批特征图的嵌入。

> **示例**
> `100x100` 像素的模型输入会生成 `4x4` 的图，因为 ⌈100 ⁄ 32⌉ = 4：

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import GhostFaceNetHead
>>> head = GhostFaceNetHead(
...     embedding_size=16,
...     input_shapes=[{"features": [Size([2, 8, 4, 4])]}],
...     original_in_shape=Size([3, 100, 100]),
... )
>>> packet = head.run([{"features": [torch.zeros(2, 8, 4, 4)]}])
>>> packet["embeddings"].shape
torch.Size([2, 16])
```

参数

 * `x` (`Tensor`): 主干网络的最后一个特征图，形状为 `[B, C, ceil(H / 32), ceil(W / 32)]`。`H` 和 `W` 来自 `original_in_shape`。

返回

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

##### initialize_weights

```python
def initialize_weights(method: str | None = None):
```

初始化卷积层和 2D 批量归一化层。

该方法首先使用 `method` 调用
[BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。然后，它从均值为
`0` 且标准差为以下值的正态分布中抽取每个 `torch.nn.Conv2d` 和 `torch.nn.Linear` 的权重：

σ = √((2)/(nin(1 + a2)))

nin 是层的扇入，a 是 `0.25`。这是斜率为 `0.25` 的 leaky ReLU 的 Kaiming 正态初始化。偏置不变。

每个 `torch.nn.BatchNorm2d` 随后获得 `momentum=0.9` 和 `eps=1e-5`。1D 批量归一化保持其默认值。PyTorch 将 `momentum` 用作新批次在运行统计中的权重。使用
`0.9`，这些统计数据因此密切跟踪最近的批次。

> **示例**
> 节点在构造后调用该方法：

```pycon
>>> from torch import Size
>>> from luxonis_train.nodes import GhostFaceNetHead
>>> head = GhostFaceNetHead(
...     input_shapes=[{"features": [Size([2, 8, 4, 4])]}],
...     original_in_shape=Size([3, 112, 112]),
...     weights="yolo",
... )
>>> batch_norm = head.head[0].bn
>>> batch_norm.momentum, batch_norm.eps
(0.9, 1e-05)
```

参数

 * `method` (`str | None`):
   [BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的方法。该值对此头部没有影响。头部没有 `"yolo"` 更改的激活，并且该方法替换了 `"yolo"` 的批量归一化值。

#### 属性

##### cross_batch_memory_size

##### embedding_size

##### head

##### in_channels

附加输入的通道数。

它是
[in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
从末尾数起的第三个维度，因此带或不带批次维度的形状给出相同的值。大小列表给出通道数列表。

引发

 * `RuntimeError`: 当
   [in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   找不到输入大小时。
 * `ValueError`: 当
   [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   不适合大小时。

##### in_width

附加输入的宽度。

它是
[in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的最后一个维度。大小列表给出宽度列表。

引发

 * `RuntimeError`: 当
   [in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   找不到输入大小时。
 * `ValueError`: 当
   [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   不适合大小时。
