5. 配置文件介绍

模型转换与评估工具提供 config.yml 配置文件，用于集中描述模型量化、编译、运行验证和评估所需的配置信息，包括：

• 模型信息： 模型名称、ONNX 路径、输出目录、输入shape、图像预处理、硬件resizer、demo/eval适配类。

• 量化信息： 量化规格、校准数据、混合精度搜索、量化扩展配置。

• 编译信息： IPU 核数、优化等级、编译 batch、并行编译任务数、编译后端和调试输出。

• 运行验证信息： demo数据目录、eval数据集目录、数据集适配类，以及 compare/check/perf 等命令需要复用的模型输出路径和编译参数。

常见使用方式如下：

hmatc quant -c config.yml
hmatc build -c config.yml
hmatc compare -c config.yml --data_path data.npz
hmatc check -c config.yml
hmatc perf -c config.yml -wn 10 -sn 1000 -tn 4
hmatc demo -c config.yml
hmatc eval -c config.yml

5.1. 完整配置文件

完整配置文件如下：

# 模型配置
model:
  name: model_name           # 模型名称，用于输出文件命名
  save_dir: ./output         # 输出目录
  model_path: model.onnx     # ONNX 模型路径

  inputs:
    images:                  # 输入名称，必须与 ONNX 输入名一致
      shape: [1, 3, 640, 640]    # 输入形状 [N, C, H, W]
      data_format: RGB           # 图像格式：RGB/BGR/GRAY；非图像输入填 null
      mean: [0.0, 0.0, 0.0]      # 图像预处理均值
      std: [255.0, 255.0, 255.0] # 图像预处理标准差
      resize_type: 1             # 0: 直接 resize；1: 等比例 resize + padding；2: 固定高度等比例宽度 + 右侧 padding
      padding_mode: 1            # 0: 左上角 padding；1: 中心 padding
      padding_values: [114, 114, 114]

      # 可选。M50芯片硬件resizer配置；与 quant.mix_search 互斥。
      resizer:
        toYUV_format: YUV420SP       # YUV400/YUV420SP/YUV422SP/YUV444SP
        resizer_input_size: [640, 640] # resizer 输入尺寸 [H, W]
        resizer_mode: 3               # 1: DYNAMIC_V2；2: DYNAMIC_V1；3: STATIC
        resizer_crop: [0, 0, 640, 640] # STATIC 模式裁剪区域 [y, x, h, w]
        resizer_pad: [0, 0, 0, 0]      # [top, left, bottom, right]，当前版本仅校验

  # 可选。demo/eval 需要模型适配类时配置，文件名不包含 .py 后缀。
  model_impl_module: model_impl
  model_impl_cls: ModelImpl

  # 可选。量化前 ONNX 图优化配置。
  app_onnx_opt:
    optimizer: false
    log_level: 0              # 0: product；1: release；2: debug；3: ignore

# 量化配置
quant:
  quant_type: w8a8h1_sefp    # 量化规格
  calib_data: /path/to/calib # 校准数据目录；未配置或 null 时使用随机数据
  calib_num: 1               # 当前版本仅使用 1 个校准样本
  config: {}                 # 预留扩展字段

  # 可选。混合精度搜索配置；与 model.inputs.*.resizer 互斥。
  mix_search:
    topk: 0.1                # 选择高精度层的比例
    weight_bits: [8, 16]     # 权重候选位宽
    act_bits: [8, 16]        # 激活候选位宽
    policy: topk             # topk/threshold
    task: cv_cls             # cv/cv_cls/llm
    metric: l1               # l1/sqnr/kl
    key_name: loss           # 输出属性名称

# 编译配置
build:
  ncore: 1                  # IPU 核数：1/2
  opt_level: 2              # 优化等级：0/1/2
  batch: 1                  # 编译 batch
  roi_num: 1                # ROI 数量，当前版本仅支持 1
  parallel_jobs: 4          # 并行编译任务数
  cpp_backend: v1           # 编译后端版本
  flash_attention: 0        # Flash Attention 开关
  dump_compiled_mlir: false # 是否导出编译后的 MLIR
  upload_dir_name: null     # 内部上传目录名
  file_prefix: null         # 内部上传压缩包前缀

