3. 精度评估与优化

模型部署后，为保证推理结果与原始模型一致，需要进行精度验证。问题通常来源于：

  • 量化阶段： 量化后模型与原始模型输出偏差。

  • 编译阶段： 编译后模型与量化后模型输出偏差。

  • 推理处理阶段： 模型输入预处理、模型输出解析及处理流程、以及模型特定的参数配置不一致。

  • 评测阶段： 数据集、评分规则或输出解析不一致。

3.1. 流程

针对不同模型类型，建议使用不同工具进行精度分析，如图所示：

../_images/accuracy.png

图 3.1 精度评估与优化流程

3.2. 精度评估工具

模型类型

推荐工具

主要作用

小模型，包括CV、检测、分类、分割等模型

模型转换与评估工具（Hmatc）

比对原始ONNX、量化后模型和编译后模型输出，定位量化或编译偏差。

LLM 大语言模型

LLM精度评测工具

测试原始模型和编译后模型的推理精度，定位精度偏差。

3.3. 小模型（CV/检测/分类/分割）

适用于CV、检测、分类、分割等输出固定形状张量的模型。此类模型可使用模型转换与评估工具中 hmatc compare 指令进行单样本输出比对，快速定位量化或编译阶段的偏差。

3.3.1. 常见精度问题

当出现以下问题时，建议使用模型转换与评估工具检测：

  • 量化后模型精度下降。

  • 编译后模型输出异常。

  • 推理结果与原始模型基线相比存在明显偏差。

  • 需要判断精度偏差来自量化阶段还是编译阶段。

3.3.2. 基础概念说明

概念

说明

原始模型

ONNX或训练框架导出的模型，通常作为精度基线。

量化后模型

经过HMQuantool量化工具量化后的模型，用于降低存储和计算开销。

编译后模型

基于量化模型，由编译器生成的可执行模型，可直接在后摩设备上运行。

Cosine Distance

输出张量相似度指标，数值越接近 1，表示两个输出越接近。

单样本评估

使用一个输入样本比对不同阶段模型输出，适合快速定位问题，不代表整体精度。

3.3.3. 使用方法

本节介绍如何使用模型转换与评估工具评测模型精度。

3.3.3.1. 环境依赖

模型转换与评估工具仅用于ModelZoo模型库的网络模型，因此需要具备ModelZoo样例运行环境。

  • Linux系统：

    Docker镜像可运行于标准Linux环境，推荐使用以下已验证环境：

    • Ubuntu 24.04（x86_64）

    其他Linux环境在满足Docker运行条件的情况下通常也可运行，但未在本产品中进行完整验证。

根据功能不同，镜像分为以下两类：

  • x86_64全功能镜像：

    支持模型量化、模型编译与模型推理。

    Dadao-convert-docker-xh2-vx.y.z-ubuntu24.04-x86.64.tar

  • x86_64推理部署镜像（deploy镜像）：

    仅支持模型推理运行，不包含模型量化与模型编译。

    镜像名称中包含 deploy 标识。

    Dadao-deploy-docker-xh2-deploy-vx.y.z-ubuntu24.04-x86.64.tar

  • AArch64推理部署镜像：

    仅支持ARM64架构下模型推理运行，不包含模型量化与模型编译。

    Dadao-deploy-docker-xh2-deploy-vx.y.z-ubuntu24.04-aarch64.tar

3.3.3.2. 环境配置

