📚 课程目录第4章离线测试方法

4、离线测试方法：模型推理脚本编写、批量测试、指标计算与结果保存

离线测试是Edge AI自动化评估体系的第一道质量闸门，其核心目标是在模型部署到目标硬件之前，利用已标注的数据集对模型进行系统性验证。与板端测试相比，离线测试不依赖真实硬件环境，具备更高的可重复性和调试便利性。本章将围绕模型推理脚本的编写规范、批量测试的执行策略、指标计算的数学定义与工程实现，以及结果保存的结构化方案展开，帮助学员建立一套可复用、可追溯的离线测试方法论。

上图展示了离线测试的完整工程链路：从数据准备开始，经过推理脚本执行、批量测试调度、指标计算，最终将结果持久化保存，并形成反馈闭环。整个流程强调模块化、可配置和可追溯性，这是自动化评估体系的基础架构。

4.1 核心原理：离线测试的定位与设计哲学

离线测试的本质是在受控环境中模拟模型推理过程，其设计哲学可以概括为“三个隔离”：与硬件隔离（不依赖具体芯片或开发板）、与运行环境隔离（使用固定版本的Python库和依赖）、与数据分布隔离（测试集独立于训练集和验证集）。这种隔离确保了测试结果的可比性和可复现性，使得算法工程师可以在模型迭代过程中快速定位性能变化的原因。

离线测试的输入通常包括：模型文件（如ONNX、TFLite、PyTorch导出格式）、测试数据集（图片/文本/传感器数据）、预处理配置（归一化参数、尺寸调整策略）、后处理配置（阈值、NMS参数）。输出则是结构化的指标报告和逐样本的预测记录。值得注意的是，离线测试并不等同于“在服务器上跑一遍模型”，它需要严格遵循目标部署时的预处理和后处理逻辑，否则测试结果会与板端表现产生显著偏差。

  关键认知：离线测试的“离线”指的是不依赖目标硬件，而非不依赖真实数据。测试数据必须来自实际业务场景的采样，且要覆盖边界情况（如光照变化、遮挡、噪声干扰）。如果使用过于“干净”的数据集，离线测试的指标会虚高，导致板端测试时出现性能悬崖。

4.2 模型推理脚本编写：从单样本到批处理的工程化实现

推理脚本是离线测试的执行核心，其质量直接决定了测试的效率和可靠性。一个健壮的推理脚本应包含以下五个层次：配置解析层（读取YAML或JSON配置）、数据加载层（支持多种数据格式和采样策略）、预处理层（与部署链路完全一致）、推理执行层（封装模型前向计算）、后处理与记录层（将原始输出转换为可计算的指标）。

以下是一个典型的推理脚本骨架，展示了如何将配置与执行逻辑分离：

import json
import time
import numpy as np
from pathlib import Path
from typing import Dict, List

class OfflineTester:
    def __init__(self, config_path: str):
        with open(config_path, 'r') as f:
            self.cfg = json.load(f)
        self.model = self._load_model(self.cfg['model_path'])
        self.preprocess_fn = self._build_preprocess(self.cfg['preprocess'])
        self.postprocess_fn = self._build_postprocess(self.cfg['postprocess'])
        
    def run_batch(self, sample_list: List[Dict]) -> Dict:
        """执行批量推理，返回指标和逐样本结果"""
        results = []
        start_time = time.time()
        for idx, sample in enumerate(sample_list):
            try:
                # 预处理
                input_tensor = self.preprocess_fn(sample['image_path'])
                # 推理
                raw_output = self.model(input_tensor)
                # 后处理
                pred = self.postprocess_fn(raw_output)
                # 记录
                results.append({
                    'sample_id': sample['id'],
                    'gt_label': sample['label'],
                    'pred_label': pred['label'],
                    'confidence': pred['confidence'],
                    'latency_ms': (time.time() - start_time) * 1000 / (idx + 1)
                })
            except Exception as e:
                results.append({
                    'sample_id': sample['id'],
                    'error': str(e),
                    'gt_label': sample['label'],
                    'pred_label': None,
                    'confidence': 0.0
                })
        return {'results': results, 'total_time': time.time() - start_time}

在编写推理脚本时，需要特别注意以下几点：异常捕获不能只记录错误信息，还要保留样本ID以便后续排查；批处理大小应根据GPU显存或CPU内存动态调整，避免OOM；随机种子必须固定，确保多次运行结果一致；日志输出要包含进度百分比和预计剩余时间，方便长时间测试的监控。

4.3 批量测试执行策略：效率与稳定性的平衡

批量测试不是简单地将所有样本循环一遍，而是需要设计合理的执行策略。常见的策略包括：全量测试（适用于小规模数据集，确保覆盖所有样本）、随机采样测试（适用于大规模数据集，按比例抽取代表性样本）、分层采样测试（按类别或难度分层，保证每个子集都有足够样本）。对于Edge AI场景，由于模型通常较小，推荐使用全量测试，除非数据集超过数万张且时间预算紧张。

批量测试的执行流程应包含以下步骤：

数据清单生成：扫描测试目录，生成包含路径、标签、元数据的CSV清单。
分片处理：将清单按固定大小（如256个样本）分片，支持断点续跑。
多线程/多进程加速：预处理和后处理可以并行，但模型推理需根据框架线程安全性决定。
实时监控：记录每个分片的耗时、内存占用、失败样本数，超过阈值时告警。
中间结果缓存：每完成一个分片就保存临时结果，防止程序崩溃导致全部重跑。

