3、原框架输出与设备输出：明确原框架（如PyTorch/TensorFlow）输出与BM1688设备输出的定义、获取方式及差异来源

在BM1688精度偏差排查工作中，首要任务并非直接比较数值，而是先厘清“原框架输出”与“设备输出”这两个基本概念的定义边界、获取路径以及差异产生的根源。很多排查工作陷入僵局，往往是因为对比的基准本身就不一致——例如，拿PyTorch的eval模式输出与设备端默认开启了BatchNorm融合后的输出直接相减，或者忽略了输入预处理（如归一化系数、通道顺序）的微小差异。本章将系统性地拆解这两个输出的定义、获取方式，并深入剖析差异的四大来源，为后续的逐层定位打下坚实基础。

上图清晰地展示了两个输出在各自链路中的位置。左侧是原框架输出，它是在模型定义、权重加载后，经过框架内前向推理得到的浮点结果；右侧是BM1688设备输出，它经历了编译转换、量化校准、TPU内核执行以及可能存在的反量化过程。中间的“差异来源”区域提示我们，两者之间的偏差并非单一因素造成，而是从算法到硬件多层因素叠加的结果。下面我们将逐一展开。

3.1 核心原理：两个输出的本质定义

原框架输出（Reference Output），通常指在PyTorch、TensorFlow等深度学习框架中，以原始浮点精度（FP32或FP16）运行模型，在特定输入下得到的张量结果。它是精度对比的“黄金基准”。需要特别强调的是，这里的“原框架输出”必须是推理模式下的输出，即关闭了Dropout、BatchNorm的training状态，且不计算梯度。如果误用了训练模式，BatchNorm层会使用当前batch的统计量，导致输出与设备端（通常融合了BN参数）产生系统性偏差。

BM1688设备输出（Device Output），是指模型经过BM1688的编译器（如TPU-MLIR或BMNETP）编译、量化后，在TPU上实际运行得到的输出。这个输出可能是INT8、FP16或INT32格式，取决于编译时的精度配置。设备输出是模型在目标硬件上真实性能的体现，也是最终部署效果的衡量标准。

两者之间的差异，用公式可以表示为：Diff = |Device_Output - Reference_Output|。但实际排查中，我们更关注的是差异的结构性分布——是整体偏移（bias），还是个别通道异常，或是特定输入下的偶发错误。这决定了后续排查的方向。

3.2 获取方式：如何拿到可信的对比数据

获取两个输出的过程看似简单，但其中隐藏着许多容易忽略的细节。以下是标准化的获取流程，建议在项目初期就固化下来，形成脚本。

3.2.1 获取原框架输出

1. 固定输入数据：选择具有代表性的输入（如ImageNet验证集子集、业务真实数据），并保存为二进制文件（如.npy或.bin），确保后续设备端使用完全相同的输入。
2. 设置模型为推理模式：在PyTorch中调用model.eval()，并使用with torch.no_grad():包裹推理代码。
3. 执行前向推理：得到输出张量后，将其转换为NumPy数组并保存。注意，如果模型包含Softmax等归一化操作，需要明确保存的是logits还是probabilities，并保持与设备端后处理一致。

# 示例：保存PyTorch模型输出
import torch
import numpy as np

model.eval()
with torch.no_grad():
    output = model(input_tensor)  # input_tensor 需与设备端输入完全一致
    np.save("ref_output.npy", output.cpu().numpy())

3.2.2 获取BM1688设备输出

1. 编译模型：使用TPU-MLIR工具链将原始模型转换为BM1688可执行的.bmodel文件。在编译时，需要指定量化模式（如INT8）和校准表。
2. 使用bmrt_test工具：该工具是获取设备输出的最直接方式。它可以加载.bmodel，输入二进制数据，并导出输出张量。
3. 运行时API获取：在部署代码中，通过bmrt_launch_tensor等API获取输出，并保存为文件。

# 使用bmrt_test获取输出（命令行示例）
bmrt_test --bmodel model_int8.bmodel --input input.bin --output device_output.npy

3.3 差异来源：四大核心因素深度拆解

理解差异来源是精准定位问题的前提。我们将差异来源归纳为以下四类，并给出判断方法。

