📚 课程目录第2章环境搭建

2. 环境搭建

在将ONNX模型部署到Intel硬件之前，首要任务是搭建一套干净、可复现的OpenVINO开发环境。很多初学者在这一步就遇到挫折，往往是因为混淆了OpenVINO Runtime与OpenVINO Development Tools的职责边界。Runtime是运行推理时必需的轻量级库，而Development Tools则包含模型优化器（Model Optimizer）、基准测试工具等开发辅助组件。对于需要将ONNX转换为IR格式的开发者，两者缺一不可。

核心原理：理解OpenVINO的组件分层

OpenVINO工具套件采用分层架构设计，其核心思想是将“模型优化”与“运行时推理”解耦。当你从ONNX格式出发时，首先经过模型优化器（Model Optimizer）完成图级别转换，生成中间表示（IR）文件（.xml与.bin），随后由推理引擎（Inference Engine）加载IR并调度到不同硬件插件（CPU、GPU、NPU等）。这一设计使得同一份IR可以在多种Intel硬件上无缝迁移，而无需重新转换模型。

关键认知：ONNX模型并非直接由OpenVINO Runtime读取，而是必须先经过模型优化器转换。Runtime只消费IR格式或ONNX格式（从2022.3版本起Runtime支持直接读取ONNX，但推荐使用IR以获得最佳性能）。

方法流程：三步完成环境搭建

以下流程以Python 3.9～3.12 + Windows/Linux为基准，使用虚拟环境隔离项目依赖，避免与系统Python包产生冲突。

第一步：创建并激活Python虚拟环境

# Windows PowerShell
python -m venv ov_env
ov_env\Scripts\activate

# Linux / macOS
python3 -m venv ov_env
source ov_env/bin/activate

建议：始终使用虚拟环境。OpenVINO依赖的numpy、networkx等库版本较敏感，全局安装容易导致其他项目出现依赖冲突。

第二步：安装OpenVINO工具套件

从2022.3版本开始，官方推荐使用pip直接安装，无需额外配置APT或YUM仓库。核心命令如下：

# 安装完整工具套件（含Runtime + Development Tools）
pip install openvino openvino-dev

# 如需指定版本（例如2024.3.0）
pip install openvino==2024.3.0 openvino-dev==2024.3.0

安装完成后，可通过pip list检查关键包是否就位。下表列出了核心组件及其作用：

包名	版本示例	作用说明
openvino	2024.3.0	运行时库，包含推理引擎与CPU/GPU插件
openvino-dev	2024.3.0	开发工具，含模型优化器、精度检查工具、benchmark_app
onnx	1.16.0	ONNX模型解析与导出（openvino-dev自动依赖）
numpy	1.26.4	数值计算基础库，OpenVINO的Python API依赖

第三步：验证安装是否成功

运行以下Python脚本，确认核心API可用且能识别当前硬件设备：

from openvino.runtime import Core

# 初始化Core对象
core = Core()

# 查询可用设备
print("可用设备:", core.available_devices)

# 检查特定设备是否可用
if "CPU" in core.available_devices:
    print("✅ CPU设备就绪")
else:
    print("❌ CPU设备未找到")

# 查看OpenVINO版本
print("OpenVINO版本:", core.get_versions("CPU")["CPU"].major,
      core.get_versions("CPU")["CPU"].minor)

预期输出示例：

可用设备: ['CPU']
✅ CPU设备就绪
OpenVINO版本: 2024 3

注意：如果输出中出现ModuleNotFoundError: No module named 'openvino'，请确认当前激活的虚拟环境是否正确，并检查pip list中是否包含openvino包。切勿使用sudo pip install（Linux）或管理员PowerShell（Windows）安装到系统Python。

案例/场景：从ONNX到IR的首次转换验证

环境搭建完成后，建议立即用一个最小ONNX模型验证工具链的完整性。以下示例使用一个随机初始化的简单模型，通过mo命令完成转换：

# 生成一个简单的ONNX模型（Python脚本）
import torch
import torch.onnx

# 定义一个线性层模型
class LinearModel(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = torch.nn.Linear(4, 2)

    def forward(self, x):
        return self.fc(x)

model = LinearModel()
dummy_input = torch.randn(1, 4)
torch.onnx.export(model, dummy_input, "linear_model.onnx",
                  input_names=["input"], output_names=["output"],
                  dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}})
print("ONNX模型已生成")

随后在命令行执行模型优化器转换：

mo --input_model linear_model.onnx --output_dir ./ir_model

转换成功后，ir_model目录下会出现linear_model.xml与linear_model.bin两个文件。此时再通过Runtime加载IR并执行一次推理：

from openvino.runtime import Core
import numpy as np

core = Core()
model = core.read_model("ir_model/linear_model.xml")
compiled_model = core.compile_model(model, "CPU")

# 构造输入数据
input_data = np.random.randn(1, 4).astype(np.float32)
output = compiled_model([input_data])
print("推理输出:", output[compiled_model.output(0)])

如果上述代码顺利输出结果，说明从ONNX到OpenVINO的完整链路已经打通，环境搭建成功。

误区/复盘：常见安装陷阱与规避策略

根据社区反馈与教学经验，以下四个误区出现频率最高，值得特别留意：

误区一：混淆Runtime与Development Tools。只安装openvino而忘记openvino-dev，导致mo命令找不到。反之，只安装openvino-dev而缺少Runtime，则推理阶段报错。务必两者同时安装。
误区二：Python版本过旧或过新。OpenVINO 2024.x系列要求Python 3.9～3.12。使用Python 3.7或3.13会导致pip解析依赖失败或运行时崩溃。建议使用python --version确认版本。
误区三：忽略numpy版本兼容性。OpenVINO对numpy有明确版本要求（通常为1.23～1.26）。如果项目中已有更高版本的numpy，建议在虚拟环境中降级：pip install "numpy<2.0"。
误区四：在系统Python中直接安装。不使用虚拟环境，导致后续安装其他深度学习框架时相互覆盖依赖。推荐使用venv或conda创建独立环境。

复盘建议：当安装后运行mo --help出现ModuleNotFoundError时，优先执行pip list | grep openvino检查包是否完整。若缺少openvino-dev，补装后重启终端即可。若出现libpython3.x.so相关错误，则需检查系统是否安装python3-dev或python3-devel包。

环境搭建是后续所有工作的地基。通过上述三步安装流程与验证方法，可以确保OpenVINO工具链完整可用。建议在完成安装后，将虚拟环境路径与版本信息记录在项目README中，便于团队协作时复现环境。至此，你已经具备了将ONNX模型迁移到OpenVINO平台的基础条件，可以开始进行模型转换与推理优化了。