工具使用前，需完成下面环境配置：

  1. 安装最新版本驱动。详情参看 《软件平台驱动安装指南》。

  2. 烧写和升级后摩设备固件镜像。详情参看 《HmUpdateTool工具使用指南》。

  3. 检测 环境依赖。

  4. 下载Docker镜像，用于模型量化、编译和推理。

    1. 登录后摩开发者社区。

    2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。

    3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为转换镜像或部署镜像的下载资源，选中该资源左边复选框。

    4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。

  5. 启动Docker镜像。

    1. 在Docker镜像存放路径下，运行下面命令导入镜像：

      docker load -i <docker_file>

      其中 docker_file 为下载的Docker镜像文件名。如果导入成功，则会显示导入后Docker镜像名，示例如下：

      Loaded image: harbor.houmo.ai/toolchain/release:Dadao-convert-xh2-v1.4.0-ubuntu24.04-x86.64

    2. 运行下面命令启动Docker镜像：

      docker run -it --pid=host --privileged -w /hmdd -v $PWD:/hmdd --shm-size 64g --name <container_name> <docker_image_name> /bin/bash

      其中 container_name 需替换为自定义容器命名；docker_image_name 需替换为Docker镜像名，如上一步示例镜像名为 harbor.houmo.ai/toolchain/release:Dadao-convert-xh2-v1.4.0-ubuntu24.04-x86.64。

  6. 在Docker镜像中下载应用开发示例包。

    1. 登录后摩开发者社区。

    2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。

    3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码的下载资源，选中该资源左边复选框。

    4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。

    ModelZoo模型库位于 houmo-examples-xh2/models 目录下。

  7. 检查 houmo-examples-xh2/env.sh 中环境变量设置：

    根据实际情况修改环境变量的值，例如如果更换数据集路径，则修改 HOUMO_DATASETS_PATH 变量。

  8. 在 houmo-examples-xh2 目录下，执行下面指令配置运行环境：

    source env.sh

  9. 如果在AArch64 架构：不支持模型量化和编译操作，用户可以直接使用提供的已编译模型进行推理。

3.3.3.3. 操作步骤

单样本精度评估旨在通过比较不同模型对单个输入样本的推理结果，来快速验证模型转换过程中的精度保持情况。该过程主要衡量以下三种模型的推理结果：

注意

由于本节操作依赖量化后模型和编译后模型，仅支持在Ubuntu 24.04 x86_64平台上执行本节操作。

  • 原始ONNX模型

  • 量化后模型

  • 编译后模型

通过比对这些模型的推理结果，工具会计算并输出Cosine Distance（余弦距离），该值是衡量编译结果正确性的重要指标。

下面以 YOLOv5s 模型为例，介绍如何对单样本进行精度评估。

配置运行环境后，在 houmo-examples-xh2/models/detection/yolov5s 目录下，执行下面指令进行单样本评估，需要指定配置文件和数据路径：

注意

执行指令前，需确保原始ONNX模型、量化后模型以及编译后模型已存放在指定路径。
hmatc compare -c config.yml --data_path coco2017/val2017/000000000139.jpg

其中 config.yml 为配置文件，用户可按需进行设置。

返回结果示例如下：

...
02:50:53.310326 xh2_exec.py:310 [INFO]
+-------------------------------------------------------+
|                    Cosine Distance                    |
+------+-----------------+-------------+----------------+
| name | onnx vs hmquant | onnx vs xh2 | hmquant vs xh2 |
+------+-----------------+-------------+----------------+
| 340  |     0.984035    |   0.999404  |    0.984125    |
| 378  |     0.975255    |   0.999342  |    0.974900    |
| 416  |     0.944464    |   0.999268  |    0.943158    |
+------+-----------------+-------------+----------------+

其中：

  • name：表示推理后模型输出节点名称。

  • onnx vs hmquant：表示原始ONNX模型与量化后模型推理结果比对。用于判断量化是否引入精度损失。

  • onnx vs xh2：表示原始ONNX模型与编译后模型推理结果比对。判断完整转换链路的总体偏差。

  • hmquant vs xh2：表示量化后模型与编译后模型推理结果比对。判断编译后模型是否保持量化模型结果。

3.3.4. 定位与优化

3.3.4.1. onnx vs hmquant值偏低

如果 onnx vs hmquant 对应的 Cosine Distance 值明显低于预期，说明量化后模型与原始 ONNX 模型输出存在较大差异，量化过程可能引入精度损失。

建议检查：

  • 校准数据是否覆盖真实业务场景。

  • 输入预处理是否与原始模型一致。

  • 是否存在对量化敏感的算子或网络层。

  • 是否需要调整量化配置。

  • 是否需要对敏感层使用混合精度策略。

3.3.4.1.1. 量化调优

