昇腾 NPU 推理环境安装与配置文档

适用场景：昇腾 aarch64 服务器 / 推理盒子，离线或内网环境，Python 3.10，Ubuntu 22.04。

本文档不包含 Docker 部署内容。

1. 环境准备

安装前需要确认以下环境已就绪：

昇腾 NPU 驱动已安装；
CANN 开发套件已安装；
Python 3.10 可用；
pip3 可用；
当前用户具有 root 权限，或可使用 sudo。

确认 NPU 驱动：

bash 复制代码

npu-smi info

确认 Python 版本：

bash 复制代码

python3 --version

确认 pip 可用：

bash 复制代码

pip3 --version

2. 配置 CANN 环境变量

安装完成后，需要加载 CANN 环境变量：

bash 复制代码

source /usr/local/Ascend/ascend-toolkit/set_env.sh

验证环境变量是否生效：

bash 复制代码

echo $ASCEND_HOME

正常应输出类似：

text 复制代码

/usr/local/Ascend/ascend-toolkit

如需永久生效，可写入 ~/.bashrc：

bash 复制代码

echo 'source /usr/local/Ascend/ascend-toolkit/set_env.sh' >> ~/.bashrc
source ~/.bashrc

3. 安装 Python 基础依赖

ais_bench 及 CANN 相关组件依赖部分 Python 库。建议优先安装以下基础依赖：

bash 复制代码

pip3 install attrs cython numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py

如果环境支持清华源，可使用：

bash 复制代码

pip3 install attrs cython numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：

numpy 版本需与当前 CANN 版本兼容；
protobuf 部分版本要求使用 3.20 系列；
具体版本以实际 CANN 文档为准。

4. 安装 aclruntime

aclruntime 是昇腾 ACL 推理接口的 Python 绑定，必须先于 ais_bench 安装。

根据服务器架构选择对应 whl 包。aarch64 环境示例：

bash 复制代码

pip3 install aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl

安装完成后，可执行：

bash 复制代码

pip3 show aclruntime

确认安装成功。

5. 安装 ais_bench

ais_bench 是昇腾 OM 离线模型推理工具，支持命令行推理和 Python API 调用。

安装命令：

bash 复制代码

pip3 install ais_bench-0.0.2-py3-none-any.whl

安装完成后验证：

bash 复制代码

python3 -m ais_bench --help

若能正常输出帮助信息，说明安装成功。

6. 验证 Python API 可用性

创建测试脚本 test_ais_bench.py：

python 复制代码

from ais_bench.infer.interface import InferSession

print("ais_bench Python API import success")

执行：

bash 复制代码

python3 test_ais_bench.py

正常输出：

text 复制代码

ais_bench Python API import success

7. 准备 OM 模型文件

推理前需要准备已转换好的 .om 模型文件。OM 模型通常由 ATC 工具从 ONNX、Caffe、TensorFlow 等框架模型转换得到。

将模型文件放置到项目目录中，例如：

text 复制代码

weights/
└── model.om

确认文件存在且可读：

bash 复制代码

ls -lh weights/model.om

注意：

模型文件必须是真实文件，不能是损坏的符号链接；
文件后缀必须为 .om；
当前用户需要对该文件具有读权限；
路径中不要包含空格、中文或特殊字符；
模型文件大小应符合当前 ais_bench 版本限制。

8. 命令行推理测试

使用 ais_bench 进行纯推理测试：

bash 复制代码

python3 -m ais_bench \
  --model weights/model.om \
  --output ./output \
  --loop 5

如果需要调试模式：

bash 复制代码

python3 -m ais_bench \
  --model weights/model.om \
  --output ./output \
  --debug 1 \
  --loop 1

输出中包含吞吐率、耗时等性能指标，可用于初步评估模型推理性能。

9. Python 接口推理测试

示例代码：

python 复制代码

import numpy as np
from ais_bench.infer.interface import InferSession

device_id = 0
model_path = "weights/model.om"

session = InferSession(device_id=device_id, model_path=model_path)

input_info = session.get_inputs()
print("Model input shape:", input_info[0].shape)

shape = input_info[0].shape
test_input = np.zeros(shape, dtype=np.float32)

outputs = session.infer([test_input], mode="static")
print("Output shape:", outputs[0].shape)

session.free_resource()

执行：

bash 复制代码

python3 test_infer.py

10. 离线环境安装说明

如果服务器无法访问外网，可在可联网机器上提前下载 whl 包，再拷贝到目标服务器安装。

在可联网机器上下载：

bash 复制代码

pip download attrs==24.3.0 --no-deps -d ./wheels
pip download aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl -d ./wheels
pip download ais_bench-0.0.2-py3-none-any.whl -d ./wheels

将 wheels 目录拷贝到目标服务器后执行：

bash 复制代码

cd wheels

pip3 install --no-index --find-links=. aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl
pip3 install --no-index --find-links=. ais_bench-0.0.2-py3-none-any.whl
pip3 install --no-index --find-links=. attrs-24.3.0-py3-none-any.whl

如果目标服务器已有旧版系统包导致安装不生效，可使用：

bash 复制代码

pip3 install --ignore-installed --no-index --find-links=. attrs-24.3.0-py3-none-any.whl

11. 安装完成检查清单

安装完成后，建议依次执行以下检查：

bash 复制代码

# 1. 检查 CANN 环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
echo $ASCEND_HOME

# 2. 检查 NPU 设备
npu-smi info

# 3. 检查 Python 版本
python3 --version

# 4. 检查已安装包
pip3 list | grep -E "aclruntime|ais_bench|attrs"

# 5. 检查 ais_bench CLI
python3 -m ais_bench --help

# 6. 检查 Python API
python3 -c "from ais_bench.infer.interface import InferSession; print('OK')"

全部通过即表示昇腾 OM 推理环境安装完成。