• 中文
  • 3.9.0

    • 推荐阅读顺序

    本章节用于在您已经明确当前任务之后，帮助您选择后续阅读路径，包括：

    • 我现在更适合先走哪条链路。

    • 这一轮应该先读到哪里。

    • 什么时候需要切换到下一条路径。

    如果您已经知道自己现在要做的是快速验证、精度优化、部署排障或平台选型，可以直接从本章节对应路径开始进行。

    使用方式

    建议您先按当前任务选择一条主线，不必在开始阶段就把所有专题全部读完。

    每条路径都建议先读到一个阶段性终点，再根据结果决定下一步：

    如果您当前同时面临平台选择和链路选择两个问题，建议先补读下面两页，再进入具体路径：

    • 平台差异说明：先确认当前平台在量化策略、输出精度、输入输出处理和部署能力上的差异。

    • 模型量化编译-总览：先判断当前更适合从 ONNX 链路进入，还是从 PyTorch 链路进入。

    快速验证路径

    这类场景的重点，是先把模型量化、编译和基础验证的主链路跑通。

    已有 ONNX 模型

    如果您当前已有 ONNX 模型，建议先沿 PTQ 链路阅读，推荐阅读顺序如下：

    1. 平台差异说明：先明确当前平台更适合的量化起点和部署验证重点。

    2. 模型量化编译-总览：先建立 ONNX 链路在整套工具链中的位置。

    3. ONNX 模型快速入门：先跑通一次最小闭环，建立对整体流程和关键产物的直观认识。

    4. ONNX 模型量化原理及流程概述：再回到主流程页，系统理解标准 PTQ 链路的整体步骤。

    5. PTQ 基本流程相关页面：继续按需阅读 浮点模型准备、模型验证、数据准备、模型量化与编译、模型性能评估 和 模型精度评估，分别补齐模型准备、模型检查、数据准备、量化编译以及精度和性能评估的细节。

    6. ONNX 模型部署一致性分析：如果您已经进入结果比对阶段，可继续通过本章节理解各阶段产物和一致性验证方法。

    7. 板端评测 或 模型推理应用开发指导：在完成 quantized.bc / hbm 验证后，继续进入板端验证和部署适配。

    这一轮通常读到已经得到 quantized.bc / hbm，并完成一次基础精度或性能验证，就可以先停下来。

    如果这时发现精度仍不满足需求，建议先阅读 精度调优指导，优先尝试进行调优。

    已有 PyTorch 模型和训练代码

    如果您当前已有 PyTorch 模型和训练代码，建议先从最小闭环开始，先确认 Prepare、Calibration、导出、定点化和编译链路可以顺利走通，推荐阅读顺序如下：

    1. 平台差异说明：先明确当前平台更适合的起始精度配置和部署验证方式。

    2. 模型量化编译-总览：先理解 PyTorch 链路在整体流程中的位置。

    3. PyTorch 模型快速上手：先把一条最小可运行链路跑通。

    4. PyTorch 模型量化简介：再补齐这条链路适合什么场景、主要解决什么问题。

    5. PyTorch 模型量化基本流程：建立从浮点模型改造到最终验证的完整主线认识。

    6. 构建 QConfig：先明确当前平台和模型适合的量化配置模板。

    7. Prepare 说明：确认图捕获、算子替换和检查产物是否符合预期。

    8. 模型校准 Calibration：重点理解 Calibration 在链路中的位置，以及它与后续导出、部署验证的关系。

    9. 定点模型转换：继续理解 export、convert 和 quantized.bc 的关系。

    10. 模型编译及性能评测：最后再进入 compile、性能评测和部署前验证。

    这条路径的阶段性目标，是先完成一次 Prepare -> Calibration -> Export / Convert -> Compile -> quantized.bc / hbm 的最小闭环。

    如果 Calibration 后精度已经基本满足需求，可以先继续做部署验证。 如果 Calibration 后精度仍不满足需求，再进入下面的精度优化路径，通常更容易带着明确问题继续阅读。

    精度优化路径

    如果当前目标已经不是“先跑通”，而是需要继续提升量化精度，建议先按当前模型来源选择对应链路。 ONNX 链路主要解决 PTQ 方向的精度调优问题；PyTorch 链路则适用于需要继续做 Calibration 深入分析、混合精度配置或 QAT 训练的场景。

    ONNX 链路

    如果您当前已经完成 PTQ 基本流程，但在精度评估阶段发现结果不达预期，建议按下面的顺序继续阅读：

    1. 平台差异说明：先确认当前平台在量化策略和计算精度上的差异，避免一开始就按不适合的平台策略调优。

    2. ONNX 模型量化原理及流程概述：重新梳理 PTQ 各阶段产物和整体流程，避免把阶段问题混在一起看。

    3. 模型精度评估：先确认当前掉点是否稳定可复现，以及精度问题是在哪一轮评估中暴露出来的。

    4. 精度调优指导：继续通过校准方法、量化参数搜索、独立量化和计算精度配置缩小范围。

    5. ONNX 模型部署一致性分析说明：如果您已经怀疑问题不只是“量化本身掉点”，还涉及不同阶段产物之间的不一致，可以继续看这一节。

    6. ONNX 模型量化常见问题 和 常见故障处理：如果过程中已经出现明确报错、配置问题或运行异常，再继续从这里排查。

    如果经过 PTQ 精度调优后，结果仍然无法满足需求，再继续评估是否需要转向进行量化感知训练。

    PyTorch 链路

    如果您当前已经进入 Prepare / Calibration / QAT 主线，或者已经明确需要通过混合精度和 QAT 继续提升精度，建议按下面的顺序阅读：

    1. 平台差异说明：先确定当前平台更适合从哪类精度配置起步。

    2. PyTorch 模型量化简介：先明确这条链路适合解决什么问题，以及它和 PTQ 路径的边界。

    3. PyTorch 模型量化基本流程：先把全链路阶段关系和阶段产物读清楚。

    4. 构建浮点模型：先确认模型结构本身是否量化友好。

    5. 构建 QConfig：确定当前平台和模型更适合的量化配置模板。

    6. Prepare 说明：确认图捕获、算子替换和检查产物是否正常。

    7. 模型校准 Calibration：先判断问题是否已经在 Calibration 阶段暴露出来。

    8. 量化感知训练：如果 Calibration 后仍无法满足需求，再进入 QAT 训练阶段。

    9. 精度调优指导：继续用分步量化、直方图分析、敏感度分析和混合精度配置缩小范围。

    10. 部署一致性分析说明：如果已经进入导出和定点化阶段，再确认问题是否已经转移到一致性层面。

    11. 调试产物解读：如果已经开始查看 model_check_result.txt、fx_graph.txt、qconfig_dtypes.pt 或逐层比较结果，可继续结合这一节判断问题落点。

    这条路径的重点，是先判断问题更可能停留在模型结构、量化配置、Calibration 结果，还是已经进入 QAT 和混合精度阶段。

    通常读到已经能比较清楚地判断当前精度问题主要集中在哪一段，这一轮阅读就已经达到目的。

    一致性分析与部署排障路径

    如果当前问题已经不是“怎么继续调精度”，而是“为什么不同阶段结果不一致”“为什么定点结果或上板结果异常”，建议按模型链路分别进入一致性分析和部署排障页面。

    ONNX 链路

    如果您当前使用的是 ONNX 模型量化链路，建议按下面的顺序阅读：

    1. ONNX 模型部署一致性分析说明：先看 xxx_original_float_model.onnx、xxx_optimized_float_model.onnx、xxx_calibrated_model.onnx、xxx_ptq_model.onnx 和 xxx_quantized_model.bc 之间的关系。

    2. 板端评测 或 模型推理应用开发指导：如果 bc 侧结果已经基本正常，但板端结果异常，再继续看部署验证和应用开发章节。

    3. ONNX 模型量化常见问题：如果当前更像是配置、模型支持度或工具使用问题，可先从这里缩小范围。

    4. 常见故障处理：如果已经出现明确错误、日志异常或运行失败，再继续看这一节。

    这条路径里，建议先判断下面几种情况：

    • 如果 xxx_calibrated_model.onnx 或 xxx_ptq_model.onnx 阶段就已经明显掉点，排查重点通常不在部署，而应先回到 模型精度评估 和 精度调优指导。

    • 如果 xxx_quantized_model.bc 异常，而前面的 onnx 阶段结果基本正常，排查重点应先放在转换和一致性分析阶段。

    • 如果 xxx_quantized_model.bc 基本正常，但板端结果异常，排查重点应先放在板端评测、前后处理和部署适配阶段。

    PyTorch 链路

    如果您当前使用的是 PyTorch 模型量化链路，建议按下面的顺序阅读：

    1. 定点模型转换：先确认 qat.pt / qat model、qat.export.pt、qat.bc、quantized.bc 等关键产物的关系。

    2. 部署一致性分析说明：再按 export、convert、compile / 部署三个阶段理解定位顺序。

    3. 调试产物解读：如果您已经在查看 model_check_result.txt、fx_graph.txt、qconfig_dtypes.pt、compare_per_layer_out.txt 等产物，可继续结合这一节一起看。

    4. 模型编译及性能评测：如果问题已经进入 compile、quantized.bc 验证或 hbm 验证阶段，再继续看这一节。

    5. 板端评测 或 模型推理应用开发指导：如果 quantized.bc 已基本正常，但 hbm 或上板结果异常，再继续排查板端验证和部署适配。

    6. PyTorch 模型量化常见问题 和 常见故障处理：如果已经出现明确报错、配置失效或训练 / 导出异常，再继续结合这两节排查。

    这条路径里，建议先判断下面几种情况：

    • 如果 qat.pt / qat model 在 Calibration 或 QAT 阶段就已经异常，排查重点通常不在 export、convert 或 compile，而应先回到 模型校准 Calibration、量化感知训练 和 精度调优指导。

    • 如果 qat.pt / qat model 正常，但 qat.bc 异常，排查重点应先放在 export 阶段。

    • 如果 qat.bc 正常，但 quantized.bc 异常，排查重点应先放在 convert 阶段。

    • 如果 quantized.bc 正常，但 hbm 或上板结果异常，排查重点应先放在 compile、板端评测和部署适配阶段。

    通常读到已经能比较稳定地判断问题更可能落在哪个阶段，这一轮阅读就已经有了明确价值。

    按角色选择入口

    如果您更习惯按当前职责来决定从哪里开始，也可以参考下面的简化入口。

    初学者

    建议先阅读 平台差异说明 和 模型量化编译-总览，先建立整体认识。 然后根据手头模型选择 ONNX 模型快速入门 或 PyTorch 模型快速上手，再进入对应链路的基本流程页。

    算法工程师

    建议先从 PyTorch 模型量化主线进入，优先阅读 PyTorch 模型量化简介、PyTorch 模型量化基本流程、构建浮点模型、构建 QConfig、Prepare 说明、模型校准 Calibration、量化感知训练 和 精度调优指导。

    部署工程师

    建议先从导出、定点化和部署验证主线进入，优先阅读对应链路的基本流程页、定点模型转换、模型编译及性能评测、PyTorch 模型部署一致性分析说明 或 ONNX 模型部署一致性分析说明、板端评测 和 模型推理应用开发指导。