2. 安装部署

2.1. 依赖关系

安装mcDF之前需要满足如下硬软件依赖：

曦云系列GPU：mcDF仅支持基于曦云系列芯片的硬件平台
MXMACA SDK：mcDF基于MXMACA SDK实现GPU计算加速，安装mcDF之前必须先安装MXMACA SDK，配套版本以《MXMAP发布说明》为准
mcDF依赖cu-bridge的安装，请参考 cu-bridge 的使用指南安装并配置cu-bridge环境，建议安装到 /opt/maca/tools/ 目录下。

可以检查以下文件是否存在，并确认cu-bridge环境是否准备完毕：
```
/opt/maca/tools/cu-bridge/bin/cucc
/opt/maca/tools/cu-bridge/tools/cmake_maca
```
mcDF依赖基于MXMACA SDK的numbax、rmmx、mcPy等Python包
Dask-mcDF的本地分布式功能依赖基于MXMACA SDK的Dask-MACA Python包
Ubuntu 18.04 LTS、Ubuntu 20.04 LTS、Ubuntu 22.04 LTS、CentOS 8，且gcc/g++ 9.5+
x86_64，glibc≥2.27
Python 3.8或3.10

2.2. mcDF自动安装与卸载

自动安装命令：
```
tar -xJf maca-mcdf-<VERSION>-linux-x86_64.tar.xz
cd mcdf-<VERSION>
bash mxmap-install.sh -f
```
如果仅需要安装whl包、rpm包或deb包，则使用命令 bash mxmap-install.sh -i whl or rpm or deb，更多的用法请使用 bash mxmap-install.sh -h 来获得帮助。
自动卸载命令：
```
cd mcdf-<VERSION>
bash mxmap-install.sh -U
```
如果仅需要卸载whl包、rpm包或deb包，则使用命令 bash mxmap-install.sh -u whl or rpm or deb，更多的用法请使用 bash mxmap-install.sh -h 来获得帮助。

2.3. mcDF手动安装与卸载

安装mcDF之前需要安装沐曦编译发布的numbax、rmmx、mcPy Python包。

备注

mcDF、mcPy、numbax等依赖的第三方Python包，可以从公开pip源下载安装，本文中将仅描述对第三方Python包的依赖关系，不描述具体的安装指导。

如果mcDF的目标安装环境支持从pip源在线下载安装Python包，则在mcDF、mcPy、numbax等包的安装过程中会自动下载安装第三方依赖。
如果mcDF的目标安装环境不支持从pip源在线下载安装Python包，则用户需将第三方依赖库离线下载到本地，然后执行pip install命令进行安装。

2.3.1. 安装mcDF

numbax、rmmx、mcPy之间存在依赖关系，需按照文档中描述的先后顺序安装。

安装 numbax。

依赖说明：

zipp>=0.5
cython
llvmlite>=0.39.0dev0,<0.40
Numpy>=1.21,<=1.25
setuptools>=65.5.1
importlib_metadata

将 numbax wheel包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从pip源下载安装上述依赖库。
```
pip install numbax-x.y.z.n-cp38-cp38-linux_x86-64.whl
```
或
```
pip install numbax-x.y.z.n-cp310-cp310-linux_x86-64.whl
```

安装 rmmx。
1. 依赖说明：
```
Numpy>=1.19
```
2. 将 rmmx wheel包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从pip源下载安装上述依赖库。
```
pip install rmmx-x.y.z.n-cp38-cp38-linux_x86-64.whl
```
  或
```
pip install rmmx-x.y.z.n-cp310-cp310-linux_x86-64.whl
```
安装 mcPy。
1. 依赖说明：
```
Numpy>=1.21,<=1.27
FastRLock>=0.5
numbax>=0.56
```
2. 将 mcPy wheel包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从pip源下载安装上述依赖库。
```
pip install mcpy-x.y.z.n-cp38-cp38-linux_x86-64.whl
```
  或
```
pip install mcpy-x.y.z.n-cp310-cp310-linux_x86-64.whl
```

安装 mcDF。

依赖说明：

cachetools
fsspec>=0.6.0
packaging
pandas>=1.0,<1.6.0dev0
protobuf>=3.20.1,<3.21.0a0
typing_extensions
pyarrow==9.0.0

将 mcDF wheel包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从pip源下载安装上述依赖库。
```
pip install mcdf-x.y.z.n-cp38-cp38-linux_x86-64.whl
```
或
```
pip install mcdf-x.y.z.n-cp310-cp310-linux_x86-64.whl
```

2.3.2. 安装Dask-mcDF

使用Dask-mcDF的本地分布式功能需要安装Dask-MACA Python包。

