Implementation:Tencent Ncnn Ncnn2table
| Knowledge Sources | |
|---|---|
| Domains | Quantization, Model_Optimization |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
External CLI tool for generating per-layer quantization calibration tables from an ncnn model and calibration dataset.
Description
ncnn2table runs forward passes of a float32 ncnn model on calibration images, collects per-layer activation histograms, and computes optimal int8 quantization scale factors. It supports three calibration methods: KL-divergence (default), ACIQ, and equalization. The output is a .table file containing per-layer scale factors that ncnn2int8 uses to produce the quantized model.
The tool accepts preprocessing parameters (mean, norm, shape, pixel format) to match the model's expected input format, and supports multi-threaded calibration for faster processing.
Usage
Use after optimizing the model with ncnnoptimize and preparing the calibration dataset. Pass preprocessing parameters that match the model's training configuration.
Code Reference
Source Location
- Repository: ncnn
- File: tools/quantize/ncnn2table.cpp
- Lines: L1676-1828 (main), L300-777 (quantize_KL), L778-1103 (quantize_ACIQ), L1104-1107 (quantize_EQ)
Signature
ncnn2table [ncnnparam] [ncnnbin] [list,...] [ncnntable] [key=value ...]
# Key parameters:
# mean=[v,v,v] Per-channel mean values
# norm=[v,v,v] Per-channel normalization values
# shape=[w,h,c] Input tensor shape
# pixel=BGR|RGB|GRAY Pixel format
# method=kl|aciq|eq Calibration method (default: kl)
# thread=N Number of parallel threads
Import
# Built from ncnn source tree
# Located in build/tools/quantize/ncnn2table after cmake build
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| ncnnparam | file path | Yes | Optimized .param file (from ncnnoptimize) |
| ncnnbin | file path | Yes | Optimized .bin file |
| list | file path(s) | Yes | Calibration image list(s), comma-separated for multi-input |
| mean | float[3] | No | Per-channel mean values for preprocessing |
| norm | float[3] | No | Per-channel normalization values |
| shape | int[3] | No | Input shape [width,height,channels] |
| pixel | string | No | Pixel format: BGR, RGB, or GRAY |
| method | string | No | Calibration method: kl (default), aciq, or eq |
| thread | int | No | Number of parallel calibration threads |
Outputs
| Name | Type | Description |
|---|---|---|
| ncnntable | File | Calibration table with per-layer quantization scale factors |
Usage Examples
Basic KL-Divergence Calibration
ncnn2table \
model-opt.ncnn.param \
model-opt.ncnn.bin \
imagelist.txt \
model.table \
mean=[104,117,123] \
norm=[1,1,1] \
shape=[227,227,3] \
pixel=BGR \
thread=4
YOLO Model Calibration
ncnn2table \
yolov8n-opt.param \
yolov8n-opt.bin \
imagelist.txt \
yolov8n.table \
mean=[0,0,0] \
norm=[0.003921,0.003921,0.003921] \
shape=[640,640,3] \
pixel=RGB \
method=kl \
thread=8
ACIQ Calibration (Faster)
ncnn2table \
model-opt.param model-opt.bin \
imagelist.txt model.table \
mean=[104,117,123] norm=[1,1,1] \
shape=[227,227,3] pixel=BGR \
method=aciq thread=4