端侧模型评测看起来很简单加载一个模型跑几条输入记录耗时对比精度。实际做起来很少有人能给出真正可复现的结论。同一个模型用不同版本的量化工具转换在不同运行时里推理换一台设备或者改变线程数结果可能差出一倍以上。更麻烦的是很多评测报告根本不告诉你数据是怎么来的。Liquid AI 开源的 Pipette就是一套试图把端侧模型、量化、运行时与硬件四类变量统一管理起来的可复现基准套件。这篇文章会从评测链路拆解开始讲清楚 Pipette 要解决什么问题、一个最小评测任务怎么配置、结果怎么解读以及排错时该按什么顺序查。1. 为什么端侧模型评测容易失真1.1 评测链路里的变量太多端侧推理不是“模型放进手机就能比较”这么简单。一次完整的端侧评测至少经过这样的链路源模型PyTorch、TensorFlow 或其他框架训练出的浮点模型。格式转换导出为 ONNX、TFLite、MNN、NCNN 等中间格式。优化和量化动态量化、静态量化、INT8、INT4以及不同的校准数据集。运行时目标机器上执行推理的框架版本例如 ONNX Runtime、TFLite Runtime、MNN、NCNN、llama.cpp 的 GGUF 后端。硬件环境CPU 型号、NPU/DSP 是否启用、内存带宽、散热状态、系统调度策略。评测脚本预热轮数、重复次数、批量大小、输入分辨率、线程数、是否绑核。任何一个环节变了最终指标都会变。传统做法是把这些信息零零散散写在 README 或实验记录里时间一长就没法追溯。Pipette 的核心思路就是把上面这些信息全部结构化让“一次评测”可以完整复现也让不同团队之间的评测结果可以互相比较。1.2 可复现评测需要锁定的四类要素标题里提到的四类要素正好对应评测中最容易失控的部分端侧模型模型架构、权重来源、输入输出尺寸、是否带后处理。量化量化方案、位宽、校准集、每个 tensor 的量化和反量化方式。运行时框架名称、版本号、算子实现、线程模型。硬件设备型号、算力单元、可用内存、功率和散热策略。如果把一次评测看作一个实验那么“模型 量化 运行时 硬件”就是实验条件。条件不同结果就没有可比性。Pipette 这类基准套件做的事情就是把这些条件变成配置项随评测结果一起输出。这样别人看到的不只是“延迟 20ms”而是“在什么设备、什么运行时、什么量化配置下的延迟 20ms”。1.3 Pipette 在评测体系里的定位Pipette 不是一个模型训练框架也不是量化工具本身。它是一个评测编排层负责把模型准备、运行时加载、输入构造、指标采集、结果汇总这些步骤串起来。可以这样理解层次代表工具职责模型训练PyTorch、TensorFlow产出浮点权重模型转换与量化ONNX、TensorRT、llama.cpp、各种量化 SDK把浮点模型变成端侧可执行格式推理运行时ONNX Runtime、TFLite、MNN、NCNN、llama.cpp在设备上执行计算评测编排Pipette 这类基准套件定义任务、采集指标、输出可复现报告实际项目里这四个层次经常混在一起导致问题难以定位。量化后精度下降到底是校准集不合适还是运行时算子实现有问题还是硬件对低精度支持不完整没有统一的评测入口很难回答。Pipette 把这几个层次解耦每个环节都有明确的输入输出出了问题就知道该查哪一段。2. 理解 Pipette 的核心设计2.1 一个评测任务由哪几部分组成从工程角度看Pipette 的一个评测任务通常由五部分组成模型清单要评测的模型和对应的导出格式。量化配置量化位宽、量化方式、校准数据来源。运行时配置用哪个推理框架、什么版本、什么线程策略。负载定义输入数据、输入尺寸、批量大小、预热轮数和正式轮数。指标定义要采集哪些指标以及指标的统计方式。把这五项写成配置文件Pipette 按配置执行最后输出一份结构化的结果文件。评测任务本身可以版本化管理放入 Git 仓库这样每次改动都有记录。2.2 量化和运行时在评测中扮演的角色量化是端侧部署绕不开的一步因为浮点模型体积大、计算量大很多端侧设备跑不动。量化的直接效果是模型体积变小、推理变快、内存占用降低代价可能是精度损失。评测时量化不应该只看“精度掉了多少”还要看这个精度损失是在什么硬件、什么运行时下产生的。运行时则是另一个关键变量。同样是 INT8 模型在架构优化好的运行时和算子全部走 fallback 的运行时里延迟可能差数倍。Pipette 评测中会记录运行时的名称和版本并把“算子是否走硬件加速”这类信息尽量暴露出来。这样当结果异常时可以快速判断是模型自身问题还是运行时执行路径问题。2.3 硬件评测要采集哪些数据硬件信息分为静态信息和动态信息两类。静态信息包括设备型号、CPU 架构、核心数、内存大小、是否支持特定加速指令动态信息包括推理时的 CPU 占用、内存峰值、功耗、温度、频率。不要只记录静态信息。很多评测结果波动都来自动态因素手机跑几轮后降频、长时间推理后温度升高、后台进程抢占 CPU。可靠的基准套件会把两类信息一起记录并在报告中标注设备状态。Pipette 的做法是在评测前后各采集一轮硬件状态把环境状态变化写进结果元数据方便复现时判断数据是否可信。3. 环境准备与安装3.1 环境清单开始使用 Pipette 之前先确认机器满足基本条件。下面的清单同时覆盖开发机和目标设备。环境项开发机要求目标设备要求操作系统Linux、macOS、Windows 均可以目标设备实际系统为准Python3.9 或更高版本不一定需要 Python取决于运行时推理运行时按评测目标安装对应运行时安装对应端侧运行时模型转换工具ONNX、量化 SDK 等按需安装只需要已转换好的模型设备连接adb、SSH 或本地执行通道开启调试或远程访问权限如果原始材料没有给出特定版本落地前要先确认依赖版本。基准测试对版本非常敏感同一运行时的大版本之间算子实现可能完全不同。建议把运行时版本固定下来不要使用“最新版”这类模糊描述。3.2 安装步骤假设使用 Python 包作为入口安装过程通常类似这样# 创建独立虚拟环境避免污染系统 Python python3 -m venv .venv source .venv/bin/activate # 安装基准套件本体 pip install liquid-pipette # 安装评测目标运行时例如 ONNX Runtime pip install onnxruntime # 如果涉及模型转换再安装转换依赖 pip install onnx onnxruntime-tools这里的关键是虚拟环境。评测工具和运行时的依赖经常互相冲突不隔离环境后面遇到 ImportError 时很难判断是哪个包引起的。3.3 验证安装安装完成后先运行一个最简单的自检任务确认工具能正确识别设备和运行时。pipette --version pipette devices list pipette runtimes list预期输出里能看到当前设备信息和已安装的运行时。如果devices list为空说明设备连接或驱动有问题如果runtimes list没有目标运行时说明依赖没装全。先解决这两个问题再进入正式评测。4. 用 Pipette 跑一个最小基准任务4.1 准备模型和数据集以一个图像分类模型为例。这个任务要做的是把一个 INT8 量化后的 MobileNet 模型在 ONNX Runtime 上跑 100 张图片记录平均延迟和 Top-1 精度。第一步是准备模型。这里不再细讲训练和量化过程假设已经得到了一个 INT8 的 ONNX 文件。模型文件命名建议带上关键信息比如mobilenet_v2_int8.onnx避免结果文件里出现难以辨认的名字。输入数据建议使用固定图片集合可以是验证集抽样也可以是一组统一的测试图像关键是要能重复加载。4.2 编写评测配置Pipette 的配置通常采用 YAML 格式。下面是一个最小示例用于说明配置结构实际项目要结合自己的包名、路径和版本调整name: mobilenet_int8_ortal device: model: RK3588 backend: cpu threads: 4 model: path: ./models/mobilenet_v2_int8.onnx input_name: input input_shape: [1, 3, 224, 224] output_name: output labels: ./data/labels.txt quantization: scheme: static precision: int8 calibration_set: ./data/calib_images runtime: name: onnxruntime version: 1.17.0 providers: [CPUExecutionProvider] benchmark: batch_size: 1 warmup_iters: 5 repeat_iters: 100 timeout_sec: 120 metrics: - latency - memory - accuracy这个配置文件把前面提到的四类要素全部固定下来。benchmark段的warmup_iters尤其重要端侧推理第一次调用通常会触发初始化、内存分配、算子编译不预热就统计延迟会把初始化开销也算进去。4.3 运行评测配置文件准备好后执行pipette run --config ./benchmarks/mobilenet_int8.yaml --output ./results/运行过程中注意观察终端输出。正常执行时工具会依次输出准备模型、加载运行时、预热、正式评测、采集硬件状态等阶段的状态。如果某个阶段卡住超过timeout_sec还没有完成可以先用更小的repeat_iters排查。4.4 查看结果运行结束后结果目录会生成结构化报告。典型的输出包括results/ ├── mobilenet_int8_ortal_summary.json ├── mobilenet_int8_ortal_detail.csv ├── mobilenet_int8_ortal_log.txt └── environment.jsonsummary.json里会有关键指标内容大致如下{ task: mobilenet_int8_ortal, device: {model: RK3588, backend: cpu, threads: 4}, runtime: {name: onnxruntime, version: 1.17.0}, metrics: { latency_avg_ms: 12.35, latency_p50_ms: 11.90, latency_p95_ms: 15.20, latency_p99_ms: 18.30, memory_peak_mb: 312, accuracy_top1: 0.882 }, environment: { temperature_start_c: 42, temperature_end_c: 47, cpu_freq_start_mhz: 1800, cpu_freq_end_mhz: 1600 } }这里最容易犯的错误是只看平均延迟。实际项目里P50、P95、P99 比平均值更能反映真实体验因为端侧推理偶尔会出现长尾延迟平均值会被极大值拉动。Pipette 在结果里同时输出多个统计值就是提醒使用者不要只读一个数字。5. 关键参数与配置详解5.1 设备与运行时参数参数含义常见值调大影响调小影响threads推理线程数4、8延迟降低但可能出现资源争抢延迟上升稳定性可能更好providers运行时执行提供方CPUExecutionProvider、CUDAExecutionProvider决定算子跑在哪个单元配置错误会导致算子全部走 fallbackruntime.version运行时版本号1.17.0高版本算子优化可能更好低版本可能与量化格式不兼容providers是一个高风险配置。ONNX Runtime 里如果请求的 Provider 不满足条件会自动回退到 CPU而且不会报错。结果就是你以为用了 GPU/NPU实际跑的是 CPU。评测时一定要在日志里确认每个算子实际使用的执行提供方。5.2 量化参数量化参数需要在模型转换阶段确定Pipette 负责记录和验证不负责重新量化。常见参数如下参数含义常见值错误配置表现scheme量化方式static、dynamicdynamic 模型在端侧可能仍保留浮点计算precision量化位宽int8、int4、fp16位宽不支持时模型加载失败calibration_set校准数据集100-500 张代表性图片校准集分布偏差导致精度明显下降per_channel是否按通道量化true、false按 tensor 量化在部分模型上精度损失更大量化评测里最常见的坑是“校准集和验证集混用”。如果校准集就是从验证集里抽出来的精度结果会虚高换一批真实数据就露馅。正确做法是校准集和验证集严格分开。5.3 数据采集参数benchmark段的参数直接决定统计结果是否可信。参数含义推荐值说明warmup_iters预热轮数5-10不预热首次调用开销会污染结果repeat_iters正式轮数50-200轮数太少P95 不稳定batch_size批量大小1端侧场景多数是单张推理timeout_sec单次任务超时120防止某个模型卡死拖垮整个评测5.4 参数速查清单写配置时建议按这个顺序检查设备信息是否准确尤其线程数和后端类型。模型路径是否存在、输入输出名是否匹配。量化配置和模型实际格式是否一致。运行时名称和版本是否与已安装依赖一致。预热轮数和正式轮数是否合理。输出目录是否可写磁盘空间是否充足。6. 结果解读与横向对比6.1 关键指标Pipette 输出的指标大致分三类性能指标延迟均值、P50、P95、P99、吞吐量。资源指标内存峰值、CPU 占用、功耗。质量指标精度、相似度等任务相关指标。对比时延迟和精度要放在一起看。一个模型延迟降低 30% 但精度下降 5 个百分点到底值不值得取决于业务场景。医疗影像、自动驾驶这类任务对精度极度敏感优先保证精度视频流检测这类高吞吐任务可以接受较少精度损失换性能。6.2 正确对比方式横向对比必须保证单一变量原则。想对比两个运行时就要用同一个模型文件、同一份输入数据、同一台设备、同一个线程数。想对比量化效果就要用同一个浮点模型作为基准分别测试浮点版本和量化版本。推荐的对比矩阵如下对比目的固定不变唯一变化运行时对比模型、量化、设备、数据运行时量化对比模型、运行时、设备、数据量化位宽或方案硬件对比模型、量化、运行时、数据硬件设备线程数对比模型、量化、运行时、设备threads 参数如果一次改了多个变量测出来的差异无法归因。这也是可复现基准套件存在的原因配置记录完整才能保证对比有效。6.3 区分学习环境与生产环境学习环境里跑通一次评测和生产环境长期做评估要求完全不一样。学习环境轮数可以少一点10 轮预热、30 轮正式测试足够验证流程。不关心功耗和温度只验证工具能跑通。设备信息不完整也可以接受。生产环境必须固定运行时版本并在结果中记录版本号。增加硬件动态状态采集监控温度和频率变化。设置失败重试机制避免单次卡死中断整个评测任务。结果自动归档关联到模型版本和代码版本。加入异常检测例如轮次结果方差过大时自动告警。生产环境的评测不是跑一次就结束而是要形成常态化回归每次模型更新、量化参数调整、运行时升级都要跑同一套基准用历史数据判断变化是否可接受。7. 常见问题排查7.1 结果波动太大现象同一份配置连续跑两次平均延迟差 20% 以上。可能原因和排查方式设备温度过高导致降频。检查结果中的temperature_start_c和temperature_end_c如果结束温度明显升高先让设备冷却再跑。后台进程抢占资源。评测前关闭无关应用必要时锁定 CPU 核心。预热不足。增加warmup_iters观察第一次和后续轮次的延迟差距。输入数据或模型加载路径变化。确认两次评测加载的是同一个模型文件和同一批输入。处理建议先固定环境温度再增加预热轮数最后检查设备频率。如果是移动设备尽量在评测期间让设备保持充电并关闭自动亮度等干扰项。7.2 量化后精度下降异常现象INT8 模型比浮点模型精度低 10 个百分点以上远超预期。排查顺序检查校准集和验证集是否重合。重合会导致虚高反过来校准集过小会导致泛化差。检查量化配置里的per_channel是否设置合理部分模型需要按通道量化。检查运行时是否完整支持量化算子。有些算子没有量化实现会走反量化到浮点再计算精度损失反而更大。检查模型的输入输出是否在预处理阶段保持一致。量化模型经常对输入归一化方式敏感。处理建议用更小的量化范围测试例如在部分层上保留浮点计算定位精度损失集中在哪一层。7.3 运行时崩溃或 OOM现象任务进行到一半进程退出或日志里出现Cannot allocate memory、segfault。排查路径先检查模型加载是否成功内存不足经常发生在模型加载阶段。确认输入张量大小是否符合模型要求非法输入可能导致崩溃。检查是否开启了过多线程。threads设置过高加上系统其他进程会造成内存压力。如果是移动设备检查可用内存和 swap 状态。处理建议先减小batch_size再降低threads最后确认系统剩余内存。日志里出现崩溃时优先保留现场日志和 core dump方便对照运行时版本排查。7.4 日志和监控怎么配合遇到问题不要只看最终结果要分层看日志日志层级内容排查价值工具日志任务阶段、配置加载、错误信息判断任务在哪一步失败运行时日志算子执行、Provider 选择、警告判断执行路径是否正确系统日志OOM、进程被杀、驱动错误判断是否有外部因素干扰排查顺序优先级是输入是否正确、路径是否存在、依赖版本是否匹配、配置是否生效、硬件资源是否充足、日志是否出现明确异常、运行时版本是否有已知限制。8. 最佳实践与扩展方向8.1 可复用的评测检查清单每次提交一份评测报告之前建议逐项核对模型文件是否包含量化信息和来源描述。配置文件是否在 Git 仓库里留存。运行时版本是否固定并记录。设备信息是否完整包括硬件型号和系统版本。是否记录预热轮数、正式轮数和线程数。结果文件是否包含 P50、P95、P99而不只是平均值。是否记录了评测前后的温度和频率状态。校准集和验证集是否严格分离。多组对比是否保证单一变量。是否有人工复核结果波动原因。这份清单既适用个人实验也适用团队发布评测报告前审查。8.2 实际项目里的落地建议在真实项目里不要把 Pipette 只当做一个命令行工具而是把它当成评测流程的基础设施。第一把配置文件纳入版本管理。每次模型更新或量化参数调整都对应一个配置文件变更。这样可以追溯“这个结果是用哪个配置跑出来的”。第二建立历史基准库。第一次跑通后把结果保存为基线。后续改动模型或运行时都和基线对比及时发现回归。第三自动化执行。在 CI 或定时任务里加入评测步骤让端侧模型评测从手工操作变成常态化回归。注意自动化和人工评测要区分自动化适合跑确定性的延迟和资源指标涉及到业务效果评估仍然需要人工设计任务。第四不要迷信单一指标。延迟、内存、精度、功耗要综合判断尤其是移动端场景功耗指标经常决定一个模型能否真正上线。8.3 扩展方向Pipette 这类可复现基准套件后续比较值得扩展的方向有三个一是多设备矩阵。同一套配置在多台设备上运行自动生成横跨硬件的对比报告。这对选择端侧芯片、确定机型适配范围很有价值。二是量化参数扫描。把量化位宽、校准集大小、per_channel 开关作为参数组合自动批量评测找到精度和性能的平衡点。手动一个个试效率太低且容易遗漏组合。三是运行时覆盖扩展。除了 ONNX Runtime、TFLite 这类常见运行时还可以接入 MNN、NCNN、llama.cpp 等不同生态的推理后端把评测范围从 CV 模型扩展到 LLM 端侧部署。端侧评测的价值不在跑出几个数字而在于这些数字可以被信任、被复现、被比较。Pipette 把“模型、量化、运行时、硬件”四个维度统一到一套配置体系里本质上是在帮助团队养成严谨的评测习惯。对刚接触端侧部署的开发者来说从给第一次评测加上完整配置记录开始就已经比大多数随手跑跑的实验靠谱很多。