策略类型	适用场景	优点	缺点
全量测试	数据集 < 10k，时间充裕	结果精确，无采样偏差	耗时较长，资源占用高
随机采样	数据集 > 50k，快速验证	速度快，资源消耗低	可能遗漏边界样本
分层采样	类别不均衡，需保证每类覆盖	各类别均有代表性样本	需要先统计类别分布

风险提示：批量测试中最常见的错误是“数据泄漏”——即测试集中的样本与训练集存在重叠（如连续帧图片）。这会导致指标虚高，且无法反映真实泛化能力。建议在数据准备阶段使用哈希去重或文件名黑名单机制。

4.4 指标计算与结果保存：从原始输出到可决策报告

指标计算是离线测试的“翻译官”，它将模型的原始输出转换为业务方可理解的性能语言。对于分类任务，核心指标包括准确率（Accuracy）、精确率（Precision）、召回率（Recall）和F1分数；对于目标检测任务，还需计算mAP（mean Average Precision）和IoU（Intersection over Union）。指标计算必须基于混淆矩阵，而不是简单地统计正确数除以总数，因为后者无法反映类别不均衡问题。

结果保存建议采用“三级目录+双格式文件”的结构：

一级目录：测试任务名称（如detection_v2.1）
二级目录：测试时间戳（如20250614_1530）
三级目录：模型版本号（如model_epoch50）
文件格式：JSON（机器可读，包含完整指标和配置信息）+ CSV（人类可读，逐样本预测结果）

{
  "task": "image_classification",
  "model": "mobilenet_v3_edgetpu",
  "dataset": "test_set_v3",
  "metrics": {
    "accuracy": 0.9234,
    "precision": 0.9156,
    "recall": 0.9087,
    "f1_score": 0.9121
  },
  "confusion_matrix": [[120, 5], [8, 67]],
  "per_class_metrics": {
    "cat": {"precision": 0.96, "recall": 0.92},
    "dog": {"precision": 0.88, "recall": 0.94}
  },
  "config_snapshot": {
    "batch_size": 32,
    "preprocess": "resize_224_normalize",
    "threshold": 0.5
  }
}

在保存结果时，务必同时保存配置快照（模型路径、预处理参数、后处理阈值）和环境信息（Python版本、框架版本、依赖库版本）。这样在后续对比不同模型或不同版本时，才能准确判断指标变化的原因。

4.5 实战案例：智能相机分类模型的离线测试调优

某智能相机项目需要部署一个垃圾分类模型，目标是在树莓派4B上实现实时推理。算法团队在离线测试阶段发现，模型在测试集上的准确率为91.2%，但部署到板端后准确率骤降至78.5%。通过离线测试脚本的详细日志，团队定位到以下问题：

初始现象：离线测试时使用PIL库进行图片缩放，而板端使用OpenCV的resize函数。两者在插值算法上的差异导致输入分布偏移。离线测试脚本中记录了每张图片的预处理参数，对比后发现缩放后像素均值偏差达12.8。

分析过程：团队修改离线测试脚本，将预处理切换为OpenCV实现，并增加了一个“预处理一致性校验”模块——随机抽取100张图片，分别用两种方式处理，计算最大像素差异。结果发现差异超过15的图片占比达23%。

实际操作：在离线测试脚本中加入预处理模拟开关，通过配置文件指定使用PIL或OpenCV。同时增加了一个“预处理指纹”功能，将每张图片的缩放尺寸、均值、标准差记录到结果文件中。

结果对比：修正预处理后，离线测试准确率变为89.7%（略有下降但更真实），板端测试准确率提升至86.3%，差距缩小到3.4个百分点。进一步分析发现剩余差距主要来自板端INT8量化误差。

复盘经验：离线测试脚本必须与部署链路保持“预处理一致性”，否则测试结果会误导优化方向。建议在脚本中内置预处理对比工具，每次测试前自动校验。

最佳实践：在离线测试脚本中增加“环境自检”功能，启动时打印Python版本、关键库版本、CPU/GPU信息，并将这些信息写入结果文件。这能避免因环境不一致导致的“在我机器上能跑”问题。

4.6 常见误区与总结复盘

在离线测试的实际执行中，以下误区需要特别警惕：误区一：只关注平均指标。平均准确率高不代表模型可靠，必须查看每类别的精确率和召回率，尤其是样本量小的类别。建议在结果报告中加入“最差类别”提示。误区二：忽略推理延迟。离线测试通常只关注精度指标，但Edge AI场景对延迟敏感。建议在脚本中记录每次推理的耗时，并输出P50/P95/P99延迟。误区三：测试集一成不变。随着业务发展，数据分布会变化，建议定期更新测试集并重新生成基线。

总结而言，离线测试是Edge AI自动化评估的基石，其核心价值在于“快速、可靠、可追溯”。通过规范化的脚本编写、科学的批量测试策略、严谨的指标计算和结构化的结果保存，团队可以在模型部署前发现绝大多数问题，为板端测试节省大量时间。下一阶段，我们将把这些离线测试的产出物作为板端测试的输入基准，实现从离线到在线的平滑过渡。