HarmonyOS 端侧设备（手机、平板、IoT）搭载 Ascend 310P NPU——算力 8 TOPS INT8，HBM 仅 8GB DDR，功耗 8W。部署大模型的第一步：FP32 的模型参数 3.5GB → INT8 量化到 0.9GB（4× 压缩），同时 NPU 的 INT8 矩阵乘吞吐比 FP16 高 4×（8 TOPS vs 2 TOPS）。但直接 PTQ（Post-Training Quantization，训练后量化）会掉精度——ResNet50 从 76.1% top-1 掉到 73.2%（-2.9%），BERT-base F1 从 88.3 掉到 83.7（-4.6%）。

cann-recipes-harmony-infer 提供了端侧量化的完整 pipeline：数据校准（KL divergence / MSE / percentile 三种 calibrator）+ QAT（Quantization-Aware Training，量化感知训练）+ 混合精度（敏感层 FP16，非敏感层 INT8）+ ATC 编译（INT8 模型 → OM 离线模型，含 INT8 算子映射）。

量化 pipeline 三阶段

原始 FP32 模型 (3.5 GB)
    │
    ▼ [阶段一：标定数据校准 calibrate]
    │  数据: 100-500 张代表性图片/文本
    │  方法: KL divergence / MSE / percentile
    │  输出: 每层的 scale + zero_point（量化参数）
    │
    ▼ [阶段二：QAT 微调 fine-tune]
    │  插入 FakeQuant 节点 → 前向 INT8 仿真 → 反向 FP32 梯度
    │  1-3 epoch fine-tune → 恢复量化掉点的精度
    │  输出: QAT 后的 FP32 权重 + 校准 scale
    │
    ▼ [阶段三：ATC 编译]
    │  FP32 → OM (INT8 offline model)
    │  算子映射: Conv2D → Conv2D_INT8, MatMul → MatMul_INT8
    │  输出: model.om (0.9 GB)

阶段一：校准（Calibration）——三种 calibrator

# cann-recipes-harmony-infer/quantization/calibrator.py
#
# INT8 量化校准：为每一层确定最佳 scale 和 zero_point
# 数值映射: q = round(x / scale) + zero_point
#   其中 scale = (max_float - min_float) / 255
#   zero_point = round(-min_float / scale)

import numpy as np
import torch
import torch_npu
from scipy import stats
from abc import ABC, abstractmethod

class Calibrator(ABC):
    """量化校准器基类"""

    def __init__(self, num_bits=8):
        self.num_bits = num_bits
        self.qmin = 0
        self.qmax = 2**num_bits - 1  # 255 for INT8

    @abstractmethod
    def calibrate(self, tensor_data: np.ndarray) -> tuple:
        """
        输入: tensor_data，shape [N_samples, ...]（多 batch 的激活值统计）
        输出: (scale, zero_point)
        """
        pass

    def _quantize(self, x, scale, zero_point):
        """量化: FP32 → INT8"""
        return np.clip(np.round(x / scale) + zero_point, self.qmin, self.qmax).astype(np.uint8)

    def _dequantize(self, q, scale, zero_point):
        """反量化: INT8 → FP32（用于精度评估）"""
        return (q.astype(np.float32) - zero_point) * scale


class MaxMinCalibrator(Calibrator):
    """
    对称量化：scale = max(|x|) / 127
    → 简单但容易受 outlier 影响
    """

    def calibrate(self, tensor_data):
        # 合并所有 batch
        all_data = tensor_data.flatten()

        # 对称量化：|min| == |max|
        abs_max = max(abs(all_data.min()), abs(all_data.max()))
        scale = abs_max / 127.0   # INT8 对称：[-127, +127]
        zero_point = 0             # 对称量化 zero_point = 0

        return scale, zero_point