安装 Dask-MACA。
1. 依赖说明：
```
dask==2023.1.1
distributed==2023.1.1
numpy>=1.18.0
pandas>=1.0
zict>=0.1.3
```
2. 将 Dask-MACA wheel包下载到本地，并执行以下命令进行安装，安装过程中会自动尝试从pip源下载安装上述依赖库。
```
pip install dask_maca-x.y.z.n-py3-none-any.whl
```
安装 mcDF，参见 2.3.1 安装mcDF。
安装 Dask-mcDF。
1. 依赖说明：
```
dask==2023.1.1
distributed>=2023.1.1
fsspec>=0.6.0
numpy
panda>=1.0,<1.6.0dev0
mcdf
mcpy
```
2. 将 Dask-mcDF wheel包下载到本地，并执行以下命令进行安装，安装过程中会自动尝试从pip源下载安装上述依赖库。
```
pip install dask_mcdf-x.y.z.n-py3-none-any.whl
```

2.3.3. 安装mcDF（C++）

安装mcDF（C++）前需要手动卸载之前安装的mcDF的deb或者rpm包。

安装依赖

安装GCC

由于mcDF基于C++17新特性开发，需要GCC 9.5及以上版本，libstdc++（版本高于libstdc++.so.6.0.28），对于Ubuntu 18.04以及CentOS 8需要手动安装GCC到 /usr/ 目录。

配置Conda依赖

mcDF还需要libarrow等第三方库。推荐使用Conda新建环境，并安装以下依赖项。注意，使用libarrow而不要使用pyarrow。

- aiobotocore>=2.2.0
- boto3>=1.21.21
- botocore>=1.24.21
- c-compiler
- cachetools
- cmake>=3.23.1,<3.25.0
- cxx-compiler
- dask>=2022.9.2
- distributed>=2022.9.2
- dlpack>=0.5,<0.6.0a0
- doxygen=1.8.20
- fastavro>=0.22.9
- fsspec>=0.6.0
- gcc_linux-64=9.*
- hypothesis
- libarrow=10
- librdkafka=1.7.0
- mimesis>=4.1.0
- moto>=4.0.8
- myst-nb
- nbsphinx
- packaging
- pip
- pre-commit
- protobuf=4.21
- s3fs>=2022.3.0
- streamz
- sysroot_linux-64==2.17
- typing_extensions
- spdlog=1.8.5
- fastrlock>=0.5
- llvmlite>=0.39.0dev0,<0.40
- xsimd=8.1.0
- bcrypt=4.0.1

安装mcDF（C++）
- Ubuntu系统
  
  假设mcDF（C++）的deb包已经保存在当前目录下，则可以使用 dpkg 安装：
```
$ sudo dpkg -i ./mcdf-x.y.z.n-linux.x86_64.deb
```
  安装成功后可以在 /opt/mxmap 下找到mcDF对应的头文件，动态库，以及CMake文件。也可以通过以下命令检查是否安装成功：
```
$ dpkg -l | grep mcdf
```
- CentOS系统
  
  假设mcDF（C++）的rpm包已经保存在当前目录，则可以使用如下命令安装：
```
$ sudo rpm -ivh ./mcdf-x.y.z.n-linux.x86_64.rpm
```
  安装成功后可以在 /opt/mxmap 下找到mcDF对应的头文件，动态库，以及CMake文件。也可以通过以下命令检查是否安装成功：
```
$ rpm -qa | grep mcdf
```

2.3.4. 卸载

执行以下命令，卸载mcDF。

$ pip uninstall mcdf # python package
$ pip uninstall dask_mcdf # python package
$ sudo dpkg -r mcdf # deb package
$ sudo rpm -e mcdf # rpm package

2.4. 环境变量设置

mcDF正常运行依赖如下环境变量：

MACA_PATH：指向MXMACA包的安装路径
MXMACA安装和运行所需要的其他环境变量

如果应用程序使用的GPU设备的数量少于实际数量，为了获得最佳性能，建议通过 MACA_VISIBLE_DEVICES 环境变量指定实际使用的GPU ID。

2.5. 常见问题

2.5.1. case1：numbax报错

如果遇到numbax报错如下：

"initialization of _internal failed without raising an exception"

请检查NumPy版本，推荐1.21 ≤ NumPy ≤ 1.25。

2.5.2. case2：关于pyarrow版本依赖关系

当采用mcDF wheel包安装部署方式时，会在mcDF的安装路径下同时安装libcudf.so和libarrow.so，这两个so之间存在配套绑定关系。

如果运行环境为conda虚拟环境，并安装了arrow-cpp和pyarrow，此时运行环境中将存在两个libarrow.so，一个是arrow-cpp中安装的，另一个是mcDF中安装的。如果在Python文件执行过程中先加载arrow-cpp的libarrow.so，那么后续执行 import cudf 时将会遇到libarrow.so中符号缺失的问题。

解决方法：

conda虚拟环境中同时安装arrow-cpp、pyarrow与仅pip安装pyarrow，这两种情况下安装的libarrow.so存在非常大的不同。

一般情况下，不会在运行时的conda虚拟环境中同时安装arrow-cpp和pyarrow。但如果同时安装了arrow-cpp和pyarrow，推荐采用mcDF的镜像发布方式。

如果可以修改运行时的conda虚拟环境，可以仅安装pyarrow而不安装arrow-cpp。

2.5.3. case3：关于glibc版本配套

mcDF运行时的glibc版本需≥glibc 2.27，否则可能存在符号缺失的问题。

可通过 ldd –version 命令查询当前环境中的glibc版本。