torch_npu自定义接口

contrib接口说明

torch_npu.contrib.npu_fused_attention_with_layernorm(hidden_states, attention_mask, query_kernel, key_kernel, value_kernel, query_bias, key_bias, value_bias, gamma, beta, scale=1, keep_prob=0)

bert自注意力与前层规范的融合实现。

• 参数解释：
  • hidden_states (Tensor)：the hidden_states of the last layer
  • attention_mask (Tensor)：attention mask
  • query_kernel (Tensor)：the weight of query
  • key_kernel (Tensor)：the weight of key
  • value_kernel (Tensor)：the weight of value
  • query_bias (Tensor)：the weight of query
  • key_bias (Tensor)：the weight of key
  • value_bias (Tensor)：the weight of value
  • gammam (Tensor)：should be a tensor of torch.nn.LayerNorm.weight
  • beta (Tensor)：should be a tensor of torch.nn.LayerNorm.bias
  • scale=1 (double)：scaling coefficient of the calculated score
  • keep_prob=0：probability of "keeping items", should equal to 1 - drop date.
• 返回值

  torch.Tensor：The result of self attention

• 约束条件：

  无

• 示例：

  无

DDP接口说明

torch_npu.is_hccl_available(): -> bool

判断npu的专属通讯后端HCCL后端是否是可用的。

• 参数解释：

  无参数。

• 约束条件：

  无

• 示例：

  无

torch.distributed.ProcessGroupHCCL(store, rank, size, timeout); -> ProcessGroup

创建一个ProcessGroupHCCL对象并返回。

• 参数解释：
  • Store：torch.distributed.distributed_c10d.PrefixStore对象，可以通过构造函数构造。
  • Rank：当前节点的rank序号。
  • Size：全部通讯节点的数量。
  • Timeout：通讯中断时间，判断节点断联，默认值为1800s。
• 约束条件：

  无

• 示例：

  无

optim接口说明

使用融合优化器约束条件：

1. 使用融合优化器，在创建融合张量时会申请融合后张量大小的内存（如融合的参数或融合的梯度、优化器状态等），device内存不足时不建议使用。
2. 融合张量内存与原张量共享内存，若更改其一的内存地址，将破坏共享内存机制，可能引起精度异常等问题，使用时须用户自行保证共享内存不被破坏。

torch_npu.optim.NpuFusedOptimizerBase(params)

通过张量融合实现优化器的基础类，实现梯度清零、梯度更新等优化器基本功能，用户可进行继承实现自定义融合优化器。

• 参数解释：

  params：模型参数或模型参数组。

• 约束条件：

  无

• 示例：

  无

torch_npu.optim.NpuFusedSGD(params, lr=required， momentum=MOMENTUM_MIN, dampening=DAMPENING_DEFAULT, weight_decay=WEIGHT_DECAY_MIN, nesterov=False)

通过张量融合实现的随机梯度下降算法。

• 参数解释：
  • params：模型参数或模型参数组 。
  • lr：学习率（默认值：1e-3）。
  • betas：用于计算梯度及其平方的运行平均值的系数（默认值：（0.9，0.999））。
  • eps：防止除0，提高数值稳定性 （默认值：1e-8）。
  • weight_decay：权重衰减（默认值：0）。
  • amsgrad：是否使用AMSGrad（默认值：False）。
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weight_decay=0.1)

torch_npu.optim.NpuFusedAdam(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=0, amsgrad=False)

通过张量融合实现的Adam算法。

• 参数解释：
  • params：模型参数或模型参数组。
  • lr：学习率（默认值：1e-3）。
  • betas：用于计算梯度及其平方的运行平均值的系数（默认值：（0.9，0.999））。
  • eps：防止除0，提高数值稳定性 （默认值：1e-8）。
  • weight_decay：权重衰减（默认值：0）。
  • amsgrad：是否使用AMSGrad（默认值：False）。
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedAdam(model.parameters(), lr=0.1, weight_decay=0.1)

torch_npu.optim.NpuFusedAdamW(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=1e-2, amsgrad=False)