class KLCalibrator(Calibrator):
    """
    KL divergence 校准器：
    找最优的截断值 T，使得原始分布 P 和量化后分布 Q 的 KL 散度最小

    原理：
    1. 将 FP32 值缩放到 [0, 2048] 的直方图
    2. 对每个可能的截断值 T（128..2048）：
       - P = 原始分布（截断到 T）
       - Q = 量化到 128 个 bin 的分布
       - KL(P||Q) 最小 → 最优 T
    3. scale = T / 127
    """

    def __init__(self, num_bits=8, num_bins=2048):
        super().__init__(num_bits)
        self.num_bins = num_bins

    def calibrate(self, tensor_data):
        all_data = tensor_data.flatten()
        abs_max = max(abs(all_data.min()), abs(all_data.max()))

        # 构建直方图（bin 宽度 = abs_max / num_bins）
        hist, bin_edges = np.histogram(
            np.abs(all_data), bins=self.num_bins, range=(0, abs_max)
        )
        hist = hist.astype(np.float64)
        hist /= hist.sum()  # 归一化为概率分布

        # 遍历所有截断值 T
        target_bins = 2 ** (self.num_bits - 1)  # 128 bins for INT8
        best_kl = float("inf")
        best_threshold = abs_max

        for t_idx in range(target_bins, self.num_bins + 1):
            # 截断分布 P：只保留 [0, t_idx] 的 bin
            p = hist[:t_idx].copy()
            p = np.append(p, hist[t_idx:].sum())  # 截断部分聚到一个 bin

            # 量化分布 Q：将 P 压缩到 128 个 bin
            q = np.zeros(target_bins)
            bin_width = t_idx / target_bins
            for i in range(target_bins):
                start = int(i * bin_width)
                end = int((i + 1) * bin_width)
                q[i] = p[start:end].sum()

            # 展平 Q 回与 P 相同的粒度（用于 KL 计算）
            q_expanded = np.zeros_like(p)
            for i in range(target_bins):
                start = int(i * bin_width)
                end = int((i + 1) * bin_width)
                q_expanded[start:end] = q[i] / max(1, end - start)

            # KL(P||Q)，跳过零概率 bin
            mask = (p > 0) & (q_expanded > 0)
            kl = np.sum(p[mask] * np.log(p[mask] / q_expanded[mask]))

            if kl < best_kl:
                best_kl = kl
                best_threshold = bin_edges[t_idx]

        # scale = 截断值 / 127
        scale = best_threshold / 127.0
        zero_point = 0

        print(f"  KL Calibrator: threshold={best_threshold:.4f}, "
              f"scale={scale:.6f}, KL={best_kl:.4f}")

        return scale, zero_point


class PercentileCalibrator(Calibrator):
    """
    百分位校准器：
    取第 99.99 百分位作为最大值
    → 比 KL 更简单，且不受 outlier 严重影响
    """

    def __init__(self, num_bits=8, percentile=99.99):
        super().__init__(num_bits)
        self.percentile = percentile

    def calibrate(self, tensor_data):
        all_data = np.abs(tensor_data.flatten())

        # 取第 99.99 百分位（丢弃 0.01% 的极端值）
        threshold = np.percentile(all_data, self.percentile)
        scale = threshold / 127.0
        zero_point = 0

        print(f"  Percentile Calibrator (P{self.percentile}): "
              f"threshold={threshold:.4f}, scale={scale:.6f}")

        return scale, zero_point