差异来源	具体表现	判断方法	典型场景
1. 数值精度损失	输出值整体偏小或偏大，误差在1%~5%之间波动	计算余弦相似度；统计误差的均值/最大值	FP32转INT8量化后，权重分布不均匀
2. 算子实现差异	特定层（如Concat、Reshape）输出完全错误，其他层正常	逐层对比中间张量（需开启设备端dump功能）	编译器对算子进行了融合或拆分，导致边界处理不同
3. 预处理/后处理归属	输出差异极大，甚至符号相反	检查输入是否经过相同的归一化（mean/std）	原框架在模型内做了Normalize，而设备端在模型外处理
4. 数据布局与内存对齐	输出shape正确，但数值错位	对比NHWC与NCHW下的输出	编译器强制将通道维对齐到16的倍数，填充了无效数据

3.3.1 数值精度损失（量化误差）

这是最常见的差异来源。当模型从FP32转为INT8时，权重和激活值都被映射到有限的整数空间。如果校准集选择不当，或者某些层的数值动态范围过大，就会导致较大的量化误差。判断方法是：如果cosine_similarity(ref, device) > 0.99，但max_abs_error > 0.1，通常属于量化噪声，可通过调整校准策略或使用混合精度（部分层保持FP16）来优化。

3.3.2 算子实现差异（图优化）

BM1688的编译器会对计算图进行优化，例如将Conv + BN + ReLU融合为一个算子。这种融合在数学上是等价的，但在数值上可能因为中间结果的舍入方式不同而产生微小差异。更严重的情况是，某些算子（如Upsample的坐标变换）在不同框架中实现不同，导致输出错位。排查此类问题，需要借助工具逐层dump设备的中间结果。

3.4 案例拆解：一个典型的INT8量化偏差排查

以下是一个实际项目中的案例，展示了如何通过明确两个输出的定义和获取方式，快速定位问题。

背景与约束：某安防检测模型，原框架为PyTorch（FP32），需部署到BM1688。要求INT8量化后，mAP下降不超过2%。

初始现象：部署后，设备端输出的检测框明显偏移，mAP下降5%。初步对比分类得分，发现差异巨大。

关键数据：

• 参考输出（PyTorch）：ref_output.npy，shape为[1, 84, 8400]（包含box和class信息）。
• 设备输出：device_output.npy，shape为[1, 84, 8400]。
• 余弦相似度：0.85（异常偏低）。

分析判断过程：

1. 首先排除预处理差异：确认输入图像均经过相同的resize和normalize操作，像素值范围一致。
2. 检查输出布局：打印两个输出的stride信息，发现设备端输出的最后一维（8400）被对齐到了8448（8400向上对齐到16的倍数）。这导致数据读取时发生了错位。
3. 进一步验证：将设备输出按8448的stride重新切出前8400个数据，再与参考输出对比，余弦相似度提升至0.98。

实际操作步骤：

# 修正设备输出布局
device_output = np.load("device_output.npy")  # 实际shape为 [1, 84, 8448]
corrected_output = device_output[:, :, :8400]  # 截取有效部分
# 再次计算相似度
cos_sim = np.dot(ref.flatten(), corrected_output.flatten()) / (np.linalg.norm(ref) * np.linalg.norm(corrected_output))
print(f"修正后余弦相似度: {cos_sim:.4f}")

结果对比：修正后，mAP恢复到下降1.5%，在可接受范围内。后续通过调整校准集，进一步将mAP下降控制在1%以内。

风险与代价：该问题如果未及时发现，会误导排查方向，浪费大量时间在调整量化参数上。而实际只需在代码中增加一个slice操作即可解决。

复盘经验：在对比两个输出之前，务必先核对元数据（shape、stride、dtype）。很多时候，问题不在“数值算得不对”，而在“数据放的位置不对”。

3.5 常见误区与总结复盘

在明确两个输出定义和获取方式的过程中，以下误区需要特别警惕：

• 误区一：忽略模型模式。使用model.train()模式获取参考输出，导致BN层统计量异常。正确做法是使用eval()模式。
• 误区二：输入数据不一致。设备端使用了BGR输入，而原框架使用RGB，导致输出完全错误。建议在保存输入时，同时保存一份预处理后的二进制文件，确保两端输入一致。
• 误区三：混淆logits与softmax输出。如果原框架输出的是softmax后的概率值，而设备端输出的是logits，则差异会非常大。在对比前，必须明确约定输出层的位置。
• 误区四：忽视量化校准的随机性。校准集不同，量化阈值就不同，设备输出也会不同。因此，在记录设备输出时，应同时记录编译时使用的校准表版本。