2、环境搭建：Python环境、ONNX、ONNX Runtime、PyTorch/TensorFlow、Netron可视化工具、模型压缩相关库（如onnxoptimizer、onnxsim）的安装与验证

TinyML端侧部署的整个技术链路中，环境搭建是决定后续所有工作能否顺利推进的基石。很多初学者在模型转换或压缩阶段遇到“莫名其妙”的报错，根源往往不是算法问题，而是Python版本冲突、依赖库缺失或ONNX算子版本不匹配。本章将系统梳理从Python基础环境到ONNX生态核心工具链的安装、验证与排障方法，帮助你建立一个干净、可复现、可迁移的TinyML开发环境。

2.1 Python基础环境与虚拟环境管理

核心原理：TinyML工具链对Python版本非常敏感。ONNX Runtime的不同版本对Python版本有明确支持范围，PyTorch和TensorFlow的安装包也分别对应不同的Python版本。使用虚拟环境可以隔离不同项目的依赖，避免全局环境被污染。推荐使用Python 3.8至3.11之间的版本，这是当前ONNX生态兼容性最好的区间。

操作流程：首先安装Python（建议从官网下载安装包，勾选“Add Python to PATH”），然后创建虚拟环境。以下是基于venv和conda两种方式的对比：

# 使用venv创建虚拟环境（Windows/Linux通用）
python -m venv tinyml_env
# 激活环境
# Windows:
tinyml_env\Scripts\activate
# Linux/Mac:
source tinyml_env/bin/activate

# 使用conda创建虚拟环境
conda create -n tinyml_env python=3.9
conda activate tinyml_env

2.2 ONNX与ONNX Runtime安装验证

核心原理：ONNX（Open Neural Network Exchange）是一种开放的模型表示格式，用于在不同深度学习框架之间转换模型。ONNX Runtime是微软推出的跨平台推理引擎，支持ONNX格式模型的高效执行。两者的关系可以理解为：ONNX是“通用语言”，ONNX Runtime是“翻译器+执行器”。

安装命令：

# 安装ONNX（用于模型转换和操作）
pip install onnx==1.14.1

# 安装ONNX Runtime（用于推理验证）
pip install onnxruntime==1.16.3

# 如果使用GPU加速（可选）
pip install onnxruntime-gpu==1.16.3

验证方法：安装完成后，通过以下Python脚本验证安装是否成功，并检查版本兼容性：

import onnx
import onnxruntime as ort

print("ONNX版本:", onnx.__version__)
print("ONNX Runtime版本:", ort.__version__)
print("可用执行提供程序:", ort.get_available_providers())

# 创建一个最简单的ONNX模型（1+1=2）
import numpy as np
from onnx import helper, TensorProto

# 定义输入输出
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [1, 2])
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [1, 2])

# 定义Add节点
node = helper.make_node('Add', inputs=['X', 'X'], outputs=['Y'])

# 创建图
graph = helper.make_graph([node], 'test_graph', [X], [Y])
model = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 13)])

# 保存模型
onnx.save(model, 'test_add.onnx')

# 使用ONNX Runtime推理
sess = ort.InferenceSession('test_add.onnx')
input_data = np.array([[1.0, 2.0]], dtype=np.float32)
output = sess.run(None, {'X': input_data})
print("推理结果:", output[0])  # 应输出 [[2.0, 4.0]]

2.3 PyTorch与TensorFlow安装及ONNX导出验证

核心原理：PyTorch和TensorFlow是当前主流的深度学习框架。在TinyML场景中，我们通常先用框架训练模型，然后导出为ONNX格式。PyTorch通过 torch.onnx.export 导出，TensorFlow通过 tf2onnx 工具转换。两者的导出机制不同，但目标一致：生成一个计算图清晰、算子兼容的ONNX模型。

安装命令：

# PyTorch（CPU版）
pip install torch==2.0.1 torchvision==0.15.2

# TensorFlow（CPU版）
pip install tensorflow==2.13.0

# TensorFlow转ONNX工具
pip install tf2onnx==1.15.1

PyTorch导出ONNX示例：

import torch
import torch.nn as nn

# 定义一个简单的CNN模型
class SimpleCNN(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv1 = nn.Conv2d(3, 16, 3, padding=1)
        self.relu = nn.ReLU()
        self.pool = nn.MaxPool2d(2)
        self.fc = nn.Linear(16*16*16, 10)
    
    def forward(self, x):
        x = self.pool(self.relu(self.conv1(x)))
        x = x.view(x.size(0), -1)
        return self.fc(x)

model = SimpleCNN()
model.eval()

# 构造示例输入
dummy_input = torch.randn(1, 3, 32, 32)

# 导出ONNX
torch.onnx.export(
    model, dummy_input, "simple_cnn.onnx",
    input_names=["input"], output_names=["output"],
    dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}},
    opset_version=13
)
print("PyTorch模型已导出为ONNX格式")

2.4 Netron可视化工具安装与使用

核心原理：Netron是一个轻量级的模型可视化工具，支持ONNX、TensorFlow、PyTorch等多种格式。它能够展示模型的网络结构、算子类型、张量维度、参数数量等关键信息，是排查模型转换问题的第一利器。

