espdl-quantize

Automates iterative esp-ppq quantization tuning to recover accuracy on ESP-DL models.

1.1k|222|Updated Nov 16, 2018
One-click install
npx skills add https://github.com/espressif/esp-dl --skill espdl-quantize
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: espdl-quantize
Source: https://github.com/espressif/esp-dl/tree/main/tools/agents/skills/espdl-quantize
Command: npx skills add https://github.com/espressif/esp-dl --skill espdl-quantize

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires esp_ppq, torch, onnx, onnxsim, pandas, scipy, tqdm, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Manually tuning esp-ppq quantization settings (calibration algorithms, TQT, equalization, bias correction, mixed precision) to recover post-quantization accuracy on ESP-DL targets is slow and error-prone. This Skill replaces the guess-and-rerun loop with a structured, distribution-aware search that iterates toward a target metric automatically.

Core Features & Use Cases

  • Phased search state machine: Runs a baseline, then a calibration × TQT cartesian product, then single-lever residual fixes, then agent-driven open exploration, with automatic plateau and target-reached detection.
  • Structured iteration artifacts: Each run emits metrics.json, layerwise_error.json, layer_stats_full.json, non_computing_hot_ops.json, and graphwise_jumps.json so decisions are driven by per-layer distribution data.
  • Target-aware safety checks: Auto-disables LSQ on POWER_OF_2 targets (esp32p4, esp32s3, c) and warns on layer-wise equalization for esp32p4 per-channel weights.
  • Use Case: Quantize a MobileNet-V2 model for ESP32-P4, find top-1 accuracy dropped after int8 quantization, and let the Skill iterate over calibration algorithms, TQT schedules, equalization, and int16 dispatching until the target accuracy is recovered.

Quick Start

Provide a user_quant.py module with your calibration dataloader and evaluate function, then ask the agent to run the espdl-quantize skill to tune my esp-ppq quantization settings until the target accuracy is reached.

Frequently Asked Questions about espdl-quantize

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I improve quantized esp-dl model accuracy?

Run the espdl-quantize skill with a user_quant.py contract module that provides a calibration dataloader and evaluate function. The skill iterates over calibration algorithms, TQT schedules, equalization, bias correction, and mixed precision until your target metric is reached or a plateau is detected.

How to choose between kl, mse, and percentile calibration in esp-ppq?

The skill runs a mandatory Phase-2 cartesian product pairing each of kl, mse, and percentile calibration with the default TQT schedule. Calibration is not separable from the training pass, so the comparison of all three legs reveals which pairing performs best for your model's distribution.

Does LSQ work on ESP32-P4 or ESP32-S3 quantization targets?

No. All esp-dl targets use a POWER_OF_2 quantization policy, and esp-ppq's LSQDelegator silently disables scale training under POWER_OF_2, so LSQ degenerates to weight-only tuning. The harness auto-disables LSQ on these targets and recommends TQT, which trains log2_scale natively.

Can I use layer-wise equalization on esp32p4?

Yes, but with caution. esp-ppq officially marks equalization as not recommended for esp32p4's per-channel weight quantization, yet some MobileNet-family networks still benefit. The harness runs it with a warning and suggests trying it only after the calibration × TQT sweep has settled.

What do I need to provide to run the quantization search?

A single Python module exporting QUANT_CONFIG (model path, input shape, target chip, primary metric), create_calib_dataloader(), and evaluate(quant_graph). Torch flows also need get_torch_model(). The skill never edits this module and stores all iteration state under outputs/.

Why did my quantization iteration regress after enabling fusion alignment?

Fusion alignment (lever 3c) only helps when the top elementwise op's max_snr falls in the 0.20-0.30 band or its input float std ratio exceeds 5. Outside that band, alignment can overwrite an already-tight TQT scale and regress; the state machine skips it when the R8 trigger does not fire.