From feddc71c6df60eb3e637712ead31dc82402b56b4 Mon Sep 17 00:00:00 2001 From: gp513 Date: Sun, 10 Mar 2024 17:09:46 +0800 Subject: [PATCH 1/3] update readme update --- README.zh.md | 285 +++++++++++++++++++++++++++------------------------ 1 file changed, 151 insertions(+), 134 deletions(-) diff --git a/README.zh.md b/README.zh.md index e916000..f287822 100644 --- a/README.zh.md +++ b/README.zh.md @@ -1,55 +1,23 @@ # Apex Patch -## 一、简介 - -### 1.1 Apex Patch功能介绍 +# 简介 Apex Patch以代码patch的形式发布，用户通过对原始Apex进行patch，可以在华为昇腾AI处理器上，使用Apex的自动混合精度训练功能进行模型训练，提升AI模型的训练效率，同时保持模型的精度和稳定性。此外，Apex-patch额外提供了如梯度融合、融合优化器等，以提升部分场景下模型在昇腾NPU上的训练效率，供用户选择使用。 -### 1.2 Apex-patch代码目录说明 - - ``` - ├── Apex - ├──patch - ├──npu.patch # Apex-patch对于原生Apex的patch文件，用于原生Apex中混合精度等功能基于昇腾AI处理器的适配 - ├──scripts - ├──docker/ # 使用Docker构建安装包的脚本与说明文件 - ├──build.sh # 构建安装包脚本 - ├──gen.sh # 使用Apex-patch对官方Apex打patch的脚本 - ├──make_patch.sh # 生成patch文件脚本 - ├──src - ├──apex - ├──contrib/ # 提供Tensor融合的Python API，供融合优化器使用 - ├──optimizers/ # 融合优化器的实现，部分场景下发挥昇腾的算力 - ├──csrc/combine_tensors/ # 提供Tensor融合的C++接口 - ├──tests # 测试用例 - ├──LICENSE - ``` - -### 1.3 Apex-patch已支持特性 - -- [x] O1/O2自动混合精度模式 -- [x] 动态/静态 loss scale -- [x] combine ddp -- [x] combine grad for unscale -- [x] npu fused optimizer: adadelta, adam, adamp, adamw, sgd, lamb, rmsprop, rmsprop_tf -- [x] 动态 loss scale新增可调参数，如：dynamic_init_scale, scale_growth_factor, scale_backoff_factor, scale_window - - -## 二、生成全量代码及编译、安装 +# 安装 -*推荐使用docker，在容器内编译：[参考链接](https://gitee.com/ascend/apex/tree/master/scripts/docker/README.md) +推荐使用docker，在容器内编译：[参考链接](https://gitee.com/ascend/apex/tree/master/scripts/docker/README.md) 建议用户以非root用户做环境的安装。若使用容器环境编译，建议使用普通用户，本仓库提供的Dockerfile仅供参考。请用户关注容器挂载目录安全性，避免系统路径，推荐只挂载业务路径，避免不必要的安全问题。 -### 2.1 获取昇腾适配的Apex-patch源码 +## 获取昇腾适配的Apex-patch源码 ``` git clone -b master https://gitee.com/ascend/apex.git cd apex/ ``` -### 2.2 编译apex的二进制包 +## 编译apex的二进制包 1、请确保torch已安装，setuptools版本小于等于65.7.0。推荐使用65.7.0，若安装其它版本请用户自行确保对应版本无重大漏洞。 @@ -57,20 +25,20 @@ cd apex/ ``` bash scripts/build.sh --python=3.7 ``` -生成的二进制包在apex/dist目录下 +过程中会自动拉取apex官方源码，请保证网络畅通，生成的二进制包在apex/dist目录下。 -### 2.3 安装 +## 安装 进入apex/dist目录，执行以下命令： ``` cd apex/dist/ pip3 uninstall apex -pip3 install --upgrade apex-0.1+ascend-{version}.whl version代表python版本和cpu架构 +pip3 install --upgrade apex-0.1+ascend-{version}.whl # version为python版本和cpu架构 ``` 如需要保存安装日志，可在pip3 install命令后面加上参数 `--log `，并对您指定的目录``做好权限管控。 -### 2.4 卸载 +## 卸载 Pytorch框架训练环境的卸载可以参考[昇腾官方文档](https://www.hiascend.com/document/detail/zh/ModelZoo/pytorchframework/ptes/ptes_00032.html)。 @@ -82,41 +50,11 @@ Apex及Apex-patch的卸载只需执行命令： 如需要保存卸载日志，可在pip3 install命令后面加上参数 `--log `，并对您指定的目录``做好权限管控。 -### 2.4 安全加固（可选） - -##### 2.4.1 安全风险提示 - -建议您务必对模型训练相关文件（如数据集、配置文件、源代码、checkpoint等）做好权限管理，避免文件被恶意篡改、破坏业务进行等风险，比如可以控制为同组/其他用户仅有只读权限。 - -##### 2.4.2 权限风险提示 - -- Linux 系统的 umask 值建议不低于027。 -- 不建议使用管理员账户安装运行，建议安装完成后对安装目录文件做好权限管控，文件及文件夹权限建议设置为 550。 -- 如需要保存安装日志，可在安装时对标准输出进行重定向， 重定向文件做好权限管控。 -- 运行程序前，建议用户对训练所需文件，模型脚本、权重等做好权限控制等安全措施，权限建议设置为 640。 -- 在多用户共享数据集的场景下，请根据需求最小化权限设置所需的文件夹以及文件的读写权限等，避免出现非法访问等安全问题。 -- 原生框架中，在使用某些特定特性时，可能会在`~/.cache`文件夹下生成临时文件，建议用户也应对`~/.cache`文件夹做好权限控制，避免安全风险。 -- 对于涉及到使用 C++ 动态编译特性的场景，建议打开 ASLR （地址空间配置随机加载）以及对编译后的 SO 文件开启 strip（移除调试符号信息），减少程序的暴露面。 因Apex-patch源码发布由用户自行编译，故需用户自行开启此类选项，开启方法参考下方章节。 - -##### 2.4.3 打开 ASLR +# 快速上手 -``` -echo 2 > /proc/sys/kernel/randomize_va_space -``` - -##### 2.4.4 对change_data_ptr等动态编译的so文件开启strip +## 自动混合精度（AMP） -安装软件后会在site-packages目录下产生change_data_ptr.{version}.so，用户可自行对该动态库开启strip。 - -``` -strip -s /xxx/python3/lib/site-packages/change_data_ptr.{version}.so # 目录路径仅供参考 -``` - -## 三、使用方法 - -### 3.1 自动混合精度 - -使用apex.amp进行混合精度训练，如： +使用apex.amp进行混合精度训练： ``` model = torch.nn.Linear(D_in, D_out).cuda() optimzier = torch.optim.SGD(model.parameters(), lr=1e-3) @@ -128,9 +66,9 @@ with amp.scale_loss(loss, optimizer) as scaled_loss: ... ``` -详细使用方式请请参考https://nvidia.github.io/apex/amp.html。 +详细使用方式请请参考[Apex官方文档](https://nvidia.github.io/apex/amp.html)。 -### 3.2 使用融合梯度进行scale/unscale +## 使用融合梯度进行scale/unscale优化加速 在amp.initialize()中将参数combine_grad设置为True，如： ``` @@ -144,9 +82,9 @@ with amp.scale_loss(loss, optimizer) as scaled_loss: ... ``` -### 3.3 融合优化器 +## 使用融合优化器优化加速 -将原有优化器替换为apex.optimizers.xxx, 其中xxx为融合优化器名称，如： +将torch原生优化器torch.optim.xxx替换为apex.optimizers.xxx, 其中xxx为融合优化器名称，apex-patch支持的优化器见*特性介绍*。 ``` model = torch.nn.Linear(D_in, D_out).cuda() optimzier = apex.optimizers.NpuFusedSGD(model.parameters(), lr=1e-3) # 使用apex.optimizers.NpuFusedSGD @@ -158,19 +96,30 @@ with amp.scale_loss(loss, optimizer) as scaled_loss: ... ``` -## 四、接口清单 +# 特性介绍 -原生API及参数说明请参考`https://nvidia.github.io/apex/amp.html`， 这里仅对Apex-patch新增接口、新增参数进行说明。 +Apex-patch已适配特性如下： -### 4.1 apex.amp +- [x] O1/O2自动混合精度模式 +- [x] 动态/静态 loss scale +- [x] combine ddp +- [x] combine grad for unscale +- [x] npu fused optimizer: adadelta, adam, adamp, adamw, sgd, lamb, rmsprop, rmsprop_tf +- [x] 动态 loss scale新增可调参数，如：dynamic_init_scale, scale_growth_factor, scale_backoff_factor, scale_window + +## 特性及接口介绍 -> 4.1.1 apex.amp.initialize(models, optimizers=None, enabled=True, opt_level="O1", cast_model_type=None, patch_torch_functions=None, keep_batchnorm_fp32=None, master_weights=None, loss_scale=None, cast_model_outputs=None, num_losses=1, verbosity=1, dynamic_init_scale=2.**16, scale_growth_factor=2., scale_backoff_factor=0.5, scale_window=2000, min_loss_scale=None, max_loss_scale=2.**24, combine_grad=None, combine_ddp=None, ddp_replica_count=4, user_cast_preferred=None, check_combined_tensors=None) +原生API及参数说明请参考[Apex官方文档](https://nvidia.github.io/apex/amp.html)， Apex-patch新增特性说明如下： -接口说明： +### apex.amp + +> apex.amp.initialize(models, optimizers=None, enabled=True, opt_level="O1", cast_model_type=None, patch_torch_functions=None, keep_batchnorm_fp32=None, master_weights=None, loss_scale=None, cast_model_outputs=None, num_losses=1, verbosity=1, dynamic_init_scale=2.**16, scale_growth_factor=2., scale_backoff_factor=0.5, scale_window=2000, min_loss_scale=None, max_loss_scale=2.**24, combine_grad=None, combine_ddp=None, ddp_replica_count=4, user_cast_preferred=None, check_combined_tensors=None) + +#### 接口说明 根据选择的opt_level等配置初始化模型、优化器，也可开启融合梯度优化、融合数据并行优化等。amp.initialize 应在构建完模型和优化器后调用，但应在通过任何 DistributedDataParallel 装饰器装饰模型之前调用。目前，amp.initialize 只应调用一次，尽管它可以处理任意数量的模型和优化器。 -新增参数说明： +#### 新增参数说明 - dynamic_init_scale - 动态loss scale初始值（默认2**16） - scale_growth_factor - loss scale增长系数（默认2） @@ -182,39 +131,45 @@ with amp.scale_loss(loss, optimizer) as scaled_loss: - user_cast_preferred - O1模式下优先选择用户注册的精度模式（默认None） - check_combined_tensors - tensor融合检查（默认None） -约束条件： +#### 约束条件 启用融合功能（combine_grad/combine_ddp）后，在创建融合张量时会申请融合后张量大小的内存，device内存不足时不建议使用。融合张量内存与原张量共享内存，若更改其一的内存地址，将破坏共享内存机制，可以引起精度异常等问题，使用时须用户自行保证共享内存不被破坏。 -示例： +#### 示例 ``` model, optim = apex.amp.initialize(model, optim, opt_level="O3", keep_batchnorm_fp32=True, ddp_replica_count=8) ``` -> 4.1.2 apex.amp.scale_loss(loss, optimizers, loss_id=0, model=None, delay_unscale=False, delay_overflow_check=False) +--- + +> apex.amp.scale_loss(loss, optimizers, loss_id=0, model=None, delay_unscale=False, delay_overflow_check=False) -接口说明： +#### 接口说明 使用混合精度时对loss进行scale，避免在低精度模式下梯度溢出。 -API及参数说明请参考`https://nvidia.github.io/apex/amp.html`，Apex-patch中修改了接口内部实现，以保证在NPU上功能正常，在开启融合功能时使用融合张量进行scale/unscale以提升训练效率。 +API及参数说明请参考[Apex官方文档](https://nvidia.github.io/apex/amp.html)，Apex-patch中修改了接口内部实现，以保证在NPU上功能正常，在开启融合功能时使用融合张量进行scale/unscale以提升训练效率。 -### 4.2 apex.optimizers +### apex.optimizers -接口说明： +#### 接口说明： 融合优化器算法实现上等价于torch中的优化器实现，在梯度更新阶段利用Tensor融合技术，使用融合的梯度和参数进行更新，以提升部分场景下昇腾训练服务器上模型训练的效率。 -示例： +#### 融合优化器约束条件 + +启用融合优化器（如apex.optimizers.NpuFusedSGD）后，在创建融合张量时会申请融合后张量大小的内存，device内存不足时不建议使用。融合张量内存与原张量共享内存，若更改其一的内存地址，将破坏共享内存机制，可以引起精度异常等问题，使用时须用户自行保证共享内存不被破坏。 + +#### 示例 将torch.optim.XXX替换为apex.optimizers.NpuFusedXXX，如： ``` opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weight_decay=0.1) ``` -已支持的融合优化器及参数说明如下： +#### 已支持的融合优化器及参数说明如下 -> 4.2.1 class apex.optimizers.NpuFusedSGD(params, lr=required， momentum=MOMENTUM_MIN, dampening=DAMPENING_DEFAULT, weight_decay=WEIGHT_DECAY_MIN, nesterov=False) +> class apex.optimizers.NpuFusedSGD(params, lr=required， momentum=MOMENTUM_MIN, dampening=DAMPENING_DEFAULT, weight_decay=WEIGHT_DECAY_MIN, nesterov=False) 参数说明： @@ -225,7 +180,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - weight_decay - 权重衰减（默认值：0.0） - nesterov - 使用nesterov动量（默认值：False） -> 4.2.2 class NpuFusedAdam(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=0, amsgrad=False) +> class NpuFusedAdam(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=0, amsgrad=False) 参数说明： @@ -236,7 +191,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - weight_decay - 权重衰减（默认值：0） - amsgrad - 是否使用AMSGrad（默认值：False） -> 4.2.3 class NpuFusedAdamW(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=1e-2, amsgrad=False) +> class NpuFusedAdamW(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8, weight_decay=1e-2, amsgrad=False) 参数说明： @@ -247,7 +202,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - weight_decay - 权重衰减（默认值：0） - amsgrad - 是否使用AMSGrad（默认值：False） -> 4.2.4 class 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) +> class 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) 参数说明： @@ -260,7 +215,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - wd_ratio - 权重衰减动态调整速率（默认值：0.1） - nesterov - 使用nesterov动量（默认值：False） -> 4.2.5 class 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) +> class 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) 参数说明： @@ -275,7 +230,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - weight_decay - 权重衰减（默认值：0.01） - max_grad_norm - 最大梯度正则（默认值：1.0，-1表示不做裁剪） -> 4.2.6 class NpuFusedAdadelta(params, lr=1.0, rho=0.9, eps=1e-6, weight_decay=0) +> class NpuFusedAdadelta(params, lr=1.0, rho=0.9, eps=1e-6, weight_decay=0) 参数说明： @@ -285,7 +240,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - eps - 分母防除0项，提高数值稳定性（默认值：1e-6） - weight_decay - 权重衰减（默认值：0） -> 4.2.7 class Lamb(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-6, weight_decay=0, adam=False) +> class Lamb(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-6, weight_decay=0, adam=False) 参数说明： @@ -296,7 +251,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - weight_decay - 权重衰减（默认值：0） - adam - 将strust_ratio设置为1，退化为Adam（默认值：False） -> 4.2.8 class NpuFusedLamb(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-6, weight_decay=0, adam=False, use_global_grad_norm=False) +> class NpuFusedLamb(params, lr=1e-3, betas=(0.9, 0.999), eps=1e-6, weight_decay=0, adam=False, use_global_grad_norm=False) 参数说明： @@ -308,7 +263,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - adam - 将strust_ratio设置为1，退化为Adam（默认值：False） - use_global_grad_norm - 使用全局梯度正则（默认值：False） -> 4.2.9 class NpuFusedRMSprop(params, lr=1e-2, alpha=0.99, eps=1e-8, weight_decay=0, momentum=0, centered=False) +> class NpuFusedRMSprop(params, lr=1e-2, alpha=0.99, eps=1e-8, weight_decay=0, momentum=0, centered=False) 参数说明： @@ -320,7 +275,7 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - momentum - 动量因子（默认值：0） - centered - 计算中心RMSProp（默认值：False） -> 4.2.10 class 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) +> class 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) 参数说明： @@ -334,36 +289,113 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig - decoupled_decay - 权重衰减仅作用于参数（默认值：False） - lr_in_momentum - 计算动量buffer时使用lr（默认值：True） -融合优化器约束条件： -启用融合优化器（如apex.optimizers.NpuFusedSGD）后，在创建融合张量时会申请融合后张量大小的内存，device内存不足时不建议使用。融合张量内存与原张量共享内存，若更改其一的内存地址，将破坏共享内存机制，可以引起精度异常等问题，使用时须用户自行保证共享内存不被破坏。 +# 安全声明 + +## 系统安全加固 + +用户可在运行系统配置时开启ASLR（级别2）以提高系统安全性，保护系统随机化开启。 可参考以下方式进行配置： + +``` +echo 2 > /proc/sys/kernel/randomize_va_space +``` -### 4.3 其它 +因Apex-patch源码需由用户自行编译，建议用户对编译后生成的SO文件开启strip，又称**移除调试符号信息**，开启方式可参考以下方式： -> 4.3.1 model.zero_grad(set_to_none: bool = False) +``` +strip -s /xxx/python3/lib/site-packages/change_data_ptr.{version}.so # 根据apex实际安装目录替换目录前缀 +``` -在torch>2.x版本后，该接口参数`set_to_none`默认值变化为True，由于融合功能要求模型梯度内存不能发生变化或释放，在开启融合功能时Apex-patch通过Monkey Patch的方式将该接口参数`set_to_none`强制设置为False。 +## 运行用户建议 -> 4.3.2 apex.optimizers.NpuFusedXXX.clip_optimizer_grad_norm_fused(max_norm, norm_type=2) +基于安全性考虑，建议您在执行任何命令时，不建议使用root等管理员类型账户执行，遵循权限最小化原则。 -在使用融合优化器时，该接口等价于`torch.nn.utils.clip_grad_norm_(parameters, max_norm, norm_type=2.0)` +## 文件权限控制 -### 4.4 C++侧接口 +建议用户在主机（包括宿主机）及容器中设置运行系统umask值为0027及以上，保障新增文件夹默认最高权限为750，新增文件默认最高权限为640。 -> 4.4.1 change_data_ptr(at::Tensor dst, at::Tensor src, int offset) +建议用户对个人数据、商业资产、源文件、训练过程中保存的各类文件等敏感内容做好权限管控。涉及场景如apex安装目录权限管控、多用户使用共享数据集权限管控等场景，管控权限可参考表1进行设置。 -接口说明： +*表1 文件（夹）各场景权限管控推荐最大值* -目标Tensor地址重指向源Tensor相对起始地址的某个偏移，用于实现Tensor融合时的Storage内存共享。该接口为Apex-patch内部使用接口，不对用户开放。 +| 类型 | linux权限参考最大值 | +| -------------- | --------------- | +| 用户主目录 | 750（rwxr-x---） | +| 程序文件(含脚本文件、库文件等) | 550（r-xr-x---） | +| 程序文件目录 | 550（r-xr-x---） | +| 配置文件 | 640（rw-r-----） | +| 配置文件目录 | 750（rwxr-x---） | +| 日志文件(记录完毕或者已经归档) | 440（r--r-----） | +| 日志文件(正在记录) | 640（rw-r-----） | +| 日志文件目录 | 750（rwxr-x---） | +| Debug文件 | 640（rw-r-----） | +| Debug文件目录 | 750（rwxr-x---） | +| 临时文件目录 | 750（rwxr-x---） | +| 维护升级文件目录 | 770（rwxrwx---） | +| 业务数据文件 | 640（rw-r-----） | +| 业务数据文件目录 | 750（rwxr-x---） | +| 密钥组件、私钥、证书、密文文件目录 | 700（rwx—----） | +| 密钥组件、私钥、证书、加密密文 | 600（rw-------） | +| 加解密接口、加解密脚本 | 500（r-x------） | -参数说明： -- dst - 用于地址重指的目标Tensor，重指后对应的Storage内存将被释放 -- src - 用于地址重指的源Tensor，目标Tensor将被指向源Tensor的某个偏移 -- offset - 目标Tensor指向源Tensor起始地址的偏移量 +## 构建安全声明 + +Apex-patch通过源码发布，需要用户自行编译，在编译时会下载依赖第三方库并执行构建shell脚本，在编译过程中会产生临时程序文件和编译目录。用户可根据需要自行对源代码目录内的文件进行权限管控避免安全风险。管控权限可参考表1进行设置。 + +## 运行安全声明 + +建议根据运行环境资源状况编写训练脚本，如模型大小、数据集、混合精度模式等选择不当时，可能导致显存超限等情况，进一步引发错误并退出进程。 + +运行异常时会退出进程并打印报错信息，建议根据报错提示定位具体原因。 + +## 公网地址声明 + +| 类型 | 开源代码地址 | 文件名 | 公网IP地址/公网URL地址/域名/邮箱地址 | 用途说明 | +| :------------: |:-------------------------------------------------------------------------------:|:---------------------------------------------------:| :----------------------------------------------------------: | :-------------------------: | +| 开源引入 | https://github.com/NVIDIA/apex.git | scripts/build.sh | https://github.com/NVIDIA/apex.git | 构建脚本中拉取原生Apex源码，结合Ascend Apex patch构建安装包 | + + +## 公开接口声明 + +Apex-patch为Apex基于昇腾NPU的适配，接口使用继承官方Apex，可参考[Apex官方文档](https://nvidia.github.io/apex/amp.html)。 + +新增公开接口参考**特性介绍**，未展示接口为内部接口，不对外暴露，可能会修改或删除，不建议用户直接使用。 + + +## 通信安全加固 + +[通信安全加固说明](https://gitee.com/ascend/pytorch/blob/master/SECURITYNOTE.md#%E9%80%9A%E4%BF%A1%E5%AE%89%E5%85%A8%E5%8A%A0%E5%9B%BA +) + +## 通信矩阵 +[通信矩阵说明](https://gitee.com/ascend/pytorch/blob/master/SECURITYNOTE.md#%E9%80%9A%E4%BF%A1%E7%9F%A9%E9%98%B5%E4%BF%A1%E6%81%AF) -## 五、Apex-patch配套软件 +# 附录 +## Apex-patch代码目录说明 + + ``` + ├── Apex + ├──patch + ├──npu.patch # Apex-patch对于原生Apex的patch文件，用于原生Apex中混合精度等功能基于昇腾AI处理器的适配 + ├──scripts + ├──docker/ # 使用Docker构建安装包的脚本与说明文件 + ├──build.sh # 构建安装包脚本 + ├──gen.sh # 使用Apex-patch对官方Apex打patch的脚本 + ├──make_patch.sh # 生成patch文件脚本 + ├──src + ├──apex + ├──contrib/ # 提供Tensor融合的Python API，供融合优化器使用 + ├──optimizers/ # 融合优化器的实现，部分场景下发挥昇腾的算力 + ├──csrc/combine_tensors/ # 提供Tensor融合的C++接口 + ├──tests # 测试用例 + ├──LICENSE + ``` + + + +## Apex-patch配套软件 | AscendPyTorch版本 | 支持PyTorch版本 | Pytorch Gitee分支名称 | Apex Gitee分支名称 | | :---------------- | :--------------- | :--------------------- | :----------------- | @@ -384,18 +416,3 @@ opt = apex.optimizers.NpuFusedSGD(model.parameters(), lr=0.1, momentum=0.9, weig | 5.0.rc2           | 1.8.1.post2, 1.11.0, 2.0.1.rc1  | v1.8.1-5.0.rc2, v1.11.0-5.0.rc2 | 5.0.rc2 | | 5.0.rc3           | 1.11.0, 2.0.1.rc1  | v1.11.1-5.0.rc3, v2.0.1-5.0.rc3 | 5.0.rc3 | -## 六、附录 - -##### 6.1 公网地址 - -|      类型      |          文件名          |             公网IP地址/公网URL地址/域名/邮箱地址             |          用途说明           | -| :------------: | :----------------------: | :----------------------------------------------------------: | :-------------------------: | -|  开源代码  |      scripts/build.sh       |          https://github.com/NVIDIA/apex.git          | 构建脚本中拉取原生Apex源码，结合Ascend Apex patch构建安装包 | - -##### 6.2 通信矩阵 - -本插件不涉及端口开放、监听等相关行为，相关端口行为由用户在模型脚本调用Pytorch原生接口开启，具体通信矩阵可参考 [torch_npu](https://gitee.com/ascend/pytorch/)，建议用户注意做好安全防护。 - -##### 6.3 资源使用 - -建议您根据自身运行环境资源状况，进行训练配置的设定与数据集的准备，若与资源状况不匹配，比如数据集的size超出内存容量/NPU存储容量等，那么Pytorch及相关三方库进程会直接退出，并自动释放占用的资源。 -- Gitee From e47386c9cf5a27e421548a14560728a1af7771fa Mon Sep 17 00:00:00 2001 From: gp513 Date: Tue, 26 Mar 2024 17:00:29 +0800 Subject: [PATCH 2/3] update readme --- README.zh.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/README.zh.md b/README.zh.md index f287822..447ca12 100644 --- a/README.zh.md +++ b/README.zh.md @@ -351,10 +351,32 @@ Apex-patch通过源码发布，需要用户自行编译，在编译时会下载 ## 公网地址声明 -| 类型 | 开源代码地址 | 文件名 | 公网IP地址/公网URL地址/域名/邮箱地址 | 用途说明 | -| :------------: |:-------------------------------------------------------------------------------:|:---------------------------------------------------:| :----------------------------------------------------------: | :-------------------------: | -| 开源引入 | https://github.com/NVIDIA/apex.git | scripts/build.sh | https://github.com/NVIDIA/apex.git | 构建脚本中拉取原生Apex源码，结合Ascend Apex patch构建安装包 | - +| 类型 | 开源代码地址 | 文件名 | 公网IP地址/公网URL地址/域名/邮箱地址 | 用途说明 | +| :---: |:---:|:---:| :---: | :---: | +| 开源引入 | https://github.com/NVIDIA/apex.git | scripts/build.sh | https://github.com/NVIDIA/apex.git | 构建脚本中拉取原生Apex源码，结合Ascend Apex patch构建安装包 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | http://jmlr.org/papers/v12/duchi11a.html | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://arxiv.org/abs/1412.6980 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://openreview.net/forum?id=ryQu7f-RZ | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://arxiv.org/abs/1904.00962 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://nvidia.github.io/OpenSeq2Seq/html/optimizers.html#novograd | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://arxiv.org/abs/1904.03288 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | http://www.cs.toronto.edu/%7Ehinton/absps/momentum.pdf | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/pytorch/pytorch/blob/master/torch/csrc/utils/tensor_flatten.h | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/cutlass.git | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/apex/issues/486 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/pytorch/pytorch/pull/23408 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/apex/pull/323#discussion_r287021798 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/pytorch/pytorch/commit/4404762d7dd955383acee92e6f06b48144a0742e | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/apex/issues/456 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://hub.docker.com/r/pytorch/pytorch | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/apex/tree/master/examples/imagenet | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/apex/issues/134#issuecomment-458307368 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://arxiv.org/abs/1904.00962 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/pytorch/pytorch/commit/eb7b39e02f7d75c26d8a795ea8c7fd911334da7e#diff-4632522f237f1e4e728cb824300403ac | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://pytorch.org/ | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://www.github.com/nvidia/apex | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/pytorch/pytorch/pull/36026 | 删除公网地址的patch代码 | +| 开源引入 | https://github.com/NVIDIA/apex.git | patch/npu.patch | https://github.com/NVIDIA/apex/issues | 删除公网地址的patch代码 | ## 公开接口声明 -- Gitee From 9d5ff203ebfebcf53de105f804e04aa30ad6d91d Mon Sep 17 00:00:00 2001 From: gp513 Date: Wed, 27 Mar 2024 10:11:34 +0800 Subject: [PATCH 3/3] update readme fix --- README.zh.md | 46 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/README.zh.md b/README.zh.md index 447ca12..3dc8e8d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -84,18 +84,42 @@ with amp.scale_loss(loss, optimizer) as scaled_loss: ## 使用融合优化器优化加速 -将torch原生优化器torch.optim.xxx替换为apex.optimizers.xxx, 其中xxx为融合优化器名称，apex-patch支持的优化器见*特性介绍*。 +适配后的APEX针对adadelta/adam/sgd/lamb等做了昇腾AI处理器亲和性优化，得到的NPU融合优化器与原生算法保持一致，但运算速度更快。使用时只需将原有优化器替换为apex.optimizers.xxx，xxx为优化器名称，例如NpuFusedSGD。 + +样例原代码： +``` +optimizer = torch.optim.SGD(model.parameters(), lr=args.lr, momentum=args.momentum) +model, optimizer = amp.initialize(model, optimizer, opt_level='O2', loss_scale=32.0) ``` -model = torch.nn.Linear(D_in, D_out).cuda() -optimzier = apex.optimizers.NpuFusedSGD(model.parameters(), lr=1e-3) # 使用apex.optimizers.NpuFusedSGD -model, optimizer = amp.initialize(model, optimizer, opt_level='O1', combine_grad=True) -... -with amp.scale_loss(loss, optimizer) as scaled_loss: -  scaled_loss.backward() -... +修改后代码： +``` +optimizer = apex.optimizers.NpuFusedSGD(model.parameters(), lr=args.lr, momentum=args.momentum) +model, optimizer = amp.initialize(model, optimizer, opt_level='O2', loss_scale=32.0, combine_grad=True) +``` + +**说明** + +当optimizer的可更新参数分为不同的多组，每组使用不同的策略，这种场景下，融合优化器只能优化掉第一个model分组的参数。因此，当优化器的参数相同时，尽量合并分组。 +优化前： +``` +optimizer = apex.optimizers.NpuFusedSGD([ + {'params': model.sharedNet.parameters()}, + {'params': model.bottleneck.parameters()}, + {'params': model.domain_classifier.parameters()}, + {'params': model.dcis.parameters()}, + {'params': model.source_fc.parameters(), 'lr': LEARNING_RATE}, + ], lr=LEARNING_RATE / 10, momentum=args.momentum, weight_decay=args.l2_decay) +``` +优化后： +``` +optimizer = apex.optimizers.NpuFusedSGD([ + {'params': list(model.sharedNet.parameters()) + list(model.bottleneck.parameters()) + list(model.domain_classifier.parameters())+list(model.dcis.parameters())}, + {'params': model.source_fc.parameters(), 'lr': LEARNING_RATE}, + ], lr=LEARNING_RATE / 10, momentum=args.momentum, weight_decay=args.l2_decay) ``` + # 特性介绍 Apex-patch已适配特性如下： @@ -107,6 +131,12 @@ Apex-patch已适配特性如下： - [x] npu fused optimizer: adadelta, adam, adamp, adamw, sgd, lamb, rmsprop, rmsprop_tf - [x] 动态 loss scale新增可调参数，如：dynamic_init_scale, scale_growth_factor, scale_backoff_factor, scale_window +## 约束与限制 + +1. APEX当前版本的实现方式为python实现，不支持APEX中的自定义优化CUDA Kernel。 +2. APEX当前版本只支持适配昇腾AI处理器的混合精度计算和多种融合优化器功能，其他功能暂未支持。融合优化器与原生优化器算法保持一致，但运算速度更快。 + + ## 特性及接口介绍 原生API及参数说明请参考[Apex官方文档](https://nvidia.github.io/apex/amp.html)， Apex-patch新增特性说明如下： -- Gitee