可通过调整量化策略和启用混合精度搜索，降低量化引入的精度损失。下面以YOLOv5s模型为例，介绍量化策略优化流程。

  1. 在 houmo-examples-xh2/models/detection/yolov5s 目录下，修改 config.yml 配置文件。示例如下：

    ...
quant:
  quant_type: w8a8h1_sefp
  calib_data: coco2017/val2017
  mix_search:
    topk: 0.1
    weight_bits: [8, 16]
    act_bits: [8, 16]
    policy: topk
    task: cv
    metric: l1
...

    其中，量化策略相关的关键配置如下：

    • quant_type：量化策略。取值格式为 wNaY_format，用于指定权重与激活值的量化尾数位宽及量化格式，其中：

      • N：表示权重的尾数位宽，当前支持4或8。

      • Y：表示激活值的尾数位宽，支持设置为任意 8 至 16 位之间任意整数值。

      • hZ：可选字段，表示 hidden bit 标志，Z 支持设置为 0 或 1，例如 h0、h1。

      • nM：可选字段，表示 nshare 参数，M 为整数，例如 n64、n128。

      • format：表示所采用的量化格式，包括：

        • sefp：缩放因子采用SEFP格式表示。

        • ssfp：缩放因子采用SSFP格式表示。

      对于 CV 类模型、Stable Diffusion 等小模型，w8a8h1_sefp 通常可作为通用量化策略。该策略表示权重和激活值均采用 8-bit 尾数位宽，并使用 SEFP 量化格式。若量化后精度不满足预期，可尝试调整 quant_type 的取值，并通过精度评测选择更合适的量化策略。

    • mix_search：用于执行混合精度搜索。默认情况下，量化工具不执行混合精度搜索，权重和激活值的尾数位宽由 quant_type 参数指定。启用混合精度搜索后，量化工具会在控制精度损失的前提下，自动搜索更适合硬件执行的精度配置，以改善量化模型精度或部署效果。

    其中：

    • topk：选择高精度层的比例。例如 0.1 表示选择前 10% 敏感层使用高精度。

    • weight_bits：权重候选位宽列表，需要与 quant_type 中配置的权重位宽保持一致。

    • act_bits：激活值候选位宽列表，需要与 quant_type 中配置的激活位宽保持一致。

    • policy：混合精度选择策略，支持 topk 和 threshold。

    • task：任务类型，用于决定敏感度计算时采用的 loss 方式，支持 cv、cv_cls 和 llm。

    • metric：敏感度度量方式，支持 l1、sqnr 和 kl。

    • key_name：输出属性名称，用于指定敏感度计算时关注的输出字段，例如 loss。

    注意：mix_search 与 resizer 配置互斥。mix_search 需要运行原始 ONNX 模型进行敏感度分析，通常使用 float32 输入；而 resizer 会引入面向硬件 resize 的 YUV/uint8 输入，两者不能同时启用。

  2. 根据调整后的量化配置重新生成量化模型。执行以下命令：

    hmatc quant -c config.yml

    可尝试不同 quant_type 或 mix_search 配置，生成多个候选量化模型。

  3. 将候选量化模型分别编译生成编译后模型。执行以下命令：

    hmatc build --hmonnx hmonnx_path

    其中，hmonnx_path：量化后模型文件路径。

  4. 使用 hmatc compare 指令对原始ONNX模型、量化后模型和编译后模型进行单样本精度比对。

  5. 对比不同量化配置下的 onnx vs hmquant、hmquant vs xh2 和 onnx vs xh2 结果，选择精度表现较优的量化配置。

  6. 选择最优量化配置的模型作为最终部署模型。

如果仍存在明显差异，建议收集模型文件、量化配置、编译配置、执行命令、日志和复现样本，并反馈后摩技术支持工程师进一步定位。

3.3.4.2. hmquant vs xh2值偏低

如果 hmquant vs xh2 对应的 Cosine Distance 值明显低于预期，说明编译后模型与量化后模型输出存在较大差异，编译或推理执行链路可能存在问题。请收集模型文件、量化配置、编译配置、执行命令、日志和复现样本，并反馈后摩技术支持工程师进一步定位。

3.3.4.3. 推理结果异常但输出相似度正常

