亲和库

详细算子接口说明

def fuse_add_softmax_dropout(training, dropout, attn_mask, attn_scores, attn_head_size, p=0.5, dim=-1):

使用NPU自定义算子替换原生写法，以提高性能。

• 参数：
  • training (Bool)：是否为训练模式。
  • dropout (nn.Module): dropout层。
  • attn_mask (Tensor)：注意力掩码。
  • attn_scores (Tensor)：原始attention分数。
  • attn_head_size (Float)：head size。
  • p (Float，默认值为0.5)：元素被归零的概率。
  • dim (Int，默认值为-1)：待计算softmax的维度。
• 调用方式样例：

  from torch_npu.contrib.function import fuse_add_softmax_dropout
  fuse_add_softmax_dropout(training, dropout, npu_input1, npu_input2, alpha, p=axis)

• 返回值：

  torch.Tensor - mask操作的结果。

• 示例：

      >>> training = True
      >>> dropout = nn.DropoutWithByteMask(0.1)
      >>> npu_input1 = torch.rand(96, 12, 384, 384).half().npu()
      >>> npu_input2 = torch.rand(96, 12, 384, 384).half().npu()
      >>> alpha = 0.125
      >>> axis = -1
      >>> output = fuse_add_softmax_dropout(training, dropout, npu_input1, npu_input2, alpha, p=axis)

def npu_diou(boxes1,boxes2,trans=True, is_cross=False, mode=0):

应用基于NPU的DIoU操作。考虑到目标之间距离，以及距离和范围的重叠率，不同目标或边界需趋于稳定。

• 注释:

  到目前为止，DIoU向后只支持当前版本中的trans==True、is_cross==False、mode==0('iou')。如果需要反向传播，确保参数正确。

• 参数：
  • boxes1 (Tensor) - 格式为xywh、shape为(4, n)的预测检测框。
  • boxes2 (Tensor) - 相应的gt检测框，shape为(4, n)。
  • trans (Bool，默认值为True) - 是否有偏移。
  • is_cross (Bool，默认值为False) - box1和box2之间是否有交叉操作。
  • mode (Int，默认值为0) - 选择DIoU的计算方式。
• 调用方式样例：

  from torch_npu.contrib.function import npu_diou
  diou = npu_diou(box1, box2)

• 返回值：

  Tensor - IoU，size为[1,n]。

• 示例：

      >>> box1 = torch.randn(4, 32).npu()
      >>> box1.requires_grad = True
      >>> box2 = torch.randn(4, 32).npu()
      >>> box2.requires_grad = True
      >>> diou = npu_diou(box1, box2) 
      >>> l = diou.sum()
      >>> l.backward()

def npu_ciou(boxes1,boxes2,trans=True, is_cross=False, mode=0):

应用基于NPU的CIoU操作。在DIoU的基础上增加了penalty item，并propose CIoU。

• 注释:

  到目前为止，CIoU向后只支持当前版本中的trans==True、is_cross==False、mode==0('iou')。如果需要反向传播，确保参数正确。

• 参数：
  • boxes1 (Tensor) - 格式为xywh、shape为(4, n)的预测检测框。
  • boxes2 (Tensor) - 相应的gt检测框，shape为(4, n)。
  • trans (Bool，默认值为True) - 是否有偏移。
  • is_cross (Bool，默认值为False) - box1和box2之间是否有交叉操作。
  • mode (Int，默认值为0) - 选择CIoU的计算方式。
• 调用方式样例：

  from torch_npu.contrib.function import npu_ciou
  ciou = npu_ciou(box1, box2) 

• 返回值：

  Tensor - IoU，size为[1,n]。

• 示例：

      >>> box1 = torch.randn(4, 32).npu()
      >>> box1.requires_grad = True
      >>> box2 = torch.randn(4, 32).npu()
      >>> box2.requires_grad = True
      >>> ciou = npu_ciou(box1, box2) 
      >>> l = ciou.sum()
      >>> l.backward()

def npu_single_level_responsible_flags(featmap_size,gt_bboxes,stride,num_base_anchors):

使用NPU OP在单个特征图中生成锚点的responsible flags。

