3. 环境准备
地平线模型转换流程对运行环境有较强的约束：它并不是一个“装完 Python 包就能跑”的纯软件工具，而是由 Python 转换前端、模型编译工具链、量化校准依赖 与 目标芯片运行时 共同组成的链路。环境准备的目标，是让这四层在同一台开发机上形成一致的版本组合，从而保证 ONNX 模型能够顺利经过解析、量化、编译，最终产出可部署的 .hbm 或 .bin 模型。
一、核心原理：环境是一条“版本对齐链”
模型转换失败，绝大多数原因并不在模型本身，而在环境版本错位。地平线工具链的各个组件之间存在明确的依赖方向：
- 操作系统层：官方推荐 Ubuntu 20.04 LTS，内核与 glibc 版本会影响工具链二进制能否加载。
- Python 层：转换脚本依赖 Python 3.8/3.10，且
numpy、onnx、torch版本需与工具链内部接口匹配。 - 工具链层：
hb_mapper、hb_model_verifier、hb_compile等命令由 OpenExplorer 工具包提供，版本号必须与芯片平台（如 X3、J5、征程 5）对应。 - 运行时层：板端
libhbucp、libhbrt与编译产物必须同源，否则模型加载会报版本不匹配。
因此，环境准备的本质不是“装软件”，而是锁定一套经过验证的版本组合，并让它在开发机与板端保持一致。
二、方法流程：从零搭建可复现环境
推荐使用 Conda 虚拟环境 + 官方 Docker 镜像 双轨策略：日常调试用 Conda，保证依赖干净；批量转换或交付时用 Docker，保证环境可复现。
# 1. 创建独立虚拟环境
conda create -n horizon_oe python=3.8 -y
conda activate horizon_oe
# 2. 安装基础依赖（版本需与工具链文档一致）
pip install numpy==1.23.5 onnx==1.12.0 onnxruntime==1.14.1
pip install torch==1.13.1 torchvision==0.14.1 --index-url https://download.pytorch.org/whl/cpu
pip install opencv-python==4.8.0.74 pyyaml tqdm
# 3. 获取并安装 OpenExplorer 工具链
tar -xzf horizon_j5_openexplorer_v1.2.8.tar.gz
cd horizon_j5_openexplorer_v1.2.8
bash install.sh --install-path /opt/horizon
# 4. 配置环境变量
export PATH=/opt/horizon/bin:$PATH
export LD_LIBRARY_PATH=/opt/horizon/lib:$LD_LIBRARY_PATH
# 5. 验证工具链可用性
hb_mapper --version
hb_model_verifier --help安装完成后，务必执行一次“最小闭环验证”：用一个已知可转换的 ONNX 模型跑通 hb_mapper 全流程，确认解析、量化、编译、验证四个阶段均无报错，再进入正式项目。
三、版本匹配对照表
| 组件 | 推荐版本 | 匹配对象 | 错配后果 |
|---|---|---|---|
| Ubuntu | 20.04 LTS | 工具链二进制 | glibc 报错，命令无法启动 |
| Python | 3.8 / 3.10 | hb_mapper 前端 | 语法或 C 扩展加载失败 |
| numpy | 1.23.x | 量化校准模块 | 数组接口不兼容，量化中断 |
| onnx | 1.12.0 | 模型解析器 | 算子解析失败或图结构误读 |
| OpenExplorer | 与芯片平台一致 | 目标芯片 | 编译产物无法在板端加载 |
| 板端运行时 | 与工具链同源 | 编译产物 | 模型加载报版本不匹配 |
四、常见环境问题与排障
典型误区：很多开发者认为“只要 pip install 成功，环境就没问题”。实际上，工具链的二进制命令依赖系统级动态库，pip 无法覆盖这部分依赖，必须通过官方安装脚本或 Docker 镜像解决。
- 问题一：
hb_mapper: command not found—— 环境变量未生效。检查PATH是否包含工具链bin目录，并确认安装脚本执行时没有中途报错。 - 问题二：
ImportError: libxxx.so not found—— 动态库缺失。使用ldd检查命令依赖，补齐LD_LIBRARY_PATH或安装对应系统库。 - 问题三：量化阶段报
numpy version mismatch—— 虚拟环境中存在多个 numpy 版本。用pip list | grep numpy确认，必要时重建环境。 - 问题四：编译成功但板端加载失败 —— 工具链与板端运行时不同源。核对两者版本号，重新获取匹配的运行时库。
- 问题五：ONNX 解析报未知算子 —— 并非环境问题，而是算子集版本过高。可尝试降低
opset或使用工具链支持的算子替换。
复盘建议：把环境搭建过程写成
setup.sh 脚本并纳入版本管理，记录每个依赖的确切版本号。这样在新机器或团队协作时，可以一键复现，避免“我这能跑，你那不行”的经典问题。
环境准备完成后，建议立即执行一次 hb_mapper --version 与 hb_model_verifier --help 的双重确认，并保存输出日志作为环境基线。只有环境基线稳定，后续的模型解析、量化校准与编译部署才具备可重复性，模型转换流程才能真正进入可控状态。