2. 环境准备
算能AI盒子（如SM5、SM7、SM8系列）作为边缘端目标检测推理设备，其核心价值在于将YOLO模型高效部署到TPU（张量处理单元）上运行。在开始模型转换与性能测试之前，必须完成一套严谨的环境准备流程。本章将围绕硬件规格认知、开发环境搭建、TPU-MLIR工具链安装以及依赖库与驱动配置四个核心模块展开，帮助开发者建立从“裸机”到“可运行YOLO模型”的完整工程链路。环境准备的质量直接决定了后续模型转换的成败与推理性能的上限，任何驱动版本不匹配或工具链配置错误，都可能导致模型编译失败或NPU资源无法充分利用。
上图展示了环境准备的整体架构与依赖关系。硬件规格决定了工具链版本的选择，而工具链与驱动之间又存在严格的版本匹配要求。下面我们将逐一深入每个环节，确保每一步都做到可验证、可复现。
2.1 算能AI盒子硬件规格深度解析
算能AI盒子（以SM5系列为例）的核心是BM1684X芯片，这是一颗专门为边缘计算设计的SoC，集成了TPU、CPU、ISP和编解码单元。在准备环境前，必须明确以下关键规格：
- TPU算力： SM5提供8 TOPS INT8算力，SM7提供16 TOPS，SM8则达到32 TOPS。对于YOLOv5s/YOLOv8s这类模型，SM5即可实现实时推理（>30 FPS），但若需同时处理多路视频流，建议选择SM7以上。
- 内存带宽： LPDDR4x 8GB，带宽约51.2GB/s。这个参数直接影响YOLO模型在NMS（非极大值抑制）阶段的性能，因为NMS需要频繁访问特征图数据。
- 编解码能力： 支持H.264/H.265硬件编解码，最高支持32路1080P@30fps解码。这意味着在部署YOLO检测时，可以将视频解码任务卸载到硬件，释放TPU资源。
- 网络接口： 双千兆以太网口，支持RGMII和SGMII模式。在多设备级联或分布式推理场景中，网络带宽是瓶颈点之一。
cat /sys/class/bm-tpu/bm-tpu0/freq查看当前频率，正常应为1.5GHz。若频率异常，需联系厂商更新固件。
2.2 开发环境搭建：主机侧与设备侧
开发环境分为主机侧（用于模型转换和交叉编译）和设备侧（AI盒子本体）。主机侧推荐使用Ubuntu 20.04 LTS x86_64系统，内存不低于16GB，硬盘剩余空间不少于50GB（用于存放数据集和中间模型）。设备侧则使用算能官方提供的Debian 11系统镜像。
主机侧环境搭建的核心步骤如下：
- 安装基础依赖：
sudo apt update && sudo apt install -y python3-pip git cmake libssl-dev - 创建Python虚拟环境：
python3 -m venv ~/venv/tpu-mlir && source ~/venv/tpu-mlir/bin/activate - 安装PyTorch与ONNX：
pip install torch==1.13.0 onnx==1.12.0 onnxsim（注意版本必须严格匹配，否则后续模型转换可能报算子不支持错误） - 安装OpenCV：
pip install opencv-python-headless==4.5.5.64（用于后续测试脚本中的图像预处理）
设备侧环境搭建则相对简单，只需将官方镜像烧录至eMMC或SD卡，然后通过串口或SSH登录。首次登录后建议执行sudo apt update && sudo apt upgrade，并安装tree、htop等常用工具。
sophgo/tpuc_dev:latest镜像，该镜像已预置所有依赖，可避免大量环境配置问题。
2.3 TPU-MLIR工具链安装与验证
TPU-MLIR是算能提供的模型转换工具链，负责将ONNX/TorchScript模型转换为TPU可执行的bmodel格式。安装过程分为三步：获取安装包、解压配置、验证安装。
# 1. 获取工具链（以v1.6.0为例）
wget https://github.com/sophgo/tpu-mlir/releases/download/v1.6.0/tpu-mlir_v1.6.0.tar.gz
tar -xzf tpu-mlir_v1.6.0.tar.gz
cd tpu-mlir_v1.6.0
# 2. 设置环境变量（建议写入~/.bashrc）
export TPU_MLIR_HOME=$(pwd)
export PATH=$TPU_MLIR_HOME/bin:$PATH
export LD_LIBRARY_PATH=$TPU_MLIR_HOME/lib:$LD_LIBRARY_PATH
source $TPU_MLIR_HOME/scripts/envsetup.sh
# 3. 验证安装
model_transform --version
# 预期输出：TPU-MLIR version 1.6.0 (build 20240101)验证过程中，如果出现libstdc++.so.6: version 'GLIBCXX_3.4.29' not found错误，说明系统gcc版本过旧。解决方案是安装较新的gcc：sudo apt install gcc-9 g++-9，并设置export CC=gcc-9 CXX=g++-9。
| 工具链组件 | 功能说明 | 验证命令 |
|---|---|---|
| model_transform | 将ONNX模型转换为MLIR中间表示 | model_transform --version |
| model_deploy | 将MLIR转换为bmodel并量化 | model_deploy --help |
| tpuc-opt | MLIR优化与算子融合 | tpuc-opt --version |
| tpuc-translate | MLIR到TPU指令的翻译 | tpuc-translate --help |
2.4 依赖库与驱动配置：确保运行时稳定
驱动和依赖库是AI盒子运行bmodel的基础。算能提供统一的驱动安装包sophon-driver和运行时库libsophon。安装时需注意版本必须与TPU-MLIR版本匹配，否则会出现算子执行错误或内存分配失败。
# 安装驱动（设备侧执行）
wget https://sophon-file.sophon.cn/sophon-prod-s3/drive/23_08_01_16/sophon-driver_3.1.0_amd64.deb
sudo dpkg -i sophon-driver_3.1.0_amd64.deb
# 安装运行时库
wget https://sophon-file.sophon.cn/sophon-prod-s3/drive/23_08_01_16/libsophon_3.1.0_amd64.deb
sudo dpkg -i libsophon_3.1.0_amd64.deb
# 验证驱动是否加载成功
ls /dev/bm* # 应看到 /dev/bm1684x 设备节点
bm-smi # 查看TPU温度、利用率、内存占用依赖库方面，除了libsophon自带的库外，还需安装以下系统库：libgomp1（OpenMP支持）、libopencv-dev（图像处理）、libjson-c-dev（配置文件解析）。这些库可通过sudo apt install -y libgomp1 libopencv-dev libjson-c-dev一键安装。
某项目组在SM5盒子上部署YOLOv8s模型，模型转换成功，但运行时出现
BM_RUNTIME_ERROR: unsupported op错误。排查过程：1. 使用
bm-smi确认驱动版本为3.0.1，而TPU-MLIR版本为1.6.0（要求驱动≥3.1.0）；2. 升级驱动至3.1.0后，错误消失，推理正常。
复盘：工具链与驱动版本必须严格对应，建议在项目启动时记录版本号，并写入
requirements.txt或version.md中。
2.5 常见误区与总结复盘
在环境准备阶段，开发者常犯以下错误：
- 误区一： 在Windows或macOS上进行模型转换。TPU-MLIR仅支持Linux环境，且部分算子优化依赖GCC特性，非Linux环境会导致不可预知的错误。
- 误区二： 忽略
LD_LIBRARY_PATH设置。在运行bmodel时，若找不到libbm1684x.so，会报cannot open shared object file错误。建议将export LD_LIBRARY_PATH=/opt/sophon/libsophon-current/lib:$LD_LIBRARY_PATH写入/etc/profile。 - 误区三： 使用过高版本的PyTorch导出ONNX。PyTorch 2.0+导出的ONNX可能包含新算子（如
aten::scaled_dot_product_attention），TPU-MLIR v1.6.0尚不支持，需使用onnxsim简化或手动替换算子。
总结： 环境准备的核心是“版本匹配”与“可验证性”。建议在项目初始化时，编写一个setup.sh脚本，将上述所有安装步骤固化，并在脚本末尾输出版本信息。这样不仅便于团队协作，也能在后续排障时快速定位问题。完成本章环境准备后，即可进入YOLO模型转换环节，届时所有工具链和驱动将协同工作，为高效推理奠定基础。