• 参数：
  • featmap_size (Tuple(Int)) - 模型总维度。
  • gt_bboxes (Tensor) - 并行attention heads。
  • stride (Tuple(Int)，默认值为None) - key的特性总数。
  • num_base_anchors (Int，默认值为None) - values的特性总数。
• 调用方式样例：

  from torch_npu.contrib.function import npu_single_level_responsible_flags
  out = npu_single_level_responsible_flags(featmap_sizes[i],gt_bboxes,stride[i],num_base_anchors)

• 返回值：

  torch.Tensor - 单层特征图中每个锚点的有效标志。输出大小为[featmap_size[0] * featmap_size[1] * num_base_anchors]。

• 示例：

      >>> featmap_sizes = [[10, 10], [20, 20], [40, 40]]
      >>> stride = [[32, 32], [16, 16], [8, 8]]
      >>> gt_bboxes = torch.randint(0, 512, size=(128, 4))
      >>> num_base_anchors = 3
      >>> featmap_level = len(featmap_sizes)
      >>> torch.npu.set_device(0)
      >>> for i in range(featmap_level):
              gt_bboxes = gt_bboxes.npu()
      >>> out = npu_single_level_responsible_flags(featmap_sizes[i],gt_bboxes,stride[i],num_base_anchors)
      >>> print(out.shape, out.max(), out.min())

def npu_bbox_coder_encode_yolo(bboxes, gt_bboxes, stride):

使用NPU OP获取将bbox转换为gt_bbox的框回归转换deltas。

• 参数:
  • bboxes (torch.Tensor) - 源框，例如锚点框。支持数据类型：float、half。
  • gt_bboxes (torch.Tensor) - 转换目标框，例如真值框。支持数据类型：float、half。
  • stride (torch.Tensor) - Bbox步长。仅支持int张量。
• 调用方式样例：

  from torch_npu.contrib.function import npu_bbox_coder_encode_yolo
  out = npu_bbox_coder_encode_yolo(bboxes, gt_bboxes, stride)

• 返回值:

  torch.Tensor - 框转换deltas。

• 示例：

      >>> A = 1024
      >>> bboxes = torch.randint(0, 512, size=(A, 4))
      >>> gt_bboxes = torch.randint(0, 512, size=(A, 4))
      >>> stride = torch.randint(0, 32, size=(A,))
      >>> torch.npu.set_device(0)
      >>> bboxes = bboxes.npu()
      >>> gt_bboxes = gt_bboxes.npu()
      >>> stride = stride.npu()
      >>> out = npu_bbox_coder_encode_yolo(bboxes, gt_bboxes, stride)
      >>> torch.npu.synchronize()
      >>> print('_npu_bbox_coder_encode_yolo done. output shape is ', out.shape)

def npu_bbox_coder_encode_xyxy2xywh(bboxes,gt_bboxes,means=None,stds=None,is_normalized=False,normalized_scale=10000.):

应用基于NPU的bbox格式编码操作，将格式从xyxy编码为xywh。

• 参数：
  • bboxes (Tensor) - 待转换的框，shape为(N, 4)。支持dtype：float, half。
  • gt_bboxes (Tensor) - 用作基准的gt_bboxes，shape为(N, 4)。支持dtype：float, half.。
  • means (List[float]，默认值为None) - 对delta坐标的目标去归一化的方法。
  • stds (List[float]，默认值为None) - 对delta坐标的目标去归一化的标准差。
  • is_normalized (Bool，默认值为False) - 坐标值是否已归一化。
  • normalized_scale (Float，默认值为10000.) - 设置坐标恢复的归一化比例。
• 调用方式样例：

  from torch_npu.contrib.function import npu_bbox_coder_encode_yolo
  out = npu_bbox_coder_encode_yolo(bboxes, gt_bboxes, stride)

• 约束限制

  不支持动态shape。由于算子语义限制，仅支持二维(n, 4)场景。Bboxes和gt_bboxesshape和dtype必须相同, dtype只可为float16和float32。第三个输入（步长）仅支持1D，且第一个维度与第一个输入（bboxes）相同。

• 返回值：

  torch.Tensor - 框转换deltas。