通过张量融合实现的AdamW算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率（默认值：1e-3）
  • betas： 用于计算梯度及其平方的运行平均值的系数（默认值：（0.9，0.999））
  • eps：防止除0，提高数值稳定性 （默认值：1e-8）
  • weight_decay：权重衰减（默认值：0）
  • amsgrad：是否使用AMSGrad（默认值：False）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedAdamW(model.parameters(), lr=0.1, weight_decay=0.1)

torch_npu.optim.NpuFusedAdamP(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=0, delta=0.1, wd_ratio=0.1, nesterov=False)

通过张量融合实现的AdamP算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率（默认值：1e-3）
  • betas： 用于计算梯度及其平方的运行平均值的系数（默认值：（0.9，0.999））
  • eps：分母防除0项，提高数值稳定性 （默认值：1e-8）
  • weight_decay：权重衰减（默认值：0）
  • delta：余弦相似度阈值（默认值：0.1）
  • wd_ratio：权重衰减动态调整速率（默认值：0.1）
  • nesterov：使用nesterov动量（默认值：False）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedAdamP(model.parameters(), lr=0.1, weight_decay=0.1, wd_ratio=0.01)

torch_npu.optim.NpuFusedBertAdam(params, lr=required, warmup=-1, t_total=-1, schedule='warmup_linear', b1=0.9, b2=0.99, e=1e-6, weight_decay=0.01, max_grad_norm=-1)

通过张量融合实现的 BertAdam 算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率（默认值：1e-3）
  • warmup：t_total的warmup比例（默认值：-1，表示不进行warmup）
  • t_total：学习率调整的步数（默认值：-1，表示固定学习率）
  • schedule：学习率warmup策略（默认值：'warmup_linear'）
  • b1：Adams b1（默认值：0.9）
  • b2：Adams b2（默认值：0.99）
  • e：Adams epsilon（默认值：1e-6）
  • weight_decay：权重衰减（默认值：0.01）
  • max_grad_norm：最大梯度正则（默认值：1.0，-1表示不做裁剪）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedBertAdam(model.parameters(), lr=0.1, weight_decay=0.01, max_grad_norm=1.0)

torch_npu.optim.NpuFusedAdadelta(params, lr=1.0, rho=0.9, eps=1e-6, weight_decay=0)

通过张量融合实现的 Adadelta 算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率（默认值：1e-3）
  • rho：梯度的均方差系数（默认值：0.9）
  • eps：分母防除0项，提高数值稳定性（默认值：1e-6）
  • weight_decay：权重衰减（默认值：0）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedAdadelta(model.parameters(), lr=0.001, rho=0.95, weight_decay=0.01)

torch_npu.optim.NpuFusedLamb(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-6, weight_decay=0, adam=False, use_global_grad_norm=False)

通过张量融合实现的 FusedLamb 算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率。（默认值：1e-3）
  • betas： 用于计算梯度及其平方的运行平均值的系数。 （默认值：（0.9，0.999））
  • eps：分母防除0项，提高数值稳定性（默认值：1e-8）
  • weight_decay：权重衰减（默认值：0）
  • adam：将strust_ratio设置为1，退化为Adam（默认值：False）
  • use_global_grad_norm：使用全局梯度正则（默认值：False）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedLamb(model.parameters(), lr=0.001, weight_decay=0.01)

torch_npu.optim.NpuFusedRMSprop(params, lr=1e-2, alpha=0.99, eps=1e-8, weight_decay=0, momentum=0, centered=False)

通过张量融合实现的 RMSprop 算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率。（默认值：1e-3）
  • alpha：平滑常量（默认值：0.99）
  • eps：分母防除0项，提高数值稳定性（默认值：1e-8）
  • weight_decay：权重衰减（默认值：0）
  • momentum：动量因子（默认值：0）
  • centered：计算中心RMSProp（默认值：False）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedRMSprop(model.parameters(), lr=0.001, weight_decay=0.01, momentum=0.9)

torch_npu.optim.NpuFusedRMSpropTF(params, lr=1e-2, alpha=0.9, eps=1e-10, weight_decay=0, momentum=0., centered=False, decoupled_decay=False, lr_in_momentum=True)

通过张量融合实现的 RMSpropTF 算法。