如果 onnx vs hmquant、hmquant vs xh2 和 onnx vs xh2 对应的 Cosine Distance 值均正常，但分类结果、检测框或分割结果与原始模型基线相比仍存在明显偏差，问题通常不在模型主体计算，而在输入处理、输出解析或后处理逻辑。

建议检查：

  • resize、crop、padding是否一致。

  • 图像格式是否正确。

  • mean、std、scale 等归一化参数是否一致。

  • 检测模型的NMS、置信度阈值、类别映射是否正确。

  • 输出tensor的维度解释是否正确。

如果在排查后问题仍无法定位，建议收集以下信息并反馈给后摩技术支持工程师，以便进一步分析：

  • 模型文件（原始模型、量化后模型、编译后模型）

  • 量化配置

  • 编译配置

  • 执行命令

  • 推理日志

  • 能复现问题的输入样本

3.4. LLM模型

LLM 输出为生成文本，不适合仅通过单个输出张量相似度判断精度，可使用LLM精度评测工具在标准数据集上评估原始模型与编译后模型的整体任务表现。

3.4.1. 常见精度问题

当出现以下问题时，建议使用LLM精度评测工具评测模型精度：

  • 编译后模型生成结果异常或与预期不符。

  • 在标准数据集上评测指标低于原始模型或历史基线。

  • 量化或编译后，需要验证模型在任务上的性能保持一致。

  • 性能优化后，应确认优化未导致精度下降。

3.4.2. 使用方法

LLM精度评测工具基于 EvalScope 实现，可通过自定义模型推理脚本调用部署在后摩芯片上的LLM模型，并在MMLU、GSM8K等数据集上输出评测结果。

当前LLM精度评测工具主要提供编译后模型精度评估能力，不包含原始模型精度评估流程。若需对比原始模型与编译后模型精度，需自行实现原始模型评测脚本。

3.4.2.1. 环境依赖和配置

LLM精度评测工具与模型转换与评估工具环境相似，详情参看 模型转换与评估工具环境依赖和配置。

3.4.2.2. 预置模型评测示例

当前工具包提供Qwen3-8B与Qwen3-VL-4B两个大模型的精度评测脚本。对于其他模型，用户可参考这些示例自行编写接入脚本，详情参看 自定义模型评测脚本。

3.4.2.2.1. Qwen3-8B示例

在 houmo-examples-xh2/tools/hmeval/examples/qwen3 目录下，执行下面指令评测模型精度：

hmeval \
   --model ./hm_xh2_qwen3.py \
   --model-dir ./models/hmm_xh2_qwen3_8b_256_32k_b1_1chip_2cores_v${HOUMO_VERSION} \
   --dataset gsm8k \
   --limit 0 \
   --model-args tokenizer_dir=./models/tokenizers

为了确保精度评估精确性，需设置 --limit 0 进行全量测试。

返回信息如下：

+----------------------------------------------+-------+--------+------+----+------+-------+
|Model                                         |Dataset|Metric  |Subset|Num |Score |Cat.0  |
+==============================================+=======+========+======+====+======+=======+
|hmm_xh2_qwen3_8b_256_8k_b1_1chip_2cores_v1.3.0|gsm8k  |mean_acc|main  |1319|0.9181|default|
+----------------------------------------------+-------+--------+------+----+------+-------+

3.4.2.3. 精度指标说明

  • Model ：本次评测运行的模型名称。

  • Dataset ：当前评估所使用的基准测试集名称。

  • Metric ：用于衡量模型表现的标准。常见指标包括：

    • mean_acc：平均准确率。

    • pass@1：单次采样通过率。

  • Subset ：数据集内部的分类。若为全量测试，通常显示为 all 或 main。

  • Num ：实际参与推理并计入评分的测试样本总数。

  • Score ：核心结果指标。取值范围通常在 0 到 1 之间，数值越高代表精度越高。

  • Cat.0 ：数据集的顶层分类标签，用于多维度聚合统计，默认为 default。

3.4.2.4. 指令说明

LLM精度评测工具指令如下：

hmeval [OPTIONS]

