诚实的性能评测

Spec: ISO/IEC 25010 Spec: ISO/IEC 17025 Evidence: Benchmark-backed

概览

一个没有方法说明的性能数字，几乎说明不了任何问题。「NextPDF 在 N 毫秒内渲染一份文档」这句话本身没有意义，除非你知道所测文档、硬件环境、执行次数以及变异程度。本页说明 NextPDF 如何衡量性能、为什么它报告的是经过统计把关的信号，而不是标题式数字，以及为什么这里不提供任何速度数字。

为什么这很重要

性能宣称是最容易发布、也最容易造假的数字——而且通常是不小心造假。在空闲的笔记本电脑上运行一次热身后的用例、取十次尝试中最快的一次、对热路径中根本没人调用的函数做微型评测：每一种都会产生一个真实的数字，却无法预测你实际工作负载中的任何情况。 Spec: ISO/IEC 25010 将性能效率定义为在指定条件下在时间与吞吐量参数内执行功能（ISO/IEC 25010，§3.10）。拿掉「在指定条件下」，这个数字就不再是一项测量，而只是一个没有意义的数字。

还有一种更隐蔽的失败：一个曾经为真的数字。当你把一个评测结果写进文章的那一刻，它就被冻结了。与此同时，代码、运行时与硬件都在持续变化。一个过时的「快」的宣称不只是帮不上忙；它是错的，而且错得悄无声息。

简短版

一个性能数字如果缺少方法就毫无意义：输入、环境、执行次数、热身策略，以及离散程度。
NextPDF 通过重复执行进行测量、舍弃热身迭代，并报告一个分布，而不是单一的最佳情况数字。
回归检测是统计性的：结果会用 Welch t 检验对照基准线来判定，因此一项变化必须同时具有统计显著性且大到值得关注，才会被计为一次回归。
不稳定的环境会被检测并报告，而不是被悄悄平均掉——过高的逐次执行变异会使结果失效，而不是藏在平均值里。
性能会以随构建一同产生的活信号形式发布，绝不会成为一个冻结的标题数字——这正是本页不出现任何毫秒数字的原因。

NextPDF 如何处理

这个引擎的性能把关是一项统计检验，而不是单次计时执行。它有文档化的方法论：将受测套件执行多次、舍弃预设数量的热身执行，并针对耗时与内存计算平均值、标准差与变异系数。接着，它会将当前结果对照一条已提交的基准线：

Repeat Run the measured suite N times under fixed conditions.
Discard warmup Drop the first W runs so cold-start noise is excluded.
Summarise Compute mean, standard deviation, and coefficient of variation for duration and memory.
Test vs baseline Welch's t-test (two-sample, unequal variance) against the committed baseline.
Decide Significant AND effect over threshold → regression. Variance over threshold → unreliable, not a pass. Absolute ceiling breach → hard fail.

NextPDF 的评测把关如何判定通过、失败或不可靠：进行重复测量、舍弃热身、汇整出分布，然后对一条已提交的基准线套用 Welch t 检定。一次回归需要统计显著性「且」具实质效应量；过度的变异会被呈报为不可靠，而非被平均成一个判定结果。

有三项特性让这件事保持诚实。第一，一次回归需要同时满足两个条件：统计显著性（这个差异不太可能只是噪声）以及超过门槛的效应量（这个差异大到值得在意）。一个微小但真实的变慢不会触发假警报；噪声数据中的一次大幅变慢也不会被漏掉。第二，不稳定本身就是一种判定：当逐次执行的变动超过界限时，把关会将该环境报告为不可靠。它不会把无意义的数值平均出来，然后称之为通过。第三，仍然有一个绝对上限——一个无论统计结果如何都会使构建失败的硬性上界。正因为有它，「无显著回归」永远无法为一个已经太慢的结果开脱。

这正是 ISO/IEC 17025 为任何可信指标所描述的测量纪律：在预先设定的条件下取得结果——包括单一环境内的可重复性（ISO/IEC 17025，§3.7）以及跨环境的再现性（ISO/IEC 17025，§3.5）。一个 NextPDF 性能数字只有在作为「此方法、此基准线、此次执行」的结果时才有意义。这也正是它与产生它的那次构建共存，而不是作为一句话放在这里的原因。

证据怎么说

