已合并
[文档] 更新社区入口、架构图及确定性与Batch一致性说明 #5666
xujiachen8创建于 25 天前
[文档] 更新社区入口、架构图及确定性与Batch一致性说明 #5666
已合并
共 7 个文件变更+81-10
| @@ -1,5 +1,18 @@ | |||
| 1 | +<div align="center"> | ||
| 2 | + | ||
| 1 | # ops-math | 3 | # ops-math |
| 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-basic/README.md) | ||
| 10 | +[](https://zread.ai/hicann/ops-math) | ||
| 11 | + | ||
| 12 | +</div> | ||
| 13 | + | ||
| 14 | +--- | ||
| 15 | + | ||
| 3 | ## 🔥Latest News | 16 | ## 🔥Latest News |
| 4 | 17 | ||
| 5 | - [2026/07] 新增支持Ascend 950系列[算子及新特性](https://gitcode.com/cann/ops-math/wiki/Ascend950重点特性与本仓算子样例介绍.md)，涵盖CumulativeLogSumExp、MatrixSetDiagV2、DropoutV3Grad、SignBitsUnpack、ProdVirialSeA等算子；引入FLOAT8/FLOAT4低精度类型支持、Philox PRNG随机数生成、Reg接口迁移等新特性。 | 18 | - [2026/07] 新增支持Ascend 950系列[算子及新特性](https://gitcode.com/cann/ops-math/wiki/Ascend950重点特性与本仓算子样例介绍.md)，涵盖CumulativeLogSumExp、MatrixSetDiagV2、DropoutV3Grad、SignBitsUnpack、ProdVirialSeA等算子；引入FLOAT8/FLOAT4低精度类型支持、Philox PRNG随机数生成、Reg接口迁移等新特性。 |
| @@ -13,9 +26,7 @@ | |||
| 13 | 26 | ||
| 14 | ops-math是[CANN](https://hiascend.com/software/cann)（Compute Architecture for Neural Networks）算子库中提供数值计算的基础算子库，包括conversion类、math类、random类等，覆盖张量形态变换、基础数学运算、随机数生成等场景，子库在架构图中的位置如下。 | 27 | ops-math是[CANN](https://hiascend.com/software/cann)（Compute Architecture for Neural Networks）算子库中提供数值计算的基础算子库，包括conversion类、math类、random类等，覆盖张量形态变换、基础数学运算、随机数生成等场景，子库在架构图中的位置如下。 |
| 15 | 28 | ||
| 16 | -<img src="docs/zh/figures/architecture.png" alt="架构图" width="700px" height="320px"> | 29 | +<img src="docs/zh/figures/architecture.png" alt="架构图" width="700px"> |
| 17 | - | ||
| 18 | -本仓已集成代码仓库智能体，点击 [](https://zread.ai/hicann/ops-math)徽章，进入其专属页面，开启在线智能代码学习与知识问答体验！ | ||
| 19 | 30 | ||
| 20 | ## 📌版本配套 | 31 | ## 📌版本配套 |
| 21 | 32 | ||
| @@ -49,6 +60,7 @@ git clone -b 9.0.0 https://gitcode.com/cann/ops-math.git | |||
| 49 | - [安全声明](SECURITY.md) | 60 | - [安全声明](SECURITY.md) |
| 50 | - [许可证](LICENSE) | 61 | - [许可证](LICENSE) |
| 51 | - [所属SIG](https://gitcode.com/cann/community/tree/master/CANN/sigs/ops-basic) | 62 | - [所属SIG](https://gitcode.com/cann/community/tree/master/CANN/sigs/ops-basic) |
| 63 | +- [committer列表](https://gitcode.com/cann/community/blob/master/CANN/sigs/ops-basic/README.md#committer%E5%88%97%E8%A1%A8) | ||
| 52 | 64 | ||
| 53 | ----- | 65 | ----- |
| 54 | PS：本项目功能和文档正在持续更新和完善中，欢迎您关注最新版本。 | 66 | PS：本项目功能和文档正在持续更新和完善中，欢迎您关注最新版本。 |
| @@ -10,3 +10,5 @@ | |||
| 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,31 @@ | |||
| 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 | +- **版本约束**：CANN版本大于等于9.2.0；通过PyTorch API配置时，TorchNPU版本还需大于等于26.2.0。 | ||
| 16 | + | ||
| 17 | +- **本仓算子约束**：例如，[aclnnReduceSum](../../../math/reduce_sum/docs/aclnnReduceSum.md)和[aclnnMean](../../../math/reduce_mean/docs/aclnnMean.md)在Ascend 950PR/Ascend 950DT上默认非Batch一致性实现，支持通过aclrtSetSysParamOpt(ACL_OPT_DETERMINISTIC, 3)开启Batch一致性。开启后，非归约轴的计算结果与所在批次大小、位置无关；归约轴不支持Batch一致性。 | ||
| 18 | + | ||
| 19 | +## 使用方法 | ||
| 20 | + | ||
| 21 | +目前CANN算子的主流调用方式为aclnn API或PyTorch API（由外部TorchNPU框架提供）。部分算子API默认Batch一致性实现，部分算子API默认非Batch一致性实现。对于非Batch一致性实现的算子，部分可通过手动配置开启Batch一致性。 | ||
| 22 | + | ||
| 23 | +- **调用aclnn API** | ||
| 24 | + | ||
| 25 | + 该场景下，通过[《Runtime运行时API》](https://hiascend.com/document/redirect/CannCommunityRuntimeApi)中“运行时配置>aclrtSetSysParamOpt”接口（进程级）配置开启Batch一致性计算。具体通过设置`ACL_OPT_DETERMINISTIC=3`开启Batch一致性计算。 | ||
| 26 | + | ||
| 27 | +- **调用PyTorch API** | ||
| 28 | + | ||
| 29 | + 该场景下，通过[《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一致性计算。 | ||
| 30 | + | ||
| 31 | +对于不同框架的算子API，其默认的Batch一致性计算实现策略请以具体的aclnn API文档或PyTorch API文档描述为准。 | ||
| @@ -0,0 +1,29 @@ | |||
| 1 | +# 确定性计算 | ||
| 2 | + | ||
| 3 | +## 简介 | ||
| 4 | + | ||
| 5 | +在应用开发过程中，由于CANN版本或NPU型号等差异，同一算子多次运行的结果可能不完全一致；即使在相同条件下使用相同随机种子，多次NPU执行结果也可能不同。该差异通常源于算子实现中存在异步多线程执行，导致浮点数累加顺序变化。 | ||
| 6 | + | ||
| 7 | +确定性计算要求平台、设备、软件版本、输入及随机性参数等运行条件相同，不保证跨CANN版本或跨NPU型号的结果一致。 | ||
| 8 | + | ||
| 9 | +在某些特殊场景下（如实验、调试和回归测试），需要算子多次运行产生相同输出，以便定位问题或进行算法分析，这一方案通常称为“确定性计算”。 | ||
| 10 | + | ||
| 11 | +## 注意事项 | ||
| 12 | + | ||
| 13 | +- 通常建议不开启确定性计算，因为同一算子采用确定性计算一般比非确定性计算执行更慢，可能导致模型单次运行性能下降。但在实验、调试和回归测试等需要保证多次运行结果一致以定位问题或分析算法的场景中，确定性计算可以提升效率。 | ||
| 14 | + | ||
| 15 | +- 线程说明：暂不推荐在一个线程中多次设置确定性。配置作用域与生效规则以配套版本的Runtime接口文档为准。 | ||
| 16 | + | ||
| 17 | +## 使用方法 | ||
| 18 | + | ||
| 19 | +目前CANN算子的主流调用方式为aclnn API或PyTorch API（由外部TorchNPU框架提供）。部分算子API默认确定性实现，部分算子API默认非确定性实现。对于非确定性实现的算子，部分可通过手动配置开启确定性计算。 | ||
| 20 | + | ||
| 21 | +- **调用aclnn API** | ||
| 22 | + | ||
| 23 | + 该场景下，通过[《Runtime运行时API》](https://hiascend.com/document/redirect/CannCommunityRuntimeApi)中“运行时配置>aclrtSetSysParamOpt”接口（进程级）配置开启确定性计算。具体通过设置`ACL_OPT_DETERMINISTIC=1`开启确定性计算。 | ||
| 24 | + | ||
| 25 | +- **调用PyTorch API** | ||
| 26 | + | ||
| 27 | + 该场景下，通过PyTorch原生开关（`torch.use_deterministic_algorithms`）开启确定性计算。 | ||
| 28 | + | ||
| 29 | +对于不同框架的算子API，其默认的确定性计算实现策略请以具体的aclnn API文档或PyTorch API文档描述为准。 | ||
| @@ -22,7 +22,7 @@ | |||
| 22 | 22 | ||
| 23 | 对于无昇腾设备的开发者，可直接使用CANNLab云开发环境，即“**一站式开发平台**”，该平台为您提供在线可直接运行的昇腾环境，环境中已安装必备的驱动固件、软件包和依赖，无需手动安装。 | 23 | 对于无昇腾设备的开发者，可直接使用CANNLab云开发环境，即“**一站式开发平台**”，该平台为您提供在线可直接运行的昇腾环境，环境中已安装必备的驱动固件、软件包和依赖，无需手动安装。 |
| 24 | 24 | ||
| 25 | -> **说明**：环境默认安装最新版本CANN包，源码下载时注意与软件配套。更多关于开发平台的介绍请参考[CANNLab指导](https://gitcode.com/org/cann/discussions/54)。 | 25 | +> **说明**：环境默认安装最新版本CANN包，源码下载时注意与软件配套。更多关于开发平台的介绍请参考[CANNLab指导](https://gitcode.com/cann/cann-learning-hub/blob/master/docs/CANNLab_env_experience_guide.md)。 |
| 26 | 26 | ||
| 27 | 1. 进入开源项目，单击“CANNLab”按钮，使用已认证过的华为云账号登录。若未注册或认证，请根据页面提示进行注册和认证。 | 27 | 1. 进入开源项目，单击“CANNLab”按钮，使用已认证过的华为云账号登录。若未注册或认证，请根据页面提示进行注册和认证。 |
| 28 | 28 | ||
| @@ -19,13 +19,10 @@ | |||
| 19 | 19 | ||
| 20 | ## 接口列表 | 20 | ## 接口列表 |
| 21 | 21 | ||
| 22 | -> **确定性简介**： | 22 | +> [!NOTE] |
| 23 | > | 23 | > |
| 24 | -> - 配置说明：因CANN或NPU型号不同等原因，可能无法保证同一个算子多次运行结果一致。在相同条件下（平台、设备、版本号和其他随机性参数等），部分算子接口可通过`aclrtCtxSetSysParamOpt`（参见[《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 | ||