HMCT 工作流路由

本 Skill 是 HMCT 工具链的统一入口，根据用户意图自动分发到对应子流程。

路由规则

用户请求
  │
  ├─ 意图：模型转换 / 量化构建 / PTQ，且提供了校准数据（cali_data_dir）
  │   └─→ 路由 A：通过 hb_config_generator 生成 YAML → j6-hbdk-compile 编译
  │
  ├─ 意图：模型转换 / 验证模型 / 快速检查，未提供校准数据
  │   └─→ 路由 B：通过 hb_config_generator 生成快速验证 YAML → j6-hbdk-compile 验证
  │
  ├─ 意图：精度调优 / cosine similarity 不达标 / 混精度配置
  │   └─→ 路由 C：精度调优工作流（转交 j6-hmct-cosine-similarity-tuning）
  │
  ├─ 意图：单项 debug 分析（灵敏度、分布、累积误差等）
  │   └─→ 路由 D：精度 Debug 工具
  │
  └─ 不确定
      └─→ 询问用户意图后再路由

路由 A：完整量化构建（YAML 驱动，推荐）

触发条件： 用户希望执行模型量化转换，且提供了校准数据。

关键词： 模型转换、量化构建、PTQ 构建、校准、hb_compile、YAML 配置

优先使用 hb_config_generator + hb_compile 方式（而非 run_build.py）。

工作流

Step 1: 收集参数 → Step 2: hb_config_generator 生成 YAML → Step 3: 用户确认 YAML → Step 4: hb_compile -c 编译

需要收集的参数

必填

可选参数

执行方式

# Step 1: 使用 hb_config_generator 生成 YAML 配置
hb_config_generator \
    --model-path <模型路径> \
    --calibration-data-dir <校准数据目录> \
    --march <芯片架构> \
    --output-path <输出目录>/compile_config.yaml

# Step 2: 用户确认 YAML 配置（默认必须确认）
# 向用户展示生成的 YAML 配置摘要（模型路径、march、校准数据等）

# Step 3: 使用 hb_compile 执行编译
hb_compile -c <输出目录>/compile_config.yaml

YAML 配置示例

model:
  onnx: /path/to/model.onnx
  march: nash-p
  calibration:
    data_dir: /path/to/cali_data
    calibration_type: max
  input:
    input_source: pyramid
    preprocessing:
      mean: [123.675, 116.28, 103.53]
      scale: [0.01712475, 0.017507, 0.0174292]
  output:
    out_dir: ./compile_output
    model_name: quantized_model

执行步骤

1. 确认 --onnx_path 和 --cali_data_dir，未提供则询问
2. 确认 --march 参数，未指定则使用默认值 nash-p
3. 运行 hb_config_generator 生成 YAML 配置
4. 向用户展示 YAML 配置摘要，等待用户确认（默认强制门禁）
5. 用户确认后，转交 j6-hbdk-compile Skill 执行 hb_compile -c
6. 检查输出日志，确认构建成功
7. 向用户报告结果和输出文件路径

参考文档

• hb_config_generator 使用文档见 horizon-tc-ui Skill
• hb_compile YAML 配置参考见 j6-hbdk-compile Skill

路由 B：快速验证（YAML 驱动）

触发条件： 用户希望验证模型是否能走通转换流程，但未提供校准数据。

关键词： 验证模型、check_model、快速检查、测试转换、能不能转

工作流

Step 1: 收集参数 → Step 2: hb_config_generator 生成验证 YAML（启用 check 模式） → Step 3: 用户确认 → Step 4: hb_compile -c 验证

需要收集的参数

执行方式

# Step 1: 生成 YAML 配置（check 模式使用随机校准数据）
hb_config_generator \
    --model-path <模型路径> \
    --march <芯片架构> \
    --output-path <输出目录>/compile_config.yaml \
    --check-mode

# Step 2: 用户确认 YAML 配置

# Step 3: 执行快速验证编译
hb_compile -c <输出目录>/compile_config.yaml

执行步骤

1. 确认 --onnx_path，未提供则询问
2. 确认 --march 参数，未指定则使用默认值 nash-p
3. 运行 hb_config_generator --check-mode 生成验证 YAML
4. 向用户展示 YAML 配置摘要，等待用户确认
5. 用户确认后，转交 j6-hbdk-compile Skill 执行 hb_compile -c
6. 若通过则告知用户模型兼容；若失败则分析错误原因

路由 C：精度调优工作流

触发条件： 用户希望对量化后模型进行精度调优，或反馈 cosine similarity 不达标。

关键词： 精度调优、cosine similarity、精度不达标、混精度、INT16、敏感节点、node_config、PTQ 调优

转交目标

转交至 j6-hmct-cosine-similarity-tuning Skill 处理。

需要收集的参数

执行方式

# 默认（由 HMCT 自动选择校准方法）
python3 HMCT_Skill/j6-hmct-cosine-similarity-tuning/script/hmct_precision_tuning.py \
    --onnx_path <模型路径> \
    --cali_data_dir <校准数据目录> \
    --march <芯片架构>

# 显式指定单一校准方法
python3 HMCT_Skill/j6-hmct-cosine-similarity-tuning/script/hmct_precision_tuning.py \
    --onnx_path <模型路径> \
    --cali_data_dir <校准数据目录> \
    --calibration_type max

# 多校准方法（HMCT 触发 modelwise search）
python3 HMCT_Skill/j6-hmct-cosine-similarity-tuning/script/hmct_precision_tuning.py \
    --onnx_path <模型路径> \
    --cali_data_dir <校准数据目录> \
    --calibration_type max kl

调优流程概览

INT8 基线 → 全 INT16 ─┬─ 达标 → INT8+INT16 渐进回退
                      └─ 未达标 → INT16+dual-int16 ─┬─ 达标 → 渐进回退
                                                    └─ 未达标 → 全 FP16 ─┬─ 达标 → 渐进回退
                                                                         └─ 未达标 → 深层分析

参考文档

完整调优流程见 j6-hmct-cosine-similarity-tuning/SKILL.md

路由 D：精度 Debug 工具（单项分析）

触发条件： 用户希望针对性地运行某一项 debug 分析（如节点灵敏度、数据分布、累积误差），而非完整调优流程。

关键词： 节点灵敏度、数据分布、逐通道分布、累积误差、tensor 分析、debug、hmct-debugger

可用工具

需要收集的参数

执行步骤

1. 确认用户需要运行哪项分析工具
2. 确认模型路径和校准数据路径
3. 如果不确定运行哪项，建议先运行 runall 一键分析
4. 使用 CLI 命令或 Python API 执行，向用户报告输出路径

参考文档

完整参数说明见 reference/debug_tools.md

路由判定示例

目录结构

HMCT_Skill/
├── SKILL.md                                    ← 本文件（路由入口）
├── reference/
│   ├── build_model.md                          ← build_model / check_model 参考文档
│   ├── run_build.py                            ← 一键构建/验证脚本（备选路径，推荐用 YAML 方式）
│   └── debug_tools.md                          ← 精度 debug 工具参考文档
└── j6-hmct-cosine-similarity-tuning/
    ├── SKILL.md                                ← 精度调优 Skill 定义
    ├── example.md                              ← Prompt 示例
    └── script/
        ├── hmct_precision_tuning.py            ← 主调优脚本（含构建逻辑）
        └── get_sensitivity_of_nodes.py         ← 敏感度分析脚本