已合并
add README and LICENSE #2
xiong_zhiqiang创建于 8月5日
add README and LICENSE #2
已合并
共 2 个文件变更+163-0
| @@ -0,0 +1,38 @@ | |||
| 1 | +CANN Open Software License Agreement Version 2.0 | ||
| 2 | + | ||
| 3 | +This CANN Open Software License Agreement Version 2.0 (hereinafter referred to as this "Agreement") is a legal agreement between you and Huawei, and it governs your use, modification, or distribution of CANN Open Software (hereinafter referred to as "Software"). Please read this Agreement carefully. | ||
| 4 | + | ||
| 5 | +If you are entering into this Agreement on behalf of a company or other legal entity, you represent that you have the legal authority to bind that entity to this Agreement, in which case "you" will mean the entity you represent. | ||
| 6 | + | ||
| 7 | +BY DOWNLOADING, INSTALLING, OR USING THE SOFTWARE, YOU AGREE YOU HAVE FULLY UNDERSTOOD AND ACCEPTED THE TERMS CONTAINED HEREIN. IF YOU DO NOT AGREE TO ANY OF THE TERMS OF THIS AGREEMENT, OR IF YOU DO NOT QUALIFY FOR AGREEING TO THIS AGREEMENT, YOU ARE NOT AUTHORIZED TO AND SHALL NOT DOWNLOAD, INSTALL, OR MAKE ANY USE OF THE SOFTWARE. | ||
| 8 | + | ||
| 9 | +1. Definition | ||
| 10 | + | ||
| 11 | +1.1 Software means the APIs, source code files, binaries, and related documents of Compute Architecture for Neural Networks("CANN") that are licensable by Huawei, and provided and licensed under this Agreement. | ||
| 12 | + | ||
| 13 | +1.2 Huawei AI Processors mean AI chipsets (i) branded with "Ascend", "Kirin"," Yueying" or other brands owned or controlled by Huawei; or (ii) manufactured (including have manufactured), supplied (including have supplied) or designed (including have designed) by Huawei. | ||
| 14 | + | ||
| 15 | +2. Grant of Intellectual Property Rights | ||
| 16 | +2.1 Subject to the terms and conditions of this Agreement, including your full compliance thereof, Huawei hereby grants you a limited, worldwide, royalty-free, non-transferable, non-sublicensable, and revocable license for you to (i) download, use, modify, integrate, and distribute the Software or its derivative works for the purpose of developing software solely for use in systems with Huawei AI Processors and/or Software, and (ii) distribute any software developed based upon Software and/or its derivative works solely for use in systems with Huawei AI Processors and/or Software. | ||
| 17 | + | ||
| 18 | +3. Restrictions | ||
| 19 | +3.1 You are not authorized to, and shall not use, modify, or distribute this Software or its derivative works for any other purposes than those expressly permitted by this Agreement. You shall not make any use of the Software or its derivative works to develop or distribute any software for use in systems with processors other than Huawei AI Processors. All rights not expressly granted herein are expressly reserved by Huawei. | ||
| 20 | + | ||
| 21 | +3.2 You are not authorized to, and shall not remove, obscure, or alter any copyright or other notices in this Software or any part of it. | ||
| 22 | + | ||
| 23 | +3.3 Distribution Restrictions | ||
| 24 | +You may distribute the Software or its derivative works in any medium, whether in source or executable forms, for the purpose stipulated in Section 2; provided that you provide recipients with a copy of this Agreement, and retain all notices in the Software. | ||
| 25 | + | ||
| 26 | +4. Disclaimer of Warranty and Limitation of Liability | ||
| 27 | +THE SOFTWARE IS PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL HUAWEI OR ANY OTHER COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL, CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE, IN WHOLE OR IN PART, NO MATTER HOW IT IS CAUSED OR THE LEGAL THEORY IT IS BASED ON, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. | ||
| 28 | + | ||
| 29 | +5. Termination | ||
| 30 | +5.1 This Agreement will continue to apply until terminated by either you or Huawei as described below: | ||
| 31 | +a．You may terminate this Agreement by ceasing your use of the Software; | ||
| 32 | +b. Huawei may at any time, terminate this Agreement if: (i) you fail to comply with any term of this Agreement; or (ii) you directly or indirectly initiate any legal proceeding against any individual or entity by alleging that the Software or any part of it infringes your intellectual property rights. | ||
| 33 | +5.2 By termination, all the rights granted to you under this Agreement are terminated, and you shall cease to use and delete this Software or any derivative works immediately. All rights granted to you under this Agreement shall hereby be void ab initio in the event of termination in accordance with Section 5.1. b above. Huawei reserves the right to pursue any and all legal remedies available to enforce the terms and conditions of this Agreement or to protect Huawei’s intellectual property rights for such breach or violation. All provisions shall survive the termination of this Agreement except for Section 2 and Section 3.3. | ||
| 34 | + | ||
| 35 | +6. MISCELLANEOUS | ||
| 36 | +If the application of any provision of this Agreement to any particular facts or circumstances is held to be invalid or unenforceable by a court of competent jurisdiction, then (a) the validity and enforceability of such provision as applied to any other particular facts or circumstances and the validity of other provisions of this Agreement shall not in any way be affected or impaired thereby and (b) such provision shall be enforced to the maximum extent possible so as to affect the intent of the you and Huawei and reformed without further action by you and Huawei to the extent necessary to make such provision valid and enforceable. | ||
| 37 | + | ||
| 38 | +END OF THE TERMS AND CONDITIONS | ||
| @@ -1,2 +1,127 @@ | |||
| 1 | # cannbot-dsl | 1 | # cannbot-dsl |
| 2 | 2 | ||
| 3 | +# CANNBot-DSL | ||
| 4 | + | ||
| 5 | +> 基于 CANNBotDSL 的 Ascend NPU 算子示例集合，提供完整实现、精度测试与性能对比数据。 | ||
| 6 | + | ||
| 7 | +[📖 概述](#概述) · [🛠️ 环境部署](#环境部署) · [⚡️ 快速入门](#快速入门) · [📦 算子列表](#算子列表) · [🧪 测试](#测试) · [📂 目录结构](#目录结构) · [📜 许可证](#许可证) | ||
| 8 | + | ||
| 9 | +--- | ||
| 10 | + | ||
| 11 | +## 概述 | ||
| 12 | + | ||
| 13 | +CANNBot-DSL 收录了一批基于 CANNBotDSL 实现的 Ascend NPU 算子示例。每个算子均包含完整的 host 侧 tiling 推导、device 侧 kernel 实现、面向 CPU 的精度 golden 与面向 NPU 的精度比对测试，以及与 CANN 内置算子的性能对比数据。 | ||
| 14 | + | ||
| 15 | +项目面向 NPU ARCH 3510（Ascend 950PR / Ascend 950DT），旨在为开发者提供从算子定义、切分调度到精度性能验证的端到端参考。 | ||
| 16 | + | ||
| 17 | +## 环境部署 | ||
| 18 | + | ||
| 19 | +### 前置依赖 | ||
| 20 | + | ||
| 21 | +| 依赖 | 版本要求 | | ||
| 22 | +| :--- | :--- | | ||
| 23 | +| OS | Linux x86_64 | | ||
| 24 | +| NPU | Ascend 950 | | ||
| 25 | +| Python | 3.12 | | ||
| 26 | +| CANN Toolkit | 9.1.0 | | ||
| 27 | +| torch / torch_npu | 与 CANN 匹配 | | ||
| 28 | +| pytest / pytest-xdist | 9.1.1 | | ||
| 29 | + | ||
| 30 | +### 安装 CANN Toolkit | ||
| 31 | + | ||
| 32 | +当前仓库验证通过的社区版 CANN Toolkit 如下： | ||
| 33 | + | ||
| 34 | +| CANN 版本 | 验证结果 | 下载链接（x86_64） | | ||
| 35 | +| :--- | :--- | :--- | | ||
| 36 | +| `9.1.0` | ✅ PASS | [Ascend-cann_9.1.0_linux-x86_64.run](https://ascend-cann-open.obs.cn-north-4.myhuaweicloud.com/CANN/CANN%209.1.0/Ascend-cann_9.1.0_linux-x86_64.run) | | ||
| 37 | + | ||
| 38 | +安装命令： | ||
| 39 | + | ||
| 40 | +```bash | ||
| 41 | +chmod +x Ascend-cann_9.1.0_linux-x86_64.run | ||
| 42 | +./Ascend-cann_9.1.0_linux-x86_64.run --install --force --install-path=${install_path} | ||
| 43 | +``` | ||
| 44 | + | ||
| 45 | +`${install_path}` 为安装路径，默认 `/usr/local/Ascend`。 | ||
| 46 | + | ||
| 47 | +### 配置环境变量 | ||
| 48 | + | ||
| 49 | +安装完成后执行： | ||
| 50 | + | ||
| 51 | +```bash | ||
| 52 | +source ${install_path}/ascend-toolkit/set_env.sh | ||
| 53 | +``` | ||
| 54 | + | ||
| 55 | +请将 `${install_path}` 替换为实际安装目录，例如 `/usr/local/Ascend` 或 `${HOME}/Ascend`。 | ||
| 56 | + | ||
| 57 | +### 安装 CANNBotDSL | ||
| 58 | + | ||
| 59 | +```bash | ||
| 60 | +python -m pip install /absolute/path/to/cannbotdsl-*-cp312-cp312-manylinux_*_x86_64.whl | ||
| 61 | +``` | ||
| 62 | + | ||
| 63 | +验证安装： | ||
| 64 | + | ||
| 65 | +```bash | ||
| 66 | +python -c 'import cannbotdsl; print(cannbotdsl.__file__)' | ||
| 67 | +``` | ||
| 68 | + | ||
| 69 | +## 快速入门 | ||
| 70 | + | ||
| 71 | +以 `matmul_basic` 为例，计算 $C[M,N] = A[M,K] @ B[N,K]^T$： | ||
| 72 | + | ||
| 73 | +```python | ||
| 74 | +import torch | ||
| 75 | +import torch_npu | ||
| 76 | +from matmul_basic import matmul_basic | ||
| 77 | + | ||
| 78 | +M, K, N = 1024, 1024, 1024 | ||
| 79 | +dtype = torch.float16 | ||
| 80 | + | ||
| 81 | +a = torch.randn(M, K, dtype=dtype).npu() # (M, K) | ||
| 82 | +b = torch.randn(N, K, dtype=dtype).npu() # (N, K) | ||
| 83 | + | ||
| 84 | +c = matmul_basic(a, b, transpose_a=False, transpose_b=True) | ||
| 85 | +``` | ||
| 86 | + | ||
| 87 | +更多算子的接口参数与约束详见 [算子列表](#算子列表) 中各子目录的 README。 | ||
| 88 | + | ||
| 89 | +## 算子列表 | ||
| 90 | + | ||
| 91 | +| 算子 | 公式 | 文档 | | ||
| 92 | +| :--- | :--- | :--- | | ||
| 93 | +| flash_attn | $O = softmax(QK^T \cdot scale) V$ | [samples/flash_attn](samples/flash_attn) | | ||
| 94 | +| matmul_basic | $C[M,N] = A[M,K] @ B[N,K]^T$ | [samples/matmul_basic](samples/matmul_basic) | | ||
| 95 | +| rms_norm | $y = x \cdot rstd \cdot \gamma$ | [samples/rms_norm](samples/rms_norm) | | ||
| 96 | + | ||
| 97 | +> **支持架构**：NPU ARCH 3510（Ascend 950PR / Ascend 950DT） | ||
| 98 | + | ||
| 99 | +## 测试 | ||
| 100 | + | ||
| 101 | +测试使用 pytest 驱动，需在 NPU 环境下运行。运行单个算子的精度测试： | ||
| 102 | + | ||
| 103 | +```bash | ||
| 104 | +pytest test/flash_attn/test_flash_attn.py -v | ||
| 105 | +pytest test/matmul_basic/test_matmul_basic.py -v | ||
| 106 | +pytest test/rms_norm/test_rms_norm.py -v | ||
| 107 | +``` | ||
| 108 | + | ||
| 109 | +## 目录结构 | ||
| 110 | + | ||
| 111 | +```text | ||
| 112 | +├── samples/ # 算子实现与使用说明 | ||
| 113 | +│ ├── flash_attn/ # Flash Attention | ||
| 114 | +│ ├── matmul_basic/ # 非量化矩阵乘 | ||
| 115 | +│ └── rms_norm/ # RmsNorm 归一化 | ||
| 116 | +├── test/ # pytest 精度测试 | ||
| 117 | +│ ├── flash_attn/ | ||
| 118 | +│ ├── matmul_basic/ | ||
| 119 | +│ └── rms_norm/ | ||
| 120 | +├── media/ # 性能对比图 | ||
| 121 | +└── README.md | ||
| 122 | +``` | ||
| 123 | + | ||
| 124 | +## 相关信息 | ||
| 125 | + | ||
| 126 | +- [许可证](LICENSE) | ||
| 127 | +- 源文件头部包含完整的版权与许可声明，遵循 CANN Open Software License Agreement Version 2.0 | ||