# ====== Calibrator Factory ======
class LayerwiseCalibrator:
    """
    逐层校准器：
    对模型的每一层分别运行 calibrator → 输出 per-layer scale/zero_point

    使用方法：
    >>> calibrator = LayerwiseCalibrator(model, KLCalibrator())
    >>> calib_data = load_calibration_images(500)
    >>> layer_scales = calibrator.calibrate_all_layers(calib_data)
    """

    def __init__(self, model, calibrator: Calibrator):
        self.model = model
        self.calibrator = calibrator
        self.hooks = []
        self.layer_outputs = {}  # layer_name → [output_batch1, output_batch2, ...]

    def _hook_fn(self, name):
        """前向 hook：收集每层输出"""
        def hook(module, input, output):
            if name not in self.layer_outputs:
                self.layer_outputs[name] = []
            self.layer_outputs[name].append(output.detach().cpu().numpy())
        return hook

    def calibrate_all_layers(self, calibration_data_loader):
        """
        对 calibration dataset 做前向推理 → 收集每层激活值 → 逐层校准
        """
        # 注册 hooks（收集 Conv2D + Linear 层的输出）
        for name, module in self.model.named_modules():
            if isinstance(module, (torch.nn.Conv2d, torch.nn.Linear)):
                self.hooks.append(module.register_forward_hook(self._hook_fn(name)))

        # 前向推理：收集 500 个 batch 的激活值
        self.model.eval()
        with torch.no_grad():
            for batch_idx, (images, _) in enumerate(calibration_data_loader):
                images = images.to("npu")
                self.model(images)

                # 通常 100-500 张图足够
                if batch_idx >= 500:
                    break

        # 移除 hooks
        for hook in self.hooks:
            hook.remove()

        # 逐层校准
        layer_scales = {}
        for name, outputs in self.layer_outputs.items():
            # 合并所有 batch 的激活值
            all_data = np.concatenate([o.flatten() for o in outputs])

            # 运行 calibrator
            scale, zp = self.calibrator.calibrate(all_data)
            layer_scales[name] = (float(scale), int(zp))

            # 评估量化的精度损失
            original = outputs[0].flatten()[:1000]
            quantized = self._quantize_dequantize(original, scale, zp)
            mse = np.mean((original - quantized) ** 2)
            print(f"  {name}: scale={scale:.6f}, MSE={mse:.6e}")

        return layer_scales

    def _quantize_dequantize(self, x, scale, zero_point):
        q = np.clip(np.round(x / scale) + zero_point, 0, 255).astype(np.uint8)
        return (q.astype(np.float32) - zero_point) * scale

阶段二：QAT（量化感知训练）——恢复量化掉点

# cann-recipes-harmony-infer/quantization/qat.py
#
# QAT: 在前向传播中插入 FakeQuant 节点
# 前向 = INT8 仿真（量化+反量化）
# 反向 = FP32 梯度（Straight-Through Estimator）

import torch
import torch.nn as nn
import torch_npu

class FakeQuantize(torch.autograd.Function):
    """
    FakeQuant 算子：前向 INT8 仿真，反向梯度直通

    前向：
      q = round(clip(x/scale, -127, 127)) * scale  ← 模拟 INT8 精度损失

    反向：
      grad_output → grad_input（直通，STE approximation）
      但 scale 的梯度：对 |x| > 127*scale 的数据，grad_scale = sign(x)*127
    """

    @staticmethod
    def forward(ctx, x, scale):
        # INT8 仿真：量化 → 反量化（精度损失）
        x_scaled = x / scale
        x_quant = torch.clamp(torch.round(x_scaled), -127, 127)
        x_dequant = x_quant * scale

        # 保存用于反向
        ctx.save_for_backward(x, scale)
        ctx.x_scaled = x_scaled

        return x_dequant

    @staticmethod
    def backward(ctx, grad_output):
        x, scale = ctx.saved_tensors

        # STE: 梯度直通（对 clip 区域梯度为零）
        grad_input = grad_output.clone()
        x_scaled = x / scale

        # 量化范围内的数据：梯度直通
        mask = (x_scaled > -127) & (x_scaled < 127)
        grad_input[~mask] = 0  # 截断区域梯度为零

        return grad_input, None  # scale 不回传梯度


