4. 浮点模型转定点模型指导手册

地平线为您提供了两种浮点模型转定点模型的方法，分别为PTQ模型量化手段和QAT模型量化手段， 本章内容包括 训练后量化（PTQ） 和 量化感知训练（QAT） ，为您详细介绍两种方法的原理及使用指导。

• 4.1. 训练后量化（PTQ）
  • 4.1.1. PTQ原理及步骤
    • 4.1.1.1. PTQ转换的流程与步骤
    • 4.1.1.2. 算子约束
    • 4.1.1.3. 浮点模型准备
    • 4.1.1.4. 验证模型
      • 4.1.1.4.1. 使用 hb_mapper checker 工具验证模型
      • 4.1.1.4.2. 检查异常处理
      • 4.1.1.4.3. 检查结果解读
      • 4.1.1.4.4. 检查结果的调优指导
    • 4.1.1.5. 校准数据准备
    • 4.1.1.6. 模型量化与编译
      • 4.1.1.6.1. 使用hb_mapper makertbin工具转换模型
        • 4.1.1.6.1.1. 配置文件具体参数信息
        • 4.1.1.6.1.2. param_value配置
      • 4.1.1.6.2. 转换内部过程解读
      • 4.1.1.6.3. 转换结果解读
      • 4.1.1.6.4. 转换产出物解读
    • 4.1.1.7. 模型性能分析与调优
      • 4.1.1.7.1. 使用 hb_perf 工具估计性能
      • 4.1.1.7.2. 开发板实测性能
      • 4.1.1.7.3. 模型性能优化
    • 4.1.1.8. 模型精度分析与调优
      • 4.1.1.8.1. 模型精度分析
      • 4.1.1.8.2. 精度调优
      • 4.1.1.8.3. 使用QAT量化感知训练方案进一步提升模型精度
        • 4.1.1.8.3.1. 关于量化
        • 4.1.1.8.3.2. 关于模型转换
        • 4.1.1.8.3.3. 关于模型量化编译流程
        • 4.1.1.8.3.4. QAT模型量化编译介绍
    • 4.1.1.9. 其他模型工具（可选）
      • 4.1.1.9.1. 模型打包
      • 4.1.1.9.2. 模型信息查看
      • 4.1.1.9.3. bin模型节点修改
    • 4.1.1.10. 训练后量化（PTQ）常见问题
      • 4.1.1.10.1. 如何理解算子约束中提及的BPU加速和CPU计算两种形式？
      • 4.1.1.10.2. 如何理解模型分段的性能影响？
      • 4.1.1.10.3. 如何理解模型尾部部分BPU可加速算子运行在CPU上？
      • 4.1.1.10.4. 是否支持非对称量化？
      • 4.1.1.10.5. 如何理解地平线的default校准方式？
      • 4.1.1.10.6. 如何理解地平线的mix校准方式？
      • 4.1.1.10.7. 如何理解yaml文件中的编译器优化等级参数？
      • 4.1.1.10.8. 为何nv12 模型 hb_perf 得出的输入大小和预测库不一致？
      • 4.1.1.10.9. 量化模型和上板bin模型的输入的数据排布是否一定一致？
      • 4.1.1.10.10. 如何编译得到多 batch 模型？
      • 4.1.1.10.11. 多输入模型在转换过程中，模型输入顺序发生变化，此种情况正常么？
      • 4.1.1.10.12. 如何理解PTQ模型转换过程中的主动量化和被动量化？
    • 4.1.1.11. 自定义算子开发
      • 4.1.1.11.1. 简介
      • 4.1.1.11.2. 含自定义算子的模型转换
        • 4.1.1.11.2.1. 模型文件修改
          • 4.1.1.11.2.1.1. Caffe 模型
          • 4.1.1.11.2.1.2. ONNX 模型
        • 4.1.1.11.2.2. 算子实现
      • 4.1.1.11.3. 含自定义算子的上板运行
        • 4.1.1.11.3.1. 自定义算子C++模版
        • 4.1.1.11.3.2. 自定义算子注册
  • 4.1.2. PTQ工具文档
    • 4.1.2.1. 模型转换过程详解
      • 4.1.2.1.1. 模型检查（hb_mapper checker）
      • 4.1.2.1.2. 准备校准图片
      • 4.1.2.1.3. 模型转换(hb_mapper makertbin)
      • 4.1.2.1.4. 单张图片的模型推理
      • 4.1.2.1.5. 模型精度验证
      • 4.1.2.1.6. 模型性能验证
      • 4.1.2.1.7. [参考]支持的校准方法
      • 4.1.2.1.8. [参考]OP列表
    • 4.1.2.2. hb_mapper 工具
      • 4.1.2.2.1. 模型检查命令（hb_mapper checker）
      • 4.1.2.2.2. 模型编译命令（hb_mapper makertbin）
      • 4.1.2.2.3. 模型推理命令（hb_mapper infer）
      • 4.1.2.2.4. 关键配置参数 calibration_parameters.preprocess_on 介绍
      • 4.1.2.2.5. 配置文件详细介绍
        • 4.1.2.2.5.1. 参考配置文件以及说明
        • 4.1.2.2.5.2. 关于 input_type_rt/ input_type_train
    • 4.1.2.3. hb_perf 工具
      • 4.1.2.3.1. 使用方法
      • 4.1.2.3.2. 命令行参数
      • 4.1.2.3.3. 输出内容说明
    • 4.1.2.4. vec_diff 工具
      • 4.1.2.4.1. 使用方式
      • 4.1.2.4.2. 命令行参数
      • 4.1.2.4.3. 输出内容说明
    • 4.1.2.5. hb_model_info 工具
      • 4.1.2.5.1. 使用方法
      • 4.1.2.5.2. 命令行参数
      • 4.1.2.5.3. 输出内容说明
    • 4.1.2.6. hb_pack 工具
      • 4.1.2.6.1. 使用方法
      • 4.1.2.6.2. 命令行参数
      • 4.1.2.6.3. 输出内容说明
    • 4.1.2.7. hb_verifier 工具
      • 4.1.2.7.1. 使用方式
      • 4.1.2.7.2. 命令行参数
      • 4.1.2.7.3. 参考使用场景样例
      • 4.1.2.7.4. 输出内容说明
    • 4.1.2.8. hb_model_modifier 工具
      • 4.1.2.8.1. 使用方式
      • 4.1.2.8.2. 命令行参数
      • 4.1.2.8.3. 输出内容说明
    • 4.1.2.9. hb_custom_op 工具
      • 4.1.2.9.1. 使用方法
      • 4.1.2.9.2. 命令行参数
      • 4.1.2.9.3. 输出内容说明
    • 4.1.2.10. hb_eval_preprocess 工具
      • 4.1.2.10.1. 使用方法
      • 4.1.2.10.2. 命令行参数
      • 4.1.2.10.3. 输出内容说明
    • 4.1.2.11. 精度debug工具
      • 4.1.2.11.1. 快速上手
        • 4.1.2.11.1.1. 校准模型与数据的保存
        • 4.1.2.11.1.2. 精度debug模块导入与API使用
        • 4.1.2.11.1.3. 分析结果展示
      • 4.1.2.11.2. API说明文档
        • 4.1.2.11.2.1. get_sensitivity_of_nodes
        • 4.1.2.11.2.2. plot_acc_error
        • 4.1.2.11.2.3. plot_distribution
        • 4.1.2.11.2.4. get_channelwise_data_distribution
  • 4.1.3. PTQ模型转换示例手册
    • 4.1.3.1. 发布物介绍
      • 4.1.3.1.1. 模型量化示例包 horizon_model_convert_sample
      • 4.1.3.1.2. 模型发布物 model_zoo
    • 4.1.3.2. 常见算法模型示例
      • 4.1.3.2.1. 位置路径
      • 4.1.3.2.2. 如何准备数据集
        • 4.1.3.2.2.1. 数据集下载地址
        • 4.1.3.2.2.2. 数据集参考结构
          • 4.1.3.2.2.2.1. ImageNet
          • 4.1.3.2.2.2.2. COCO
          • 4.1.3.2.2.2.3. VOC
          • 4.1.3.2.2.2.4. Cityscapes
          • 4.1.3.2.2.2.5. CIFAR-10
      • 4.1.3.2.3. 如何准备模型
        • 4.1.3.2.3.1. fcos_efficientnetb0
        • 4.1.3.2.3.2. fcos_efficientnetb1
        • 4.1.3.2.3.3. fcos_efficientnetb2
        • 4.1.3.2.3.4. MobileNetv1/v2
        • 4.1.3.2.3.5. GoogleNet
        • 4.1.3.2.3.6. ResNet18
        • 4.1.3.2.3.7. mobilenet_onnx
        • 4.1.3.2.3.8. EfficientNet_Lite0/1/2/3/4
        • 4.1.3.2.3.9. YOLOv2_Darknet19
        • 4.1.3.2.3.10. YOLOv3_Darknet53
        • 4.1.3.2.3.11. YOLOv5s
        • 4.1.3.2.3.12. SSD_MobileNetv1
        • 4.1.3.2.3.13. EfficientNetDetd0
        • 4.1.3.2.3.14. CenterNet_Resnet50
        • 4.1.3.2.3.15. Fcos_efficientnetb0
        • 4.1.3.2.3.16. UNet_mobilenet
        • 4.1.3.2.3.17. DeeplabV3plus_efficientnetb0
        • 4.1.3.2.3.18. Fastscnn_efficientnetb0
      • 4.1.3.2.4. 算法模型示例的使用演示
        • 4.1.3.2.4.1. 进入Docker容器
        • 4.1.3.2.4.2. 验证模型是否能够执行
        • 4.1.3.2.4.3. 准备校准用的数据集
        • 4.1.3.2.4.4. build异构模型
        • 4.1.3.2.4.5. 单张图片推理
        • 4.1.3.2.4.6. 精度测试
      • 4.1.3.2.5. 常见问题
        • 4.1.3.2.5.1. 如何对齐开源框架训练得到的ONNX原始浮点模型与使用 hb_mapper makertbin 工具得到的***_original_float_model.onnx的结果？
        • 4.1.3.2.5.2. 复现的精度为什么与文档中提供的指标有细微差异？
        • 4.1.3.2.5.3. 定点模型精度为何与ai_benchmark示例中的bin文件上板精度无法对齐？
    • 4.1.3.3. 其他算法模型示例
      • 4.1.3.3.1. 如何使用
      • 4.1.3.3.2. 杂项示例
        • 4.1.3.3.2.1. lenet_gray
          • 4.1.3.3.2.1.1. 目录结构
          • 4.1.3.3.2.1.2. 示例内容
        • 4.1.3.3.2.2. resnet50_feature
          • 4.1.3.3.2.2.1. 目录结构
          • 4.1.3.3.2.2.2. 示例内容
        • 4.1.3.3.2.3. vector-diff
          • 4.1.3.3.2.3.1. 目录结构
          • 4.1.3.3.2.3.2. 输出内容
        • 4.1.3.3.2.4. multi_input_example
          • 4.1.3.3.2.4.1. 目录结构
          • 4.1.3.3.2.4.2. 示例内容
        • 4.1.3.3.2.5. model_verifier
          • 4.1.3.3.2.5.1. 目录结构
          • 4.1.3.3.2.5.2. 示例内容
        • 4.1.3.3.2.6. model_info
          • 4.1.3.3.2.6.1. 目录结构
          • 4.1.3.3.2.6.2. 示例内容
        • 4.1.3.3.2.7. mobilenet_bgr
          • 4.1.3.3.2.7.1. 目录结构
          • 4.1.3.3.2.7.2. 示例内容
        • 4.1.3.3.2.8. mobilenet_yuv444
          • 4.1.3.3.2.8.1. 目录结构
          • 4.1.3.3.2.8.2. 示例内容
      • 4.1.3.3.3. 用户自定义OP示例
        • 4.1.3.3.3.1. 目录结构
        • 4.1.3.3.3.2. 示例介绍
  • 4.1.4. 附录
    • 4.1.4.1. norm_type配置说明
      • 4.1.4.1.1. 参数说明解析
      • 4.1.4.1.2. 计算公式及示例说明
        • 4.1.4.1.2.1. 模型训练时的数据标准化处理计算公式
        • 4.1.4.1.2.2. 模型推理时的计算公式
    • 4.1.4.2. 图片处理transformer说明
      • 4.1.4.2.1. AddTransformer
      • 4.1.4.2.2. MeanTransformer
      • 4.1.4.2.3. ScaleTransformer
      • 4.1.4.2.4. NormalizeTransformer
      • 4.1.4.2.5. TransposeTransformer
      • 4.1.4.2.6. HWC2CHWTransformer
      • 4.1.4.2.7. CHW2HWCTransformer
      • 4.1.4.2.8. CenterCropTransformer
      • 4.1.4.2.9. PILCenterCropTransformer
      • 4.1.4.2.10. LongSideCropTransformer
      • 4.1.4.2.11. PadResizeTransformer
      • 4.1.4.2.12. ResizeTransformer
      • 4.1.4.2.13. PILResizeTransformer
      • 4.1.4.2.14. ShortLongResizeTransformer
      • 4.1.4.2.15. PadTransformer
      • 4.1.4.2.16. ShortSideResizeTransformer
      • 4.1.4.2.17. PaddedCenterCropTransformer
      • 4.1.4.2.18. BGR2RGBTransformer
      • 4.1.4.2.19. RGB2BGRTransformer
      • 4.1.4.2.20. RGB2GRAYTransformer
      • 4.1.4.2.21. BGR2GRAYTransformer
      • 4.1.4.2.22. RGB2GRAY_128Transformer
      • 4.1.4.2.23. RGB2YUV444Transformer
      • 4.1.4.2.24. BGR2YUV444Transformer
      • 4.1.4.2.25. BGR2YUV444_128Transformer
      • 4.1.4.2.26. RGB2YUV444_128Transformer
      • 4.1.4.2.27. BGR2YUVBT601VIDEOTransformer
      • 4.1.4.2.28. RGB2YUVBT601VIDEOTransformer
      • 4.1.4.2.29. YUVTransformer
      • 4.1.4.2.30. ReduceChannelTransformer
      • 4.1.4.2.31. BGR2NV12Transformer
      • 4.1.4.2.32. RGB2NV12Transformer
      • 4.1.4.2.33. NV12ToYUV444Transformer
      • 4.1.4.2.34. WarpAffineTransformer
      • 4.1.4.2.35. F32ToS8Transformer
      • 4.1.4.2.36. F32ToU8Transformer
    • 4.1.4.3. 常见故障处理
      • 4.1.4.3.1. hb_mapper checker 常见故障
      • 4.1.4.3.2. hb_mapper makertbin常见故障
      • 4.1.4.3.3. hb_model_modifier常见故障
      • 4.1.4.3.4. hb_verifier常见故障
      • 4.1.4.3.5. hb_onnxruntime常见故障
      • 4.1.4.3.6. libDNN常见故障
