# blocks

Python API: `luxonis_train.nodes.backbones.efficientvit.blocks`

EfficientViT 主干网络的卷积和注意力块。

## 类

### DepthWiseSeparableConv

带可选残差连接的深度可分离卷积。

该块运行一个深度
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)，然后是一个
`1x1` 点式
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。深度卷积为每个输入通道设置一个组。两个卷积都带有批归一化。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.backbones.efficientvit.blocks import (
...     DepthWiseSeparableConv,
... )
>>> block = DepthWiseSeparableConv(8, 16, stride=2)
>>> block(torch.zeros(1, 8, 15, 15)).shape
torch.Size([1, 16, 8, 8])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, kernel_size: int = 3, stride: int = 1, depthwise_bias: bool = False,
pointwise_bias: bool = False, depthwise_activation: nn.Module | None = None, pointwise_activation: nn.Module | None = None,
padding: int | str | None = None, dilation: int | tuple[int, int] = 1, use_residual: bool = False):
```

构建深度卷积和点式卷积。

参数

 * `in_channels` (`int`): 输入通道数。深度卷积保持此通道数。
 * `out_channels` (`int`): 点式卷积的输出通道数。
 * `kernel_size` (`int`): 深度卷积的核大小。默认为 `3`。
 * `stride` (`int`): 深度卷积的步幅。默认为 `1`。
 * `depthwise_bias` (`bool`): 深度卷积是否具有偏置项。默认为 `False`。
 * `pointwise_bias` (`bool`): 点式卷积是否具有偏置项。默认为 `False`。
 * `depthwise_activation` (`nn.Module | None`): 深度卷积后的激活函数。`None` 选择 `torch.nn.ReLU6`。
 * `pointwise_activation` (`nn.Module | None`): 点式卷积后的激活函数。`None` 选择无激活函数。
 * `padding` (`int | str | None`): 深度卷积的填充，或字符串 `"same"` 或 `"valid"`。`None` 选择 `kernel_size // 2`。此值仅在核大小为奇数、步幅为 `1` 且膨胀为 `1` 时保持大小。
 * `dilation` (`int | tuple[int, int]`): 深度卷积的膨胀。默认为 `1`。
 * `use_residual` (`bool`): [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 是否将输入添加到输出。输入和输出必须具有相同的形状。默认为 `False`。

##### forward

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

应用深度卷积和点式卷积。

参数

 * `x` (`Tensor`): 形状为 `[B, in_channels, H, W]` 的输入。

返回

 * `Tensor`: 形状为 `[B, out_channels, H', W']` 的输出。对于默认填充、奇数核大小和膨胀为 `1` 的情况，H’ = ⌈H ⁄ s⌉ 且 W’ = ⌈W ⁄ s⌉，其中 s 是 `stride`。当 `use_residual` 为 `True` 时，该方法将输入添加到结果中。

#### 属性

##### depthwise_conv

##### pointwise_conv

### EfficientViTBlock

EfficientViT 块，包含注意力部分和卷积部分。

[LightweightMLABlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 混合所有位置的特征。然后，[MobileBottleneckBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 混合相邻位置的特征。两部分都将其输入添加到其输出，因此该块保持其输入的形状。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.backbones.efficientvit.blocks import (
...     EfficientViTBlock,
... )
>>> block = EfficientViTBlock(32, head_dim=8)
>>> block(torch.zeros(1, 32, 8, 8)).shape
torch.Size([1, 32, 8, 8])
```

#### 方法

##### init

```python
def __init__(n_channels: int, attention_ratio: float = 1.0, head_dim: int = 32, expansion_factor: float = 4.0, aggregation_scales: tuple[int, ...] = (5)):
```

构建注意力部分和卷积部分。

注意力部分是一个
[LightweightMLABlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md)，仅在其投影后带有批归一化。卷积部分是一个
[MobileBottleneckBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md)，带有
`3x3` 核。其扩展层和深度层具有偏置项和 `torch.nn.Hardswish` 激活。只有其投影层具有批归一化。

参数

 * `n_channels` (`int`): 输入和输出通道数。
 * `attention_ratio` (`float`): 注意力头数量的因子。注意力部分有 `int(n_channels // head_dim * attention_ratio)` 个头。头的数量必须至少为 `1`。当头数为 `0`
   且至少有一个聚合尺度时，`torch.nn.Conv2d` 会引发 `ValueError`。默认为 `1.0`。
 * `head_dim` (`int`): 每个注意力头的查询、键和值通道数。默认为 `32`。
 * `expansion_factor` (`float`): 卷积部分的通道扩展因子。默认为 `4.0`。
 * `aggregation_scales` (`tuple[int, ...]`): 注意力部分每个多尺度聚合分支的深度卷积核大小。值必须为奇数。默认为 `(5,)`。

##### forward

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

先应用注意力部分，然后应用卷积部分。

参数

 * `x` (`Tensor`): 形状为 `[B, n_channels, H, W]` 的输入。

返回

 * `Tensor`: 形状为 `[B, n_channels, H, W]` 的输出。

#### 属性

##### attention_module

##### feature_module

### LightweightMLABlock

EfficientViT 的轻量级多尺度线性注意力块。

一个 `1x1`
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
计算所有头的查询、键和值，作为一个 `qkv` 张量。每个聚合分支在该张量上运行一个深度卷积（核大小来自 `scale_factors`）和一个分组 `1x1` 卷积。该块连接 `qkv`
张量和分支输出。然后，每个尺度的每个头计算其自身的注意力。对于一个头的查询 Q、键 K 和值 V，位置 j 的输出为：

Oj = (∑iVi ϕ(Ki)⊤ϕ(Qj))/(∑iϕ(Ki)⊤ϕ(Qj) + ϵ)

求和遍历所有位置 i。ϕ 是 `kernel_activation`。一个 `1x1`
[ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
将所有尺度的注意力输出投影到 `output_channels`。当 `use_residual` 为 `True` 时，该块将输入添加到投影输出。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.backbones.efficientvit.blocks import (
...     LightweightMLABlock,
... )
>>> block = LightweightMLABlock(16, 24, use_residual=False)
>>> block.qkv_layer.conv.out_channels
48
>>> block(torch.zeros(1, 16, 4, 4)).shape
torch.Size([1, 24, 4, 4])
```

#### 方法

##### init

```python
def __init__(input_channels: int, output_channels: int, n_heads: int | None = None, head_ratio: float = 1.0, dimension: int = 8,
use_bias: list[bool] | None = None, use_norm: list[bool] | None = None, activations: list[nn.Module] | None = None, scale_factors:
tuple[int, ...] = (5), epsilon: float = 1e-15, use_residual: bool = True, kernel_activation: nn.Module | None = None):
```

构建 `qkv` 层、聚合分支和投影。

参数

 * `input_channels` (`int`): 输入通道数。
 * `output_channels` (`int`): 输出通道数。当 `use_residual` 为 `True` 时，它必须等于 `input_channels`。
 * `n_heads` (`int | None`): 注意力头数。`None` 或 `0` 选择 `int(input_channels // dimension * head_ratio)`。头的数量必须至少为 `1`。当头数为 `0` 且至少有一个聚合分支时，`torch.nn.Conv2d` 会引发 `ValueError`。
 * `head_ratio` (`float`): 当 `n_heads` 为 `None` 或 `0` 时，头数量的因子。默认为 `1.0`。
 * `dimension` (`int`): 每个头的查询、键和值通道数。默认为 `8`。
 * `use_bias` (`list[bool] | None`): 层是否具有偏置项，作为两个值。第一个值应用于 `qkv` 层和聚合分支的卷积。第二个值应用于投影。`None` 选择 `[False, False]`。
 * `use_norm` (`list[bool] | None`): `qkv` 层和投影是否具有批归一化，作为两个值。`None` 选择 `[False, True]`。
 * `activations` (`list[nn.Module] | None`): `qkv` 层后和投影后的激活函数。`None` 选择两个 `torch.nn.Identity` 模块。
 * `scale_factors` (`tuple[int, ...]`): 每个聚合分支的深度卷积核大小。该块为每个值设置一个分支。值必须为奇数。偶数值会改变分支输出的高度和宽度，并且 [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 会失败。默认为 `(5,)`。
 * `epsilon` (`float`): 注意力添加到其分母的值。默认为 `1e-15`。
 * `use_residual` (`bool`): [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 是否将输入添加到输出。默认为 `True`。
 * `kernel_activation` (`nn.Module | None`): 在查询和键上运行的核函数 ϕ。`None` 选择 `torch.nn.ReLU`。

##### forward

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

计算多尺度注意力并投影结果。

该方法运行 `qkv` 层和聚合分支，并连接它们的输出。当 `H * W` 大于 `dimension` 时，它调用 [linear_attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md)。否则，它调用 [quadratic_attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md)。它将 [linear_attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 的结果转换回 `qkv` 张量的类型。然后，投影将结果映射到 `output_channels`。当 `use_residual` 为 `True` 时，该方法将输入就地添加到投影输出。

参数

 * `x` (`Tensor`): 形状为 `[B, input_channels, H, W]` 的输入。

返回

 * `Tensor`: 形状为 `[B, output_channels, H, W]` 的输出。

##### linear_attention

```python
def linear_attention(qkv_tensor: Tensor) -> Tensor:
```

以线性成本计算每个头的注意力。

该方法将 `qkv_tensor` 的通道分成 `3 * dimension` 个通道组。每个组包含一个头的查询、键和值。该方法计算 [LightweightMLABlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 所示的注意力公式。它首先用一行 1 填充 V，并将结果乘以 ϕ(K)⊤。额外的行然后给出分母。因此，成本随 `H * W` 线性增长。

该方法在禁用 CUDA 自动混合精度的情况下运行。`float16` 输入以 `float32` 运行。`bfloat16` 输入以 `bfloat16` 运行，并且该方法在除法之前将结果转换为 `float32`。

> **示例**
> 线性和二次注意力给出相同的值。

```pycon
>>> import torch
>>> from luxonis_train.nodes.backbones.efficientvit.blocks import (
...     LightweightMLABlock,
... )
>>> block = LightweightMLABlock(8, 8, dimension=4)
>>> qkv = torch.arange(96.0).reshape(1, 24, 2, 2) / 96
>>> linear = block.linear_attention(qkv)
>>> linear.shape
torch.Size([1, 8, 2, 2])
>>> torch.allclose(linear, block.quadratic_attention(qkv))
True
```

参数

 * `qkv_tensor` (`Tensor`): 形状为 `[B, G * 3 * dimension, H, W]` 的查询、键和值，其中 `G` 是组数。

返回

 * `Tensor`: 形状为 `[B, G * dimension, H, W]` 的注意力输出。当输入为 `float16` 或 `bfloat16` 时，它为 `float32`。

##### quadratic_attention

```python
def quadratic_attention(qkv_tensor: Tensor) -> Tensor:
```

使用完整的注意力图计算每个头的注意力。

该方法将 `qkv_tensor` 的通道分成组，如 [linear_attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 所述。它构建形状为 `[B, G, H * W, H * W]` 的注意力图 Aij = ϕ(Ki)⊤ϕ(Qj)。它将图的每列 j 除以 ∑iAij + ϵ。然后它返回 Oj = ∑iViAij 和除法后的图。这些值与 [linear_attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md) 的值相同，但成本随 `H * W` 的平方增长。

该方法在禁用 CUDA 自动混合精度的情况下运行。它以 `float32` 归一化 `float16` 或 `bfloat16` 注意力图，然后将图转换回输入类型。

参数

 * `qkv_tensor` (`Tensor`): 形状为 `[B, G * 3 * dimension, H, W]` 的查询、键和值，其中 `G` 是组数。

返回

 * `Tensor`: 形状为 `[B, G * dimension, H, W]` 的注意力输出，类型与输入相同。

#### 属性

##### kernel_activation

##### multi_scale_aggregators

##### projection_layer

##### qkv_layer

### MobileBottleneckBlock

移动倒置瓶颈块。

该块运行三个 [ConvBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 层。一个 `1x1` 卷积扩展通道。接着是一个深度卷积，每个隐藏通道一个组。第二个 `1x1` 卷积将通道投影到 `out_channels`。这三层中的每一层都有自己的偏置、批归一化和激活设置。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.backbones.efficientvit.blocks import (
...     MobileBottleneckBlock,
... )
>>> block = MobileBottleneckBlock(8, 16, stride=2, expand_ratio=4)
>>> block.depthwise_conv.conv.in_channels
32
>>> block(torch.zeros(1, 8, 16, 16)).shape
torch.Size([1, 16, 8, 8])
```

#### 方法

##### init

```python
def __init__(in_channels: int, out_channels: int, kernel_size: int = 3, stride: int = 1, expand_ratio: float = 6, use_bias: list[bool] | None = None, use_norm: list[bool] | None = None, activation: list[nn.Module] | None = None, use_residual: bool = False):
```

构建扩展层、深度层和投影层。

参数

 * `in_channels` (`int`): 输入通道数。
 * `out_channels` (`int`): 输出通道数。
 * `kernel_size` (`int`): 深度卷积的核大小。填充为 `kernel_size // 2`。默认为 `3`。
 * `stride` (`int`): 深度卷积的步幅。默认为 `1`。
 * `expand_ratio` (`float`): 通道扩展因子。隐藏层有 `round(in_channels * expand_ratio)` 个通道。默认为 `6`。
 * `use_bias` (`list[bool] | None`): 每层是否具有偏置项，作为扩展层、深度层和投影层的三个值。`None` 选择 `[False, False, False]`。
 * `use_norm` (`list[bool] | None`): 每层是否具有批归一化，顺序相同。`None` 选择 `[True, True, True]`。
 * `activation` (`list[nn.Module] | None`): 每层后的激活函数，顺序相同。`None` 选择 `torch.nn.ReLU6`、`torch.nn.ReLU6` 和 `torch.nn.Identity`。
 * `use_residual` (`bool`):
   [forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/efficientvit/blocks.md)
   是否将输入添加到输出。输入和输出必须具有相同的形状。默认为 `False`。

##### forward

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

应用扩展层、深度层和投影层。

参数

 * `x` (`Tensor`): 形状为 `[B, in_channels, H, W]` 的输入。

返回

 * `Tensor`: 形状为 `[B, out_channels, H', W']` 的输出。对于奇数核大小，H’ = ⌈H ⁄ s⌉ 且 W’ = ⌈W ⁄ s⌉，其中 s 是 `stride`。当 `use_residual` 为 `True`
   时，该方法将输入添加到结果中。

#### 属性

##### depthwise_conv

##### expand_conv

##### project_conv