• 示例：

      >>> A = 1024
      >>> bboxes = torch.randint(0, 512, size=(A, 4))
      >>> gt_bboxes = torch.randint(0, 512, size=(A, 4))
      >>> stride = torch.randint(0, 32, size=(A,))
      >>> torch.npu.set_device(0)
      >>> bboxes = bboxes.npu()
      >>> gt_bboxes = gt_bboxes.npu()
      >>> stride = stride.npu()
      >>> out = npu_bbox_coder_encode_yolo(bboxes, gt_bboxes, stride)
      >>> torch.npu.synchronize()
      >>> print('_npu_bbox_coder_encode_yolo done. output shape is ', out.shape)

def npu_bbox_coder_decode_xywh2xyxy(bboxes,pred_bboxes,means=None,stds=None,max_shape=[9999, 9999],wh_ratio_clip=16 / 1000):

应用基于NPU的bbox格式编码操作，将格式从xywh编码为xyxy。

• 参数：
  • anchors (torch.Tensor) - 基础框，shape为(N, 4)。支持dtype：float, half。
  • pred_bboxes (torch.Tensor) - 编码框，shape为(N, 4)。支持dtype：float, half。
  • means (List[float]，默认值为None) - 对delta坐标的目标去归一化的方法。该参数需要与编码参数对齐。
  • stds (List[float]，默认值为None) - 对delta坐标的目标去归一化的标准差。该参数需要与编码参数对齐。
  • max_shape (Tuple[int]，可选，默认为[9999,9999]不受限制)：最大框shape(H, W)，一般对应bbox所在的真实图片的大小。
  • wh_ratio_clip (Float，可选，默认值为16/1000) - 可允许的宽高比。
• 调用方式样例：

  from torch_npu.contrib.function import npu_bbox_coder_decode_xywh2xyxy
  out = npu_bbox_coder_decode_xywh2xyxy(bboxes, pred_bboxes, max_shape=(max_shape, max_shape))

• 返回值：

  Tensor - shape为(N, 4)的框，其中4表示tl_x、tl_y、br_x、br_y。

• 示例：

      >>> A = 1024
      >>> max_shape = 512
      >>> bboxes = torch.randint(0, max_shape, size=(A, 4))
      >>> pred_bboxes = torch.randn(A, 4)
      >>> torch.npu.set_device(0)
      >>> bboxes = bboxes.npu()
      >>> pred_bboxes = pred_bboxes.npu()
      >>> out = npu_bbox_coder_decode_xywh2xyxy(bboxes, pred_bboxes, max_shape=(max_shape, max_shape))
      >>> torch.npu.synchronize    >>> ()
      >>> print('_npu_bbox_coder_decode_xywh2xyxy done. output shape is ', out.shape)

def npu_fast_condition_index_put(x, condition, value):

使用NPU亲和写法替换bool型index_put函数中的原生写法。

• 参数：
  • x (torch.Tensor) - normal Tensor。
  • condition (torch.BoolTensor) - 判断条件。
  • value (Int, Float) - bboxes步长。
• 调用方式样例：

  from torch_npu.contrib.function import npu_fast_condition_index_put
  x1_opt = npu_fast_condition_index_put(x, condition, value)

• 返回值：

  torch.Tensor - 框转换deltas。

• 示例：

      >>> x = torch.randn(128, 8192)
      >>> condition = x < 0.5
      >>> value = 0.
      >>> x1 = copy.deepcopy(x)[condition] = value
      >>> x1_opt = npu_fast_condition_index_put(x, condition, value)

class 
matmul_transpose
(torch.autograd.Function):

使用NPU自定义算子替换原生写法，以提高性能。

• 参数：
  • tensor1 (Tensor) - 第一个要乘的张量
  • tensor2 (Tensor) - 第二个要乘的张量
• 调用方式样例：

  from torch_npu.contrib.function import 
  matmul_transpose
  output = matmul_transpose(tensor1, tensor2)

• 约束限制

  在动态shape场景中，由于算子限制，不支持Box transformation deltas。

• 返回值：

  Tensor - 输出张量

• 示例：

          
          >>> tensor1 = torch.randn(68, 5, 75, 16).npu()
          >>> tensor1.requires_grad_(True)
          >>> tensor2 = torch.randn(68, 5, 75, 16).npu()
          >>> tensor2.requires_grad_(True)
          >>> output = matmul_transpose(tensor1, tensor2)
          >>> output.sum().backward()

