2、环境搭建：Python环境、TensorFlow/PyTorch安装、ONNX Runtime、嵌入式工具链准备

TinyML手势识别项目的落地路径，是从“数据采集与模型训练”到“模型转换与端侧推理”的完整闭环。在这一过程中，开发环境的搭建质量直接决定了后续调试效率与部署成功率。本章将围绕四个核心维度展开：Python基础环境、深度学习框架（TensorFlow/PyTorch）、ONNX Runtime推理引擎，以及嵌入式端（以STM32/ESP32系列为例）的交叉编译工具链。我们不仅关注“装什么”，更关注“为什么这样装”以及“装完后如何验证”。

2.1 Python环境：版本选择与虚拟环境隔离

Python是TinyML开发的基础载体。手势识别项目通常涉及TensorFlow/PyTorch、ONNX Runtime、NumPy、OpenCV（用于图像预处理）等多个依赖库，这些库对Python版本有严格兼容性要求。例如，TensorFlow 2.10及以上版本在Windows上不再支持GPU原生训练（需WSL2），而PyTorch 2.x要求Python 3.8以上。因此，版本锁定是环境搭建的第一步。

推荐使用Anaconda或Miniconda创建独立虚拟环境，避免系统级Python被污染。具体操作流程如下：

1. 安装Miniconda（约80MB），选择Python 3.9或3.10作为基础解释器。
2. 创建虚拟环境：conda create -n tinyml python=3.9。
3. 激活环境：conda activate tinyml。
4. 安装核心科学计算库：pip install numpy scikit-learn matplotlib。

这里有一个关键判断方法：查看依赖库的发布说明。例如，ONNX Runtime 1.16.0支持Python 3.8~3.11，但1.17.0开始要求Python≥3.9。如果项目需要部署到老旧MCU，可能还需要使用TensorFlow Lite Converter，其版本与TensorFlow主版本强绑定。建议在项目开始时，用pip freeze > requirements.txt锁定所有依赖版本，方便复现。

2.2 深度学习框架安装：TensorFlow与PyTorch的取舍

手势识别模型通常采用卷积神经网络（CNN）或轻量级Transformer。TensorFlow和PyTorch都能胜任，但安装策略不同。TensorFlow的安装重点在于CPU/GPU版本选择和Keras API兼容性；PyTorch则更关注torchvision（用于图像增强）和torch.onnx.export的配合。

以TensorFlow 2.13为例，安装命令为：

pip install tensorflow==2.13.0
# 若需GPU支持（仅限Linux+WSL2）：
pip install tensorflow[and-cuda]==2.13.0

PyTorch 2.1安装命令为：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# 若需CUDA 11.8：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

安装完成后，必须进行最小化验证：

python -c "import tensorflow as tf; print(tf.__version__)"
python -c "import torch; print(torch.__version__)"

对于TinyML项目，不建议在开发机上追求极致GPU性能，因为手势识别模型参数量通常在几十KB到几MB之间，CPU训练完全够用。反而应关注模型量化工具的兼容性——TensorFlow的TFLite Converter和PyTorch的torch.quantization都需要特定版本支持。

2.3 ONNX Runtime：模型转换与推理验证

ONNX Runtime是连接训练框架与嵌入式推理引擎的桥梁。在TinyML手势识别项目中，我们通常将训练好的模型导出为ONNX格式，再通过ONNX Runtime在PC端验证推理结果，最后转换为嵌入式专用格式（如TFLite或STM32CubeAI的.c/.h文件）。

安装ONNX Runtime非常简单：

pip install onnxruntime==1.16.3
# 若需GPU加速（仅PC端验证用）：
pip install onnxruntime-gpu==1.16.3

关键操作流程包括三步：

1. 模型导出：PyTorch使用torch.onnx.export，TensorFlow使用tf2onnx.convert。
2. 模型检查：使用onnx.checker.check_model验证模型结构完整性。
3. 推理验证：用ONNX Runtime加载模型，输入随机张量或真实样本，对比输出与原始框架是否一致。

以下是一个典型的ONNX推理验证代码片段：

import onnxruntime as ort
import numpy as np

sess = ort.InferenceSession("gesture_model.onnx")
input_name = sess.get_inputs()[0].name
output_name = sess.get_outputs()[0].name

# 模拟输入：1x3x96x96 的手势图像张量
dummy_input = np.random.randn(1, 3, 96, 96).astype(np.float32)
result = sess.run([output_name], {input_name: dummy_input})
print("输出类别概率:", result[0])

这里有一个常见误区：ONNX Runtime的输入张量顺序必须与训练时完全一致。例如，PyTorch默认通道顺序为NCHW，而TensorFlow默认NHWC。如果转换时未指定，会导致推理结果错误。建议在导出ONNX时显式声明input_names和output_names，并固定动态轴。

2.4 嵌入式工具链准备：交叉编译与烧录

嵌入式端部署是TinyML的最终目标。以STM32F746G-DISCO开发板为例，需要准备以下工具链：

• STM32CubeMX：用于生成初始化代码和AI模型集成工程。
• STM32CubeIDE 或 arm-none-eabi-gcc：交叉编译器，将C代码编译为ARM Cortex-M7机器码。
• X-CUBE-AI 扩展包：将ONNX/TFLite模型转换为STM32优化的C代码。
• ST-Link Utility 或 OpenOCD：固件烧录工具。

安装验证方法：在命令行执行arm-none-eabi-gcc --version，确认输出包含arm-none-eabi-gcc (GNU Arm Embedded Toolchain 10.3-2021.10)。对于ESP32系列，则需安装ESP-IDF，并执行idf.py --version验证。

一个完整的嵌入式工具链准备流程如下：

1. 安装STM32CubeMX（需要Java运行环境）。
2. 在CubeMX中安装X-CUBE-AI扩展包（选择与CubeMX版本匹配的版本）。
3. 创建新工程，选择MCU型号，配置时钟（通常为216MHz）和调试接口（SWD）。
4. 在“Software Packs”中选择X-CUBE-AI，导入ONNX模型，设置输入/输出张量形状。
5. 生成代码，使用STM32CubeIDE编译，确认无报错。
6. 连接开发板，烧录固件，通过串口打印推理结果。

2.5 环境联调与常见误区复盘

环境搭建的最终目标是实现“开发机训练→ONNX转换→嵌入式推理”的无缝衔接。建议在项目启动第一天就完成一次端到端冒烟测试：训练一个随机权重的小模型（如输入1x3x32x32，输出10类），走完整个部署流程，确认每个环节的工具链都正常工作。

以下是三个高频误区及应对策略：

• 误区一：盲目追求最新版本。最新版TensorFlow/PyTorch可能引入不兼容的API变更。建议使用“次新稳定版”，并参考官方发布说明中的“Deprecation”部分。
• 误区二：忽略模型输入预处理。PC端推理时，图像通常归一化到[0,1]或[-1,1]，但嵌入式端可能使用整数运算。若未在模型转换时嵌入预处理逻辑，会导致推理结果偏差。
• 误区三：不检查内存占用。STM32F746仅有320KB RAM，一个1MB的模型文件无法直接加载。必须使用量化、剪枝或知识蒸馏技术压缩模型，并在编译时查看.map文件确认内存使用。

总结复盘：环境搭建不是一次性工作，而是伴随项目迭代持续调整的过程。建议维护一份environment.md文档，记录每个工具的版本、安装命令、验证方法和已知问题。当团队协作时，这份文档能大幅降低“在我电脑上能跑”的沟通成本。