# blocks

Python API: `luxonis_train.nodes.necks.svtr_neck.blocks`

SVTR 颈部的 token 混合器和 Transformer 块。

## 类

### Attention

对 token 序列进行多头自注意力。

一个线性层计算所有头的查询 Q、键 K 和值 V。每个头计算

softmax(s Q**KT + M)V

其中 s 是比例，M 是掩码。然后一个线性层合并这些头。在 softmax 和合并之后是 Dropout。

`"global"` 混合器没有掩码，因此每个 token 都会关注所有 token。`"local"` 混合器让一个 token 只关注其周围 `kernel_size` 窗口内的 token。对于奇数大小，窗口以 token 为中心。掩码在窗口内为
`0`，在窗口外为 − ∞。它的形状为 `[1, 1, N, N]`，其中 `N` 是 `height * width`。

警告： 掩码是一个普通属性，而不是缓冲区。`torch.nn.Module.to` 不会移动它，状态字典也不包含它。掩码保留在 CPU 上，因此 `"local"` 混合器仅适用于 CPU 上的输入。

> **示例**
> 对于 `3x3` 窗口，第 `1` 行第 `2` 列的 token `7` 会看到 `3x5` 映射的三个列。只有它看到的 token 才会从其输出中获得梯度：

```pycon
>>> import torch
>>> from luxonis_train.nodes.necks.svtr_neck.blocks import Attention
>>> attention = Attention(
...     8, height=3, width=5, n_heads=2, mixer="local", kernel_size=3
... )
>>> tokens = torch.randn(1, 15, 8, requires_grad=True)
>>> attention(tokens)[0, 7].sum().backward()
>>> seen = tokens.grad[0].abs().sum(dim=1) > 0
>>> seen.view(3, 5).int().tolist()
[[0, 1, 1, 1, 0], [0, 1, 1, 1, 0], [0, 1, 1, 1, 0]]
```

#### 方法

##### init

```python
def __init__(dim: int, height: int | None = None, width: int | None = None, n_heads: int = 8, mixer: Literal['global', 'local'] = 'global', kernel_size: tuple[int, int] | int = (7, 11), qk_scale: float | None = None, attn_drop: float = 0.0, proj_drop: float = 0.0):
```

构建线性层和局部混合器的掩码。

参数

 * `dim` (`int`): 每个 token 的通道数。它必须是 `n_heads` 的倍数。当 `qk_scale` 为 `None` 或 `0` 时，小于 `n_heads` 的值会使构造函数引发 `ZeroDivisionError`。
 * `height` (`int | None`): token 映射的高度。`"local"` 混合器需要它。`"global"` 混合器忽略它。
 * `width` (`int | None`): token 映射的宽度。`"local"` 混合器需要它。`"global"` 混合器忽略它。
 * `n_heads` (`int`): 注意力头的数量。每个头获得 `dim // n_heads` 个通道。
 * `mixer` (`Literal['global', 'local']`): 注意力类型。`"global"` 没有掩码。`"local"` 构建窗口掩码。
 * `kernel_size` (`tuple[int, int] | int`): `"local"` 混合器窗口的高度和宽度。整数表示方形窗口。`"global"` 混合器忽略它。
 * `qk_scale` (`float | None`): 查询的比例 s。`None` 或 `0` 给出 1 ⁄ √(d)，其中 d 是 `dim // n_heads`。
 * `attn_drop` (`float`): 注意力权重的 Dropout 概率。
 * `proj_drop` (`float`): 合并头部的线性层之后的 Dropout 概率。

引发

 * `ValueError`: 当 `mixer` 为 `"local"` 且 `height` 或 `width` 为 `None` 时。

##### forward

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

将自注意力应用于 token 序列。

参数

 * `x` (`Tensor`): token，形状为 `[B, N, dim]`。对于 `"local"` 混合器，`N` 必须是 `height * width`，并且 `x` 必须在 CPU 上。在其他设备上，添加 CPU 掩码会引发
   `RuntimeError`。

返回

 * `Tensor`: 经过注意力的 token，形状为 `[B, N, dim]`。

#### 属性

##### attn_drop

##### proj

##### proj_drop

##### qkv

### ConvMixer

[SVTRBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/necks/svtr_neck/blocks.md)
的 token 混合器，使用分组卷积。

