誠實的效能評測

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）——一個無論統計比較如何都會使建置失敗的硬性上界。