系列编排日期为 2026 年 8 月；技术基线核对与教学代码 CPU 验证日期为 2026-10-12。适用 Hi3516CV610 与本系列注明的 SDK/工具版本，实测范围见第 12 章。
返回系列目录 · 本篇属于 12 章与 4 份附录。
转换环境的第一项任务是固定工具链。主机能执行 atc 并不代表调用了本项目所需的版本；Python、共享库和环境变量也可能来自另一套安装。
文档与项目入口
先读《驱动和开发环境安装指南》的主机环境和安装章节，再读《ATC工具使用指南》2.1.1、2.1.2。项目把容器封装放在：
|
它与工具包内原有 Docker 示例是两套入口。项目 CPU 镜像使用 Ubuntu 22.04，准备了 PyTorch 2.1.0+cpu、torchvision 0.16.0 的 Python 3.10 安装包，并固定安装 ultralytics 8.2.103。这些是当前构建脚本的配置，不代表任意宿主机或未来重新构建镜像已经具备相同环境。
准备资源和构建镜像
以下命令在项目根目录执行，要求已安装 Docker，并拥有本项目 SDK 和工具包。
|
缺少可下载资源时，先阅读脚本的资源清单，再按其支持方式使用 --download。下载、解压和构建都可能占用较大空间。不要把“准备资源”理解为只读检查。
PrepareResources.sh 对已经解压的 SVP 包使用 cp -al：目标与源文件可能共享同一个 inode。直接改 Resources 内文件可能同时改变原工具包；需要修改的实验配置放在独立目录，需要独立副本时使用普通复制。
默认镜像名为 hi3516cv610-svp-model-convert:cpu。Run.sh 把项目根目录挂到 /workspace，容器初始工作目录是 /workspace/SDK/Tools/Npu。博客代码下载后应复制到项目内部，容器才能从 /workspace/... 访问。宿主机的 /home/某用户/... 不会自动出现在容器内。
显式加载环境并核对工具
进入容器后先执行：
|
svp_latest 是安装版本入口，必须记录它实际指向的位置。非交互式 bash 不保证读取交互式启动文件，因此自动化脚本也要显式 source。若脚本启用 set -u，可以在加载厂商环境后再打开，避免厂商脚本读取未定义变量而意外退出。
为每次实验保存环境证据：
|
若 command -v atc 指向脚本而非 ELF，ldd 可能提示不是动态可执行文件，此时应继续定位该脚本实际调用的二进制。检查中出现 not found 时先修动态库加载，不要用随机软链接把另一版本的库接进来。
区分导出环境和转换环境
训练工程可能依赖新版本 PyTorch，而 ATC 对自己的 Python 和库有固定要求。可以在训练环境导出 ONNX，在转换容器内只运行 ATC；二者通过模型文件、模型卡和样本基准衔接。不要为了安装训练依赖升级转换容器中的全部包。
本系列教学脚本的 CPU 验证环境实际为 NumPy 2.3.5、OpenCV 5.0.0、ONNX 1.22.0、ONNX Runtime 1.28.0。它们是本次宿主机验证记录，与上面的厂商转换容器版本不同。教学脚本产生的是 ONNX、PNG、二进制和 NPZ，ATC 不需要导入教学脚本使用的 ORT。
离线环境可用已下载且校验过的 wheel 建立单独虚拟环境。保留包清单、Python 版本和 wheel 来源，避免文档只写一句 pip install -U，导致日后无法解释行为变化。
环境验收和常见故障
环境验收应包括 atc --version 成功、目标工具路径正确、模型和校准路径在容器中可读、输出目录可写，以及官方最小样例能够运行。实际模型转换还需检查目标芯片与算子限制。
找不到 atc 时检查是否 source；找不到 .so 时检查工具版本与 LD_LIBRARY_PATH；图像不存在时在容器中检查清单中的每个路径；权限失败时检查挂载目录 UID/GID 和写权限；Python import 失败时确认所用解释器。不要先更换模型来掩盖环境问题。