📚 课程目录第2章环境准备

2、环境准备：注册Edge Impulse账号、创建项目、安装并配置Edge Impulse CLI、Python环境与TensorFlow/Keras版本兼容性检查

在开始将Keras模型导入Edge Impulse并进行再训练之前，必须先完成一套严谨的环境搭建。很多初学者在模型导入阶段遭遇“玄学”报错，根源往往不是模型结构本身，而是本地Python环境、TensorFlow版本与Edge Impulse云端编译器之间的隐性冲突。本章将按照“账号与项目 → CLI工具链 → Python与深度学习框架”三个层次，逐步完成环境准备，并重点解决版本兼容性这一最容易踩坑的环节。

2.1 注册Edge Impulse账号与创建项目

核心原理：Edge Impulse采用“云端编译+本地采集”的混合架构。账号体系不仅用于身份认证，还承载了项目数据隔离、模型版本管理、部署产物生成等核心功能。每个Project在云端拥有独立的存储空间和计算配额，而API Key则是本地CLI与云端通信的“通行证”。

操作流程：

访问 https://studio.edgeimpulse.com，使用GitHub、Google或邮箱注册账号。企业用户建议使用组织邮箱，便于团队协作。
登录后点击右上角头像，选择“Create new organization”，输入组织名称（如“AIoT-Lab”）。组织是项目分组的顶层单元，免费版可创建3个项目。
在组织首页点击“Create new project”，输入项目名称（如“keras_gesture_recognition”），在“Project type”中选择“Keras model import”或“Bring your own model”。
进入项目后，点击左侧“Dashboard”，在“API keys”区域点击“Add new API key”，选择权限为“Full access”，复制生成的Key（格式类似 ei_xxxxxxxxxxxxxxxx）。

风险提示：API Key等同于账号密码，切勿提交到GitHub或分享到公开文档。若泄露，请立即在Dashboard中删除并重新生成。免费版项目有数据上传量限制（约100MB），导入大型Keras模型前需确认模型文件大小。

2.2 安装并配置Edge Impulse CLI

核心原理：Edge Impulse CLI是一组基于Node.js的命令行工具，负责三件事：数据采集（edge-impulse-daemon）、数据上传（edge-impulse-uploader）、模型部署（edge-impulse-linux等）。CLI通过API Key与云端通信，将本地传感器数据流式传输到项目，或将编译后的模型下载到本地设备。

安装步骤：

# 1. 安装Node.js（建议使用v16或v18 LTS版本）
# 检查是否已安装
node --version

# 2. 全局安装Edge Impulse CLI
npm install -g edge-impulse-cli

# 3. 验证安装
edge-impulse-daemon --version

# 4. 登录（会提示输入API Key）
edge-impulse-daemon --api-key ei_xxxxxxxxxxxxxxxx

配置要点：在Linux系统中，若使用USB连接开发板（如Arduino Nano 33 BLE Sense），需要添加udev规则以获取串口权限：

sudo usermod -a -G dialout $USER
# 重新登录终端使权限生效

案例拆解：某团队在Windows环境下安装CLI时，遇到edge-impulse-daemon无法识别USB串口的问题。排查过程如下：

初始现象：执行edge-impulse-daemon后提示“No device found”。
分析判断：首先检查设备管理器，确认开发板枚举为COM3；其次检查驱动，发现未安装CP210x USB转串口驱动。
实际操作：安装Silicon Labs CP210x驱动，重新插拔设备，再次运行CLI，成功识别设备。
复盘经验：Windows下90%的CLI连接问题源于驱动缺失或端口占用，建议先使用串口助手（如PuTTY）测试端口连通性。

2.3 Python环境与TensorFlow/Keras版本兼容性检查

核心原理：Edge Impulse的模型导入功能依赖TensorFlow的SavedModel格式。云端编译器对TensorFlow版本有明确要求——过新或过旧的版本都会导致算子解析失败。Keras作为TensorFlow的高层API，其版本与TF严格绑定（TF 2.x内置Keras 2.x）。因此，本地环境必须与云端支持的版本范围对齐。

版本兼容性矩阵：

Python版本	TensorFlow版本	Keras版本	Edge Impulse支持	备注
3.8	2.8.0	2.8.0	✅ 推荐	最稳定组合
3.9	2.10.0	2.10.0	✅ 推荐	支持Windows GPU
3.10	2.13.0	2.13.0	⚠️ 需测试	部分算子需转换
3.11	2.15.0	2.15.0	❌ 不推荐	云端编译器可能报错

检查与配置流程：

# 1. 创建虚拟环境（推荐使用conda或venv）
python -m venv ei_env
source ei_env/bin/activate  # Windows: ei_env\Scripts\activate

# 2. 安装指定版本TensorFlow
pip install tensorflow==2.10.0

# 3. 验证版本
python -c "import tensorflow as tf; print(tf.__version__); print(tf.keras.__version__)"

# 4. 检查关键算子兼容性（示例：深度可分离卷积）
python -c "
from tensorflow.keras.layers import DepthwiseConv2D
print('DepthwiseConv2D OK')
"

常见误区与排障：

  误区1：盲目使用最新版TensorFlow。Edge Impulse的编译器更新滞后于TF官方发布，建议使用TF 2.8~2.10区间。

  误区2：忽略模型中的自定义层。若Keras模型包含Lambda层或自定义损失函数，导入时需将这些层转换为TensorFlow原生算子，否则云端编译会报“Unsupported op”。

  误区3：在GPU环境下训练，在CPU环境下导出。GPU训练产生的某些算子（如tf.float16）在CPU推理时可能不兼容，建议统一使用CPU导出。

案例闭环：某开发者使用TF 2.16训练了一个手势识别模型（包含Conv1D + LSTM），导入Edge Impulse时出现Op type not registered 'BlockLSTM'错误。分析发现，LSTM在TF 2.16中默认使用tf.raw_ops.BlockLSTM，而Edge Impulse的TFLite编译器仅支持UnidirectionalSequenceLSTM。解决方案是：

将模型改用tf.keras.layers.LSTM(..., implementation=1)强制使用旧版实现。
重新导出SavedModel，并验证算子：saved_model_cli show --dir ./model --all。
导入Edge Impulse后，在“Model testing”页面确认推理结果与本地一致。

此案例说明，版本兼容性检查不仅是“装对版本”，更需要对模型内部的算子实现有清晰认知。

2.4 环境验证与联调

核心原理：环境准备是否成功，最终要通过一次完整的“本地导出 → 云端导入 → 模型测试”链路来验证。这能提前暴露80%的集成问题，避免后续在数据采集和训练阶段反复返工。

验证清单：

✅ CLI能正常登录并列出项目
✅ Python能加载训练好的Keras模型并输出推理结果
✅ 模型导出为SavedModel格式，且无自定义算子警告
✅ 在Edge Impulse Studio中成功上传模型，并完成一次“Model testing”

操作示例：

# 导出Keras模型为SavedModel
model.save('saved_model_dir', save_format='tf')

# 使用CLI上传模型（需在项目Dashboard中获取Upload API Key）
edge-impulse-uploader --api-key ei_xxx --category training saved_model_dir/

总结复盘：环境准备的核心不是“装好软件”，而是建立一条可控的版本链路。建议将Python依赖写入requirements.txt并纳入版本管理，同时记录CLI版本和Node.js版本，形成可复现的环境快照。这样当团队协作或更换开发机时，可以快速重建环境，避免“在我电脑上能跑”的尴尬局面。