diff --git a/README.md b/README.md
index ad2fc88958242aa81bb8295b328cdc2c41d9c8ac..760e342e3bb6e0c4de1b30a9b36d96b105e55221 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,38 @@
# Ascend Transformer Boost
## 介绍
-Ascend Transformer Boost加速库(下文简称为ATB加速库)是一款高效、可靠的加速库,基于华为Ascend AI处理器,专门为Transformer模型的训练和推理而设计。
+Ascend Transformer Boost加速库(下文简称为ATB加速库)是一款基于华为Ascend AI处理器,专门为Transformer模型的训练和推理而设计的加速库。主要包含一系列Transformer模型算子和运行时优化措施, 提高模型性能。
-ATB加速库采用了一系列优化策略,包括算法优化、硬件优化和软件优化,能够显著提升Transformer模型的训练和推理速度,同时降低能耗和成本。具体来说,ATB加速库通过优化矩阵乘法等核心算子和注意力机制的实现方式,实现了对Transformer模型的高效加速。此外,ATB加速库还充分利用了Ascend AI处理器的硬件特性,如算力、存储带宽和内存带宽,通过硬件加速和数据重用等技术,进一步提升了性能和效率。ATB加速库目前提供了底层基础的高性能算子以及高效的算子组合技术(Graph图算子),同时上层支持对接多种模型框架如PyTorch、MindSpore、Paddle。
-
-总而言之,ATB加速库中包含了各类Transformer类模型的高度优化模块,在各种应用场景中发挥重要作用,为模型的训练和推理提供了强有力的支持。
+- 高性能算子:针对昇腾系列芯片, 提供高度优化的Transformer算子, 包括Linear/softmax/PageAttention/RingAttention等。
+- 组图能力: 支持通过手动构图方式将上述算子或用户自定义算子构建成图算子,用于表征Layer或Model。
+- 运行时优化: 通过算子间内存复用和算子下发顺序优化, 提升整体模型性能。
+- Plugin: 提供Plugin能力, 支持用户使用第三方算子组图。
## 软件架构
-加速库接口功能主要分成三部分:
-- 提供基础原生的算子(Operation),用户可以根据需求使用对应的算子完成计算功能。
-- 提供图算子机制,用户根据模型设计对应的图算子,使用加速库提供的原生算子和创建的自定义算子创建图算子,完成相应的计算。
-- 提供插件(Plugin)机制,用户可以根据自己的需求创建自定义的算子。
-## 环境构建
- - [安装CANN环境](https://www.hiascend.com/document/detail/zh/canncommercial/80RC22/softwareinst/instg/instg_0001.html?Mode=PmIns&OS=Ubuntu&Software=cannToolKit)
- - 设置cann环境变量
- ```sh
- source [cann安装路径](默认为/usr/local/Ascend/ascend-toolkit)/set_env.sh
- ```
+
-## 使用教程
-
- - 加速库编译
+
+ATB的架构大致可以分成3层:
+1. 接口层: 提供单算子接口、组图接口、PlugIn算子接入接口三类
+2. 功能实现层:包括算子实现、运行时优化、Context管理等
+3. 算子运行时:主要提供算子分包、下发等功能。
+
+## 编译安装
+ 用户可以选择从源码编译安装,也可以通过官网下载版本包安装。 下面的安装方式2选1.
+ 前置条件:已经在环境上安装了对应的CANN ToolKit包。 安装步骤见:https://www.hiascend.com/document/detail/zh/canncommercial/82RC1/softwareinst/instg/instg_quick.html?Mode=PmIns&InstallType=local&OS=Debian&Software=cannToolKit
+
+ - 源码编译并安装
+ 注意: ATB是CANN的标准组件, 提供标准的安装包供用户使用。如果希望使用已经编译好的标准包, 可以跳过这一步骤。
编译加速库,设置加速库环境变量:
```sh
> cd ascend-transformer-boost
- > bash scripts/build.sh
- > source output/atb/set_env.sh
+ > bash scripts/build.sh # 编译
+ > source output/atb/set_env.sh #安装
```
- - 无法获取ascend-op-common-lib代码仓时,可通过安装nnal软件包获取对应so文件
- - 安装步骤可参考 `run包使用`
- - 代码及软件包版本对应关系:
- nnal软件包需保持和toolkit及kernels软件包版本一致
- |CANN|代码分支|
- |-|-|
- |CANN 8.1.RC1|br_feature_cann_8.2.RC1_0515POC_20250630|
- - 执行
- ```sh
- source {install path}/nnal/atb/set_env.sh
- export ATB_BUILD_DEPENDENCY_PATH=${ATB_HOME_PATH}
- ```
- - run包使用
+ - ATN安装使用
- run包获取
1. 进入网址:https://www.hiascend.com/developer/download/commercial
2. 产品系列选择服务器,产品型号根据设备型号选择,选择所需解决方案版本,随后在CANN区域选择软件包跟随指引即可获取相关run包
@@ -51,25 +40,68 @@ ATB加速库采用了一系列优化策略,包括算法优化、硬件优化
其中,{version}表示软件版本号,{arch}表示CPU架构。
- 安装run包(需要依赖cann环境)
```sh
- chmod +x 软件包名.run # 增加对软件包的可执行权限
- ./软件包名.run --check # 校验软件包安装文件的一致性和完整性
- ./软件包名.run --install # 安装软件,可使用--help查询相关安装选项
+ chmod +x Ascend-cann-nnal__linux-.run # 增加对软件包的可执行权限
+ ./Ascend-cann-nnal__linux-.run --check # 校验软件包安装文件的一致性和完整性
+ ./Ascend-cann-nnal__linux-.run --install --whitelist=atb # 安装软件,可使用--help查询相关安装选项
```
出现提示`xxx install success!`则安装成功
## 使用说明
-- 加速库算子单元测试
- - c++
- ```sh
- bash scripts/build.sh unittest
+- 单算子调用
```
- - python
- ```sh
- bash scripts/build.sh pythontest
- ```
- - csv
- ```sh
- bash scripts/build.sh csvopstest
+ #include
+ #include
+
+ int deviceId = 0;
+ aclError status = aclrtSetDevice(deviceId);
+ // 以elewise大类中的Add算子为例,可通过以下方式构造对应参数:
+ atb::infer::ElewiseParam param;
+ param.elewiseType = atb::infer::ElewiseParam::ELEWISE_ADD;
+ // 创建算子对象实例
+ atb::Operation *op = nullptr;
+ atb::Status st = atb::CreateOperation(param, &op);
+
+ // Tensor构造方法
+ atb::Tensor a;
+ a.desc.dtype = ACL_FLOAT16; // 配置Tensor数据类型
+ a.desc.format = ACL_FORMAT_ND; // 配置Tensor格式
+ a.desc.shape.dimNum = 2; // 配置Tensor维度数
+ a.desc.shape.dims[0] = 3; // 配置Tensor第0维大小
+ a.desc.shape.dims[1] = 3; // 配置Tensor第1维大小
+ a.dataSize = Utils::GetTensorSize(a); // 获取Tensor内存大小
+ status = aclrtMalloc(&a.deviceData, a.dataSize, ACL_MEM_MALLOC_HUGE_FIRST); // 申请device内存
+ // 按上述方法构造所有输入和输出tensor,存入VariantPack
+ atb::VariantPack variantPack;
+ variantPack.inTensors = { a, ... };
+ variantPack.outTensors = { output, ... };
+
+ atb::Context *context = nullptr;
+ st = atb::CreateContext(&context);
+ aclrtStream stream = nullptr;
+ status = aclrtCreateStream(&stream);
+ context->SetExecuteStream(stream);
+
+ // 调用Setup接口,计算workspace大小。
+ uint64_t workspaceSize = 0;
+ st = op->Setup(variantPack, workspaceSize, context);
+
+ // 根据workspace大小申请NPU内存。
+ void *workspace = nullptr;
+ status = aclrtMalloc(&workspace, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
+
+ // 调用Execute接口,执行算子。
+ st = op->Execute(variantPack, (uint8_t *)workspace, workspaceSize, context);
+
+ // 销毁创建的对象,释放内存。
+ status = aclrtDestroyStream(stream); // 销毁stream
+ status = aclrtFree(workspace); // 销毁workspace
+ st = atb::DestroyOperation(op); // 销毁op对象
+ st = atb::DestroyContext(context); // 销毁context
+ // 下面代码为释放Tensor的示例代码,实际使用时需释放VariantPack中的所有Tensor
+ status = aclrtFree(tensor.deviceData);
+ tensor.deviceData = nullptr;
+ tensor.dataSize = 0;
+
```
## 参与贡献
diff --git a/docs/media/image.png b/docs/media/image.png
new file mode 100644
index 0000000000000000000000000000000000000000..952ded40a4ce749c37b3a175b8836c948e1c13e3
Binary files /dev/null and b/docs/media/image.png differ