# 演示配置
demo:
  data_dir: /path/to/images # 图片或 NPZ 数据目录
  num: 0                    # 演示数量，0 表示全部

# 评估配置
eval:
  data_dir: /path/to/dataset
  num: 0
  dataset_module: dataset   # 数据集模块文件名，不包含 .py 后缀
  dataset_cls: Dataset      # 数据集类名

5.2. 字段约束

下表中的“是否必填”表示在相关命令或相关输入类型下的要求。例如，图像输入需要配置预处理字段；demo 与 eval 相关字段仅在执行对应命令时生效。为避免表格过宽，字段名按 YAML 层级分组展示；分组标题即为字段完整路径前缀。

5.2.1. model字段

字段	是否必填	类型/取值	缺省值	说明
name	否	string	model	用于 HMONNX/HMM 等输出文件命名。
save_dir	是	string	无	输出根目录；量化、编译、日志和结果文件均写入该目录下的目标平台子目录。
model_path	是	string	""	ONNX 模型路径；本地路径不存在时按 HOUMO_MODEL_PATH 解析。
inputs	是	map	无	key 为 ONNX 输入名。
model_impl_module	demo/eval 需要	string	无	模型适配模块文件名，不包含 .py 后缀。
model_impl_cls	demo/eval 需要	string	无	模型适配类名。

5.2.2. model.inputs.<input_name>字段

字段	是否必填	类型/取值	缺省值	说明
shape	是	list[int]	无	输入形状；静态 ONNX 需与模型输入一致。
data_format	否	null/RGB/BGR/GRAY	null	非图像输入填 null；图像输入需指定实际颜色格式。
mean	图像输入必填	list[number]	无	图像预处理均值；长度应与输入通道数 C 一致。
std	图像输入必填	list[number]	无	图像预处理标准差；长度应与输入通道数 C 一致。
resize_type	图像输入必填	0/1/2	无	0 表示直接 resize；1 表示等比例 resize 后 padding；2 表示固定高度等比例宽度并右侧 padding。
padding_mode	条件必填	0/1	无	resize_type=1 必填；0 表示左上角 padding，1 表示中心 padding；resize_type=2 只能为 0 或省略。
padding_values	条件必填	list[number]	resize_type=2 未配置时按 0	padding 填充值；resize_type=1 必填，长度必须等于输入通道数 C。
resizer	否	map/null	无	启用硬件 resizer；与 quant.mix_search 互斥。

5.2.3. model.inputs.<input_name>.resizer字段

字段	是否必填	类型/取值	缺省值	说明
toYUV_format	否	YUV 格式	YUV420SP	支持 YUV400、YUV420SP、YUV422SP、YUV444SP；YUV400 用于灰度输入。
resizer_input_size	否	[H, W]	[shape[2], shape[3]]	H/W 均不超过 4096；H 需 2 对齐；W 在大于 2048 时需 32 对齐，否则需 2 对齐。
resizer_mode	否	1/2/3	3	1 为 DYNAMIC_V2；2 为 DYNAMIC_V1，当前编译器暂不支持；3 为 STATIC。
resizer_crop	STATIC 可选	[y, x, h, w]	全图 crop	仅 resizer_mode=3 有效；4 个值均需为偶数，且 crop 区域不能越界。
resizer_pad	否	[top, left, bottom, right]	无	4 个值均需为偶数；当前版本仅校验，构建流程不使用。

5.2.4. model.app_onnx_opt字段

字段	是否必填	类型/取值	缺省值	说明
optimizer	否	bool	false	量化前执行 ONNX 优化。
log_level	否	0/1/2/3	0	优化器日志模式。

5.2.5. quant字段

