【地平线 J6工具链入门教程】PTQ 深度使用指南

一、快速评测：摸透模型性能上限

1. 解决的核心问题

2. PTQ 实战操作

直接使用hb_compile工具的--fast-perf参数，一步完成性能评测与基础配置生成。

执行命令：

• 核心作用：

  • 自动将 BPU 可执行算子优先分配到 BPU（int8 精度），最大化性能。

  • 自动删除模型首尾冗余算子（如 Quantize/Dequantize、Cast、Transpose、Reshape 等），减少性能损耗。

  • 输出两个关键结果：板端最高性能数据、基础版config.yaml（默认生成路径在.fast_perf目录下，后续可直接修改使用）。

3. 参考手册

二、校准部署：快速生成与修改 config.yaml

1. 解决的核心问题

开发者需要基于快速评测结果，配置模型校准参数（如校准数据路径、输入格式），完成从浮点模型到可部署模型的转换，同时避免从零编写config.yaml的繁琐工作。

2. PTQ 实战操作

（1）快速生成基础 config.yaml

无需手动创建，直接复用 “快速评测” 步骤中--fast-perf参数输出的基础版config.yaml（默认生成路径在.fast_perf目录下），该文件已包含march（平台型号）、onnx_model（模型路径）等核心配置，减少 70% 以上的基础配置工作量。

（2）按需修改关键配置项

根据实际部署需求，修改config.yaml中的核心模块，以下为常见场景示例：

（3）执行校准部署命令

完成配置后，执行标准转换命令：hb_compile -c config.yaml，工具将自动完成模型校准、量化与编译，最终输出可部署的.hbm模型文件。

3. 参考手册

三、模型部署：平衡性能与精度的实战流程

1. 解决的核心问题

2. PTQ 实战三步法

第一步：用 fast-perf 确认性能上限

执行hb_compile --march nash-b -m xxx.onnx --fast-perf，获取 int8 精度下的最高性能（如推理延迟、吞吐量），作为性能基准。

第二步：用全 int16 确认精度上限

修改config.yaml关联的quant_config.json，将模型所有算子设置为 int16 精度（通过model_config配置"all_node_type": "int16"），执行hb_compile -c config.yaml，测试模型精度，作为精度基准。

第三步：用 hmct-debugger 调混合精度

1. 问题定位：使用hmct-debugger工具，分析哪些算子用 int8 时精度损耗大（如 Softmax、MatMul），哪些算子用 int8 无明显精度影响（如 Conv、Add）。

2. 混合配置：在quant_config.json中，对精度敏感算子单独设置 int16，其余用 int8。示例配置如下：

3. 验证效果：执行hb_compile -c config.yaml，测试混合精度模型的性能与精度，确保性能接近 int8 上限、精度接近 int16 上限。

3. 参考手册

• hmct-debugger 使用指南：精度debug工具
• 混合精度配置示例：PTQ 精度调优实战

四、常见问题与 PTQ 解决方案

问题 1：模型转换后精度掉太多

• PTQ 解决方法：

  • 开启权重偏差校正（bias correction）；

  • 对敏感算子改用 int16 或 fp16

• 操作步骤：

  • 在quant_config.json的weight模块添加 "bias_correction": {"num_sample": 1, "metric": "cosine-similarity"}；

  • 在node_config中指定敏感算子（如 MatMul、Softmax）的qtype为 int16 或 fp16

问题 2：多输入模型（如多特征图）配置复杂

• PTQ 解决方法：复用--fast-perf基础配置，用分号分隔多输入参数
• 操作步骤：在input_parameters中设置：

  • input_name: input0;input1;input2

  • input_shape: 1x1x1296x1600;50176;18816并对应配置input_type_rt和norm_type

问题 3：校准结果不稳定

• PTQ 解决方法：

  • 增加校准样本数；

  • 启用多校准方法搜索

• 操作步骤：

  • 在config.yaml中调整calibration_parameters的样本量；

  • 在quant_config.json的activation模块设置calibration_type: ["max", "kl"]校准方式，配置多组量化参数，启用modelwise_search会同时对多组量化参数做搜索，找到一个量化损失最小的校准方法。

五、关键配置文件模板

1. config.yaml 模板

2. 含校准搜索与混合精度的 quant_config.json 模板

六、附录：核心参数与 quant_config 配置详解

1. 核心参数总表

指定算子以 int16 输出，其功能已合入 node_info，后续版本将废弃指定算子以 int16 输入输出，或强制指定算子运行在 CPU 或 BPU 上，j6使用quant_config配置校准参数组（所有参数并非独立可选，不能都不配置）强制指定算子在 CPU 上运行，其功能已合入 node_info，后续版本将废弃强制指定算子在 BPU 上运行，其功能已合入 node_info，后续版本将废弃编译参数组（要求至少有一个参数，不能都不配置）编译 bin 模型时的进程数，J6编译 bc 模型时的进程数自定义算子参数组（可以都不配置）

2. quant_config 配置说明

编译模型时可以通过quant_config进行量化参数的配置，支持在model_config、op_config、subgraph_config、node_config四个层面配置模型量化参数：

• model_config：配置模型总体的量化参数，key是自定义名称。

• op_config：配置某类算子的量化参数，key是算子的类型。

• subgraph_config：配置某个子图的量化参数，key是子图的名字。

• node_config：配置某个具体节点的量化参数，key是节点的名字。

配置时四个层面存在优先级关系，配置粒度越小优先级越高，即优先级model_config < op_config < subgraph_config < node_config，当某个节点同时被多个维度配置时，优先级高的维度最终生效。

激活参数配置

• calibration_type：校准方式支持max、kl、[max、kl]

• num_bin、max_num_bin：这些是kl量化的参数

• max_percentile：用于max校准百分位

• per_channel：是否开启per-channel量化

• asymmetric：是否开启非对称量化

注：如果配置了多个校准方法,会启动Modelwise搜索方法，从多个候选校准模型中找出最优的量化模型；如果配置了Layerwise参数，则启动Layerwise搜索方法，逐层搜索最优的量化参数。

权重校准参数配置

• num_sample：配置参与bias correction的样本数

• metric：偏差校正误差度量方法cosine-similarity、mse、mae、mre、sqnr以及chebyshev，默认值cosine-similarity。

校准参数搜索方法

• modelwise_search：在模型层面对量化参数进行搜索，该方法允许一次性配置多种校准方法，通过比较量化前后模型输出的量化损失metric（可配置），找到一个量化损失最小的校准方法。

• layerwise_search：在节点层面对量化参数进行搜索，该方法会根据每个节点量化前后模型输出，计算量化损失metric（可配置），为该节点分配量化损失最小的校准方法。

注：多个校准方法时modelwise_search和layerwise_search可以都不配置，但默认会执行modelwise_search的逻辑(metric会采用默认的cosine-similarity)。

注：modelwise和layerwise同时配置的时候，layerwise优先级高。

参考手册

• quant_config 详细配置指南：quant_config 配置指南

3. DeformConv2d自定义算子

需要导入算子库进行算子注册from hmct.plugin.deformconv2d import *