---
description: "MacでLLMベンチマークの正確な結果を得る方法：サーマル管理、バックグラウンドアプリ、実行回数、再現性のヒント。"
---

# ベンチマークのベストプラクティス

> **バージョン**: 0.3.2
> **ステータス**: 進化に合わせて更新されるリビングドキュメント
> **参考**: MLPerf Inference、SPEC CPU 2017、NVIDIA GenAI-Perf

## 概要

`asiai bench`は、確立されたベンチマーク標準に従い、Apple Silicon上の推論エンジン間で**信頼性があり、再現可能で、比較可能**な結果を生成します。このドキュメントでは、実装済み、計画中、または意図的に除外されたベストプラクティスを追跡します。

## 準拠サマリー

| カテゴリ | プラクティス | ステータス | 導入バージョン |
|----------|----------|--------|-------|
| **メトリクス** | TTFTとtok/sの分離 | 実装済み | v0.3.1 |
| | 決定論的サンプリング（temperature=0） | 実装済み | v0.3.2 |
| | サーバーAPIからのトークンカウント（SSEチャンクではない） | 実装済み | v0.3.1 |
| | エンジンごとの電力モニタリング | 実装済み | v0.3.1 |
| | generation_duration_msの明示的フィールド | 実装済み | v0.3.1 |
| **ウォームアップ** | エンジンごとに1回の非計測生成 | 実装済み | v0.3.2 |
| **実行回数** | デフォルト3回（SPEC最小要件） | 実装済み | v0.3.2 |
| | 主要メトリクスとして中央値（SPEC標準） | 実装済み | v0.3.2 |
| | 副次メトリクスとして平均値 + 標準偏差 | 実装済み | v0.3.0 |
| **分散** | プーリングされたプロンプト内標準偏差 | 実装済み | v0.3.1 |
| | CVベースの安定性分類 | 実装済み | v0.3.0 |
| **環境** | 逐次エンジン実行（メモリ分離） | 実装済み | v0.1 |
| | サーマルスロットリング検出 + 警告 | 実装済み | v0.3.2 |
| | サーマルレベル + speed_limitの記録 | 実装済み | v0.1 |
| **再現性** | エンジンバージョンをベンチマークごとに保存 | 実装済み | v0.3.2 |
| | モデルフォーマット + 量子化を保存 | 実装済み | v0.3.2 |
| | ハードウェアチップ + macOSバージョンを保存 | 実装済み | v0.3.2 |
| | オープンソースのベンチマークコード | 実装済み | v0.1 |
| **リグレッション** | 履歴ベースラインとの比較（SQLite） | 実装済み | v0.3.0 |
| | (engine, model, prompt_type)ごとの比較 | 実装済み | v0.3.1 |
| | metrics_versionフィルタリング | 実装済み | v0.3.1 |
| **プロンプト** | 4種類の多様なプロンプト + コンテキストフィル | 実装済み | v0.1 |
| | プロンプトごとの固定max_tokens | 実装済み | v0.1 |

## 計画中の改善

### P1 — 統計的厳密性

| プラクティス | 説明 | 標準 |
|----------|-------------|----------|
| **95%信頼区間** | CI = mean +/- 2*SE。+/- stddevよりも有益。 | 学術 |
| **パーセンタイル（P50/P90/P99）** | 特にTTFT用 — テールレイテンシが重要。 | NVIDIA GenAI-Perf |
| **外れ値検出（IQR）** | [Q1 - 1.5*IQR, Q3 + 1.5*IQR]外の実行をフラグ。 | 統計標準 |
| **トレンド検出** | 実行間のモノトーンなパフォーマンス低下を検出（サーマルドリフト）。 | 学術 |

### P2 — 再現性

| プラクティス | 説明 | 標準 |
|----------|-------------|----------|
| **エンジン間のクールダウン** | サーマルを安定させるため3-5秒の一時停止。 | GPUベンチマーク |
| **トークン比率の検証** | tokens_generated < max_tokensの90%で警告。 | MLPerf |
| **エクスポートフォーマット** | コミュニティ投稿用の`asiai bench --export` JSON。 | MLPerf投稿 |

### P3 — 上級

| プラクティス | 説明 | 標準 |
|----------|-------------|----------|
| **`ignore_eos`オプション** | スループットベンチマーク用にmax_tokensまで強制生成。 | NVIDIA |
| **同時リクエストテスト** | バッチングスループットのテスト（vllm-mlxに関連）。 | NVIDIA |
| **バックグラウンドプロセス監査** | ベンチマーク中に重いプロセスが動作中の場合に警告。 | SPEC |

