2、环境准备：搭建BM1684模型转换与推理的软件环境

BM1684是算能科技推出的第三代AI推理芯片，其软件栈的完整性与版本匹配度直接决定模型转换和推理的成败。本章聚焦于TPU-MLIR与BMNNSDK两大核心工具链的安装、配置与验证，帮助开发者建立一套可复现、可诊断的软件环境基线。我们将从工具链的组成与版本对应关系入手，逐步讲解安装流程、环境变量配置、验证方法，并通过一个典型的“从ONNX到BModel”的实战案例，展示环境问题如何被快速定位与解决。

上图展示了BM1684模型转换与推理环境的整体架构。左侧为主机开发环境，中间为模型转换链路，右侧为目标设备运行环境。整个流程中，TPU-MLIR负责将前端模型（ONNX/Caffe/TFLite）转换为MLIR中间表示，再通过量化与编译生成BModel；BMNNSDK则提供运行时库、驱动和工具，支撑BModel在BM1684上的高效推理。理解这一架构，是后续环境搭建与问题排查的基础。

2.1 工具链组成与版本对应关系

BM1684的软件栈主要由TPU-MLIR和BMNNSDK两大部分构成，二者分工明确、相互依赖。TPU-MLIR是模型转换与编译工具链，负责将ONNX、Caffe、TFLite等格式的模型转换为BM1684可执行的BModel文件；BMNNSDK则是运行时环境，包含驱动、运行时库（libbmrt）、推理API（sophon）以及调试工具（bmrt_test、bm_modelinfo等）。

版本匹配是环境搭建中最容易出错的一环。TPU-MLIR与BMNNSDK的版本必须与BM1684的固件（Firmware）版本兼容，否则会出现“模型转换成功但推理失败”或“驱动加载异常”等问题。下表列出了常见的版本组合与适用场景：

选择版本时，应优先参考算能官方发布的《版本兼容性矩阵》。若项目已有历史模型，建议保持与原有环境一致，避免因升级引入不确定性。

2.2 安装流程与关键步骤

环境安装推荐使用Docker方式，这能有效隔离系统依赖，避免污染宿主机环境。以下是基于Docker的安装流程：

1. 拉取官方镜像：从算能镜像仓库拉取包含TPU-MLIR和BMNNSDK的Docker镜像，例如 sophgo/tpucpp:latest。
2. 启动容器：使用 docker run 命令挂载工作目录，并映射设备节点（若需在容器内访问BM1684设备）。
3. 验证工具链：进入容器后，运行 model_transform.py --version 和 bmrt_test --help 确认工具可用。
4. 配置环境变量：将TPU-MLIR的 bin 目录和BMNNSDK的 lib 目录加入 PATH 和 LD_LIBRARY_PATH。

# 拉取镜像（示例）
docker pull sophgo/tpucpp:latest

# 启动容器并挂载工作目录
docker run -it --name bm1684_env \
  -v /home/user/projects:/workspace \
  -v /dev/bmdev:/dev/bmdev \
  --privileged \
  sophgo/tpucpp:latest /bin/bash

# 容器内验证
model_transform.py --version
bmrt_test --help

若在物理机上直接安装，需手动安装BMNNSDK的deb包，并确保内核模块 bmdev 已加载。安装完成后，使用 bm-smi 命令查看设备状态，确认驱动与固件版本。

2.3 环境验证与常见问题排查

环境验证是确保后续工作顺利进行的关键步骤。验证分为三个层次：工具链可用性、设备连通性、模型转换与推理的端到端验证。

• 工具链验证：运行 model_transform.py --version 和 bmrt_test --help，确认命令存在且能正常输出。
• 设备验证：执行 bm-smi 查看设备列表，确认BM1684芯片被正确识别，温度、显存等信息正常。
• 端到端验证：使用官方提供的示例模型（如ResNet50）完成一次完整的转换与推理，确保全链路畅通。

另一个高频问题是Python环境冲突。TPU-MLIR依赖特定版本的numpy、onnx等库，若与系统Python环境混用，可能出现“ImportError: libcudnn.so.8: cannot open shared object file”等错误。建议在Docker容器或虚拟环境中安装，避免污染全局环境。

2.4 实战案例：从ONNX到BModel的完整验证

本案例演示如何在一个全新的环境中，从零开始完成一个ONNX模型的转换与推理验证。该案例模拟了实际项目中“环境搭建后首次跑通模型”的典型场景。

背景与约束：开发团队刚收到一台配置了BM1684 PCIe卡的服务器，操作系统为Ubuntu 20.04，需要搭建环境并验证一个YOLOv5s的ONNX模型能否正常转换和推理。团队没有历史环境可参考，需从零开始。

初始现象：按照官方文档安装TPU-MLIR v1.6和BMNNSDK v4.0后，运行 model_transform.py 时报错：ModuleNotFoundError: No module named 'onnx'。

分析判断：该错误表明Python环境中缺少onnx库。进一步检查发现，系统默认的Python 3.8环境中安装了多个AI相关库，但版本混乱，且TPU-MLIR的依赖未完全安装。

实际操作步骤：

1. 创建独立的虚拟环境：python3 -m venv tpu_env，并激活。
2. 安装TPU-MLIR的依赖：pip install -r requirements.txt（从TPU-MLIR目录中获取）。
3. 重新运行转换命令，成功生成MLIR中间文件。
4. 执行 model_deploy.py 进行INT8量化，生成BModel。
5. 使用 bmrt_test 加载BModel，输入随机数据，验证推理输出shape与数值范围。

结果对比：修复前，转换在第一步即失败；修复后，整个流程在10分钟内完成，推理输出与PyTorch参考结果的平均相对误差小于1%。

风险与代价：虚拟环境隔离了依赖，但后续若需使用sophon Python API，需在同一个虚拟环境中安装BMNNSDK的Python包，否则会出现“找不到libbmrt.so”的运行时错误。

复盘经验：环境搭建时，应优先使用官方Docker镜像，避免手动安装依赖带来的版本冲突。若必须手动安装，务必使用虚拟环境，并记录所有安装步骤，便于复现。

2.5 环境配置清单与总结

为了帮助开发者快速搭建可复现的环境，下表总结了关键配置项及其推荐值：

环境搭建是模型兼容性排查的第一道防线。一个干净、版本匹配的环境能避免大量无谓的调试时间。建议在项目启动初期，就建立环境基线文档，记录所有组件的版本号、安装路径和验证命令，为后续的模型转换与推理提供稳定的基础。