字段	是否必填	类型/取值	缺省值	说明
quant_type	否	string	w8a8h1_sefp	量化规格，例如 w8a8h1_sefp、w8a16h1_sefp、w8w16a8a16_sefp。
calib_data	否	string/null	null	校准数据目录；未配置时使用随机数据；目录不存在时按 HOUMO_DATASETS_PATH 解析。
calib_num	否	int	1	当前忽略，仅使用 1 张校准样本。
config	否	map	{}	当前版本未使用该字段内容，作为扩展配置保留。
mix_search	否	map	无	混合精度搜索配置；与任意 model.inputs.<input_name>.resizer 互斥。

5.2.6. quant.mix_search字段

字段	是否必填	类型/取值	缺省值	说明
topk	否	number	无	选择高精度层的比例，建议范围为 (0, 1]。
weight_bits	否	list[int]	无	权重候选位宽；支持 4、8、16。
act_bits	否	list[int]	无	激活候选位宽；支持 4、8、16。
policy	否	topk/threshold	无	高精度层选择策略。
task	否	cv/cv_cls/llm	无	敏感度分析任务类型；cv_cls 与 llm 使用 cross entropy，cv 使用 MSE。
metric	否	l1/sqnr/kl	无	敏感度度量方式。
key_name	否	string	无	用于敏感度计算的输出属性名称，例如 loss 或 logits。

5.2.7. build字段

字段	是否必填	类型/取值	缺省值	说明
ncore	否	1/2	1	编译使用的 IPU 核数。
opt_level	否	0/1/2	2	编译优化等级，对应 O0/O1/O2。
batch	否	int >= 1	1	编译 batch；最终 HMM batch 为模型输入 batch 与该值的乘积。
roi_num	否	int >= 1	1	ROI 数量；当前版本仅支持 1。
parallel_jobs	否	int >= 1	CPU 物理核数	并行编译任务数，可通过 -j/--jobs 覆盖。
cpp_backend	否	string	v1	编译后端版本，常用取值为 v1 或 v2。
flash_attention	否	int	0	Flash Attention 开关；0 表示关闭，1 表示图级优化，2 表示算子级优化。
dump_compiled_mlir	否	bool	false	导出编译后 MLIR。
upload_dir_name	否	string/null	当前目录名	内部上传目录名。
file_prefix	否	string/null	upload_dir_name	内部上传压缩包前缀。

5.2.8. demo字段

字段	是否必填	类型/取值	缺省值	说明
data_dir	demo 必填	string	""	demo 数据目录；本地目录不存在时按 HOUMO_DATASETS_PATH 解析。
num	否	int >= 0	0	0 表示全部。

5.2.9. eval字段

字段	是否必填	类型/取值	缺省值	说明
data_dir	eval 必填	string	""	eval 数据集目录；本地目录不存在时按 HOUMO_DATASETS_PATH 解析。
num	否	int >= 0	0	0 表示全部。
dataset_module	eval 必填	string	无	数据集模块文件名，不包含 .py 后缀。
dataset_cls	eval 必填	string	无	数据集类名。

5.3. 生成 config.yml

可以使用 hmatc gen 指令根据ONNX模型生成基础 config.yml：

hmatc gen --onnx onnx_path --output yml_file_path

其中：

• onnx_path：原始 ONNX 模型文件路径。

• yml_file_path：生成的配置文件保存路径。

该命令会读取ONNX模型的输入信息，并生成包含模型路径、输入shape、基础量化配置和基础编译配置的配置文件。生成内容主要包括：

• model.name

• model.save_dir

• model.model_path

• model.inputs.<input_name>.shape

• model.inputs.<input_name>.data_format

• quant.calib_data

• quant.calib_num

• build.ncore

• build.opt_level

hmatc gen 生成的是基础配置模板。图像预处理参数、硬件 resizer、混合精度搜索、demo/eval 适配类、数据集路径等业务相关配置，需要根据模型和任务场景继续补充。