• 参数解释：
  • params：模型参数或模型参数组
  • lr：学习率（默认值：1e-3）
  • alpha：平滑常量（默认值：0.9）
  • eps：分母防除0项，提高数值稳定性（默认值：1e-10）
  • weight_decay：权重衰减（默认值：0）
  • momentum：动量因子（默认值：0）
  • centered： 计算中心RMSProp（默认值：False）
  • decoupled_decay：权重衰减仅作用于参数（默认值：False）
  • lr_in_momentum：计算动量buffer时使用lr（默认值：True）
• 约束条件：

  无

• 示例：

  opt = torch_npu.optim.NpuFusedRMSpropTF(model.parameters(), lr=0.001, weight_decay=0.01, momentum=0.9)

amp接口说明

torch_npu.npu.get_npu_overflow_flag()

检测npu计算过程中是否有数值溢出。

• 参数解释：

  无参数

• 约束条件：

  无

• 示例：

  >>>a = torch.Tensor([65535]).npu().half()
  >>>a = a + a
  >>>ret = torch_npu.npu.get_npu_overflow_flag()

torch_npu.npu.clear_npu_overflow_flag

对npu芯片溢出检测为进行清零。

• 参数解释：

  无参数，无返回值。

• 约束条件：

  无

• 示例：

  无

dump接口说明

torch_npu.npu.init_dump()

初始化dump配置。

• 参数解释：

  无参数

• 约束条件：

  无

• 示例：

  无

torch_npu.npu.set_dump(path_to_json)

传入配置文件来配置dump参数。

• 参数解释：

  path_to_json：配置文件路径，用户自行配置。

• 约束条件：

  无

• 示例：

  >>>torch_npu.npu.set_dump("/home/HwHiAiUser/dump.json") 

torch_npu.npu.finalize_dump()

结束dump。

• 参数解释：

  无参数

• 约束条件：

  无

• 示例：

  无

算子接口说明

torch_npu.npu.set_compile_mode(jit_compile = bool)

设置是否开启二进制。

• 参数解释：

  jit_compile：jit_compile=True时是非二进制模式，jit_compile=False时是二进制模式。

• 约束条件：

  无

• 示例：

  >>>torch.npu.set_compile_mode(jit_compile=False)

torch_npu.npu.is_jit_compile_false()

torch_npu.npu.set_mm_bmm_format_nd(bool)

torch_npu.npu.get_mm_bmm_format_nd()

torch_npu.npu.config.allow_internal_format = bool

是否使用私有格式，设置为True时允许使用私有格式，设置为False时，不允许申请任何私有格式的tensor，避免了适配层出现私有格式流通。

• 参数解释：

  输入bool值，默认值为True。

• 返回值：

  无

• 约束条件：

  无

• 示例：

  >>>torch_npu.npu.config.allow_internal_format = False

profiling接口说明

torch_npu.npu.set_aoe (dump_path)

torch_npu.npu.profile(profiler_result_path, use_e2e_profiler, config)

torch_npu.npu.prof_init (profiler_result_path)

torch_npu.npu.prof_start (config)

torch_npu.npu.prof_stop()

torch_npu.npu.prof_finalize()

torch_npu.npu.iteration_start()

torch_npu.npu.iteration_end()

torch_npu.npu.profileConfig(ACL_PROF_ACL_API=True, \
                        ACL_PROF_TASK_TIME=True, ACL_PROF_AICORE_METRICS=True, \
                        ACL_PROF_AICPU=True, ACL_PROF_L2CACHE=False, \
                        ACL_PROF_HCCL_TRACE=True, ACL_PROF_TRAINING_TRACE=False, \
                        TORCH_CALL_STACK=False, \
                        aiCoreMetricsType=1)

torch_npu.profiler.profile(activities=None, schedule=None, on_trace_ready=None, record_shapes=False, profile_memory=False, with_stack=False, with_flops=False, with_modules=False, experimental_config=None, use_cuda=None)

提供对训练过程数据的profiling功能。