混合器将 token 序列重塑为 `height` 乘以 `width` 的 token 映射。一个具有 `n_heads` 组和偏置的卷积将每个 token 与其邻居混合。然后混合器将映射展平回序列，逐行进行。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.necks.svtr_neck.blocks import ConvMixer
>>> mixer = ConvMixer(8, height=2, width=4, n_heads=2)
>>> mixer(torch.zeros(1, 8, 8)).shape
torch.Size([1, 8, 8])
```

#### 方法

##### init

```python
def __init__(dim: int, height: int, width: int, n_heads: int, kernel_size: tuple[int, int] = (3, 3)):
```

构建分组卷积。

参数

 * `dim` (`int`): 每个 token 的通道数。它必须是 `n_heads` 的倍数。
 * `height` (`int`): token 映射的高度。
 * `width` (`int`): token 映射的宽度。
 * `n_heads` (`int`): 卷积的组数。
 * `kernel_size` (`tuple[int, int]`): 卷积核的高度和宽度。填充是每个值的一半，向下取整。因此只有奇数值才能保持映射的大小。

##### forward

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

将每个 token 与其在 token 映射中的邻居混合。

参数

 * `x` (`Tensor`): token，形状为 `[B, height * width, dim]`。对于其他数量的 token，`reshape` 会引发 `RuntimeError`。

返回

 * `Tensor`: 混合后的 token，对于奇数核大小，其形状与 `x` 相同。

#### 属性

##### local_mixer

### SVTRBlock

带有 token 混合器和 MLP 的 SVTR Transformer 块。

该块有两个残差分支。第一个分支运行混合器：

 * `"global"` 和 `"local"` 构建一个 [Attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/necks/svtr_neck/blocks.md)。
 * `"conv"` 构建一个 [ConvMixer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/necks/svtr_neck/blocks.md)。

第二个分支运行一个 MLP：一个线性层到 `int(dim * mlp_ratio)` 特征，`act_layer`，Dropout，一个线性层回到 `dim`，以及 Dropout。当 `drop_path` 大于 `0` 时，[DropPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 在训练模式下为随机样本丢弃每个分支。

`prenorm` 设置两个范数层的位置。f 是一个分支：

 * `True`: 在每个残差和之后，x ← norm(x + f(x))。
 * `False`: 在每个分支之前，x ← x + f(norm(x))。

标志名称与常用术语不符： `prenorm=True` 将范数层放在和之后。

> **示例**
> ```pycon
>>> import torch
>>> from luxonis_train.nodes.necks.svtr_neck.blocks import SVTRBlock
>>> block = SVTRBlock(8, n_heads=2, mixer="conv", height=2, width=4)
>>> block(torch.zeros(1, 8, 8)).shape
torch.Size([1, 8, 8])
```

#### 方法

##### init

```python
def __init__(dim: int, n_heads: int, height: int | None = None, width: int | None = None, mixer: Literal['global', 'local', 'conv'] = 'global', mixer_kernel_size: tuple[int, int] = (7, 11), mlp_ratio: float = 4.0, qk_scale: float | None = None, dropout: float = 0.0, attn_drop: float = 0.0, drop_path: float = 0.0, act_layer: type[nn.Module] = nn.GELU, norm_layer: type[nn.Module] = nn.LayerNorm, epsilon: float = 1e-06, prenorm: bool = True):
```

构建混合器、MLP 和两个范数层。

参数

 * `dim` (`int`): 每个 token 的通道数。它必须是 `n_heads` 的倍数。
 * `n_heads` (`int`): 注意力头的数量，或 `"conv"` 混合器的卷积组数。
 * `height` (`int | None`): token 映射的高度。`"local"` 和 `"conv"` 混合器需要它。
 * `width` (`int | None`): token 映射的宽度。`"local"` 和 `"conv"` 混合器需要它。
 * `mixer` (`Literal['global', 'local', 'conv']`): token
   混合器。[Attention](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/necks/svtr_neck/blocks.md)
   在没有 `height` 和 `width` 的情况下，对 `"local"` 引发 `ValueError`。
 * `mixer_kernel_size` (`tuple[int, int]`): `"local"` 混合器的窗口，或 `"conv"` 混合器的核。`"global"` 混合器忽略它。
 * `mlp_ratio` (`float`): MLP 的隐藏特征数，作为 `dim` 的倍数。
 * `qk_scale` (`float | None`): 注意力查询的比例。`None` 或 `0` 给出 1 ⁄ √(d)，其中 d 是 `dim // n_heads`。`"conv"` 混合器忽略它。
 * `dropout` (`float`): MLP 的两个 Dropout 层的 Dropout 概率。`"global"` 和 `"local"` 混合器也将其应用于其输出。
 * `attn_drop` (`float`): 注意力权重的 Dropout 概率。`"conv"` 混合器忽略它。
 * `drop_path` (`float`):
   [DropPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   在训练模式下为样本丢弃分支的概率。`0.0` 不添加
   [DropPath](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。
 * `act_layer` (`type[nn.Module]`): MLP 的激活类。MLP 在没有参数的情况下调用它。
 * `norm_layer` (`type[nn.Module]`): 范数类。该块将其作为 `norm_layer(dim, eps=epsilon)` 调用。
 * `epsilon` (`float`): 两个范数层的 `eps`。
 * `prenorm` (`bool`): `True` 将范数层放在残差和之后。`False` 将它们放在分支之前。

引发

 * `ValueError`: 当 `mixer` 为 `"conv"` 且 `height` 或 `width` 为 `None` 时。

##### forward

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

运行混合器分支，然后运行 MLP 分支。

参数

 * `x` (`Tensor`): token，形状为 `[B, N, dim]`。`"local"` 和 `"conv"` 混合器需要 `N` 为 `height * width`。

返回

 * `Tensor`: 经过两个残差分支后的 token，形状为 `[B, N, dim]`。

#### 属性

##### drop_path

##### mixer

##### mlp

##### norm1

##### norm2