## 意図的な逸脱

| プラクティス | 逸脱の理由 |
|----------|---------------------|
| **MLPerf最小600秒の実行時間** | データセンターGPU向けに設計。Apple Siliconでのローカル推論は3回実行 + 4プロンプトで約2-5分で十分安定した結果が得られます。 |
| **SPEC 2回の非計測ウォームアップワークロード** | 1回のウォームアップ生成を使用（2回のフルワークロードではなく）。ローカル推論エンジンではJITウォームアップが最小限のため、1回のウォームアップで十分です。 |
| **母集団標準偏差 vs 標本標準偏差** | N-1除数ではなくN除数の母集団標準偏差を使用。少ないN（3-5回）では差は最小限で、母集団の方がより保守的です。 |
| **周波数スケーリング制御** | Apple SiliconはCPUガバナー制御を公開していません。代わりにthermal_speed_limitを記録してスロットリングを検出します。 |

## Apple Silicon固有の考慮事項

### ユニファイドメモリアーキテクチャ

Apple SiliconはCPUとGPUでメモリを共有します。2つの重要な意味があります:

1. **2つのエンジンを同時にベンチマークしない** — 同じメモリプールを競合します。`asiai bench`は設計上エンジンを逐次的に実行します。
2. **VRAMレポート** — OllamaとLM Studioは`size_vram`をネイティブに報告します。その他のエンジン（llama.cpp、mlx-lm、oMLX、vLLM-MLX、Exo）ではlibproc経由の`ri_phys_footprint`をフォールバック推定値として使用します。これはActivity Monitorが表示する値と同じで、Metal/GPUのアロケーションを含みます。推定値はUIに「(est.)」と表示されます。

### サーマルスロットリング

- **MacBook Air**（ファンなし）：持続負荷下で深刻なスロットリング。5-10分後に結果が劣化。
- **MacBook Pro**（ファンあり）：スロットリングは軽微で、通常ファンの回転数上昇で対処。
- **Mac Mini/Studio/Pro**：アクティブ冷却、最小限のスロットリング。

`asiai bench`は結果ごとに`thermal_speed_limit`を記録し、いずれかの実行でスロットリングが検出された場合（speed_limit < 100%）に警告を出します。

### KVキャッシュとコンテキスト長

大きなコンテキストサイズ（32k以上）は、モデルロード時にKVキャッシュを事前割り当てするエンジンでパフォーマンスの不安定性を引き起こす可能性があります。例：LM Studioのデフォルトは`loaded_context_length: 262144`（256k）で、35Bモデルに対して約15-25 GBのKVキャッシュを割り当て、64 GBのユニファイドメモリを飽和させる可能性があります。

**推奨事項**:
- 大きなコンテキストのベンチマークでは、実際のテストサイズに合わせてエンジンのコンテキスト長を設定してください（例：64kテストの場合`lms load model --context-length 65536`）。
- 公平な結果のため、同等のコンテキスト長設定のエンジンを比較してください。

## ベンチマークごとに保存されるメタデータ

SQLiteのすべてのベンチマーク結果に含まれます:

| フィールド | 例 | 目的 |
|-------|---------|---------|
| `engine` | "ollama" | エンジンの識別 |
| `engine_version` | "0.17.4" | アップデート間のパフォーマンス変化の検出 |
| `model` | "qwen3.5:35b-a3b" | モデルの識別 |
| `model_format` | "gguf" | フォーマットバリアントの区別 |
| `model_quantization` | "Q4_K_M" | 量子化レベルの区別 |
| `hw_chip` | "Apple M4 Pro" | ハードウェアの識別 |
| `os_version` | "15.3" | macOSバージョンの追跡 |
| `thermal_level` | "nominal" | 環境条件 |
| `thermal_speed_limit` | 100 | スロットリングの検出 |
| `metrics_version` | 2 | 計算式バージョン（バージョン間リグレッションの防止） |

このメタデータにより以下が可能になります:
- **公平なリグレッション比較**: メタデータが一致する結果のみを比較
- **マシン間ベンチマーク**: ハードウェアの違いを識別
- **コミュニティデータ共有**: 自己記述的な結果（v1.xで計画中）