• 参数解释：
  • activities：CPU、NPU事件采集列表，Enum类型。取值为：

  torch_npu.profiler.ProfilerActivity.CPU：框架侧数据采集的开关。

  torch_npu.profiler.ProfilerActivity.NPU：CANN软件栈及NPU数据采集的开关。

  默认情况下两个开关同时开启。

  • schedule：设置不同step的行为，Callable类型。由schedule类控制。
  • on_trace_ready：采集结束时自动执行操作，Callable类型。当前仅支持执行tensorboard_trace_handler函数的操作，默认不执行任何操作。
  • record_shapes：算子的InputShapes和InputTypes，Bool类型。取值为：
    • True：开启。
    • False：关闭。默认值。

      开启torch_npu.profiler.ProfilerActivity.CPU时生效。

  • profile_memory算子的内存占用情况，Bool类型。取值为：
    • True：开启。
    • False：关闭。默认值。
  • with_stack：算子调用栈，Bool类型。取值为：
    • True：开启。
    • False：关闭。默认值。

    开启torch_npu.profiler.ProfilerActivity.CPU时生效。

  • with_flops：算子浮点操作，Bool类型（该参数暂不支持解析性能数据）。取值为：
    • True：开启。
    • False：关闭。默认值。

      开启torch_npu.profiler.ProfilerActivity.CPU时生效。

  • with_modules：with_stack时modules分层信息，Bool类型（该参数暂不支持解析性能数据）。取值为：
    • True：开启。
    • False：关闭。默认值。

      开启torch_npu.profiler.ProfilerActivity.CPU时生效。

  experimental_config：扩展参数，通过扩展配置性能分析工具常用的采集项。支持采集项和详细介绍请参见torch_npu.profiler._ExperimentalConfig

• 返回值：

  无

• 约束条件：

  无

• 示例：

  experimental_config = torch_npu.profiler._ExperimentalConfig(
          aic_metrics=torch_npu.profiler.AiCMetrics.PipeUtilization, profiler_level=torch_npu.profiler.ProfilerLevel.Level1, l2_cache=False
  )
  with torch_npu.profiler.profile(
          activities=[
              torch_npu.profiler.ProfilerActivity.CPU,
              torch_npu.profiler.ProfilerActivity.NPU
              ],
          schedule=torch_npu.profiler.schedule(wait=1, warmup=1, active=2, repeat=2, skip_first=10),
          on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./result"),
   
          record_shapes=True,
          profile_memory=True,
          with_stack=True,
          with_flops=False,
          with_modules=False,
          experimental_config=experimental_config) as prof:
              for step in range(steps):
                  train_one_step(step, steps, train_loader, model, optimizer, criterion)
                  prof.step()

torch_npu.profiler.ProfilerActivity

事件采集列表，枚举类。用于赋值给torch_npu.profiler.profile的activities参数。

• 参数解释：
  • torch_npu.profiler.ProfilerActivity.CPU：框架侧数据采集的开关。
  • torch_npu.profiler.ProfilerActivity.NPU：CANN软件栈及NPU数据采集的开关。
• 返回值：

  无

• 约束条件：

  无

• 示例：

  无

torch_npu.profiler.supported_activities()

random接口说明

torch_npu.npu._in_bad_fork()

用在 torch.manual_seed 的全局变量

• 参数解释：

  无参数。

• 返回值：

  无

• 约束条件：

  无

• 示例：

  无

aclnn接口说明

torch_npu.aclnn.allow_hf32:bool

设置conv算子是否支持hf32，一个属性值，对aclnn的allow_hf32属性的设置和查询，默认值为true。

• 参数解释：

  aclnn的bool类的属性

• 约束条件：

  无

• 示例：

  >>>res = torch.npu.aclnn.allow_hf32
     res=True
  >>>torch.npu.aclnn.allow_hf32 = True
  >>>res = torch.npu.aclnn.allow_hf32
     res=True
  >>>torch.npu.aclnn.allow_hf32 = False
  >>>res = torch.npu.aclnn.allow_hf32
     res=False

torch_npu.aclnn.version(): -> None

查询当前aclnn的版本信息,当前版本还没有支持正确的aclnn的版本，兼容返回None同时做warn提示torch.npu.aclnn.version isn't implemented!

• 参数解释：

  无参数

• 约束条件：

  无

• 示例：

  >>>res = torch_npu.npu.aclnn.version()
     res=None