入门指南

[English]

硬件要求

  • 一块 ESP32-S3 或 ESP32-P4 开发板。推荐使用：ESP32-S3-EYE 或 ESP32-P4-Function-EV-Board

  • 一台 PC（Linux 系统）

备注

  • 部分开发板目前采用 Type C 接口。请确保使用正确的线缆连接开发板！

  • ESP-DL 也支持 ESP32，但其算子实现采用 C 编写，因此 ESP32 运行速度会远慢于 ESP32-S3 或 ESP32-P4。如有需要，可在项目中自行添加编译配置文件，ESP-DL 的函数接口调用方式完全一致。需要注意的是:

    • 使用 ESP-PPQ 量化 ESP32 平台模型时，需将 target 设置为 c。

    • 使用 ESP-DL 部署 ESP32 平台模型时，项目编译 target 则设置为 esp32。

软件要求

ESP-IDF

ESP-DL 基于 ESP-IDF 运行。有关如何获取 ESP-IDF 的详细说明，请参阅 ESP-IDF 编程指南。

备注

请使用 ESP-IDF 的 release/v5.3 或更高版本。

ESP-PPQ

ESP-PPQ 是基于 ppq 的量化工具，其 代码 已全部开源。ESP-PPQ 在 PPQ 的基础上添加了乐鑫定制的 quantizer 和 exporter，方便用户根据不同的芯片选择和 ESP-DL 匹配的量化规则，并导出为 ESP-DL 可以直接加载的标准模型文件。ESP-PPQ 兼容 PPQ 所有的 API 和量化脚本。更多细节请参考 PPQ 文档和视频。如果您想量化自己的模型，可以使用如下方式安装 esp-ppq：

方式一: 使用 pip 安装包

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install esp-ppq

方式二: 使用 pip 安装源码，以便保持与 master 分支同步

git clone https://github.com/espressif/esp-ppq.git
cd esp-ppq
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install -e .

方式三: 使用 uv 安装包

uv pip install "esp-ppq[cpu]" --torch-backend=cpu
# GPU
# uv pip install "esp-ppq[cpu]" --torch-backend=cu124
# AMD GPU
# uv pip install "esp-ppq[cpu]" --torch-backend=rocm6.2
# Intel XPU
# uv pip install "esp-ppq[cpu]" --torch-backend=xpu

方式四: 使用 uv 安装源码，以便保持与 master 分支同步

git clone https://github.com/espressif/esp-ppq.git
cd esp-ppq
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
uv pip install -e .

方式五: 在 docker 中使用 esp-ppq

docker build -t esp-ppq:your_tag https://github.com/espressif/esp-ppq.git

备注

  • 示例代码中安装的是 linux pytorch cpu 版本，请根据实际情况安装对应的 pytorch。

  • 如果使用 uv 安装包，仅需要更改 --torch-backend 参数即可，其会忽略项目中配置的 pytorch URLs 索引。

快速开始

ESP-DL 提供了一些开箱即用的 示例

示例编译 & 烧录

idf.py set-target [Soc]
idf.py flash monitor

使用具体的芯片替换 [Soc]，目前支持 esp32s3 和 esp32p4。示例暂未添加 esp32 的模型和编译配置文件。

示例配置

idf.py menuconfig

一些示例包含可配置的选项，可以在使用 idf.py set-target 指定芯片之后使用 idf.py menuconfig 进行配置。

故障排除

查看 ESP-IDF 文档

请参阅 ESP-IDF DOC

擦除 FLASH 和清除示例

idf.py eras-flash -p [PORT]

删除 build/、sdkconfig、dependencies.lock、managed_components/ 并重试。

模型量化

首先，请参考 ESP-DL 算子支持状态 operator_support_state.md，确保您的模型中的算子已经得到支持。

ESP-DL 必须使用专有格式 .espdl 进行模型部署，深度学习模型需要进行量化和格式转换之后才能使用。ESP-PPQ 提供了 espdl_quantize_onnx 和 espdl_quantize_torch 两种接口以支持 ONNX 模型和 PyTorch 模型导出为 .espdl 模型。其他深度学习框架，如 TensorfFlow, PaddlePaddle 等都需要先将模型转换为 ONNX 。因此请确保您的模型可以转换为 ONNX 模型。更多详细信息，请参阅：

模型部署

ESP-DL 提供了一系列 API 来快速加载和运行模型。更多详细信息，请参阅：