def npu_multiclass_nms(multi_bboxes,multi_scores, score_thr=0.05,nms_thr=0.45,max_num=50,score_factors=None):

使用NPU API的多类bbox NMS。

• 参数：
  • multi_bboxes (Tensor) - shape(n, #class, 4)或(n, 4)。
  • multi_scores (Tensor) - shape(n, #class+1)，其中最后一列包含background class分数，可忽略。在NPU上，为保持语义畅通，我们将统一维度。
  • score_thr (Float，默认值为0.05) - bbox阈值，分数低于它的bbox将不被考虑。
  • nms_thr (Float，默认值为0.45) - NMS IoU阈值。最初的实现是传递{"iouthreshold": 0.45}字典，这里做了简化。
  • max_num (Int，默认值为50) - 如果NMS后的bbox数超过max_num值，则只保留最大max_num；如果NMS后的bbox数小于max_num值，则输出将零填充到max_num值。在NPU上需提前申请内存，因此目前不能将max_num值设置为-1。
  • score_factors (Tensor，默认值为None) - NMS应用前用来乘分数的因子。
• 调用方式样例：

  from torch_npu.contrib.function import npu_multiclass_nms
  det_bboxes, det_labels = npu_multiclass_nms(boxes, scores, score_thr=0.3, nms_thr=0.5, max_num=3)

• 约束限制

  在动态shape条件下，由于NPU op的限制，最多支持20个类别（nmsed_classes）和10000个框（nmsed_boxes）。

• 返回值：

  Tuple - (bboxes, labels)，shape为(k, 5)和(k, 1)的张量。标签以0为基础。

• 示例：

          >>> boxes = torch.randint(1, 255, size=(1000, 4))
          >>> scores = torch.randn(1000, 81)
          >>> boxes = boxes.npu().half()
          >>> scores = scores.npu().half()
          >>> det_bboxes, det_labels = npu_multiclass_nms(boxes, scores, score_thr=0.3, nms_thr=0.5, max_num=3)
          >>> expedt_det_bboxes = torch.tensor([[ 57.0000, 198.8750, 45.9688, 221.8750, 4.1484],[215.0000, 155.0000, 236.8750, 137.0000,3.9023], [208.8750, 221.0000, 228.0000,  17.0000,   3.8867]],dtype=torch.float16)

def npu_batched_multiclass_nms(multi_bboxes,multi_scores,score_thr=0.05,nms_thr=0.45,max_num=50,score_factors=None):

使用NPU API的批量多类bbox NMS。

• 参数：
  • multi_bboxes (Tensor) - shape(bs, n, #class, 4)或(bs, n, 4)。
  • multi_scores (Tensor) - shape(bs, n, #class+1)，其中最后一列包含background class分数，可忽略。在NPU上，为保持语义畅通，我们将统一维度。
  • score_thr (Float，默认值为0.05) - bbox阈值，分数低于它的bbox将不被考虑。
  • nms_thr (Float，默认值为0.45) - NMS IoU阈值。最初的实现是传递{"iouthreshold": 0.45}字典，这里做了简化。
  • max_num (Int，默认值为50) - 如果NMS后的bbox数超过max_num值，则只保留最大max_num；如果NMS后的bbox数小于max_num值，则输出将零填充到max_num值。在NPU上需提前申请内存，因此目前不能将max_num值设置为-1。
  • score_factors (Tensor，默认值为None) - NMS应用前用来乘分数的因子。
• 调用方式样例：

  from torch_npu.contrib.function import npu_batched_multiclass_nms
  det_bboxes, det_labels = npu_batched_multiclass_nms(boxes, scores, score_thr=0.3, nms_thr=0.5, max_num=3)

• 约束限制

  在动态shape条件下，由于NPU op的限制，最多支持20个类别（nmsed_classes）和10000个框（nmsed_boxes）。

• 返回值：

  Tuple - (bboxes, labels)，shape为(bs, k, 5)和(bs, k, 1)的张量。标签以0为基础。

• 示例：

    >>> boxes = torch.randint(1, 255, size=(4, 200, 80, 4))
    >>> scores = torch.randn(4, 200, 81)
    >>> boxes = boxes.npu().half()
    >>> scores = scores.npu().half()
    >>> det_bboxes, det_labels = npu_batched_multiclass_nms(boxes, scores, score_thr=0.3, nms_thr=0.5, max_num=3)
    >>> expedt_det_bboxes = torch.tensor([[[221.8750,  60.0000, 183.0000,  22.0000,   3.8867], [167.0000, 250.0000, 136.0000, 144.0000,   3.6445], [ 45.9688, 147.0000,  67.0000, 241.8750,   3.4844]], 
          [[  5.0000, 178.0000, 243.8750, 138.0000,   3.7344], [238.0000, 132.0000,  47.0000,  84.0000,   3.6836], [ 32.0000, 110.0000, 131.0000,  73.0000,   3.6309]], 
          [[111.9375, 120.9375,  54.0000, 231.0000,   3.9219], [147.0000, 162.0000,  78.0000,   1.0010,   3.9219], [157.0000, 118.0000,  57.0000, 115.0000,   3.6523]], 
          [[ 80.0000, 126.9375,  54.0000, 246.8750,   3.7344], [ 31.0000, 253.8750,  19.0000, 138.0000,   3.6328], [ 54.0000, 253.8750,  78.0000,  75.0000,   3.5586]]],dtype=torch.float16)

def dropout_with_byte_mask(input1, p=0.5, training=True, inplace=False)

此dropout_with_byte_mask方法生成无状态随机uint8掩码，并根据掩码执行dropout。

• 参数：
  • input1 (Tensor) - 输入张量。
  • p (Float，默认值为0.5) - 通道被归零的概率。
  • training (Bool，默认值为True) - 如果设置为True，则执行dropout。
  • inplace (Bool，默认值为False) - 如果设置为True，将就地执行此操作。
• 调用方式样例：

  from torch_npu.contrib.function import dropout_with_byte_mask
  torch_npu.dropout_with_byte_mask(input1, p, training)

• 示例：

  无

class roll():

使用NPU亲和写法替换swin-transformer中的原生roll。

• 参数：
  • input1 (Tensor) - 输入张量。
  • shifts (Int或Tuple of python:ints) - 张量元素移动的位置数。如果该shift组成的是tuple，则dims必须是大小相同的tuple，每个维度都将按相应的值roll。
  • dims (Int或Tuple of python:ints) - 沿着roll的轴。
• 调用方式样例：

  from torch_npu.contrib.function import roll
  shifted_x_npu = roll(input1, shifts=(-shift_size, -shift_size), dims=(1, 2))

• 返回值：

  Tensor - shifted input。

• 示例：

         
          >>> input1 = torch.randn(32, 56, 56, 16).npu()
          >>> shift_size = 3
          >>> shifted_x_npu = roll(input1, shifts=(-shift_size, -shift_size), dims=(1, 2))

class Mish(nn.Module):

应用基于NPU的Mish操作。

• 参数：

  无

• 调用方式样例：

  from torch_npu.contrib.module import Mish
  m = nn.Mish()

• 示例：

              >>> m = nn.Mish()
              >>> input_tensor = torch.randn(2, 32, 5, 5)
              >>> output = m(input_tensor)

class SiLU(nn.Module):

按元素应用基于NPU的Sigmoid线性单元（SiLU）函数。SiLU函数也称为Swish函数。

• 参数：

  无

• 调用方式样例：

  from torch_npu.contrib.module import SiLU
  m = nn.SiLU()

• 示例：

              >>> m = nn.SiLU()
              >>> input_tensor = torch.randn(2, 32, 5, 5)
              >>> output = m(input_tensor)

class ChannelShuffle(nn.Module):

应用NPU兼容的通道shuffle操作。为避免NPU上效率不高的连续操作，我们用相同语义重写替换原始操作。以下两个不连续操作已被替换：transpose和chunk。

• 参数：
  • Input (Tensor) - 输入张量。 (N, C_{in}, L_{in}), (N, C_{in}, L_{in})。
  • in_channels (Int) - 输入张量中的通道总数。
  • groups (Int，默认值为2) - shuffle组数。
  • split_shuffle (Bool，默认值为True) - Shuffle后是否执行chunk操作。默认值：True。
• 调用方式样例：

  from torch_npu.contrib.module import ChannelShuffle
  m = ChannelShuffle(64, split_shuffle=True)

• 返回值

  Output (Tensor) - 输出张量(N, C_{out}, L_{out})。

• 约束限制：

  只实现了group=2，请自行修改其他group场景。

• 示例：

     >>> x1 = torch.randn(2,32,7,7)
     >>> x2 = torch.randn(2,32,7,7)
     >>> m = ChannelShuffle(64, split_shuffle=True)
     >>> output = m(x1, x2)

class LabelSmoothingCrossEntropy(nn.Module):

使用NPU API进行LabelSmoothing Cross Entropy。

• 参数：
  • smooth_factor (Float，默认值为0) -如果正在使用LabelSmoothing，请改为0.1([0, 1])。
  • num_classes (Float) - 用于onehot的class数量。
• 调用方式样例：

  from torch_npu.contrib.module import LabelSmoothingCrossEntropy
  m = LabelSmoothingCrossEntropy(10)

• 返回值:

  Float - shape为(k, 5)和(k, 1)的张量。标签以0为基础。

• 示例：

     >>> x = torch.randn(2, 10)
     >>> y = torch.randint(0, 10, size=(2,))
     >>> x = x.npu()
     >>> y = y.npu()
     >>> x.requires_grad = True
     >>> m = LabelSmoothingCrossEntropy(10)
     >>> npu_output = m(x, y)
     >>> npu_output.backward()

class ModulatedDeformConv(nn.Module):

应用基于NPU的Modulated Deformable 2D卷积操作。

• 参数：
  • in_channels (Int) - 输入图像中的通道数。
  • out_channels (Int) - 卷积产生的通道数。
  • kernel_size(Int或Tuple) - 卷积核大小。
  • stride(Int, Tuple，默认值为1) - 卷积步长。
  • padding (Int或Tuple，默认值为0) - 添加到输入两侧的零填充。
  • dilation (Int或Tuple，默认值为1) - 内核元素间距。
  • groups (Int，默认值为1) - 从输入通道到输出通道的阻塞连接数。
  • deform_groups (Int) - 可变形组分区的数量。
  • bias (Bool，默认值为False) - 如果值为True，则向输出添加可学习偏差。
  • pack (Bool，默认值为True) - 如果值为True，此模块将包括con_offset和掩码。
• 调用方式样例：

  from torch_npu.contrib.module import ModulatedDeformConv
  m = ModulatedDeformConv(32, 32, 1)

• 约束限制

  ModedDeformConv仅实现float32数据类型的操作。conv_offset中权重和偏置必须初始化为0。

• 示例：

     >>> m = ModulatedDeformConv(32, 32, 1)
     >>> input_tensor = torch.randn(2, 32, 5, 5)
     >>> output = m(input_tensor)
  
     >>> x = torch.randn(2, 32, 7, 7) 
     >>> model = ModulatedDeformConv(32, 32, 3, 2, 1)
  
     >>> torch.npu.set_device(0)
     >>> x = x.npu()
     >>> model = model.npu()
  
     >>> o = model(x)
     >>> l = o.sum()
     >>> l.backward()
     >>> print(l)

class NpuDropPath(nn.Module):

使用NPU亲和写法替换swin_transformer.py中的原生Drop路径。丢弃每个样本（应用于residual blocks的主路径）的路径（随机深度）。

• 参数：
  • drop_prob (Float) - dropout概率。
  • x (Tensor) - 应用dropout的输入张量。
• 调用方式样例：

  from torch_npu.contrib.module import NpuDropPath
  fast_drop_path = NpuDropPath(0).npu()

• 示例：

    >>> input1 = torch.randn(68, 5).npu()
    >>> input1.requires_grad_(True)
    >>> input2 = torch.randn(68, 5).npu()
    >>> input2.requires_grad_(True)
    >>> fast_drop_path = NpuDropPath(0).npu()
    >>> output = input1 + fast_drop_path(input2)
    >>> output.sum().backward()

class NpuCachedDropout(torch.nn.Dropout):

在NPU设备上使用FairseqDropout。

• 参数：
  • p (Float) - 元素归零的概率。
  • module_name (String) - 模型名称。
• 调用方式样例：

  from torch_npu.contrib.module import NpuDropPath
  NpuCachedDropout.enable_dropout_ensemble(model)

• 示例：

    >>> model = NpuMNIST().to("npu")
    >>> x = torch.randn(2,10,16,16).to("npu")
    >>> NpuCachedDropout.enable_dropout_ensemble(model)
    >>> output = model(x)

class Focus(nn.Module):

使用NPU亲和写法替换YOLOv5中的原生Focus。

• 参数：
  • c1 (Int) - 输入图像中的通道数。
  • c2 (Int) - 卷积产生的通道数。
  • k(Int，默认值为1) - 卷积核大小。
  • s(Int，默认值为1) - 卷积步长。
  • p (Int) - 填充。
  • g (Int，默认值为1) - 从输入通道到输出通道的阻塞连接数。
  • act (Bool，默认值为True) - 是否使用激活函数。
• 调用方式样例：

  from torch_npu.contrib.module import Focus
  fast_focus = Focus(8, 13).npu()

• 示例：

     >>> input = torch.randn(4, 8, 300, 40).npu()
     >>> input.requires_grad_(True)
     >>> fast_focus = Focus(8, 13).npu()
     >>> output = fast_focus(input)
     >>> output.sum().backward()

class FusedColorJitter(torch.nn.Module):

随机更改图像的亮度、对比度、饱和度和色调。

• 参数：
  • brightness (Float或Tuple of float (min, max)) - 亮度调整值。Brightness_factor统一从[max(0, 1 - brightness), 1 + brightness]或给定的[min, max]中选择。非负数。
  • contrast (Float或Tuple of float (min, max)) - 对比度调整值。Contrast_factor统一从[max(0, 1 - contrast), 1 + contrast]或给定的[min, max]中选择。非负数。
  • saturation (Float或Tuple of float (min, max)) - 饱和度调整值。Saturation_factor统一从[max(0, 1 - saturation), 1 + saturation]或给定的[min, max]中选择。非负数。
  • hue (Float或Tuple of float (min, max)) - 色调调整值。Hue_factor统一从[-hue, hue]或给定的[min, max]中选择，且满足0<= hue <= 0.5或-0.5 <= min <= max <= 0.5
• 调用方式样例：

  from torch_npu.contrib.module import FusedColorJitter
  fcj = FusedColorJitter(0.1, 0.1, 0.1, 0.1) 

• 示例：

  from PIL import Image     
  image = Image.fromarray(torch.randint(0, 256, size=(224, 224, 3)).numpy().astype(np.uint8))    
  fcj = FusedColorJitter(0.1, 0.1, 0.1, 0.1)    
  image = fcj(image)

class MultiheadAttention(nn.Module):

Multi-headed attention.

• 参数：
  • embed_dim (Int) - 模型总维度。
  • num_heads (Int) - 并行attention head。
  • kdim(Int，默认值为None) - key的特性总数。
  • vdim(Int，默认值为None) - value的特性总数。
  • dropout (Float) - Dropout概率。
  • bias (Bool，默认值为True) - 如果指定此参数，则向输入/输出投影层添加偏置。
  • add_bias_kv (Bool，默认值为False) - 如果指定此参数，则在dim=0处向键值序列添加偏置。
  • add_zero_attn (Bool，默认值为False) - 如果指定此参数，则在dim=1处向键值序列新加一批零。
  • self_attention (Bool，默认值为False) - 计算你自己的attention score。
  • encoder_decoder_attention (Bool，默认值为False) - 输入为编码器输出和解码器self-attention输出，其中编码器self-attention用作key和value，解码器self-attention用作查询。
  • q_noise(Float) - 量化噪声量。
  • qn_block_size(Int) - 用于后续iPQ量化的块大小。
• 调用方式样例：

  from torch_npu.contrib.module import MultiheadAttention
  model = MultiheadAttention(embed_dim=1024,num_heads=16,dropout=0.1,kdim=1024,vdim=1024,self_attention=True,encoder_decoder_attention=True)

• 示例：

     >>> model = MultiheadAttention(embed_dim=1024,num_heads=16,dropout=0.1,kdim=1024,vdim=1024,self_attention=True,encoder_decoder_attention=True)
     >>> _, query = create_common_tensor([np.float16, FORMAT_NZ, (1024,1024)], -1, 1)
     >>> _, key = create_common_tensor([np.float16, FORMAT_NZ, (1024, 1024)], -1, 1)
     >>> _, value = create_common_tensor([np.float16, FORMAT_NZ, (1024, 1024)], -1, 1)
     >>> _, key_padding_mask = create_common_tensor([np.float16, FORMAT_NZ, (16,16,64,64)], -65504, 65504)
     >>> bsz = 16
     >>> tgt_len = 64
     >>> s_len=64
     >>> model = model.to("npu")
     >>> output = model(query, key, value, bsz, tgt_len, s_len,   key_padding_mask)

class DropoutWithByteMask(Module):

应用NPU兼容的DropoutWithByteMask操作。

• 参数：
  • Input (Tensor) - 输入张量，可为任何shape。
  • p (Float，默认值为0.5) - 元素归零的概率。
  • inplace (Bool，默认值为False) - 如果设置为True，原地执行此操作。
• 调用方式样例：

  from torch_npu.contrib.module.npu_modules import DropoutWithByteMask
  m = DropoutWithByteMask(p=0.5)

• 返回值：
  • Output (Tensor) - 输出张量与输入张量的shape相同。
• 约束限制：
  • Maxseed是一个与底层算子强相关的超参数。请检查算子包的dropoutv2.py文件中的MAX(2 ** 31 - 1 / 2 ** 10 - 1)以匹配设置。默认情况下，它与PyTorch和算子包匹配。
  • 仅支持NPU设备。
• 示例：

    >>> m = DropoutWithByteMask(p=0.5)
    >>> input = torch.randn(16, 16)
    >>> output = m(input)

def dropout_with_byte_mask(input1, p=0.5, training=True, inplace=False)

class PSROIPool(nn.Module):

使用NPU API进行ROIAlign。

• 参数：
  • pooled_height (Int) - 池化高度。
  • pooled_width (Int) - 池化宽度。
  • spatial_scale (Float) - 按此参数值缩放输入框。
  • group_size (Int) - 编码位置敏感分数图的组数。
  • output_dim (Int) - 输出通道数。
• 调用方式样例：

  from torch_npu.contrib.module import PSROIPool
  model = PSROIPool(pooled_height=7, pooled_width=7, spatial_scale=1 / 16.0, group_size=7, output_dim=22)

• 返回值：

  Float - shape为(k, 5)和(k, 1)的张量。标签以0为基础。

• 约束限制

  仅实现了pooled_height == pooled_width == group_size。

• 示例：

  无

class ROIAlign(nn.Module):

使用NPU API进行ROIAlign。

• 注释：

  aligned=True含义：

  给定一个连续坐标c，使用floor(c - 0.5) 和ceil(c - 0.5)对它的两个相邻像素索引（像素模型中）进行计算。例如，c=1.3具有离散索引为[0]和[1] （从连续坐标0.5到1.5的底层信号采样）的像素邻域。但原始ROIAlign（aligned=False）在计算相邻像素索引时不会减去0.5，因此在执行双线性插值时，它使用的是未完全对齐的像素（相对于我们的像素模型有一点不对齐）。当aligned=True，首先适当缩放ROI，然后在调用ROIAlign之前将其移动-0.5。这样可以生成正确的邻域。相关验证请参见detectron2/tests/testroialign.py。如果ROIAlign与conv层一起使用，差异也不会对模型的性能产生影响。

• 参数：
  • output_size (Tuple) - h, w。
  • spatial_scale (Float) - 按此参数值缩放输入框。
  • sampling_ratio (Int) - 为每个输出样本采集的输入样本数。0表示密集采样。
  • aligned (Bool) - 如果值为False，使用Detectron中的原实现方式。如果值为True，可更准确地对齐结果。
• 调用方式样例：

  from torch_npu.contrib.module import ROIAlign
  roi_align(input_tensor.float(), rois, output_size, spatial_scale, sampling_ratio, aligned)

• 返回值：

  Float - shape为(k, 5)和(k, 1)的张量。标签以0为基础。

• 示例：

  无