指令参数说明如下：

  • --model：必选参数，指定自定义模型评测脚本（.py 文件）的路径。

  • --model-dir：必选参数，指定模型权重或模型编译后文件所在目录。

  • --dataset：必选参数，指定一个或多个评测数据集，用空格分隔，如 mmlu gsm8k。

  • --limit：可选参数，限制评测的样本数量（0 为全量测试）。

  • --model-args：可选参数，自定义配置参数。用于向模型脚本传递用户定义的扩展配置。支持以 KEY=VALUE 形式多次指定。

运行示例如下：

hmeval \
    --model ./hm_xh2_qwen3.py \
    --model-dir ./models/hmm_xh2_qwen3_8b_256_8k_b1_1chip_2cores_v${HOUMO_VERSION} \
    --dataset gsm8k \
    --limit 1 \
    --model-args tokenizer_dir=./models/tokenizers

3.4.2.5. 自定义模型评测脚本

LLM精度评测工具仅提供部分编译后模型的精度评测示例。若需评估原始模型，或评估未提供示例的其他编译后模型，需自行编写模型评测脚本。

自定义评测脚本需遵循EvalScope接口规范，并通过Python实现模型加载、推理调用、结果返回和输出解析等逻辑，以接入LLM精度评测流程。

3.4.2.5.1. 必要条件

模型脚本必须完成以下四个核心步骤：

  1. 定义API名称：设置全局常量 API_NAME。

  2. 注册模型：使用 @register_model_api(name=API_NAME) 装饰模型类。

  3. 继承基类：模型类必须继承自 ModelAPI。

  4. 实现推理接口：实现 generate() 方法，并返回 ModelOutput 对象。

3.4.2.5.2. 脚本推荐模板

以下是一个模板，展示了如何接收 hmeval 注入的参数：

from typing import List, Dict, Any, Optional
from evalscope.api.model import ModelAPI, GenerateConfig, ModelOutput
from evalscope.api.messages import ChatMessage
from evalscope.api.tool import ToolChoice, ToolInfo
from evalscope.api.registry import register_model_api

API_NAME = "my_custom_model"


@register_model_api(name=API_NAME)
class MyCustomModel(ModelAPI):
    def __init__(
        self,
        model_name: str,
        base_url: Optional[str] = None,
        api_key: Optional[str] = None,
        config: GenerateConfig = GenerateConfig(),
        **model_args: Dict[str, Any],
    ) -> None:
        super().__init__(model_name, base_url, api_key, config)

        # hmeval 会自动传入
        self.model_dir = model_args.get("model_dir")
        if not self.model_dir:
            raise ValueError("`model_dir` is required")

        # 来自 --model-args
        self.tokenizer_dir = model_args.get("tokenizer_dir")

    def generate(
        self,
        input: List[ChatMessage],
        tools: List[ToolInfo],
        tool_choice: ToolChoice,
        config: GenerateConfig,
    ) -> ModelOutput:
        # 在这里实现推理逻辑
        text = "hello"
        return ModelOutput.from_content(model="my_custom_model", content=text)

3.4.3. 定位与优化

3.4.3.1. 原始模型正常，编译后模型分数下降

如果原始模型在相同数据集上的评测结果正常，而编译后模型在标准数据集上的指标明显低于原始模型或历史基线，说明模型部署后的任务精度下降。此时应先排查量化配置和编译配置，确认是否是这两个环节引入的误差。

建议检查：

  • 量化配置是否影响生成质量。

  • 编译配置是否正确。

如果上述配置均正确，但编译后模型仍存在明显精度下降，可尝试调整量化参数，重新完成量化和编译，并使用LLM精度评测工具评估不同编译后模型的精度结果，选择精度表现较优的量化配置。

3.4.3.1.1. 量化调优

可通过调整量化策略和启用混合精度搜索，降低量化引入的精度损失。下面以qwen3.5模型为例，介绍量化策略优化流程。

  1. 在 houmo-examples-xh2/models/llm/qwen3.5 目录下，修改 config.yml 配置文件。示例如下：

    ...
quant:
  quant_type: w4a8h0_ssfp
  calib_data: ...
  mix_search:
    topk: 0.1
    weight_bits: [4, 8]
    act_bits: [8, 16]
    policy: topk
    task: llm
    metric: l1
    key_name: loss
