ESP-DL [中文]

ESP-DL 是一款专为 ESP 系列芯片设计的轻量级、高效的神经网络推理框架。借助 ESP-DL，您可以轻松快速地使用乐鑫的系统级芯片（SoC）开发 AI 应用程序。

概述

ESP-DL 提供了加载、调试和运行 AI 模型的 API。该框架易于使用，可与乐鑫的其他 SDK 无缝集成。ESP-PPQ 是 ESP-DL 的量化工具，能够对 ONNX、Pytorch 和 TensorFlow 格式的模型进行量化，并导出为 ESP-DL 标准模型格式。

• ESP-DL 标准模型格式：该格式类似于 ONNX，但使用 FlatBuffers 而不是 Protobuf，因此更加轻量，并支持零拷贝反序列化，文件扩展名为 .espdl。
• 高效算子实现：ESP-DL 高效实现了常见的 AI 算子，如 Conv、Gemm、Add 和 Mul。支持的算子列表。
• 静态内存规划器：内存规划器会根据用户指定的内部 RAM 大小，自动将不同层分配到最优的内存位置，从而在最小化内存占用的同时，确保整体运行效率。
• 双核调度：自动的双核调度功能使计算密集型算子能够充分利用双核计算能力。目前，Conv2D 和 DepthwiseConv2D 支持双核调度。
• 8位查找表激活：除 ReLU 和 PReLU 外，ESP-DL 中的所有激活函数都采用 8 位查找表（LUT）方法实现，以加速推理。您可以使用任何激活函数，其计算复杂度保持不变。

新闻

• [2026/3/12] 添加了 YOLO26 模型，感谢 BoumedineBillal 的贡献。开始训练并部署您自己的 YOLO26 模型。
• [2026/3/11] ESP-DL Agent 工具已演变为 espdl-operator 技能，使 AI 代理能够更轻松地自动实现算子。请参阅 how_to_implement_operators_with_ai_agent.rst。
• [2026/2/27] 支持使用 TrainedQuantizedThresholdPass 对模型进行量化。详情请见 quantize_model_with_TQT.rst。
• [2026/1/14] 支持在 netron 中可视化 .espdl 模型，便于模型调试。
• [2025/11/4] 发布了 ESP-DL Agent 工具 v1.0。该工具专为代码代理系统设计，用于协助实现和优化 ESP-DL 框架中的算子。
• [2025/10/20] 我们发布了 ESP-DL v3.2.0，进一步提升了模型量化和部署能力。
• [2025/07/22] 将 ESP-PPQ 包从 ppq 重命名为 esp-ppq，以避免与 ppq 冲突，并将所有 ESP-PPQ 的依赖项升级到最新版本。注意：在量化脚本中，请务必修改包名。
• [2025/04/30] 我们发布了一个新的 esp-detection 项目以及 ESPDet-Pico 模型，可以轻松训练和部署目标检测模型。espdet_pico_224_224_cat espdl 模型 和 示例 是由 esp-detection 训练的猫检测模型。欢迎试用并分享您的反馈！
• [2025/02/18] 我们支持 yolo11n espdl 模型 和 示例。
• [2025/01/09] 我们更新了 espdl 模型的架构，并发布了 ESP-DL v3.1.0。请注意：旧版模型仍可被新架构加载，但新模型与旧版本不兼容。
• [2024/12/20] 我们发布了 ESP-DL v3.0.0。

入门指南

软件要求

• ESP-IDF

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

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

• ESP-PPQ

ESP-PPQ 是基于 ppq 的量化工具。如果您想量化自己的模型，可以通过以下方式安装 esp-ppq。更多安装方法请参考 入门指南。

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

[!NOTE]

• 示例代码安装的是 Linux 版 PyTorch CPU 版本。请根据您的实际需求安装合适的 PyTorch 版本。

模型量化

首先，请参考 ESP-DL 算子支持状态，确保您的模型中的算子已被支持。