• 4.2. 量化感知训练（QAT）
  • 4.2.1. 术语约定
    • 4.2.1.1. Float 模型 / 浮点模型
    • 4.2.1.2. Calibration
    • 4.2.1.3. Calibration 模型
    • 4.2.1.4. QAT / 量化训练
    • 4.2.1.5. QAT 模型
    • 4.2.1.6. 伪量化
    • 4.2.1.7. 伪量化模型
    • 4.2.1.8. Quantized 模型 / 定点模型 / 量化模型
    • 4.2.1.9. Traced 模型
    • 4.2.1.10. TorchScript 模型
    • 4.2.1.11. pt 模型
    • 4.2.1.12. Bernoulli2，Bayes
    • 4.2.1.13. X3，J3，J5
    • 4.2.1.14. BPU 架构和处理器的对应关系
  • 4.2.2. 环境依赖
  • 4.2.3. 快速入门
    • 4.2.3.1. 基本流程
    • 4.2.3.2. 获取浮点模型
    • 4.2.3.3. Calibration
    • 4.2.3.4. 量化训练
    • 4.2.3.5. 转定点模型
    • 4.2.3.6. 模型部署
  • 4.2.4. 开发指南
    • 4.2.4.1. 浮点模型的要求
      • 4.2.4.1.1. symbolic_trace
      • 4.2.4.1.2. 仅支持部分算子
    • 4.2.4.2. Calibration 指南
      • 4.2.4.2.1. 流程和示例
      • 4.2.4.2.2. 常用算法介绍
      • 4.2.4.2.3. 调参技巧
      • 4.2.4.2.4. Observer 参数文档
    • 4.2.4.3. 量化训练指南
      • 4.2.4.3.1. 流程和示例
        • 4.2.4.3.1.1. prepare_qat_fx
        • 4.2.4.3.1.2. 加载 Calibration 模型参数
        • 4.2.4.3.1.3. 训练迭代
      • 4.2.4.3.2. 伪量化算子
        • 4.2.4.3.2.1. 伪量化过程
        • 4.2.4.3.2.2. 基于统计的方法
        • 4.2.4.3.2.3. 基于学习的方法
    • 4.2.4.4. 异构模型指南
      • 4.2.4.4.1. 异构模型介绍
      • 4.2.4.4.2. 使用流程
      • 4.2.4.4.3. 算子限制
      • 4.2.4.4.4. 主要接口参数说明
      • 4.2.4.4.5. 流程和示例
    • 4.2.4.5. 分析工具使用指南
      • 4.2.4.5.1. 总览
      • 4.2.4.5.2. 集成接口
      • 4.2.4.5.3. fuse 检查
      • 4.2.4.5.4. 共享 op 检查
      • 4.2.4.5.5. 量化配置检查
      • 4.2.4.5.6. 可视化：ONNX 模型可视化
      • 4.2.4.5.7. 相似度对比
      • 4.2.4.5.8. 统计量
      • 4.2.4.5.9. 模型 weight 比较
      • 4.2.4.5.10. 分步量化
      • 4.2.4.5.11. 单算子转换精度调试
      • 4.2.4.5.12. 异构模型部署 device 检查
      • 4.2.4.5.13. torchscript 和 hbdk 结果对比
      • 4.2.4.5.14. 不同版本 torchscript 模型的结果对比
      • 4.2.4.5.15. 模型显存占用分析工具
    • 4.2.4.6. 量化训练精度调优建议
      • 4.2.4.6.1. 参考流程
      • 4.2.4.6.2. 前言
      • 4.2.4.6.3. 推荐超参配置
      • 4.2.4.6.4. 精度异常现象
      • 4.2.4.6.5. 调参策略
      • 4.2.4.6.6. Debug 量化异常层
    • 4.2.4.7. 量化部署 PT 模型的跨设备 Inference 说明
      • 4.2.4.7.1. PT 模型执行使用的 device 和 trace 不一致
      • 4.2.4.7.2. 多卡并行推理
    • 4.2.4.8. 常见问题
      • 4.2.4.8.1. import 出错
      • 4.2.4.8.2. 无法正常 prepare_calibration/qat
      • 4.2.4.8.3. prepare_qat 后 forward 报错
      • 4.2.4.8.4. 编译报错
      • 4.2.4.8.5. 量化精度异常
      • 4.2.4.8.6. 使用 torch.jit.load 加载 pt 文件报错
    • 4.2.4.9. 常见使用误区
      • 4.2.4.9.1. 设置类错误
      • 4.2.4.9.2. 方法类错误
      • 4.2.4.9.3. 网络类错误
      • 4.2.4.9.4. 算子类错误
      • 4.2.4.9.5. 模型类错误
  • 4.2.5. 深入探索
    • 4.2.5.1. 自定义 qconfig
      • 4.2.5.1.1. Activation 的量化信息
      • 4.2.5.1.2. Weight 的量化信息
      • 4.2.5.1.3. QConfig
    • 4.2.5.2. FX Quantization 原理介绍
      • 4.2.5.2.1. 量化流程
        • 4.2.5.2.1.1. Fuse（可选）
        • 4.2.5.2.1.2. Prepare
        • 4.2.5.2.1.3. Convert
        • 4.2.5.2.1.4. Eager Mode 兼容性
    • 4.2.5.3. RGB888 数据部署
      • 4.2.5.3.1. 场景
      • 4.2.5.3.2. YUV 格式简介
      • 4.2.5.3.3. 在训练时对 RGB 输入进行预处理
      • 4.2.5.3.4. 在推理时对 YUV 输入进行实时转换
        • 4.2.5.3.4.1. 算子定义
        • 4.2.5.3.4.2. 使用方法
    • 4.2.5.4. 模型分段部署
      • 4.2.5.4.1. 场景
      • 4.2.5.4.2. 方法
    • 4.2.5.5. 算子融合
      • 4.2.5.5.1. 吸收 BN
      • 4.2.5.5.2. 融合 Add、ReLU(6)
      • 4.2.5.5.3. 实现原理
      • 4.2.5.5.4. 可以融合的算子
  • 4.2.6. API Reference
    • 4.2.6.1. March
    • 4.2.6.2. qconfig
      • 4.2.6.2.1. qconfig 定义示例
    • 4.2.6.3. 伪量化算子
    • 4.2.6.4. QAT
    • 4.2.6.5. ONNX
    • 4.2.6.6. TorchScript 模型保存和加载
    • 4.2.6.7. Horizon 算子
    • 4.2.6.8. 模型编译
  • 4.2.7. 附录
    • 4.2.7.1. Eager 模式
      • 4.2.7.1.1. 与 fx 模式的区别
      • 4.2.7.1.2. 使用流程
        • 4.2.7.1.2.1. 构建浮点模型
        • 4.2.7.1.2.2. 浮点模型预训练
        • 4.2.7.1.2.3. 设置 BPU 架构
        • 4.2.7.1.2.4. 算子融合
        • 4.2.7.1.2.5. 浮点模型转为量化模型
        • 4.2.7.1.2.6. 量化训练
        • 4.2.7.1.2.7. 量化模型转为定点模型
        • 4.2.7.1.2.8. 对定点预测模型进行检查和编译
    • 4.2.7.2. 支持的公版算子
      • 4.2.7.2.1. 综合说明
      • 4.2.7.2.2. torch function 类
      • 4.2.7.2.3. torch.nn.functional function 类
      • 4.2.7.2.4. torch.nn Module 类
      • 4.2.7.2.5. torch.quantization Module 类
      • 4.2.7.2.6. torch.Tensor method 类
      • 4.2.7.2.7. torchvision 类