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. 配置文件具体参数信息
        • 4.1.1.6.1.3. 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. HB_ONNXRuntime 推理库
      • 4.1.2.11.1. 使用方法
      • 4.1.2.11.2. 参数说明
    • 4.1.2.12. 精度 debug 工具
      • 4.1.2.12.1. 快速上手
        • 4.1.2.12.1.1. 校准模型与数据的保存
        • 4.1.2.12.1.2. 精度 debug 模块导入与使用
        • 4.1.2.12.1.3. 分析结果展示
      • 4.1.2.12.2. 功能说明文档
        • 4.1.2.12.2.1. get_sensitivity_of_nodes
        • 4.1.2.12.2.2. plot_acc_error
        • 4.1.2.12.2.3. plot_distribution
        • 4.1.2.12.2.4. get_channelwise_data_distribution
        • 4.1.2.12.2.5. sensitivity_analysis
        • 4.1.2.12.2.6. runall
  • 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. EfficientDetd0
        • 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. 准备校准用的数据集
        • 4.1.3.2.4.5. build 异构模型
        • 4.1.3.2.4.6. 单张图片推理
        • 4.1.3.2.4.7. 精度测试
      • 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，Bayes-e
    • 4.2.1.13. X3
    • 4.2.1.14. 处理器，BPU 架构，代码中 enum 的对应关系
  • 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.1.3. 构建量化友好模型
    • 4.2.4.2. qconfig 详解
      • 4.2.4.2.1. 什么是 qconfig
      • 4.2.4.2.2. 如何获取 qconfig
      • 4.2.4.2.3. 如何设置 qconfig
      • 4.2.4.2.4. qconfig 模板
    • 4.2.4.3. Calibration 指南
      • 4.2.4.3.1. 流程和示例
      • 4.2.4.3.2. 常用算法介绍
      • 4.2.4.3.3. 调参技巧
      • 4.2.4.3.4. Observer 参数文档
    • 4.2.4.4. 量化感知训练指南
      • 4.2.4.4.1. 流程和示例
        • 4.2.4.4.1.1. prepare_qat_fx
        • 4.2.4.4.1.2. 加载 Calibration 模型参数
        • 4.2.4.4.1.3. 训练迭代
      • 4.2.4.4.2. 伪量化算子
        • 4.2.4.4.2.1. 伪量化过程
        • 4.2.4.4.2.2. 基于统计的方法
        • 4.2.4.4.2.3. 基于学习的方法
    • 4.2.4.5. 异构模型指南
      • 4.2.4.5.1. 异构模型介绍
      • 4.2.4.5.2. 使用流程
      • 4.2.4.5.3. 算子限制
      • 4.2.4.5.4. 主要接口参数说明
      • 4.2.4.5.5. 流程和示例
    • 4.2.4.6. 精度调优工具使用指南
      • 4.2.4.6.1. 快速上手
      • 4.2.4.6.2. API Reference
        • 4.2.4.6.2.1. 模型结构检查
        • 4.2.4.6.2.2. QuantAnalysis 类
          • 4.2.4.6.2.2.1. auto_find_bad_case
          • 4.2.4.6.2.2.2. set_bad_case
          • 4.2.4.6.2.2.3. load_bad_case
          • 4.2.4.6.2.2.4. save_bad_case
          • 4.2.4.6.2.2.5. set_model_profiler_dir
          • 4.2.4.6.2.2.6. run
          • 4.2.4.6.2.2.7. compare_per_layer
          • 4.2.4.6.2.2.8. sensitivity
          • 4.2.4.6.2.2.9. clean
        • 4.2.4.6.2.3. ModelProfiler 类
          • 4.2.4.6.2.3.1. get_info_manager
            • 4.2.4.6.2.3.1.1. table
            • 4.2.4.6.2.3.1.2. tensorboard
    • 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. FX Quantization 原理介绍
      • 4.2.5.1.1. 量化流程
        • 4.2.5.1.1.1. Fuse（可选）
        • 4.2.5.1.1.2. Prepare
        • 4.2.5.1.1.3. Convert
        • 4.2.5.1.1.4. Eager Mode 兼容性
    • 4.2.5.2. RGB888 数据部署
      • 4.2.5.2.1. 场景
      • 4.2.5.2.2. YUV 格式简介
      • 4.2.5.2.3. 在训练时对 RGB 输入进行预处理
      • 4.2.5.2.4. 在推理时对 YUV 输入进行实时转换
        • 4.2.5.2.4.1. 算子定义
        • 4.2.5.2.4.2. 使用方法
    • 4.2.5.3. 模型分段部署
      • 4.2.5.3.1. 场景
      • 4.2.5.3.2. 方法
    • 4.2.5.4. 算子融合
      • 4.2.5.4.1. 吸收 BN
      • 4.2.5.4.2. 融合 Add、ReLU(6)
      • 4.2.5.4.3. 实现原理
      • 4.2.5.4.4. 可以融合的算子
    • 4.2.5.5. Adaround（实验性功能）
      • 4.2.5.5.1. 基本原理
      • 4.2.5.5.2. 接口定义
      • 4.2.5.5.3. 使用方法
        • 4.2.5.5.3.1. list/tuple（推荐）
        • 4.2.5.5.3.2. torch.utils.data.DataLoader
    • 4.2.5.6. 自动校准（实验性功能）
      • 4.2.5.6.1. 基本原理
      • 4.2.5.6.2. 接口定义
      • 4.2.5.6.3. 使用方法
        • 4.2.5.6.3.1. list/tuple（推荐）
        • 4.2.5.6.3.2. torch.utils.data.DataLoader
  • 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. D-Robotics 算子
    • 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 类