安装、卸载和升级
- 建议使用普通用户进行安装和运行。MindX SDK依赖于CANN包的低权限用户的动态库,使用root用户运行程序时,存在链接的动态库被低权限用户篡改的安全风险。
- 当前特征检索基于开放形态设计和发布,开放形态下的HDC通信机制受HwHiAiUser用户属组控制,滥用HwHiAiUser属组权限可能引发特征检索服务不可用或信息泄露等风险。
- 包括HDC通信机制在内,针对开放形态文件系统的恶意篡改和攻击所带来的安全隐患不在华为所管理的安全风险范围内,进行下一步的安装和使用前,请确保已知悉上述情形。
特征检索以二进制共享库形式发布,软件包在本地用户自定义路径通过run包安装。
安装特征检索
当前支持的昇腾硬件平台为昇腾310 AI处理器和昇腾310P AI处理器。
- 以软件包的安装用户登录安装环境。
- 将软件包上传到安装环境的任意路径下(如:“/home/package”)并进入软件包所在路径。
- 增加对软件包的可执行权限。
chmod +x Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run
- 执行如下命令,校验软件包的一致性和完整性。
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --check
若显示如下信息,说明软件包已通过校验。
Verifying archive integrity... 100% SHA256 checksums are OK. All good.
- 创建软件包的安装路径。
- 若用户想指定安装路径,需要先创建安装路径。以安装路径“/home/work/FeatureRetrieval”为例:
mkdir -p /home/work/FeatureRetrieval
- 若用户未指定安装路径,软件会默认安装到软件包所在的路径。
- 若用户想指定安装路径,需要先创建安装路径。以安装路径“/home/work/FeatureRetrieval”为例:
- 安装软件包,用户需确保整个安装过程由root用户执行,安装路径和解压路径仅允许root用户访问。
- 若用户指定了安装路径。以安装路径“/home/work/FeatureRetrieval”为例:
- 对于昇腾310 AI处理器:
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --install --install-path=/home/work/FeatureRetrieval --platform=310
- 对于昇腾310P AI处理器:
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --install --install-path=/home/work/FeatureRetrieval --platform=310P
- 对于昇腾310 AI处理器:
- 若用户未指定安装路径,安装路径默认为命令执行所在目录:
- 对于昇腾310 AI处理器:
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --install --platform=310
- 对于昇腾310P AI处理器:
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --install --platform=310P
- 对于昇腾310 AI处理器:
安装完成后会生成目录“mxIndex-{version}”,若显示如下信息,则表示软件成功安装。Uncompressing ASCEND MXINDEX RUN PACKAGE 100%
具体安装命令的接口参数介绍,请参见表1。
- 若用户指定了安装路径。以安装路径“/home/work/FeatureRetrieval”为例:
- 安装特征检索。
- 进入安装目录“mxIndex-{version}”,目录及文件名称参见如表2。
cd mxIndex-{version}
表2 mxIndex目录及文件名介绍 目录或文件名称
说明
ascendfaissdaemon
开放态部署方式下执行检索业务的程序,运行在Device侧。通过“install.sh”进行安装。
device
包含IndexIL算法的动态库和头文件。
filelist.txt
软件包文件列表。
host
包含标准态部署方式动态库。
通过标准态部署方式进行特征检索时,请链接此文件夹下的动态库。
include
API头文件,标准态和开放态部署方式均适用。
install.sh
部署脚本,将ascendfaissdaemon和modelpath打包到Device文件系统中,并完成Deviec侧安装部署启动。
lib
包含开放态部署方式动态库。
通过开放态部署方式进行特征检索时,请链接此文件夹下的动态库。
modelpath
算子om文件存放目录。编译好算子之后,需要将om文件放置于此文件夹。
ops
包含“custom_opp_<arch>.run”脚本,用于检索算法算子安装。
script
包含卸载脚本“uninstall.sh”,用于卸载mxIndex安装包。
tools
包含用于算子生成python脚本。
version.info
包含版本相关信息。
- 进入ops目录,编译算子前需要设置“ASCEND_HOME”和“ASCEND_VERSION”环境变量,默认分别为“/usr/local/Ascend和ascend-toolkit/latest”
export ASCEND_HOME=/usr/local/Ascend # Ascend home path export ASCEND_VERSION=ascend-toolkit/latest # atc/opp/toolkit installation path export ASCEND_OPP_PATH=/usr/local/Ascend/ascend-toolkit/latest/opp # opp installation path
- “ASCEND_HOME”表示“driver/ascend-toolkit”等组件所在路径。
- “ASCEND_VERSION”表示当前使用的Ascend版本,如果ATC工具安装路径是“/usr/local/Ascend/ascend-toolkit/latest”则无需设置“ASCEND_HOME”和“ASCEND_VERSION”,另外用户需要“ASCEND_OPP_PATH”目录的写权限。
- 根据实际系统架构执行对应脚本。
- ARM架构对应“custom_opp_aarch64.run”。
- x86_64架构对应“custom_opp_x86_64.run”。
./custom_opp_{arch}.run
表3 custom_opp_{arch}.run 参数说明 参数名称
说明
-h |--help
显示帮助信息。
--info
打印安装包的信息。
--list
打印安装包的文件列表。
--check
检测压缩包完整性。
--comfirm
运行嵌入式脚本前询问是否进行。
--quiet
不打印解压过程中的非错误信息。
--noexec
不执行嵌入的安装脚本。
--target
指定解压路径。
--keep
保留临时目录。
--noprogress
不打印解压进度。
--nochown
不修改文件属主到当前用户。
--nodiskspace
不检测磁盘剩余空间。
- 进入“tools”目录,编译算子。算子编译脚本具体请参考自定义算子介绍。
- 对于昇腾310 AI处理器:
cd ../tools && python3 run_generate_model.py
- 对于昇腾310P AI处理器:
cd ../tools && python3 run_generate_model.py -t 310P
- 对于昇腾310 AI处理器:
- 准备算子模型文件。
- 对于标准态部署方式,支持将算子模型文件目录配置为环境变量“MX_INDEX_MODELPATH”(环境变量支持以~开头的路径、相对路径和绝对路径,使用该变量时将统一转化为绝对路径并限制在“/home”或“/root”路径下)。
如未使用环境变量进行配置,需将算子模型文件移动到当前目录的“modelpath”目录下。
mv op_models/* $PWD/modelpath
- 对于开放态部署方式,需将算子模型文件移动到源码目录下的“modelpath”目录下。
mv op_models/* ../modelpath
算子生成后,请妥善保管相关om文件并确保文件不被篡改。
- 对于标准态部署方式,支持将算子模型文件目录配置为环境变量“MX_INDEX_MODELPATH”(环境变量支持以~开头的路径、相对路径和绝对路径,使用该变量时将统一转化为绝对路径并限制在“/home”或“/root”路径下)。
- (对于开放态部署方式)请执行以下命令完成环境部署,“install.sh”必须以root用户执行,请确保“mxIndex”安装目录所有文件不被篡改。
- 对于昇腾310 AI处理器,<driver-untar-path>为“Ascend310-driver-{software version}-minios.aarch64-src.tar.gz”文件解压后的目录。
cd .. && bash install.sh -d <driver-untar-path>
- 对于昇腾310P AI处理器,<driver-untar-path>为“Ascend310P-driver-{software version}-minios.aarch64-src.tar.gz”文件解压后的目录,-t 为芯片类型(默认为310,需要改为310P),具体可以通过-h 查看帮助信息。
cd .. && bash install.sh -d <driver-untar-path> -t 310P
默认情况下,deamon进程受OOM机制管控。如需启用设备极限内存,可在执行“install.sh”脚本命令时使用“-m”参数,关闭控制组(Cgroup)的OOM机制命令执行参考如下(以昇腾310 AI处理器为例)。
bash install.sh -d <driver-untar-path> -m
使用该参数后,Device侧内存占用将不受限制,可能会引起内存不足等问题,导致设备运行不稳定。
用户可登陆Device侧,执行以下命令,确认该参数是否启用。
cat /sys/fs/cgroup/memory/usermemory/memory.limit_in_bytes
- 如返回字节数大于设备内存大小,则该参数已启用。
- 如返回字节数小于设备内存大小,则该参数未启用。
- 对于昇腾310 AI处理器,<driver-untar-path>为“Ascend310-driver-{software version}-minios.aarch64-src.tar.gz”文件解压后的目录。
- (对于开放态部署方式)执行命令重启,完成部署。
reboot
- 进入安装目录“mxIndex-{version}”,目录及文件名称参见如表2。
卸载特征检索
卸载操作涉及对安装目录的删除步骤,如目录下存在其他文件,也会被一并删除。请在执行卸载操作前,确保所有数据都已妥善处理。
- 进入安装目录mxIndex-{version}。
cd mxIndex-{version}
- 进入“script”目录。
cd script
- 添加“uninstall.sh”文件可执行权限,并执行,完成卸载。
chmod +x uninstall.sh ./uninstall.sh
请根据实际情况,删除Host侧的算子,恢复在Device侧的变更修改(如重新安装驱动,恢复安全启动操作的修改)。
升级特征检索
升级操作涉及对安装目录的卸载再安装,如目录下存在其他文件,也会被一并删除。请在执行升级操作前,确保所有数据都已妥善处理。
如需从开放态部署变更为标准态部署,请参见卸载特征检索,卸载开放态部署后再次部署标准态特征检索。
特征检索包升级操作参考以下命令执行,升级操作参数说明请参见表4。
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --upgrade --platform={soc_version} --install-path={mxIndex_install_path}
参数名 |
参数说明 |
---|---|
--upgrade |
特征检索软件包升级操作命令,将特征检索升级到安装包所包含的mxIndex版本。 |
--platform |
对应昇腾AI处理器类型。
|
--install-path |
(可选)自定义特征检索软件包安装根目录。如未设置,默认为当前命令执行所在目录。 如使用自定义目录安装,建议在升级操作时使用该参数。 |
- 特征检索包升级命令执行示例参见如下,以安装路径“/home/work/FeatureRetrieval”为例。
- 对于昇腾310 AI处理器:
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --upgrade --platform=310 --install-path=/home/work/FeatureRetrieval
- 对于昇腾310P AI处理器:
./Ascend-mindxsdk-mxindex_{version}_linux-{arch}.run --upgrade --platform=310P --install-path=/home/work/FeatureRetrieval
命令执行后返回如下信息,则表示特征检索包升级成功。
Upgrade mxIndex package successfully.
- 对于昇腾310 AI处理器:
- 完成以上操作后,请参考安装特征检索步骤,完成特征检索后续安装配置过程。