ESP-PPQ 可直接读取 ONNX 模型进行量化。Pytorch 和 TensorFlow 需要先转换为 ONNX 模型，因此请确保您的模型可以转换为 ONNX 模型。有关量化更详细的说明，请参阅：

如何量化模型
如何量化 MobileNetV2
如何量化 YOLO11n

模型部署

ESP-DL 提供了一系列 API，可快速加载和运行模型。典型示例如下：

如何加载测试模型
如何运行模型

ESP-DL 模型库

目录 models 包含一系列针对 ESP32 系列芯片优化的预训练和量化模型。每个模型都以 ESP-IDF 组件的形式提供，便于集成。更多详情请参阅 ESP-DL 模型库。

支持的算子

如果您遇到不支持的算子，请在 issues 中指出，我们将尽快予以支持。我们也欢迎对 ESP-DL 的贡献，更多详情请参阅 创建新模块（算子）。

ESP-DL 算子支持状态

ESP-DL 快速上手指南

ESP-DL 是乐鑫专为 ESP 系列芯片打造的轻量级、高效神经网络推理框架。本指南将帮助您快速完成环境搭建、模型量化及部署运行。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• ESP-IDF：必须安装 release/v5.3 或更高版本。
  • 获取方式：参考 ESP-IDF 编程指南。
• Python 环境：用于安装量化工具依赖。
• 硬件：ESP32 系列开发板（支持双核调度的型号效果更佳）。

2. 安装步骤

2.1 配置 ESP-IDF

按照官方文档完成 ESP-IDF 的安装与环境变量导出。确保 idf.py --version 能正常输出版本信息且版本 >= 5.3。

2.2 安装量化工具 (ESP-PPQ)

ESP-PPQ 是将 ONNX/PyTorch/TensorFlow 模型转换为 ESP-DL 专用格式 (.espdl) 的关键工具。

在终端中执行以下命令安装依赖（以 Linux CPU 版本为例，其他平台请根据需求调整 PyTorch 源）：

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

注意：如果您之前使用过旧版 ppq 包，请注意乐鑫已将其重命名为 esp-ppq 以避免冲突，请在脚本中更新导入名称。

3. 基本使用流程

ESP-DL 的核心工作流分为两步：模型量化（在 PC 端进行）和 模型部署（在 ESP 芯片上运行）。

3.1 模型量化

在量化前，请查阅 算子支持列表 确认您的模型算子已被支持。ESP-PPQ 直接支持读取 ONNX 模型。

简要步骤：

1. 将您的 PyTorch 或 TensorFlow 模型导出为 ONNX 格式。
2. 使用 ESP-PPQ 脚本进行量化并生成 .espdl 文件。

参考官方教程进行具体操作：

• 如何量化模型
• MobileNetV2 量化示例
• YOLO11n 量化示例

生成的 .espdl 模型文件可直接放入 ESP-IDF 项目的 main 目录或作为组件引用。您可以使用 Netron 可视化查看 .espdl 模型结构以辅助调试。

3.2 模型部署与运行

在 ESP-IDF 项目中，ESP-DL 提供了简洁的 API 来加载和运行模型。

典型代码逻辑：

1. 加载模型：使用 API 读取存储在 Flash 中的 .espdl 文件。
2. 准备输入：将图像或传感器数据预处理为模型所需的张量格式。
3. 执行推理：调用运行接口，框架会自动利用静态内存规划器和双核调度优化性能。
4. 处理结果：解析输出张量获取推理结果。

详细代码示例请参考：

• 加载测试配置文件模型
• 运行模型示例

4. 进阶资源

• 模型库 (Model Zoo)：访问 models 目录，获取预训练并量化好的模型（如 YOLO 系列、猫检测模型等），它们已封装为 ESP-IDF 组件，可直接集成使用。
• 算子扩展：若遇到不支持的算子，可通过 AI Agent 技能 辅助生成代码，或参考 新增算子教程 手动实现并提交贡献。