1. 概述

mcApex在Apex的基础上增加了MXMACA^® 后端，支持使用MXMACA硬件加速Apex中各类计算任务。

当前发布包含以下版本安装包：

基于mcPyTorch 2.0.0编译的Python 3.8版本mcApex0.1
基于mcPyTorch 2.0.0编译的Python 3.10版本mcApex0.1
基于mcPyTorch 2.1.2编译的Python 3.8版本mcApex0.1
基于mcPyTorch 2.1.2编译的Python 3.10版本mcApex0.1
基于mcPyTorch 2.4.0编译的Python 3.8版本mcApex0.1
基于mcPyTorch 2.4.0编译的Python 3.10版本mcApex0.1
基于mcPyTorch 2.6.0编译的Python 3.10版本mcApex0.1

基于2.4.0之前版本mcPyTorch编译的mcApex支持在x86_64/Arm架构下Ubuntu 18/20/22以及CentOS 8/9系统上运行。基于2.4.0及之后版本mcPyTorch编译的mcApex支持在x86_64/Arm架构下Ubuntu 20/22以及CentOS 8/9系统上运行。mcApex的具体支持功能，参见 3 功能支持。

2. 快速安装

2.1. 基于pip安装

2.1.1. 环境准备

Python

匹配目标安装包的Python版本（例如，Python 3.8或者Python 3.10）
MXMACA环境

安装Driver软件包以及MXMACA SDK软件包
PyTorch环境

安装PyTorch软件包

2.1.2. 开始安装

mcApex安装包以apex-${APEX_VERSION}+metax${MACA_VERSION}-${PYTHON_VERSION}-${PYTHON_VERSION}-${arch_info}.whl格式命名。例如，mcApex + Python 3.8版本的安装包名称为：apex-0.1+metax2.24.0.1-cp38-cp38-linux_x86_64.whl。

操作步骤

安装方式同标准whl包。

安装mcApex：
```
python -m pip install apex-*.whl
```

2.1.3. 验证安装

操作步骤

运行前设置环境变量：

export MACA_PATH=/opt/maca/
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/mxgpu_llvm/lib:${LD_LIBRARY_PATH}
export MACA_CLANG_PATH=${MACA_PATH}/mxgpu_llvm/bin/

执行以下命令，没有报错即表明安装成功：
```
python -c "import apex"
```

2.1.4. 如何卸载

卸载方式同标准whl包。

操作步骤

卸载mcApex：
```
python -m pip uninstall apex
```

2.2. 使用Docker运行

mcApex依赖mcPyTorch运行，在MXMACA-PyTorch镜像中提供了预装的mcApex。MXMACA-PyTorch镜像以离线形式发布，用户可在随本文档发布的软件包中找到相关压缩包。

本文档中以mxc500-torch2.0-py38-mc2.23.0.6-ubuntu20.04-x86_64.container.xz为例，用户应根据实际收到的软件包版本对版本字段进行相应替换。

操作步骤

获取MXMACA容器镜像，执行以下命令，完成容器镜像的加载：

docker load < ./mxc500-torch2.0-py38-mc2.23.0.6-ubuntu20.04-x86_64.container.xz

在Docker容器中使用板卡，使用全部曦云系列GPU（以C500为例）：

docker run -it --device=/dev/mxcd --device=/dev/dri --group-add video mxc500-torch2.0-py38:mc2.23.0.6-ubuntu20.04-x86_64 /bin/bash

3. 功能支持

mcApex以兼容Apex的原生使用方式为设计目标，当前支持部分Apex的接口。

本章参照Apex官方文档内容，介绍mcApex各模块使用的兼容性和注意事项。其中：

支持：支持并兼容原生用法
部分支持：部分支持原生用法，或API行为和原生用法有区别

3.1. apex.fused_dense.FusedDense

支持

3.2. apex.transformer.functional.FusedScaleMaskSoftmax

支持

3.3. apex.transformer.functional.fused_apply_rotary_pos_emb

支持

3.4. apex.transformer.functional.fused_apply_rotary_pos_emb_cached

支持

3.5. apex.transformer.functional.fused_apply_rotary_pos_emb_thd

支持

3.6. apex.normalization.FusedLayerNorm

支持

3.7. apex.normalization.FusedRMSNorm

支持

3.8. apex.normalization.MixedFusedLayerNorm

支持

3.9. apex.normalization.MixedFusedRMSNorm

支持

3.10. apex.contrib.layer_norm.FastLayerNorm

支持