...

    其中，量化策略相关的关键配置如下：

    • quant_type：量化策略。取值格式为 wNaY_format，用于指定权重与激活值的量化尾数位宽及量化格式，其中：

      • N：表示权重的尾数位宽，当前支持4或8。

      • Y：表示激活值的尾数位宽，支持设置为任意 8 至 16 位之间任意整数值。

      • hZ：可选字段，表示 hidden bit 标志，Z 支持设置为 0 或 1，例如 h0、h1。

      • nM：可选字段，表示 nshare 参数，M 为整数，例如 n64、n128。

      • format：表示所采用的量化格式，包括：

        • sefp：缩放因子采用SEFP格式表示。

        • ssfp：缩放因子采用SSFP格式表示。

      对于LLM模型，w4a8h0_ssfp 通常可作为通用量化策略。该策略表示权重尾数位为4‑bit，激活值尾数位为8‑bit，并使用SSFP量化格式。若量化后精度不满足预期，可尝试调整 quant_type 的取值，并通过精度评测选择更合适的量化策略。

    • mix_search：用于执行混合精度搜索。默认情况下，量化工具不执行混合精度搜索，权重和激活值的尾数位宽由 quant_type 参数指定。启用混合精度搜索后，量化工具会在控制精度损失的前提下，自动搜索更适合硬件执行的精度配置，以改善量化模型精度或部署效果。

    其中：

    • topk：选择高精度层的比例。例如 0.1 表示选择前 10% 敏感层使用高精度。

    • weight_bits：权重候选位宽列表，需要与 quant_type 中配置的权重位宽保持一致。

    • act_bits：激活值候选位宽列表，需要与 quant_type 中配置的激活位宽保持一致。

    • policy：混合精度选择策略，支持 topk 和 threshold。

    • task：任务类型，用于决定敏感度计算时采用的 loss 方式，支持 cv、cv_cls 和 llm。

    • metric：敏感度度量方式，支持 l1、sqnr 和 kl。

    • key_name：输出属性名称，用于指定敏感度计算时关注的输出字段，例如 loss。

    注意：mix_search 与 resizer 配置互斥。mix_search 需要运行原始 ONNX 模型进行敏感度分析，通常使用 float32 输入；而 resizer 会引入面向硬件 resize 的 YUV/uint8 输入，两者不能同时启用。

  2. 根据调整后的量化配置重新生成量化模型。执行以下命令：

    hmatc quant -c config.yml

    可尝试不同 quant_type 或 mix_search 配置，生成多个候选量化模型。

  3. 将候选量化模型分别编译生成编译后模型。执行以下命令：

    hmatc build --hmonnx hmonnx_path

    其中，hmonnx_path：量化后模型文件路径。

  4. 使用LLM精度评测工具重新对编译后模型进行精度评测。

  5. 选择最优量化配置的模型作为最终部署模型。

如果仍存在明显差异，建议收集模型文件、量化配置、编译配置、执行命令、日志和复现样本，并反馈后摩技术支持工程师进一步定位。

3.4.3.2. 单条样本回答异常

建议抽取异常样本单独复现，并检查：

  • 输入文本是否正确拼接。

  • chat template 是否与原始模型一致。

  • system、user、assistant 角色格式是否正确。

  • tokenizer 版本和词表是否正确。

  • 输入是否因上下文长度限制被截断。

  • stop words 是否导致生成提前结束。

如果仍存在明显差异，建议收集模型文件、量化配置、编译配置、执行命令、日志和复现样本，并反馈后摩技术支持工程师进一步定位。

3.4.3.3. 评测分数低，但人工判断回答正确

通常是输出解析或评分规则问题。

建议检查：

  • 答案提取规则是否正确。

  • 是否包含多余解释导致评分失败。

  • 选择题是否按要求输出 A/B/C/D。

  • 数学题是否正确提取最终答案。

  • 评测脚本是否只截取了部分输出。

如果仍存在明显差异，建议收集模型文件、量化配置、编译配置、执行命令、日志和复现样本，并反馈后摩技术支持工程师进一步定位。