class QATConv2d(nn.Conv2d):
    """
    量化感知卷积层（Conv2D + FakeQuant）
    替代标准 Conv2d → 前向自动模拟 INT8 推理
    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 可学习的 scale 参数
        self.register_parameter(
            "input_scale",
            nn.Parameter(torch.tensor(1.0))
        )
        self.register_parameter(
            "weight_scale",
            nn.Parameter(torch.tensor(1.0))
        )

    def forward(self, x):
        # 1. 量化输入
        x_q = FakeQuantize.apply(x, self.input_scale)

        # 2. 量化权重
        w_q = FakeQuantize.apply(self.weight, self.weight_scale)

        # 3. INT8 卷积（依然是 FP32 计算，但权重和输入已量化为 INT8 精度）
        #    这精确模拟了 INT8 推理的精度损失
        if self.bias is not None:
            return nn.functional.conv2d(
                x_q, w_q, self.bias,
                self.stride, self.padding, self.dilation, self.groups
            )
        else:
            return nn.functional.conv2d(
                x_q, w_q, None,
                self.stride, self.padding, self.dilation, self.groups
            )


class QATLinear(nn.Linear):
    """量化感知全连接层"""
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.register_parameter("input_scale", nn.Parameter(torch.tensor(1.0)))
        self.register_parameter("weight_scale", nn.Parameter(torch.tensor(1.0)))

    def forward(self, x):
        x_q = FakeQuantize.apply(x, self.input_scale)
        w_q = FakeQuantize.apply(self.weight, self.weight_scale)
        return nn.functional.linear(x_q, w_q, self.bias)


def convert_to_qat(model):
    """
    将标准 PyTorch 模型转换为 QAT 模型
    只替换 Conv2d 和 Linear（不量化 BatchNorm、ReLU 等）
    """

    for name, module in model.named_children():
        if isinstance(module, nn.Conv2d):
            # 替换为 QAT 卷积层
            qat_conv = QATConv2d(
                module.in_channels, module.out_channels,
                module.kernel_size,
                stride=module.stride, padding=module.padding,
                dilation=module.dilation, groups=module.groups,
                bias=module.bias is not None
            )
            qat_conv.weight.data = module.weight.data.clone()
            if module.bias is not None:
                qat_conv.bias.data = module.bias.data.clone()
            setattr(model, name, qat_conv)

        elif isinstance(module, nn.Linear):
            qat_linear = QATLinear(
                module.in_features, module.out_features,
                bias=module.bias is not None
            )
            qat_linear.weight.data = module.weight.data.clone()
            if module.bias is not None:
                qat_linear.bias.data = module.bias.data.clone()
            setattr(model, name, qat_linear)

        else:
            # 递归处理子模块
            convert_to_qat(module)

    return model


# ====== QAT 训练循环 ======
def qat_fine_tune(model, train_loader, epochs=3, lr=1e-5):
    """
    QAT fine-tune（1-3 epoch）
    lr 通常设为原始训练的 1/100-1/10
    """

    # 1. 转换为 QAT 模型
    qat_model = convert_to_qat(model).to("npu")

    # 2. 加载校准 scale（从阶段一的 calibrator 输出）
    layer_scales = torch.load("calibration_scales.pt")
    for name, module in qat_model.named_modules():
        if isinstance(module, (QATConv2d, QATLinear)):
            if name in layer_scales:
                scale_val = layer_scales[name][0]
                module.input_scale.data.fill_(scale_val)
                module.weight_scale.data.fill_(scale_val * 0.5)  # weight scale 通常比 input scale 小一半

    # 3. 优化器（只优化 scale 参数 + BN running stats）
    optimizer = torch.optim.SGD(
        [p for n, p in qat_model.named_parameters() if "scale" in n or "bn" in n],
        lr=lr, momentum=0.9
    )

    # 4. QAT fine-tune
    qat_model.train()
    for epoch in range(epochs):
        total_loss = 0
        for images, labels in train_loader:
            images, labels = images.to("npu"), labels.to("npu")

            optimizer.zero_grad()
            outputs = qat_model(images)
            loss = nn.functional.cross_entropy(outputs, labels)
            loss.backward()
            optimizer.step()

            total_loss += loss.item()

        print(f"QAT Epoch {epoch+1}/{epochs}: loss={total_loss/len(train_loader):.4f}")

    return qat_model

阶段三：混合精度——敏感层判断

# cann-recipes-harmony-infer/quantization/mixed_precision.py
#
# 并非所有层都适合 INT8 量化
# 敏感层检测：量化后该层输出 MSE 过大 → 保留 FP16

def detect_sensitive_layers(model, calibration_data_loader, mse_threshold=1e-3):
    """
    检测 INT8 量化敏感层
    策略：对每层分别量化 → 计算输出 MSE → MSE > threshold → FP16

    Returns:
        sensitive_layers: set of layer names to keep in FP16
    """

    # 首先对所有层做量化校准
    calibrator = LayerwiseCalibrator(model, KLCalibrator())
    layer_scales = calibrator.calibrate_all_layers(calibration_data_loader)

    # 计算每层的量化 MSE
    sensitive_layers = set()
    for name, outputs in calibrator.layer_outputs.items():
        fp32_output = outputs[0]  # 第一个 batch 的输出
        scale, zp = layer_scales[name]

        # 量化
        q_output = calibrator._quantize_dequantize(fp32_output, scale, zp)

        # MSE
        mse = np.mean((fp32_output - q_output) ** 2)
        var = np.var(fp32_output)

        # 相对误差 = MSE / variance（归一化 MSE）
        relative_error = mse / max(var, 1e-8)

        is_sensitive = relative_error > mse_threshold
        if is_sensitive:
            sensitive_layers.add(name)
            print(f"  {name}: relative_error={relative_error:.6f} → FP16 (sensitive)")
        else:
            print(f"  {name}: relative_error={relative_error:.6f} → INT8")

    return sensitive_layers

# 典型敏感层模式：
# - 第一层 Conv2d（输入分布不稳定，scale 漂移大）→ FP16
# - 最后一层 Linear（分类头，精度敏感）→ FP16
# - 中间层 → INT8（占 95% 的计算量）
#
# 混合精度结果示例（ResNet50 on 310P）：
# INT8 layers: 48/50 (96%),  FP16 layers: 2/50 (4%)
# 加速: 3.7× vs FP16,  精度: 76.0% (vs FP32 76.1%, 仅 -0.1%)

阶段四：ATC 编译（INT8 → OM 离线模型）

# cann-recipes-harmony-infer/scripts/compile_int8.sh
#
# ATC (Ascend Tensor Compiler) 编译 INT8 模型
# 输入: FP32 ONNX/TF/Caffe 模型 + calibration JSON
# 输出: OM 离线模型（含 INT8 算子映射）

# === ResNet50 INT8 量化示例 ===

# Step 1: 导出 QAT 模型为 ONNX
python -c "
import torch, torch_npu

model = torch.load('resnet50_qat.pt', map_location='cpu')
model.eval()

dummy_input = torch.randn(1, 3, 224, 224)
torch.onnx.export(model, dummy_input, 'resnet50_qat.onnx',
    input_names=['input'],
    output_names=['output'],
    opset_version=13,
    dynamic_axes={'input': {0: 'batch'}, 'output': {0: 'batch'}}
)
"

# Step 2: ATC 编译 ONNX → OM（指定 INT8 量化参数）
atc \
    --model=resnet50_qat.onnx \
    --framework=5 \                          # 5 = ONNX
    --output=resnet50_int8 \                 # 输出 OM 文件名（无后缀）
    --soc_version=Ascend310P3 \              # 端侧 NPU 型号
    --input_shape="input:1,3,224,224" \
    --input_format=NCHW \
    --output_type=FP32 \                     # 输出保持 FP32（不需要量化最后一层）
    --precision_mode=force_fp16 \            # 混合精度：不支持的算子回退 FP16
    \
    # ====== INT8 量化关键参数 ======
    --insert_op_conf=calibration.cfg \       # 量化配置文件（逐层 scale/zero_point）
    --compression_optimize_conf= \
        enable_first_layer_quantization:true,\  # 首层也量化（ResNet 首层非敏感）
        enable_compress_weight:true,\            # 压缩权重存储格式
        compress_weight_conf= \
            enable_record_compress_fp32_weight:false

# calibration.cfg 示例内容（由 calibrator 输出）
cat > calibration.cfg << 'CFG'
# 逐层量化配置
# 格式: op_name:OpType:quant_type:scale:zero_point:offset
#   quant_type=SCALAR → per-tensor 量化
#   quant_type=VECTOR → per-channel 量化

# 首层 Conv2d（输入数据范围通常较小）
input_0:Input:SCALAR:0.007843:0:0

# 中间 Conv2d 层（per-tensor）
Conv2d_1:Convolution:SCALAR:0.023456:0:0
Conv2d_2:Convolution:SCALAR:0.018901:0:0
# ...

# 分类头（不量化，保持 FP16）
Linear_fc:FullConnection:FP16:1.0:0:0
CFG

echo "✅ OM file: resnet50_int8.om"
echo "   Size: $(ls -lh resnet50_int8.om | awk '{print $5}')"
# → Size: 24M (vs FP32 ONNX 98M, 4.1× 压缩)

ATC 编译生成的 calibration.cfg 自动编写脚本

# cann-recipes-harmony-infer/quantization/generate_calib_cfg.py
#
# 自动从 calibrator 输出生成 calibration.cfg

def generate_compression_cfg(layer_scales, model_info, output_path="calibration.cfg"):
    """
    从逐层 scale 生成 ATC 量化配置文件

    layer_scales: {layer_name: (scale, zero_point)}
    model_info: dict of {layer_name: {"type": "Convolution"|"FullConnection"|"MatMul"}}
    """

    lines = []
    lines.append("# Auto-generated calibration config")
    lines.append(f"# Model: {model_info.get('name', 'unknown')}")
    lines.append(f"# Layers: {len(layer_scales)}")
    lines.append("")

    for name, (scale, zp) in layer_scales.items():
        layer_type = model_info.get(name, {}).get("type", "Convolution")

        if zp == 0:
            quant_type = "SCALAR"  # per-tensor 对称量化
        else:
            quant_type = "SCALAR"  # per-tensor 非对称量化

        lines.append(f"{name}:{layer_type}:{quant_type}:{scale:.6f}:{int(zp)}:0")

    # 添加 Fallback（未知算子回退 FP16）
    lines.append("")
    lines.append("# Fallback: 未知算子保持 FP16")
    lines.append("unknown:Convolution:FP16:1.0:0:0")

    with open(output_path, "w") as f:
        f.write("\n".join(lines))

    print(f"✅ Calibration config written to {output_path}")

    # 统计
    int8_count = sum(1 for l in lines if ":SCALAR:" in l)
    fp16_count = sum(1 for l in lines if ":FP16:" in l)
    print(f"   INT8 layers: {int8_count}")
    print(f"   FP16 layers: {fp16_count}")
    print(f"   Total: {int8_count + fp16_count}")

踩坑一：校准数据太少——100 张图 vs 5000 张图，scale 差异 2.3×

# ❌ 只用 100 张图校准
# KL Calibrator: threshold=3.421, scale=0.02694
# → 实际推理时，50% 的激活值超出阈值 → 被 clip → 精度损失严重

# ✅ 500 张图校准（Coverage 分析）
def coverage_check(layer_scales, full_dataset_loader):
    """
    验证校准 scale 是否覆盖实际推理分布
    """
    coverage_stats = {}

    for name, (scale, zp) in layer_scales.items():
        threshold = scale * 127  # INT8 对称量化范围

        # 在 5000 张图上统计超过阈值的比例
        overflow_count = 0
        total_count = 0

        with torch.no_grad():
            for images, _ in full_dataset_loader:
                outputs = get_layer_output(model, name, images)
                overflow = np.abs(outputs) > threshold
                overflow_count += overflow.sum()
                total_count += outputs.size

        overflow_ratio = overflow_count / total_count

        if overflow_ratio > 0.001:  # 超过 0.1% → 校准不足
            print(f"⚠️  {name}: {overflow_ratio*100:.2f}% values clipped! "
                  f"(need more calibration data or use PercentileCalibrator)")
            coverage_stats[name] = {"status": "insufficient", "clipped": overflow_ratio}
        else:
            coverage_stats[name] = {"status": "OK", "clipped": overflow_ratio}

    return coverage_stats

# 如果发现校准不足 → 增加数据或切换到 PercentileCalibrator(P99.99)

踩坑二：QAT 训练中 scale 参数震荡——每 100 步 scale 变化 30%，模型不收敛

# ❌ scale 参数震荡
# Epoch 1 Step 100:  input_scale(Conv1) = 0.0234
# Epoch 1 Step 200:  input_scale(Conv1) = 0.0341  (↑ 46%)
# Epoch 1 Step 300:  input_scale(Conv1) = 0.0189  (↓ 45%)
# → 每次 scale 更新，FakeQuant 的 clip 范围变化 → 梯度突变 → 不收敛

# ✅ 冻结 scale 前 80% 的训练步骤，只在最后 20% 微调
class GradualScaleUnfreeze:
    """渐进解冻 scale：前 80% steps 冻结，最后 20% 解冻微调"""

    def __init__(self, optimizer, total_steps, unfreeze_at=0.8):
        self.optimizer = optimizer
        self.unfreeze_step = int(total_steps * unfreeze_at)
        self.scale_params = {
            name: param
            for name, param in model.named_parameters()
            if "scale" in name
        }

        # 初始冻结所有 scale 参数
        for param in self.scale_params.values():
            param.requires_grad = False

    def step(self, current_step):
        """每个 optimizer step 后调用"""
        if current_step == self.unfreeze_step:
            # 解冻 scale 参数
            for param in self.scale_params.values():
                param.requires_grad = True

            # 降低学习率
            for pg in self.optimizer.param_groups:
                pg["lr"] *= 0.1

            print(f"🔓 Step {current_step}: Scale parameters unfrozen, lr reduced to {pg['lr']}")

    # 效果：最后 20% 的微调让 scale 收敛到最优值
    # scale 变化从 ±45% 降到 ±3%

踩坑三：端侧 OM 模型加载失败——ATC 编译时 NPU 型号写错（Ascend310P vs Ascend310P3）

# ❌ soc_version=Ascend310P（旧型号名）
# → ATC 编译成功，但部署到 HarmonyOS 设备时报错
# Error: "Soc version mismatch: compiled for Ascend310P, running on Ascend310P3"
# → OM 模型无法加载

# ✅ 正确型号名：Ascend310P3（端侧 HarmonyOS 设备）
atc --soc_version=Ascend310P3 ...

# 补充：不同设备对应不同的 soc_version
# 设备            soc_version
# Atlas 200       Ascend310
# Atlas 300I      Ascend310P
# HarmonyOS 端侧  Ascend310P3  ← 手机/平板/IoT
# 验证命令：
npu-smi info -t board -i 0 | grep "Chip Name"
# Chip Name: Ascend310P3     ← 这就是 soc_version

cann-recipes-harmony-infer 的 INT8 量化 pipeline 四阶段：数据校准（KL/Percentile/MaxMin 三种 calibrator，500 张图逐层确定 scale）→ QAT fine-tune（FakeQuant 节点 + STE 梯度直通，1-3 epoch 恢复精度）→ 混合精度敏感层检测（MSE/variance > 1e-3 → FP16，其余 INT8 占 96%）→ ATC 编译（calibration.cfg + INT8 算子映射 → 0.9GB OM 模型）。ResNet50 量化 4.1× 压缩（98MB→24MB），精度仅 -0.1%（76.1%→76.0%）。三个踩坑：校准数据 100 张不充分→coverage check 补充到 500 张、QAT scale 震荡 ±45%→前 80% 冻结后 20% 微调解冻、soc_version 旧名 Ascend310P 不兼容 HarmonyOS→正确使用 Ascend310P3。