Evidence: Benchmark-backed 这个引擎的评测把关实现了带热身舍弃的重复测量、平均值/标准差/变异系数的汇总，以及一项双样本 Welch t 检验来对照一条已提交的基准线，并给出明确的通过/回归/ 不稳定/硬性上限等结果。性能评测也以一个专属、可独立执行的套件与一套 PHPBench 工具的形式存在。性能是经过刻意测量得来的，而不是估算出来的。

Evidence: Standard-backed 「在指定条件下」并非编辑上的谨慎措辞。它就是定义本身。 Spec: ISO/IEC 25010, §3.10 将性能效率绑定到指定的时间、吞吐量与资源条件。一个缺少条件的数字并不是一项较弱的测量；它根本不是一项测量。

Evidence: Standard-backed 可重复性与再现性的框架遵循 Spec: ISO/IEC 17025 ：一个结果唯有相对于预先设定的条件才可信，并且需要区分同一环境内的可重复性与跨环境的再现性。一个无法说明其条件的评测，两者都不能宣称。

实际范例

「诚实」在实践中的样貌是一份方法陈述，而不是一个数字：

<?php

declare(strict_types=1);

// The gate is invoked with its conditions made explicit, e.g.:
//
//   php ci/scripts/benchmark-gate.php \
//       --runs=5 --warmup=1 --testsuite=Unit \
//       --baseline=<committed-baseline>
//
// It then reports, for duration AND memory:
//   - mean, standard deviation, coefficient of variation (the spread)
//   - Welch's t-test p-value and effect size vs the baseline
//   - a verdict: PASS | REGRESSION | UNSTABLE | hard-ceiling FAIL
//
// An honest performance statement is therefore shaped like:
//   "<suite>, <runs> runs (<warmup> warmup), <hardware/runtime>,
//    no statistically significant regression vs baseline <id>;
//    coefficient of variation within bound."
//
// It is NEVER shaped like:
//   "NextPDF is fast" — or a bare millisecond number with no method.

一次评测的交付成果，是那套可重现的方法以及判定结果。原始的毫秒数值属于产生它的那次构建，你可以在那里重新推导出它——而不是把它誊写进一份你无法重现它的文档里。

常见误解

第一个误解是以为评测就是一个数字。评测是一个产生分布的程序，那个数字只是从中抽出的一次取样。报告数次执行中最好的一次，或报告一次热身后的执行，并不是乐观；那是在测量另一件事（理想条件下的峰值），却把它标记为典型性能。

第二个误解是以为「无统计显著回归」代表「保证跟之前一样快」。它的含义是：在这个执行次数与这个变异程度下，观察到的差异落在该方法能够与噪声区分的范围之内。这是一个有边界、有条件的陈述。这正是为什么 NextPDF 将绝对上限保留为一道独立防护，并拒绝把结果压缩成一个未经条件限定的宣称——无论是为自己，还是针对任何其他人。

限制与边界

本页描述的是 NextPDF 如何测量与报告性能。它刻意不陈述任何吞吐量、延迟或内存数字。那些是在指定条件下由持续集成产物所产生的活信号，当前数值会随构建一同发布。在这里重述一个数字会失去条件限定，并且会变得过时——这正是本页所反对的失败方式。没有一个稳定的性能常数可供引用，所以这里一个也不引用。纪律本身就是交付成果。

执行次数、热身策略、门槛与基准线都由这个引擎的评测配置拥有，并随引擎及其硬件一同演进。如果该配置与本说明有任何冲突，以配置为准。NextPDF 不对任何其他库做性能比较——无论有利或不利——因为一个没有相同且明示条件的比较，正是本页要拒绝的那种未经条件限定的宣称。

词汇表

评测（Benchmark）——一套已定义的程序，在指定条件下产生测量值的分布，而不是单一数字。
热身执行（Warmup run）——一次被舍弃的起始迭代，用于避免冷启动效应（JIT、缓存、自动加载）污染被测量的结果。
变异系数（Coefficient of variation）——标准差除以平均值；一个无单位的离散程度度量，用来判断一次执行是否稳定到足以信任。
Welch t 检验（Welch’s t-test）——一项用于方差不相等情形的双样本统计检验，此处用来判定一个结果是否在噪声之外有别于基准线。
效应量（Effect size）——一个差异有多大，独立于统计显著性之外；NextPDF 在宣告回归前同时要求两者成立。
可重复性/再现性（Repeatability / reproducibility）——在预先设定的条件下，结果在单一环境内（可重复性）或跨环境（再现性）的一致程度，依 ISO/IEC 17025。
绝对上限（Absolute ceiling）——一个无论统计比较如何都会使构建失败的硬性上界。