适用场景：昇腾 Ascend310P3 / aarch64 / Ubuntu 22.04 / Python 3.10 / CANN 8.x+ / ATC 模型转换 / ais_bench 推理 本文档按”从零到跑通”顺序编写，所有命令可直接在服务器上复制执行。 文档中涉及的路径、账号、IP 均为通用占位，部署时请按实际环境替换。

1. 环境适配检查

在开始安装前，先确认服务器基础条件是否满足。

1.1 检查 NPU 驱动与固件

npu-smi info

正常输出应包含 NPU 型号、Health 状态、芯片信息等。如果命令不存在，说明 NPU 驱动未安装，需要先安装驱动和固件。

1.2 检查 CPU 架构

uname -m

• aarch64：ARM 架构，选择 linux-aarch64 安装包
• x86_64：x86 架构，选择 linux-x86_64 安装包

1.3 检查 Python 环境

python3 --version
pip3 --version

CANN 8.x 系列支持 Python 3.7.x ~ 3.11.4，Python 3.10 可用。

1.4 检查磁盘空间

df -h /usr/local/Ascend

CANN Toolkit 安装目录需要至少 10GB 可用空间。

2. 下载 CANN Toolkit

前往昇腾社区下载页面，选择与 NPU 型号和 CPU 架构匹配的软件包：

• 昇腾社区资源下载：https://www.hiascend.com/software/cann/community
• 驱动与固件：https://www.hiascend.com/hardware/firmware-drivers/community

需要下载的软件包（以 aarch64 为例）：

软件包	用途	是否必须
Ascend-hdk-310p-npu-driver_*.run	NPU 驱动	未装驱动时必须
Ascend-hdk-310p-npu-firmware_*.run	NPU 固件	未装固件时必须
Ascend-cann-toolkit_*.run	CANN 开发套件（含 ATC）	必须
Ascend-cann-310p-ops_*.run	芯片算子包	必须
Ascend-cann-nnal_*.run	NNAL 神经网络加速库	可选

注意：驱动和固件安装后需要重启服务器，CANN 包安装不需要重启。

3. 安装 NPU 驱动与固件（如未安装）

如果 npu-smi info 已能正常输出，可跳过此节。

# 赋予执行权限

chmod +x Ascend-hdk-310p-npu-driver_*.run
chmod +x Ascend-hdk-310p-npu-firmware_*.run

# 安装驱动

./Ascend-hdk-310p-npu-driver_*.run --full --install-for-all

# 安装固件

./Ascend-hdk-310p-npu-firmware_*.run --full --install-for-all

# 重启服务器

reboot

重启后再次执行 npu-smi info 确认驱动加载正常。

4. 安装 CANN Toolkit

4.1 安装 Toolkit

# 赋予执行权限
chmod +x Ascend-cann-toolkit_*.run

# 安装（默认路径 /usr/local/Ascend）
./Ascend-cann-toolkit_*.run --install

如需指定安装路径：

./Ascend-cann-toolkit_*.run --install --install-path=/opt/Ascend

4.2 安装芯片算子包

chmod +x Ascend-cann-310p-ops_*.run
./Ascend-cann-310p-ops_*.run --install

4.3 安装 NNAL 加速库（可选）

chmod +x Ascend-cann-nnal_*.run
./Ascend-cann-nnal_*.run --install

4.4 配置环境变量

# 当前会话生效
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 永久生效
echo 'source /usr/local/Ascend/ascend-toolkit/set_env.sh' >> ~/.bashrc
source ~/.bashrc

如果安装了 NNAL，还需额外加载：

source /usr/local/Ascend/nnal/atb/set_env.sh

建议将两条 source 都写入 ~/.bashrc。

4.5 验证安装

# 检查环境变量
echo $ASCEND_HOME

# 检查 ATC 工具
atc --version

# 检查 NPU 设备
npu-smi info

5. 安装 ATC 模型转换 Python 依赖

ATC 工具依赖一组 Python 第三方库，缺少会导致 ModuleNotFoundError。

5.1 在线安装（服务器可访问外网）

pip3 install attrs cython 'numpy>=1.19.2,<=1.24.0' decorator sympy cffi \
  pyyaml pathlib2 psutil 'protobuf==3.20.0' scipy requests absl-py

5.2 离线安装（服务器无外网）

在可联网的机器上下载 whl 包：

mkdir cann-deps && cd cann-deps

pip3 download attrs cython 'numpy>=1.19.2,<=1.24.0' decorator sympy cffi \
  pyyaml pathlib2 psutil 'protobuf==3.20.0' scipy requests absl-py \
  -d . -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：如果目标服务器是 aarch64，下载含 C 扩展的包（如 cffi、numpy）时需指定平台：

pip3 download cffi numpy --no-deps -d . \
  --platform manylinux2014_aarch64 --python-version 310 --only-binary=:all: \
  -i https:

将 cann-deps 目录拷贝到目标服务器后执行：

cd cann-deps
python3 -m pip install --no-index --find-links=. *.whl

5.3 验证依赖

python3 -c "import decorator, sympy, cffi, numpy, protobuf; print('deps ok')"

6. 使用 ATC 转换 ONNX 模型为 OM

6.1 准备 ONNX 模型

将训练好的模型导出为 ONNX 格式，例如 model.onnx。

6.2 执行转换

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

atc --model=model.onnx \
    --framework=5 \
    --output=model_out \
    --input_format=NCHW \
    --input_shape="images:1,3,640,640" \
    --precision_mode=force_fp32 \
    --soc_version=Ascend310P3

参数说明：

参数	说明
--model	输入 ONNX 模型路径
--framework=5	输入框架为 ONNX
--output	输出 OM 文件路径前缀（不带 .om）
--input_format	输入数据格式，常用 NCHW
--input_shape	输入张量名称和形状，需与 ONNX 一致
--precision_mode	精度模式，force_fp32 表示强制 FP32
--soc_version	目标芯片版本，需与 npu-smi info 一致

转换成功后会在当前目录生成 model_out.om。

6.3 查看 OM 模型信息

atc --mode=1 --om=model_out.om

7. 安装推理工具 aclruntime 与 ais_bench

ais_bench 是昇腾 OM 离线模型推理评测工具，依赖 aclruntime 底层库。

7.1 在线安装

pip3 install https://aisbench.obs.myhuaweicloud.com/packet/ais_bench_infer/0.0.2/ait/aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl
pip3 install https://aisbench.obs.myhuaweicloud.com/packet/ais_bench_infer/0.0.2/ait/ais_bench-0.0.2-py3-none-any.whl

7.2 离线安装

在可联网机器上下载：

wget https://aisbench.obs.myhuaweicloud.com/packet/ais_bench_infer/0.0.2/ait/aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl
wget https://aisbench.obs.myhuaweicloud.com/packet/ais_bench_infer/0.0.2/ait/ais_bench-0.0.2-py3-none-any.whl

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

pip3 install aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl
pip3 install ais_bench-0.0.2-py3-none-any.whl

7.3 验证安装

python3 -m ais_bench --help

能输出帮助信息即表示安装成功。

8. OM 模型文件权限配置

ais_bench 加载 OM 模型时会进行安全检查，要求运行用户与模型文件属主/属组匹配，且文件权限不能过宽。

8.1 确认当前运行用户

whoami

8.2 确认模型文件属主

ls -lh weights/model.om

8.3 修改文件属主

# 将模型文件属主改为当前运行用户
chown root:root weights/model.om

# 如果项目中有多个 OM 文件，可递归修改
chown -R root:root weights/

8.4 修改文件权限

# OM 模型文件设为 644（属主读写，组和其他只读）
chmod 644 weights/model.om

# 目录设为 755
chmod 755 weights/

# 批量修正目录下所有 .om 文件
find weights/ -name "*.om" -exec chmod 644 {} \;

修改后确认：

ls -lh weights/model.om

期望输出：-rw-r--r-- 1 root root ... model.om

9. 命令行推理测试

9.1 纯推理性能测试

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

不指定 --input 时，工具自动构造全 0 数据进行纯推理，用于测试吞吐和时延。

9.2 调试模式

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

开启 --debug 1 会打印模型输入输出参数、详细耗时等信息。

9.3 使用真实输入数据

python3 -m ais_bench \
  --model weights/model.om \
  --input ./test_data \
  --output ./output \
  --outfmt BIN \
  --loop 5

输入数据支持 NPY / BIN 格式，多输入用逗号分隔。

10. 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()

执行：

python3 test_infer.py

11. 安装完成检查清单

依次执行以下命令，全部通过即可开始模型转换与推理部署：

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

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

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

# 4. 检查 Python 依赖
python3 -c "import decorator, sympy, cffi, numpy, protobuf; print('deps ok')"

# 5. 检查 ATC 工具
atc --version

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

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

# 8. 检查 OM 文件权限
ls -lh weights/model.om

# 9. 检查推理接口
python3 -c "from ais_bench.infer.interface import InferSession; print('OK')"

12. 常见问题速查

现象	原因	解决
atc: command not found	CANN 环境变量未加载	source /usr/local/Ascend/ascend-toolkit/set_env.sh
No module named 'decorator'	ATC Python 依赖缺失	按第 5 节补齐依赖
No module named 'tbe'	TBE 算子库未正确加载	确认已安装 ops 包并 source 环境变量
file owner or ownergroup error	运行用户与 OM 文件属主不匹配	chown 修改属主
permission should not be over 0o755	OM 文件权限过宽	chmod 644 模型文件
soc_version not found	芯片版本写错	用 npu-smi info 确认实际型号