安装方式：

# 方式一：pip安装（推荐）
pip install netron

# 方式二：直接下载桌面版
# 访问 https://github.com/lutzroeder/netron 下载对应系统安装包

使用流程：

1. 在Python中启动Netron服务：python -m netron simple_cnn.onnx
2. 浏览器自动打开可视化界面，或手动访问 http://localhost:8080
3. 检查模型结构：点击每个节点查看算子属性、输入输出维度
4. 验证模型完整性：确认没有悬空的输入/输出，所有张量维度合理

2.5 模型压缩相关库安装与验证

核心原理：模型压缩是TinyML部署的关键环节。onnxoptimizer提供图优化（如算子融合、常量折叠），onnxsim（onnx-simplifier）用于简化模型结构（如消除冗余节点、简化Shape计算）。这两个工具能显著减小模型体积、提升推理速度。

安装命令：

# 安装onnxoptimizer
pip install onnxoptimizer==0.3.2

# 安装onnxsim
pip install onnxsim==0.4.33

# 安装onnxruntime-tools（提供量化工具）
pip install onnxruntime-tools==1.7.0

验证与使用示例：

import onnx
import onnxoptimizer
import onnxsim

# 加载原始模型
model = onnx.load("simple_cnn.onnx")

# 1. 使用onnxoptimizer进行图优化
optimized_model = onnxoptimizer.optimize(model)
onnx.save(optimized_model, "simple_cnn_optimized.onnx")
print("onnxoptimizer优化完成")

# 2. 使用onnxsim进行模型简化
simplified_model, check = onnxsim.simplify("simple_cnn.onnx")
if check:
    onnx.save(simplified_model, "simple_cnn_simplified.onnx")
    print("onnxsim简化完成，模型已保存")
else:
    print("onnxsim简化失败，请检查模型结构")

# 3. 对比模型大小
import os
original_size = os.path.getsize("simple_cnn.onnx") / 1024
optimized_size = os.path.getsize("simple_cnn_optimized.onnx") / 1024
simplified_size = os.path.getsize("simple_cnn_simplified.onnx") / 1024

print(f"原始模型: {original_size:.2f} KB")
print(f"优化后: {optimized_size:.2f} KB")
print(f"简化后: {simplified_size:.2f} KB")

2.6 环境验证综合案例：从PyTorch到ONNX的完整链路

案例背景：某智能家居项目需要将一个人脸检测模型部署到树莓派4B上。模型在PyTorch中训练，参数量约2.3MB，FP32精度。目标是将模型压缩到1MB以内，并确保在树莓派上推理延迟小于200ms。

初始现象与目标：原始PyTorch模型直接导出ONNX后大小为2.3MB，在树莓派CPU上推理延迟约450ms，远超目标。需要经过环境搭建、模型转换、压缩优化、验证四个阶段。

关键操作步骤：

1. 环境准备：在开发机上创建Python 3.9虚拟环境，安装PyTorch 2.0.1、ONNX 1.14.1、ONNX Runtime 1.16.3、onnxsim 0.4.33。
2. 模型导出：使用 torch.onnx.export 导出模型，设置opset_version=13，动态batch维度。
3. 模型简化：使用onnxsim对导出的ONNX模型进行简化，模型大小从2.3MB降至1.8MB。
4. 量化压缩：使用onnxruntime-tools进行动态量化（int8），模型大小降至0.9MB。
5. 推理验证：在开发机上使用ONNX Runtime加载量化后模型，对比原始PyTorch模型输出，最大误差小于0.01。
6. 端侧部署：将量化后的ONNX模型拷贝到树莓派，安装onnxruntime（ARM版），实测推理延迟为180ms，满足要求。

结果对比：

复盘经验：环境搭建阶段最容易忽略的是版本兼容性。在本案例中，最初使用onnxruntime 1.15.0时，量化工具报错“Unsupported operator”，升级到1.16.3后问题解决。建议在项目开始时就将所有依赖版本锁定，并编写自动化验证脚本，确保环境可复现。

2.7 环境验证清单与总结

完成上述所有安装后，建议执行以下验证清单，确保环境完全就绪：

• Python版本：运行 python --version，确认在3.8-3.11之间
• 虚拟环境激活：确认当前终端提示符显示虚拟环境名称
• ONNX导入测试：运行 import onnx; print(onnx.__version__)
• ONNX Runtime推理测试：运行2.2节中的加法模型验证脚本
• 框架导出测试：运行2.3节中的PyTorch导出脚本，确认生成ONNX文件
• Netron可视化：启动Netron并打开导出的ONNX文件，确认结构正确
• 压缩工具测试：对导出的模型执行onnxsim简化，确认输出正常

环境搭建不是一次性的工作。随着项目推进，可能需要安装额外的工具库（如模型量化工具、编译器工具链）。建议建立一份“环境搭建文档”，记录所有安装命令、版本号、遇到的问题及解决方案，这不仅方便自己回溯，也能帮助团队成员快速上手。