已合并
新增Batch一致性特性介绍 #10302
chenjiao创建于 17 天前
新增Batch一致性特性介绍 #10302
已合并
共 8 个文件变更+91-20
| @@ -1,5 +1,18 @@ | |||
| 1 | +<div align="center"> | ||
| 2 | + | ||
| 1 | # ops-nn | 3 | # ops-nn |
| 2 | 4 | ||
| 5 | +[](https://www.hiascend.com/document/redirect/CannCommunityOplist) | ||
| 6 | +[](docs) | ||
| 7 | +[](LICENSE) | ||
| 8 | +[](CONTRIBUTING.md) | ||
| 9 | +[](https://gitcode.com/cann/community/blob/master/CANN/sigs/ops-nn/README.md) | ||
| 10 | +[](https://zread.ai/hicann/ops-nn) | ||
| 11 | + | ||
| 12 | +</div> | ||
| 13 | + | ||
| 14 | +--- | ||
| 15 | + | ||
| 3 | ## 🔥Latest News | 16 | ## 🔥Latest News |
| 4 | 17 | ||
| 5 | - [2026/05] 优化kernel编译配置项，减少simplified_key和ascendc_config配置文件（[!3330](https://gitcode.com/cann/ops-nn/pull/3330)）。 | 18 | - [2026/05] 优化kernel编译配置项，减少simplified_key和ascendc_config配置文件（[!3330](https://gitcode.com/cann/ops-nn/pull/3330)）。 |
| @@ -1,12 +1,14 @@ | |||
| 1 | -# 基本概念 | 1 | +# 基本概念 |
| 2 | - | 2 | + |
| 3 | -- [两段式接口](./two_phase_api.md) | 3 | +- [两段式接口](./two_phase_api.md) |
| 4 | -- [数据结构](./data_structure.md) | 4 | +- [数据结构](./data_structure.md) |
| 5 | -- [数据类型](./data_type.md) | 5 | +- [数据类型](./data_type.md) |
| 6 | -- [数据格式](./data_format.md) | 6 | +- [数据格式](./data_format.md) |
| 7 | -- [非连续的Tensor](./non_contiguous_tensor.md) | 7 | +- [非连续的Tensor](./non_contiguous_tensor.md) |
| 8 | -- [broadcast关系](./broadcast_relationship.md) | 8 | +- [broadcast关系](./broadcast_relationship.md) |
| 9 | -- [互推导关系](./deduction_relationship.md) | 9 | +- [互推导关系](./deduction_relationship.md) |
| 10 | -- [互转换关系](./conversion_relationship.md) | 10 | +- [互转换关系](./conversion_relationship.md) |
| 11 | -- [量化介绍](./quant_mode_introduction.md) | 11 | +- [量化介绍](./quant_mode_introduction.md) |
| 12 | -- [sparse模式介绍](./sparse_mode_introduction.md) | 12 | +- [sparse模式介绍](./sparse_mode_introduction.md) |
| 13 | +- [确定性计算](determinism_compute.md) | ||
| 14 | +- [Batch一致性](batch_consistency.md) | ||
| @@ -0,0 +1,29 @@ | |||
| 1 | +# Batch一致性 | ||
| 2 | + | ||
| 3 | +## 简介 | ||
| 4 | + | ||
| 5 | +在应用开发过程中，部分算子为了追求较高的性能，针对同一个Token在不同批次大小或者同一批次不同位置场景中，可能存在计算结果偏差。 | ||
| 6 | +当前，针对部分算子在满足相同的运行环境条件下，可以通过配置计算过程采用Batch一致性算法，来使得无论如何组合输入，计算结果保持完全一致。 | ||
| 7 | +**batch一致性算法**：对于给定的一个Token，无论该Token在批次内所处的位置、批次大小、或是和哪些其他Token一同被批处理，输出结果必须逐比特完全一致。 | ||
| 8 | + | ||
| 9 | +## 注意事项 | ||
| 10 | + | ||
| 11 | +- 通常建议不开启Batch一致性计算，因为同一个算子开启Batch一致性计算后相关算子存在一定的性能劣化，因此模型的单次运行性能可能会下降。但在实验、调试和回归测试等需要保证多次运行结果相同来定位问题和实验算法的场景，Batch一致性计算可以提升效率。 | ||
| 12 | + | ||
| 13 | +- 当前配置为进程级开关配置。 | ||
| 14 | + | ||
| 15 | +- **版本约束**：TorchNPU版本大于等于26.2.0，CANN版本大于等于9.2.0。 | ||
| 16 | + | ||
| 17 | +## 使用方法 | ||
| 18 | + | ||
| 19 | +目前CANN算子的主流调用方式为aclnn API或PyTorch API（torch_extension）。部分算子API默认Batch一致性实现，部分算子API默认非Batch一致性实现。对于非Batch一致性实现的算子，部分可通过手动配置开启Batch一致性。 | ||
| 20 | + | ||
| 21 | +- **调用aclnn API** | ||
| 22 | + | ||
| 23 | + 该场景下，通过[《Runtime运行时API》](https://hiascend.com/document/redirect/CannCommunityRuntimeApi)中“运行时配置>aclrtSetSysParamOpt”接口（进程级）配置开启确定性计算。具体通过设置`ACL_OPT_DETERMINISTIC=3`开启Batch一致性计算。 | ||
| 24 | + | ||
| 25 | +- **调用PyTorch API** | ||
| 26 | + | ||
| 27 | + 该场景下，通过[《TorchNPU自定义API》](https://www.hiascend.com/document/detail/zh/Pytorch/latest/apiref/customapi/docs/zh/custom_APIs/overview.md)中`torch_npu.npu.set_deterministic_level`接口开启Batch一致性计算。 | ||
| 28 | + | ||
| 29 | +对于不同框架的算子API，其默认的Batch一致性计算实现策略请以具体的aclnn API文档或PyTorch API文档描述为准。 | ||
| @@ -0,0 +1,27 @@ | |||
| 1 | +# 确定性计算 | ||
| 2 | + | ||
| 3 | +## 简介 | ||
| 4 | + | ||
| 5 | +在应用开发过程中，由于CANN版本或NPU型号等差异，同一算子多次运行的结果可能不完全一致；即使在相同条件下使用相同随机种子，多次NPU执行结果也可能不同。该差异通常源于算子实现中存在异步多线程执行，导致浮点数累加顺序变化。 | ||
| 6 | + | ||
| 7 | +在某些特殊场景下（如实验、调试和回归测试），需要算子多次运行产生相同输出，以便定位问题或进行算法分析，这一方案通常称为“确定性计算”。 | ||
| 8 | + | ||
| 9 | +## 注意事项 | ||
| 10 | + | ||
| 11 | +- 通常建议不开启确定性计算，因为同一算子采用确定性计算一般比非确定性计算执行更慢，可能导致模型单次运行性能下降。但在实验、调试和回归测试等需要保证多次运行结果一致以定位问题或分析算法的场景中，确定性计算可以提升效率。 | ||
| 12 | + | ||
| 13 | +- 线程说明：同一线程中只能设置一次确定性状态，多次设置以最后一次有效设置为准。有效设置是指设置确定性状态后，真正执行了一次算子任务下发。如果仅设置而未下发算子任务，则确定性变量虽已开启但未下发给算子，算子不会执行。暂不推荐在一个线程中多次设置确定性。该问题在二进制开启和关闭情况下均存在，将在后续版本中解决。 | ||
| 14 | + | ||
| 15 | +## 使用方法 | ||
| 16 | + | ||
| 17 | +目前CANN算子的主流调用方式为aclnn API或PyTorch API（torch_extension）。部分算子API默认确定性实现，部分算子API默认非确定性实现。对于非确定性实现的算子，部分可通过手动配置开启确定性计算。 | ||
| 18 | + | ||
| 19 | +- **调用aclnn API** | ||
| 20 | + | ||
| 21 | + 该场景下，通过[《Runtime运行时API》](https://hiascend.com/document/redirect/CannCommunityRuntimeApi)中“运行时配置>aclrtSetSysParamOpt”接口（进程级）配置开启确定性计算。具体通过设置`ACL_OPT_DETERMINISTIC=1`开启确定性计算。 | ||
| 22 | + | ||
| 23 | +- **调用PyTorch API** | ||
| 24 | + | ||
| 25 | + 该场景下，通过PyTorch原生开关（`torch.use_deterministic_algorithms`）开启确定性计算。 | ||
| 26 | + | ||
| 27 | +对于不同框架的算子API，其默认的确定性计算实现策略请以具体的aclnn API文档或PyTorch API文档描述为准。 | ||
| @@ -21,7 +21,7 @@ | |||
| 21 | 21 | ||
| 22 | 对于无昇腾设备的开发者，可直接使用CANNLab云开发环境，即“**一站式开发平台**”，该平台为您提供在线可直接运行的昇腾环境，环境中已安装必备的驱动、软件包和依赖，无需手动安装。 | 22 | 对于无昇腾设备的开发者，可直接使用CANNLab云开发环境，即“**一站式开发平台**”，该平台为您提供在线可直接运行的昇腾环境，环境中已安装必备的驱动、软件包和依赖，无需手动安装。 |
| 23 | 23 | ||
| 24 | -> **说明**：环境默认安装最新版本CANN包，源码下载时注意与软件配套。更多关于开发平台的介绍请参考[CANNLab指导](https://gitcode.com/org/cann/discussions/54)。 | 24 | +> **说明**：环境默认安装最新版本CANN包，源码下载时注意与软件配套。更多关于开发平台的介绍请参考[CANNLab指导](https://gitcode.com/cann/cann-learning-hub/blob/master/docs/CANNLab_env_experience_guide.md)。 |
| 25 | 25 | ||
| 26 | 1. 进入开源项目，单击“`CANNLab`”按钮，使用已认证过的华为云账号登录。若未注册或认证，请根据页面提示进行注册和认证。 | 26 | 1. 进入开源项目，单击“`CANNLab`”按钮，使用已认证过的华为云账号登录。若未注册或认证，请根据页面提示进行注册和认证。 |
| 27 | 27 | ||
| @@ -19,13 +19,10 @@ | |||
| 19 | 19 | ||
| 20 | ## 接口列表 | 20 | ## 接口列表 |
| 21 | 21 | ||
| 22 | -> **确定性简介**： | 22 | +> [!NOTE] |
| 23 | > | 23 | > |
| 24 | -> - 配置说明：因CANN或NPU型号不同等原因，可能无法保证同一个算子多次运行结果一致。在相同条件下（平台、设备、版本号和其他随机性参数等），部分算子接口可通过`aclrtSetSysParamOpt`（参见[《Runtime运行时API》](https://hiascend.com/document/redirect/CannCommunityRuntimeApi)）开启确定性算法，使多次运行结果一致。 | 24 | +> - 算子特性介绍：调用API前，请先学习算子相关基础知识，包括**确定性算法**、**Batch一致性**、**常见量化模式**等，具体介绍参见[算子基本概念](context/basic_concept.md)。 |
| 25 | -> - 性能说明：同一个算子采用确定性计算通常比非确定性慢，因此模型单次运行性能可能会下降。但在实验、调试和调测等需要保证多次运行结果相同来定位问题的场景，确定性计算可以提升效率。 | 25 | +> - 符号说明：表格中“-”符号表示该接口暂不支持当前列产品。 |
| 26 | -> - 线程说明：同一线程中只能设置一次确定性状态，多次设置以最后一次有效设置为准。有效设置是指设置确定性状态后，真正执行了一次算子任务下发。如果仅设置，没有算子下发，只能是确定性变量开启但未下发给算子，因此不执行算子。 | ||
| 27 | -> 解决方案：暂不推荐一个线程多次设置确定性。该问题在二进制开启和关闭情况下均存在，在后续版本中会解决该问题。 | ||
| 28 | -> - 符号说明：表中 “- ”符号表示该接口暂不支持当前列产品。 | ||
| 29 | 26 | ||
| 30 | 算子接口列表如下： | 27 | 算子接口列表如下： |
| 31 | 28 | ||
| @@ -20,7 +20,10 @@ | |||
| 20 | 20 | ||
| 21 | ## 接口列表 | 21 | ## 接口列表 |
| 22 | 22 | ||
| 23 | -> **确定性简介**：因CANN或NPU型号不同等原因，可能无法保证同一个API运行结果一致。在相同条件下（平台、设备、版本号和其他随机性参数等），部分接口可通过PyTorch中控制算法确定性的全局开关[torch.use_deterministic_algorithms](https://github.com/pytorch/pytorch/blob/main/torch/__init__.py)开启确定性算法，使多次运行结果一致。 | 23 | +> [!NOTE] |
| 24 | +> | ||
| 25 | +> - 算子特性介绍：调用API前，请先学习算子相关基础知识，包括**确定性算法**、**Batch一致性**、**常见量化模式**等，具体介绍参见[算子基本概念](context/basic_concept.md)。 | ||
| 26 | +> - 符号说明：表格中“-”符号表示该接口暂不支持当前列产品。 | ||
| 24 | 27 | ||
| 25 | | 接口名 | 说明 | 确定性说明（A2/A3） | 确定性说明（Ascend 950） | | 28 | | 接口名 | 说明 | 确定性说明（A2/A3） | 确定性说明（Ascend 950） | |
| 26 | | ----------- | ------------------- | ------------------- | ------------------- | | 29 | | ----------- | ------------------- | ------------------- | ------------------- | |