2. 环境准备
在开始任何模型转换与部署工作之前，搭建一套可靠、版本匹配的TPU开发环境是整个项目的地基。算能（Sophgo）的TPU（如BM1684X、BM1688、CV186X等）与NVIDIA GPU的CUDA生态不同，其工具链、运行时库（libsophon）、交叉编译工具链以及目标板端的系统镜像必须严格对应。本章将围绕“工具链安装”、“交叉编译环境配置”和“开发板连接验证”三个核心环节展开，帮助您从零构建一套可用的算能TPU开发环境，并规避最常见的版本错配与连接故障。
上图展示了完整的开发环境拓扑：PC端负责模型转换与交叉编译，目标板负责推理执行，两者之间通过SSH/SCP或USB/串口进行连接。下面我们按照实际操作顺序，逐步完成环境搭建。
2.1 安装算能TPU工具链：tpu-mlir与bmnet的选择与安装
核心原理：算能TPU的模型转换工具链经历了从旧版bmnet到新版tpu-mlir的演进。bmnet是早期基于Caffe/TensorFlow的转换工具，而tpu-mlir是基于MLIR（Multi-Level Intermediate Representation）的下一代编译器，支持更广泛的模型格式（ONNX、PyTorch、TFLite等），并提供了更精细的量化控制。对于新项目，强烈建议直接使用tpu-mlir；仅当维护遗留的bmnet工程时才考虑旧工具链。
操作流程：以tpu-mlir为例，安装步骤如下：
- 获取工具链：从算能官方资源（GitHub Release或百度网盘）下载与目标芯片匹配的
tpu-mlir_xxx.tar.gz。注意区分BM1684X、BM1688、CV186X等不同芯片版本。 - 解压与环境变量：将压缩包解压至
/opt/tpu-mlir，并设置环境变量：
# 解压
mkdir -p /opt/tpu-mlir
tar -zxvf tpu-mlir_v1.8.0_xxx.tar.gz -C /opt/tpu-mlir
# 设置环境变量（建议写入 ~/.bashrc）
export TPU_MLIR_HOME=/opt/tpu-mlir
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- 验证安装：运行
model_transform --version，若显示版本号则安装成功。
conda create -n tpu python=3.8），避免与系统Python环境冲突。同时，务必记录工具链版本号，后续板端libsophon版本必须与其严格对应。
2.2 配置交叉编译环境：从PC到ARM64目标板
核心原理：算能TPU目标板（如SE5、SM5、R1等）通常运行ARM64架构的Linux系统，而开发PC多为x86_64架构。为了在PC上编译出可在板端运行的C++推理程序，必须使用交叉编译工具链（aarch64-linux-gnu-g++）。同时，需要将板端运行时库（libsophon）的头文件和动态库同步到PC端，供编译时链接。
操作流程：
- 安装交叉编译工具链：在Ubuntu PC上执行：
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu- 获取libsophon：从算能官网下载与板端系统镜像匹配的
libsophon_xxx_aarch64.tar.gz。解压后，目录结构通常包含include（头文件）和lib（动态库）。 - 配置CMake工具链文件：创建
aarch64-linux-gnu.cmake文件，内容示例如下：
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_FIND_ROOT_PATH /opt/sophon/libsophon_aarch64)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)- 编译测试程序：编写一个简单的
main.cpp，调用bmrt.h接口，使用交叉编译工具链编译，确认无链接错误。
CMAKE_FIND_ROOT_PATH指向的libsophon路径正确，且板端系统镜像的Linux内核版本与libsophon驱动版本兼容。若板端无法加载bmodel，优先检查bmrt_get_version()返回的运行时版本是否与编译时一致。
2.3 验证开发板与PC连接：网络、SSH与文件传输
核心原理：开发板与PC的连接是部署工作的物理基础。通常使用以太网（千兆/百兆）连接，配置静态IP或DHCP，通过SSH进行远程操作，通过SCP或SFTP传输bmodel文件和编译好的可执行程序。部分开发板（如SE5）还支持USB OTG或串口调试，但网络连接是最常用、最稳定的方式。
操作流程：
- 物理连接：使用网线将开发板网口与PC直连，或接入同一交换机/路由器。
- 配置IP地址：开发板默认IP通常为
192.168.1.10（以SE5为例），PC端配置同网段静态IP，如192.168.1.100。 - 测试连通性：在PC端执行
ping 192.168.1.10，确认网络通畅。 - SSH登录：执行
ssh root@192.168.1.10，默认密码通常为admin或123456（具体见产品文档）。 - 验证TPU设备：登录板端后，执行
bm-smi命令，查看TPU芯片状态、温度、显存使用情况。若能看到芯片信息，说明驱动和固件正常。
bm-smi无法显示芯片信息。排查过程：首先dmesg | grep bm查看内核日志，发现驱动加载失败；进一步检查发现板端/lib/modules/下的驱动版本与镜像不匹配。重新刷入匹配的驱动后，bm-smi正常显示。复盘经验：工具链、libsophon、板端驱动三者版本必须形成“铁三角”对应关系，任何一环不一致都会导致部署失败。
2.4 常见误区与总结复盘
| 误区/问题 | 现象 | 正确做法 |
|---|---|---|
| 工具链版本与芯片不匹配 | model_transform报错“Unsupported chip” | 确认tpu-mlir版本支持目标芯片（如BM1684X需v1.6+） |
| 交叉编译时链接了x86库 | 编译通过，但板端运行报“cannot open shared object file” | 检查CMake中CMAKE_FIND_ROOT_PATH设置，确保只链接aarch64库 |
| 板端IP冲突或无法ping通 | SSH连接超时 | 检查网线、交换机端口，使用串口登录板端查看IP配置 |
| 忽略libsophon版本 | 板端加载bmodel失败，报“version mismatch” | 严格匹配tpu-mlir与libsophon的版本号（如v1.8.0对应v1.8.0） |
总结复盘：环境准备的核心是“版本一致性”和“路径正确性”。建议在项目启动初期，就建立一份环境清单，记录PC端工具链版本、libsophon版本、板端镜像版本、交叉编译工具链版本，并验证一次完整的“模型转换→交叉编译→板端运行”流程。这个基础流程一旦跑通，后续的模型部署工作将事半功倍。同时，务必保存好envsetup.sh的source操作，避免每次打开终端都重复配置环境变量。