2. 快速入门

2.1. 软件包

如果使用离线镜像文件安装 mcDF，可以忽略本章节。

2.1.1. 软件包信息

mcDF提供了 maca-mcdf-<VERSION>-linux-x86_64.tar.xz，可以使用命令 tar -xJf 进行解压，解压后可获得依赖的 mcPy 二进制软件包和 mcDF 二进制软件包。

mcPy 二进制软件包的说明，参见《曦云^® 系列通用GPU mcPy使用手册》。mcDF二进制软件包的信息说明，参见表 2.1。

表 2.1 软件包
软件包类型	文件名示例	说明
Python wheel 包	mcdf-x.y.z.n+bu.v.w.m-cp310-cp310-linux_86_64.whl	适用于 Python 3.10 的 mcDF Python wheel安装包
Python wheel 包	mcdf-x.y.z.n+bu.v.w.m-cp312-cp312-linux_86_64.whl	适用于 Python 3.12 的 mcDF Python wheel安装包
Python wheel 包	pylibmcdf-x.y.z.n+bu.v.w.m-cp310-cp310-linux_86_64.whl	适用于 Python 3.10 的 mcDF Python wheel安装包
Python wheel 包	pylibmcdf-x.y.z.n+bu.v.w.m-cp312-cp312-linux_86_64.whl	适用于 Python 3.12 的 mcDF Python wheel安装包
Python wheel 包	libmcdf-x.y.z.n+bu.v.w.m-py3-none-linux_86_64.whl	mcDF Python wheel安装包
Python wheel 包	mcpy-x.y.z.n+bu.v.w.m-cp310-cp310-linux_86_64.whl	适用于Python 3.10 的 mcPy Python wheel安装包
Python wheel 包	mcpy-x.y.z.n+bu.v.w.m-cp312-cp312-linux_86_64.whl	适用于Python 3.12 的 mcPy Python wheel安装包
Python wheel 包	numbax-x.y.z.n+bu.v.w.m-cp310-cp310-linux_86_64.whl	适用于Python 3.10 的 numbax Python wheel安装包
Python wheel 包	numbax-x.y.z.n+bu.v.w.m-cp312-cp312-linux_86_64.whl	适用于Python 3.12 的 numbax Python wheel安装包
Python wheel 包	rmmx-x.y.z.n+bu.v.w.m-cp310-cp310-linux_86_64.whl	适用于Python 3.10 的 rmmx Python wheel安装包
Python wheel 包	rmmx-x.y.z.n+bu.v.w.m-cp312-cp312-linux_86_64.whl	适用于Python 3.12 的 rmmx Python wheel安装包
Python wheel 包	librmm-x.y.z.n+bu.v.w.m-py3-none-linux_86_64.whl	适用于Python 3.12 的 rmmx Python wheel安装包

备注

x.y.z.n 表示对应包的软件代码版本号，bu.v.w.m 表示编译出包时的构建版本号。
当前支持 x86_64 平台的 Python 3.12，请选取适配具体 Python 版本的软件包。

2.2. 离线镜像文件部署方式

执行以下命令进入容器:

$ sudo docker load -i mcvs_mcdf_25.12_macax.y.z.n_py312_ubuntu24.04_amd64.tar.gz
$ sudo docker run -it --device=/dev/mxcd --device=/dev/dri --group-add video mxcr.io/dc-release/c500/mcvs_mcdf_25.12:x.y.z.n-ubuntu2404-x86_64 /bin/bash

2.3. 软件包安装部署方式

2.3.1. 依赖关系

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

曦云系列GPU：mcDF 仅支持基于曦云系列芯片的硬件平台
MXMACA SDK：mcDF 基于 MXMACA SDK 实现 GPU 计算加速，安装mcDF之前必须先安装MXMACA SDK，配套版本以《MXMAP发布说明》为准
mcDF 依赖基于 MXMACA SDK 的numbax、rmmx、mcPy 等 Python 包
Ubuntu 20.04 LTS、Ubuntu 22.04 LTS、Ubuntu 24.04 LTS，且 gcc/g++ 14.3+
x86_64，glibc≥2.31
Python 3.10、3.12

2.3.2. 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.2.1. 安装 mcDF（Python）

numbax、rmmx、mcPy 之间存在依赖关系，需按照文档中描述的先后顺序安装（这里以python3.12环境为例）。

安装 numbax
1. 依赖说明：
```
zipp>=0.5
cython
llvmlite>=0.39.0dev0,<0.40
numpy>=1.21,<=1.25
setuptools>=65.5.1
importlib_metadata
```
1. 将numbax wheel包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从 pip 源下载安装上述依赖库。
```
$ pip install numbax-x.y.z.n-cp312-cp312-linux_x86-64.whl
```
安装 rmmx
1. 依赖说明：
```
numpy>=1.19
```
1. 将 rmmx wheel 包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从 pip 源下载安装上述依赖库。
```
$ pip install rmmx-x.y.z.n+bu.v.w.m-cp312-cp312-linux_x86-64.whl
$ pip install librmm-x.y.z.n+bu.v.w.m-py3-none-linux_x86-64.whl
```
安装 mcPy
1. 依赖说明：
```
numpy>=1.21,<=1.27
fastRLock>=0.5
```
1. 将mcPy wheel包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从 pip 源下载安装上述依赖库。
```
$ pip install mcpy-x.y.z.n-cp312-cp312-linux_x86-64.whl
```

安装mcDF

依赖说明：

cachetools
fsspec>=0.6.0
packaging
pandas>=2.0,<2.4.0dev0
rich
pyarrow>=15.0.0,<=20.0.0

将 mcDF wheel 包下载到本地，执行以下命令进行安装，安装过程中会自动尝试从 pip 源下载安装上述依赖库。

$ pip install libmcdf-x.y.z.n+bu.v.w.m-py3-none-linux_x86-64.whl
$ pip install pylibmcdf-x.y.z.n+bu.v.w.m-cp312-cp312-linux_x86-64.whl
$ pip install mcdf-x.y.z.n+bu.v.w.m-cp312-cp312-linux_x86-64.whl

2.3.2.2. 卸载

执行以下命令，卸载mcDF。

$ pip uninstall mcdf # python package

2.3.3. 环境变量设置

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

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

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

2.4. 常见问题

2.4.1. case1：numbax报错

如果遇到numbax报错如下：

"initialization of _internal failed without raising an exception"

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

2.4.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.4.3. case3：关于glibc版本配套

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

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

2.4.4. case4: libldap.so符号不匹配

由于mcDF核心代码使用了C++20标准的实现，因此系统库版本会比较高，如果遇到了诸如”libldap.so.2: undefined symbol: EVP_md2, version OPENSSL_3.0.0” 可以升级liibcurl。推荐在conda环境中使用。并conda install libcurl=8.20.0