Liquid AI 开源了一个基准测试套件 Pipette它把端侧模型、模型量化、运行时和硬件四个维度统一到同一套评测流程中。和那种“一个脚本只跑一个指标”的做法不同Pipette 的定位是让模型评测可复现模型版本、量化档位、运行时版本、硬件环境都作为明确的评测变量记录并固定下来跑出来的结果可以被回溯、被对比、被别人复现。换句话说它要解决的是端侧 AI 选型中最常见的问题——模型在宣传页面上跑得很漂亮但换到自己的手机、自己的推理框架、自己的量化参数之后准确率和速度到底还剩多少。这个问题如果不把评测流程固定下来每次讨论都会变成不同变量的交叉比较很难得出可靠结论。这次我们来看 Pipette 到底能做什么同时给出适合本地试跑的部署和评测思路。文章会先讲清楚这个基准套件的核心能力再展开环境准备、安装启动、评测任务设计、批量跑分、结果汇总和常见问题排查。如果你正在做端侧模型部署、量化方案选型、运行时切换或者硬件适配评估这篇文章可以直接收藏按步骤跑一遍之后至少能建立一套属于自己的模型评测基线。1. Pipette 核心能力速览在动手前先对 Pipette 有一个整体判断。下面这张表整理了它的能力边界其中标注“以官方文档为准”的项请结合你下载到的实际版本确认避免版本差异导致误判。能力项说明项目类型开源基准测试套件定位为可复现的模型评测工具开源方Liquid AI主要功能同时评测端侧模型、量化方案、运行时与硬件四个维度核心特点可复现、可配置、多因素交叉对比评测对象端侧大语言模型或推理模型模型格式和来源以项目实际支持列表为准典型指标准确率类任务指标、推理延迟、吞吐量、资源占用等以项目输出为准运行环境通常支持 Linux 系统具体操作系统要求以官方 README 为准GPU 要求取决于被测硬件CPU 和 GPU 设备都可能被纳入评测启动方式命令行为主建议通过虚拟环境或容器隔离是否提供 API不确定需查看官方文档基准测试工具通常以 CLI 为主要入口是否支持批量任务评测矩阵天然适合批量执行实际支持程度以项目实现为准适合场景端侧模型选型、量化精度评估、运行时性能对比、硬件适配测试、CI 回归从这张表可以提炼出 Pipette 的关键价值它不是又一个“拿几个数据集刷分”的脚本合集而是一套把评测条件显式化、可配置化的体系。对于团队来说这意味着组内不同成员跑出的结果可以放在同一张表里比较对于个人来说这意味着三个月前跑过的评测三个月后还能用同样条件复现并检查变化。需要特别说明的是本文并不替代官方 README。开源项目迭代很快仓库地址、文件结构、CLI 参数、依赖版本都可能在文章发布后变化下面所有命令和配置都以“通用模板”形式给出使用时必须替换成你的实际路径和参数。2. Pipette 要解决的评测难题2.1 传统评测流程的三个痛点先看一个很常见的场景你想知道一款 7B 模型量化成 INT4 之后在自己的设备上能不能用。于是你分别做了三件事——用一个脚本跑模型准确率用另一个脚本测推理速度再开一个工具记录显存占用。三个脚本各自独立数据集可能不一样采样参数可能不一样甚至模型的输入输出长度都不一样。最后你得到一堆数据却很难回答“INT4 比 FP16 到底慢了多少”“量化之后准确率损失是否可以接受”。这就是传统评测流程的第一个痛点评测标准不统一。不同脚本、不同数据集、不同 prompt 模板都会让结果失去可比性。第二个痛点是量化与运行时互相干扰。同一个量化模型放到 llama.cpp 和 ONNX Runtime 里性能差异可能来自量化本身也可能来自运行时对算子的优化程度不同。如果没有把“量化档位”和“运行时”分开控制你很难定位瓶颈在哪里。第三个痛点是硬件差异导致结果漂移。同一个模型在 RTX 4090、MacBook M 系列芯片和 Android 手机上跑结果可能完全不是一回事。如果你的评测流程没有记录硬件环境结论就无法迁移。2.2 可复现基准套件意味着什么Pipette 的做法是把评测对象拆成几个可控维度然后让使用者为每个维度指定明确值。你可以把模型、量化格式、运行时、硬件型号都写进评测配置系统按照配置批量执行任务并把环境信息、模型哈希、参数版本一并记录到输出结果中。这样做的好处是评测结果不再依赖“某个人当时怎么跑的”而是依赖“一份配置文件和一次命令执行”。只要配置文件不变、数据版本不变、硬件环境一致任何人都可以在自己的设备上复现同一套结果。这正是基准测试工具区别于临时脚本的地方。从工程实践角度看可复现还意味着可以接入自动化流水线。每次模型更新、量化算法更新、运行时版本更新都可以触发一次完整的 Pipette 评测把“效果有没有回退”变成一条可自动检查的规则。3. 适用场景与使用边界在动手部署之前先判断一下 Pipette 适不适合你的情况。它能解决一类特定问题但不是所有评测场景都需要它。3.1 适合谁如果你属于以下几类角色Pipette 值得重点评估。端侧部署工程师。你需要确认某个模型在目标设备上的真实表现包括量化后的精度损失、单次推理耗时、内存占用、功耗曲线等。通过 Pipette 把模型和硬件之间的匹配关系测试清楚可以少走很多弯路。量化算法选型人员。你需要在 FP16、INT8、INT4 以及不同 GGUF 量化档位之间做选择。Pipette 的评测矩阵设计正好适合这种横向对比同一个模型跑多个量化档位结果直接并列比较。运行时维护者。你维护或使用 llama.cpp、MLC-LLM、ONNX Runtime、TensorRT 等推理引擎需要评估运行时升级对性能和效果的影响。此时可以把运行时作为唯一变量固定模型和数据集跑出前后对比。硬件采购或适配人员。你想比较不同芯片、不同 GPU、不同内存配置下的推理表现Pipette 可以帮你统一测试口径避免“拿 A 卡跑出的结果和 B 卡跑出的结果直接比”这种不公平比较。3.2 不适合谁如果你只是想快速试一个模型好不好用随手在 Hugging Face 上跑一段 demo 就够不需要专门搭一套基准测试环境。如果你的业务指标非常特殊比如必须使用自研评估公式、自定义复杂 Agent 流程那么通用基准套件只能作为参考你仍需要在此基础上做二次开发。另外如果你只依赖云端商业平台自带评测不需要本地沉淀历史数据Pipette 也未必是首选。3.3 合规与安全边界使用任何模型评测工具都需要注意几个边界。第一测试数据集必须确认授权范围不要随意把未公开数据、版权数据或包含个人隐私的数据塞进评测集。第二被测模型的权重文件要根据模型许可证使用尤其是商用场景必须确认权重是否允许商用。第三如果测试内容涉及人脸、声音、对话记录等敏感信息必须先做匿名化处理并取得必要授权。第四Pipette 属于软件工具卸载、停止服务、删除缓存数据时要考虑数据残留问题评测输出中可能包含测试输入发布前要做好脱敏。4. 环境准备与前置条件部署 Pipette 之前先把环境检查一遍。这里给出一份通用清单具体版本要求请以项目 README 为准。4.1 操作系统基准测试工具通常以 Linux 为主要支持平台常见发行版如 Ubuntu 22.04、Debian 12 一般都能跑通。Windows 环境下建议使用 WSL2 或直接在 Linux 虚拟机上运行遇到问题的概率更低。macOS 也可以尝试但部分运行时依赖可能需要编译过程更容易出问题。4.2 Python 与包管理建议准备 Python 3.10 或更高版本并提前装好 pip、venv 或 conda。如果项目依赖 PyTorch、transformers 等重量级库这些库本身又会带来大量传递依赖一定要用虚拟环境隔离避免污染系统 Python。4.3 GPU 与驱动是否必须 GPU 取决于你要评测的内容。如果只是评测端侧小模型并观察 CPU 推理性能没有 GPU 也能跑如果要评测 CUDA 推理、需要大显存加载大模型则要提前装好 NVIDIA 驱动和 CUDA Toolkit。具体 CUDA 版本取决于依赖库要求不要盲目装最新版。在 Linux 下检查 GPUnvidia-smi如果命令找不到说明驱动没有装好或者没有加入 PATH。确认 GPU 是否被 PyTorch 识别import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU only)4.4 磁盘空间与网络评测过程需要下载模型权重、数据集和依赖库。一个 7B 模型的 FP16 权重大约需要 15GB 磁盘空间INT4 量化版会小很多大约 4GB 左右。一组评测数据集可能从几十 MB 到几个 GB 不等。建议准备至少 50GB 的可用磁盘空间并保证网络可以正常访问模型仓库和 Python 包仓库。4.5 端口资源如果 Pipette 提供 Web 界面或 API 服务需要检查端口是否被占用。常见端口如 7860、8000、8080 可能被其他服务占用。启动前可以用命令检查ss -tlnp | grep 7860如果端口被占用要么释放端口要么在配置中换一个端口。5. 安装部署与启动方式Pipette 的安装方式取决于官方仓库提供的入口。下面给出一套通用流程覆盖源码克隆、依赖安装和启动验证三个步骤。5.1 克隆仓库并创建虚拟环境git clone Pipette 官方仓库地址 cd pipette python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt这里有两个地方需要替换Pipette 官方仓库地址要替换成官方 README 中给出的真实地址requirements.txt要根据仓库实际文件名调整可能是requirements-dev.txt或通过pyproject.toml安装。5.2 验证安装安装完成后先查看命令行帮助确认主程序能正常启动。pipette --help如果命令不存在可以尝试用模块方式启动python -m pipette --help输出中应该能看到评测任务的子命令列表例如run、list、report之类的名称。具体子命令以项目实际实现为准。5.3 准备模型和数据集目录为了让后续评测可复现强烈建议在项目外单独建一个工作目录把模型、数据集、评测输出分开管理。mkdir -p ~/benchmark/models mkdir -p ~/benchmark/datasets mkdir -p ~/benchmark/outputs模型文件可以下载到~/benchmark/models数据集放在~/benchmark/datasets每次评测结果输出到~/benchmark/outputs。这样后续写批量脚本时路径逻辑会非常清晰。5.4 启动评测任务Pipette 通常以命令行方式运行。一个典型的评测命令大概长这样pipette run \ --model 模型路径或模型名 \ --quantization 量化档位 \ --runtime 运行时名称 \ --hardware 硬件标识 \ --dataset 数据集路径 \ --output-dir 输出目录以上参数名只是通用示例。实际参数名可能完全不一样请务必先执行pipette run --help查看当前版本支持哪些参数再拼接命令。6. 评测任务设计与效果验证6.1 先明确评测目标启动一次评测之前先想清楚“这次我要对比哪个变量”。这是一个很关键的原则一次评测尽量只改变一个变量否则结果很难解释。如果你要对比不同量化档位那么模型、运行时、硬件、数据集都要固定如果你要对比不同运行时那么模型、量化档位、硬件、数据集都要固定。Pipette 的价值就在于它允许你把这些变量写进配置不容易看错。6.2 设计评测矩阵举例来说假设你要评估“同一个 7B 模型在 FP16、INT8、INT4 三种量化方案下在目标设备上的表现”评测矩阵可以这样定义固定项值模型固定某个 7B 基座模型版本运行时固定某个推理引擎版本硬件固定一台设备数据集固定同一份评测数据固定 prompt 模板采样参数固定温度、max length、并发数、预热轮数变量项量化方案FP16 / INT8 / INT4如果你还要同时比较多个运行时矩阵就会扩展成一个二维交叉表量化档位和运行时都在变。这样会跑很多次但对于选型来说往往是最有价值的。6.3 编写评测配置很多基准测试工具支持用 JSON 或 YAML 文件描述评测任务。下面的 JSON 示例展示了一个“多变量交叉对比”的配置结构字段名需要按实际项目接口修改{ model: { name: your-model-name, revision: specific-commit-or-tag }, quantizations: [fp16, int8, int4], runtimes: [runtime-a, runtime-b], hardware: your-device-id, dataset: { path: /path/to/dataset, prompt_template: your-template, max_samples: 100 }, generation: { temperature: 0.0, max_tokens: 128, batch_size: 1, num_runs: 3 }, output: { dir: /path/to/outputs, format: jsonl } }这里的关键字段是quantizations和runtimes使用了数组代表你要执行的交叉评测组合。num_runs表示同一条件跑几次用于降低随机波动。revision用于锁定模型版本这是可复现性的重要一环。6.4 运行评测配置好之后执行评测。pipette run --config benchmark.json运行过程中要注意观察日志输出。正常情况下控制台会逐条打印每个评测组合的进度。如果中途失败先看错误堆栈不要急于重跑。6.5 判断成功标准一个评测组合是否成功可以从几个维度判断。任务指标是否正常。如果是问答或分类类任务检查准确率、F1、匹配率等指标是否在合理区间。如果量化后结果严重偏离 FP16 基线说明量化精度损失过大需要审查量化算法或回退档位。性能指标是否完整。启动后能否正常输出每轮延迟、吞吐量、峰值资源占用。如果只有任务指标没有性能指标说明评测配置可能漏掉了资源采集组件。可复现性是否达标。同一评测条件重复跑三次主要指标的波动范围应该在可接受区间。如果波动过大先检查是否有后台进程抢占资源或者模型评测是否依赖随机采样。ls -lh /path/to/outputs/你要能看到每个评测组合对应的输出文件。打开其中一个确认里面记录了模型名、量化档位、运行时版本、硬件信息、任务指标和性能指标。缺少这些元信息评测结果就很难回追溯源。7. 批量评测与结果汇总7.1 批量任务的执行方式端侧评测往往不是跑一次就结束而是要跑一整套矩阵。Pipette 这类基准测试工具通常支持重复执行命令你可以用一条 shell 循环把整个矩阵串起来。下面是一个批量执行示例只做演示实际命令以项目 CLI 为准for quantization in fp16 int8 int4; do for runtime in runtime-a runtime-b; do pipette run \ --model your-model-name \ --quantization $quantization \ --runtime $runtime \ --hardware your-device-id \ --dataset /path/to/dataset \ --output-dir /path/to/outputs/${quantization}_${runtime} done done批量执行时要注意两点第一每个任务要有独立的输出目录避免结果互相覆盖第二建议在循环中加入失败重试和超时保护不要因为一个组合失败就让整个矩阵中断。7.2 结果汇总与对比批量评测完成之后输出目录里会有大量 JSON 文件。你可以写一个 Python 脚本把所有结果读进来汇总成表格。import json import glob rows [] for path in glob.glob(/path/to/outputs/**/result.json, recursiveTrue): with open(path, r, encodingutf-8) as f: data json.load(f) rows.append({ quantization: data.get(quantization), runtime: data.get(runtime), accuracy: data.get(accuracy), latency_ms: data.get(latency_ms), tokens_per_second: data.get(tokens_per_second), peak_memory_mb: data.get(peak_memory_mb), }) for row in sorted(rows, keylambda x: x[tokens_per_second], reverseTrue): print(row)这种汇总方式可以让你快速看到谁快、谁准、谁占内存。更完整的做法是把结果导出成 CSV然后放到表格工具里做交叉分析。7.3 接入自动化流水线如果你的团队有 CI/CD 系统可以把这个评测矩阵做成一个定时任务或者发布前检查项。模型权重更新、推理引擎升级、量化工具链变更都可以触发一次评测。判断标准也很直接准确率不能低于某个阈值吞吐量不能低于某个底线峰值内存不能超出设备上限。接入 CI 时建议把评测结果作为一个可上传的 artifact 保存并对比历史基线。这样每次回归都能看到变化是变好还是变坏而不是只看到“今天跑过了”。8. 资源占用与性能观察8.1 如何观察显存与内存评测过程中如果目标是 GPU最直接的方式是在另一个终端里运行nvidia-smi实时观察显存占用watch -n 1 nvidia-smi如果目标是 CPU 推理可以用htop查看多核负载和内存。更精确的做法是在评测脚本里调用系统 API 周期性记录资源使用量并写进结果文件。具体实现方式取决于运行平台但思路是一样的资源占用必须是评测输出的一部分而不是事后估算。8.2 控制变量减少测量误差推理性能测试最怕干扰。如果你一边跑评测一边开浏览器、下载文件、编译代码测出来的延迟一定是不稳定的。为了保证可复现建议做到以下几点固定采样参数。温度、top-p、max tokens、batch size 都要固定尤其是长文本生成任务输出长度不同会直接影响延迟。加入预热轮。深度学习框架的首次推理通常会额外做算子加载和显存分配直接计入平均值会偏高。每一组配置先跑一次或几次预热再把正式轮次用于统计。使用多次运行取中位数。不要只跑一次最低跑三次取中位数或者均值。如果方差依然很大检查后台进程和 CPU 频率策略。记录硬件状态。CPU 频率是否锁定、GPU 是否有其他进程占用、内存是否充足这些都应该记录。否则两个同学跑同一个配置结果差异很大时会很难解释。8.3 不同硬件和量化档位的观察重点端侧模型的资源占用和量化档位强相关。FP16 模型显存占用最高INT8 显著下降INT4 通常最低。量化不仅影响模型权重体积也影响计算过程中的中间激活值。如果评测目标是在 4GB 显存设备上跑模型重点观察峰值显存是否接近上限如果在 CPU 设备上跑重点观察内存和线程并发对吞吐的影响。这些表现需要以本机实测为准。不要照搬别人的显存数字因为模型结构、输入长度、并发数、运行时实现都会影响结果。9. 常见问题与排查方法安装和评测过程中总会出现各种问题。下面整理了一张排查清单覆盖从环境到结果的常见故障。问题现象可能原因排查方式解决方案安装依赖失败网络问题、Python 版本不匹配查看 pip 错误日志检查 Python 版本切换 pip 镜像源升级 Python 版本或降级依赖启动命令不存在未安装成功、入口脚本名不同执行pip list查看包名查看 README用python -m模块方式启动或按实际入口调整CUDA 相关报错驱动版本过低、CUDA Toolkit 不匹配执行nvidia-smi和torch.cuda.is_available()升级驱动安装项目要求的 CUDA 版本显存不足模型太大、量化档位不够低、并发过高观察nvidia-smi显存占用降低并发改用低比特量化或使用 CPU 推理端口被占用其他服务占用同一端口执行ss -tlnp检查端口换端口或先停掉占用端口的服务评测结果波动大后台任务干扰、未充分预热观察 CPU/GPU 占用检查是否预热锁定频率加入预热轮多次运行取中位数模型加载失败权重损坏、模型路径错误、格式不支持检查文件哈希和目录权限重新下载模型确认模型格式与运行时兼容输出文件为空评测中断、配置字段不正确查看日志尾部堆栈修正配置单独运行一个最小组合量化后准确率骤降量化算法不支持某些算子、校准数据不匹配比较不同量化档位结果回退量化档位或更换量化工具10. 最佳实践建议10.1 第一次先跑最小配置不要一上来就跑完整的模型矩阵。先跑一个最小配置比如“一个模型、一个量化档位、一个运行时、10 条数据”确认流程能跑通。流程通了之后再逐步把数据量和评测矩阵扩大。这样做能在最开始就发现配置错误而不是等到跑了几小时后才发现参数名打错了。10.2 模型、数据、输出分目录管理建议把模型权重、测试数据集、评测输出分成三个独立目录并且给输出文件加上时间戳和评测矩阵标识。一个常见的目录结构可能长这样benchmark/ ├── models/ │ └── your-model/ ├── datasets/ │ └── eval-set-v1/ └── outputs/ ├── 2025-05-01-fp16-runtime-a/ └── 2025-05-01-int4-runtime-b/这样做的好处是无论什么时候回看你都能知道某份结果来自哪个模型、哪个数据集、哪个时间点。10.3 保存完整环境信息评测结果只有模型指标是不够的。至少要把操作系统版本、Python 版本、GPU 型号、驱动版本、运行时版本、依赖版本都记下来。有些框架自带版本查询命令建议把输出追加到评测日志里。这样别人复现结果时才有足够信息还原环境。pip freeze /path/to/outputs/requirements.txt nvidia-smi /path/to/outputs/env_info.txt10.4 批量任务加日志和失败重试批量跑评测矩阵时绝对不能裸奔。每个任务都要有独立日志失败时能快速定位是哪一组组合、哪个环节出错。脚本里可以加入重试逻辑但要注意避免“卡死的任务反复重试”。更稳妥的方式是任务级超时、失败记录、最后统一汇总失败列表。这样即使某个组合失败也不影响其他组合的结果。10.5 注意授权与隐私如果你使用第三方数据集先确认许可证是否允许重新分发、是否允许用于模型评测。如果你评测业务数据先脱敏。如果评测结果可能对外公开输出报告前检查是否包含敏感文本或个人信息。涉及人脸图片、声纹数据、对话记录时尤其要谨慎。11. 总结与下一步Pipette 值得尝试的点在于它把“模型评测”从临时脚本变成了一套可配置、可复现、可批量执行的工作流。对端侧模型开发者来说它帮你把模型、量化、运行时、硬件四个变量理清避免在选型时被孤立的指标误导。对量化工程实践来说它是比较不同压缩方案的有力辅助工具对运行时和硬件适配来说它提供了一套统一口径的对照方法。建议拿到项目后先做三件事第一跑通最小配置确认 CLI 参数和环境没问题第二固定同一模型对比两种量化档位或两个运行时的差异建立基线第三把评测输出整理成固定格式接入自己的脚本或 CI之后每次模型升级都能自动回归。最容易踩的坑有两个一是配置里没有锁定模型版本和数据集版本导致结果无法横向比较二是性能测量没有预热和多次运行导致波动掩盖了真实差异。把这两个坑填平你的评测结果就已经超过很多人随手跑的结论。后续可以继续扩展的方向包括把自定义业务指标嵌入评测流程、引入更多端侧推理引擎、增加多设备并发评测、把评测报告导出成可视化看板。只要结果输出格式保持稳定这些扩展都能在现有基础上逐步加上去。建议先克隆仓库读一遍 README跑通一个最小评测任务再决定要不要把它做成团队内部的标准流程。