ベンチマーク

このガイドでは、laurus のベンチマークの実行方法、ベースライン（baseline）の保存と比較方法、プルリクエストでの結果報告方法について説明します。

ベンチマークスイートは laurus/benches/ 配下にあり、Criterion で構築されています。衛生ルール（決定的シード、ファイル冒頭ドキュメント、sanity assert、sample_size ポリシー）は laurus/benches/common.rs で一元管理されています。

スイート一覧

ファイル	スコープ
`bkd_bench.rs`	BKD ツリーの範囲検索（range search）、交差判定（intersect）、構築（1D / 2D / 3D、10k / 100k / 1M ポイント）
`distance_bench.rs`	`DistanceMetric::distance` の cosine / Euclidean / Manhattan / dot product（現状は単一次元、次元スイープは #424 で対応予定）
`lexical_search_bench.rs`	`Engine::search` 経由のエンドツーエンド lexical 検索（term / boolean / phrase / fuzzy / DSL）
`search_perf.rs`	Posting iterator の `skip_to`、`BM25Scorer::score`、SIMD バッチスコアリング、コンパクト posting 変換
`spell_correction_bench.rs`	`SpellingCorrector::correct`、各イテレーションごとに fresh corrector を渡す cold-state 計測
`synonym_bench.rs`	`SynonymDictionary::get_synonyms` のルックアップ（100 / 1k / 10k グループ）と構築コスト
`text_analysis_bench.rs`	`StandardAnalyzer::analyze` のシングルドキュメントとバッチ（100 ドキュメント）解析
`vector_search_bench.rs`	Flat / IVF / HNSW の構築と検索（1k / 5k ベクタ、dim 128、top-10）

各ファイル冒頭の //! ドキュメントコメントにスコープ・シナリオ・フィルタ方法が書かれています。実行前に確認してください。

ベンチマークの実行

単一ベンチファイルを実行：

cargo bench -p laurus --bench distance_bench

criterion id でフィルタ（部分一致）：

cargo bench -p laurus --bench distance_bench -- cosine
cargo bench -p laurus --bench vector_search_bench -- "HNSW Search/top10"

コンパイル確認のみ（CI やリファクタリング時に有用）：

cargo bench -p laurus --bench distance_bench --no-run

ワークスペースの全ベンチを実行：

cargo bench -p laurus

ベースラインの保存と比較

Criterion は名前付きベースラインをサポートしており、フィーチャーブランチを main（または任意の参照状態）と比較できます。

現在の状態を main という名前のベースラインとして保存：

cargo bench -p laurus --bench distance_bench -- --save-baseline main

その後の実行結果をベースラインと比較：

cargo bench -p laurus --bench distance_bench -- --baseline main

出力には change: 行がベンチマーク単位で表示され、変化率と判定（No change in performance detected、Performance has improved、Performance has regressed）が示されます。Criterion はベースラインを target/criterion/<bench-id>/<baseline>/ 配下に保存します。

perf PR の推奨フロー：

main（または変更前の状態）で — cargo bench --bench RELEVANT -- --save-baseline main
ブランチで変更を実装
ブランチで — cargo bench --bench RELEVANT -- --baseline main
change: 行を PR 説明にコピーする

推奨環境

µs / ns 単位のマイクロベンチマークはシステムノイズに敏感です。意味のある数値を得るには：

CPU governor: performance に設定（Linux）：
```
sudo cpupower frequency-set -g performance
```
Turbo boost: 周波数スケーリングが結果を歪めないように無効化：
```
echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo   # Intel
```
AMD システムや BIOS レベルの設定は異なるためベンダーのドキュメントを参照してください。
バックグラウンド負荷: ブラウザ・IDE・ビルドウォッチャー・Docker を停止する。CPU を共有するものは短時間ベンチを歪めます。
コア固定（任意）: 利用可能なら固定コアにピン留め：
```
taskset -c 2 cargo bench -p laurus --bench distance_bench
```
再実行: 2 回実行して比較する。チューニング済みマシンで ~5 % 以下の差はノイズ。共有ワークステーションでは ~5 % を超える差もノイズの可能性がある。1 回の実行結果を過大解釈しない。

環境を安定化できない場合は、不安定な数値を権威ある数値として提示せず、PR で明示的に断ること（例:「共有ノート PC で測定、~10 % のノイズを想定」）。

Make ターゲット

Makefile から共通エントリポイントを利用できます：

make bench             # cargo bench -p laurus
make bench-baseline    # cargo bench -p laurus -- --save-baseline main
make bench-compare     # cargo bench -p laurus -- --baseline main

単一ベンチを指定する場合は BENCH=name を渡します：

make bench BENCH=distance_bench
make bench-baseline BENCH=distance_bench
make bench-compare BENCH=distance_bench

PR 説明テンプレート

PR で計測可能なパフォーマンス変化を主張する場合、下記のようなテーブルを説明に貼り付けてください：

## Performance

Environment: <CPU モデル>, governor=performance, turbo disabled, dedicated machine.

Baseline: `main` at <commit-sha>. After: this branch at <commit-sha>.

| Bench | Before | After | Δ | Verdict |
| --- | --- | --- | --- | --- |
| `distance_metrics/cosine` | 4.20 µs | 3.10 µs | -26 % | improved |
| `distance_metrics/euclidean` | 2.18 µs | 2.16 µs | -1 % | no change |

Reproduce: `cargo bench -p laurus --bench distance_bench -- --baseline main`

比較が再現可能となるように、ベースラインと変更後の commit SHA を必ず含めてください。チューニング済みマシンで実行した場合でも環境を明示してください。

新しいベンチマークの追加

新規ベンチファイルを追加する際は、laurus/benches/common.rs のスイート全体衛生ルールに従ってください：

common::DEFAULT_SEED（または lcg_* ヘルパ）で決定的シードを使う。rand::rng() は使わない。
ファイル冒頭に //! ドキュメントコメントでスコープ・シナリオ・実行コマンド・フィルタ例を記載する。
タイミング b.iter の外側で 1 度だけ assert! を実行し、空結果を出す regression を黙ってパスさせない。
SAMPLE_SIZE_FAST（デフォルト、50 ms 以下の操作向け）または SAMPLE_SIZE_SLOW（構築パス向け）のいずれかを選ぶ。中間値は使わない。
laurus/Cargo.toml に [[bench]] name = "..." harness = false で登録する。クレートは autobenches = false を設定しているため、benches/ 配下のファイルは自動検出されない。

ファイル間でヘルパを共有する必要がある場合は、benches/common.rs を拡張してコード重複を避けてください。

CI 連携

現状、CI ではリグレッション検出のベンチジョブは実行していません。perf 系の PR は、推奨環境下で取得した baseline-vs-after 数値を手動で投稿することが想定されています。

将来的には大きなリグレッションで失敗するスモークセットのベンチジョブを追加する案があり、アンブレラ Issue #429 で追跡されています。

Keyboard shortcuts

Laurus ドキュメント