Inferbench

InferBench

ワンクリックでローカル LLM 推論エンジンをダウンロード、起動し、ベンチマークを実行できます。
Docker は必須ではありません。コマンドラインを操作する必要もありません。データがマシンの外に出ることはありません。

⭐ GPU に適したモデル選びの時間を節約できましたか？ スターを付けてください — それが最も手軽な応援方法です。
エンジンが見つからない場合や、ハードウェアで起動しない場合は、issue を作成してください。確認します。

_{RTX 3070 での実際の製品デモです。数値はこれらの実行結果であり、編集や高速化はしていません。}

---

LLM をローカルで動かしたいけれど、GPU に適した量子化も、実際の tok/sも、お使いのハードウェアで最速のエンジンもわからない、という方はいませんか？InferBench が実測して答えます。数値をでっち上げることはありません。

Eliges modelo + cuantizaciones → InferBench:
  ① descarga el binario del motor (release oficial GitHub)
  ② descarga los GGUF que falten desde Hugging Face
  ③ arranca el motor con la config óptima para tu hardware
  ④ ejecuta la suite de prompts midiendo TTFT, tok/s, VRAM, calidad
  ⑤ guarda los resultados y te deja compararlos lado a lado

実測例

RTX 3070 · 8 GB VRAM · 32 GB RAM — ネイティブの llama.cpp で SmolLM2-360M Q8_0 を実行：

指標	結果
TTFT	588 ms
スループット	272 tok/s
VRAM ピーク	2.47 GB
品質（オフラインスコアラー）	75 / 100
自動コンテキスト	8 192 tokens

本番ランナーで取得した数値です。データをでっち上げていません。

---

ダウンロード

Releases ページからお使いのシステム用インストーラーをダウンロードしてください。Python や Node のインストールは不要です。バックエンドはサイドカーとして組み込まれています：

システム	ファイル
Windows	InferBench Setup *.exe (NSIS)
macOS	InferBench-*.dmg
Linux	InferBench-*.AppImage

自分でビルドしたいですか？インストール（開発）に進んでください。

---

機能

• エンドツーエンドの自動ブートストラップ：ワンクリックでバイナリの取得＋モデルの取得＋起動＋ベンチマーク＋クリーンアップ
• llama.cpp のネイティブモード（Docker 不要）：GitHub からビルド済みリリースをダウンロードします（CUDA を自動検出し、ランタイム DLL もダウンロードします）
• 必要なエンジンではDocker モードを利用できます
• ハードウェアの自動検出：CPU、RAM、GPU（NVIDIA は NVML、AMD は rocm-smi、Apple Silicon は system_profiler を使用）。結果はキャッシュされるため、互換性一覧を瞬時に表示できます（カタログ全体で約 4 ms）
• HF から GGUF を自動ダウンロードできる126 モデルのカタログ。すべて HuggingFace で検証済みです（ビジョン、コード、推論、MoE、画像拡散を含む）。カタログを参照してください
• ローカル GGUF のスキャン：LM Studio、Ollama、HF キャッシュなどのモデルを検出し、GGUF メタデータから実際のパラメーター数を読み取ります（量子化とは無関係です）
• 本格的なビジョン（マルチモーダル）：ビジョンモデル（Qwen2-VL、Qwen2.5-VL、MiniCPM-V）では、mmproj をダウンロードし、--mmproj を指定して llama-server を起動します。OpenAI 互換のビジョン API を通じて実際の画像を使ったプロンプトをベンチマークします。API（gpt-4o、claude）やDockerエンジン（vLLM がビジョンモデルを提供）でも利用できます。ただし、vLLM でビジョンモデルを使うにはかなりの VRAM が必要です（2B モデルでも 8 GB では余裕がありません。ローカル環境で VRAM が少ない場合は、llama.cpp が確実な選択肢です）
• オプティマイザー：ハードウェア＋モデル＋エンジンに基づき、最適な量子化、KV キャッシュ、最大コンテキスト長、MoE オフロード、フラグを算出します
• KV キャッシュの圧縮を解説：圧縮プリセットを 5 種類（品質→極限）用意し、何をするか／何に影響するか／何が可能になるかを説明します。さらに、使用するハードウェアで各圧縮設定に収まる最も高性能なモデルの表もあります
• 3 つのモードで品質を評価：リファレンスベースのオフラインスコアラー（GPU／API 不要で、どの PC でも実行可能）、ローカルエンジンを使った LLM ジャッジ、外部 API を使った LLM ジャッジ。品質を参照してください
• スイープモード：同じモデルを異なる量子化設定で N 回、キューに登録して実行します
• 比較：履歴から複数の実行を選び、メトリクスとグラフを並べて確認できます
• ライブ SSE：ダウンロードの進行状況（%）、TTFT、現在の tok/s、ターミナル風ログを表示します
• 堅牢なダウンロード：数十 GB の GGUF も自動再試行（指数バックオフ）に対応し、ネットワーク切断時には Range ヘッダーを使って部分ダウンロードから再開できます
• OS のキーリングに API キーを保存：OpenAI／Anthropic／OpenRouter／NVIDIA のキーをシステムの資格情報マネージャーに保存します（設定 → API キー）。ベンチマークではキーが自動的に使われ、ディスクに書き込まれることはありません
• lookspan によるオブザーバビリティ（オプトイン）：LOOKSPAN_ENDPOINT を設定すると、ベンチマークの実行ごとにトレースが lookspan へエクスポートされます（ルートスパンと、各プロンプトの TTFT、tok/s、VRAM、実際の品質を含む llm_call）。ベストエフォートで実行されるため、ネットワーク障害でベンチマークが中断されることはありません
• いつでも停止：ブートストラップ、ダウンロード、実行をキャンセルできます
• 永続化：SQLite にすべての実行（エンジン、モデル、量子化、フラグ、プロンプトごとのメトリクス、生出力）を保存します
• Serve / MCP モード：最適な量子化モデルを常駐させ、MCP 経由で任意のアプリに提供します。Serve / MCPを参照してください
• 画像生成（ローカル）：テキスト LLM に加えて、InferBench は stable-diffusion.cpp を通じて画像モデルもオーケストレーションします。llama.cpp と同じ方式です。画像モデルを提供し、アプリから、または MCP（generate_image）経由で画像を生成します。画像生成を参照してください

---

Serve / MCP

ベンチマークだけでなく、InferBench は量子化モデルを常駐させてMCP（Model Context Protocol）経由であらゆるアプリに公開することもできます。ベンチマークと同じパイプライン（ハードウェア検出 → オプティマイザー → GGUF のダウンロード → エンジン起動）を再利用します。InferBench はモデルをオーケストレーションする仲介役として、ハードウェアに最適な量子化方式を選び、GGUF をダウンロードし、エンジンを起動して推論をルーティングします。

Eliges modelo (o "recomendar para mi hardware") → InferBench:
  ① elige la cuantización óptima para tu GPU (o respeta la que indiques)
  ② descarga el GGUF que falte desde Hugging Face
  ③ arranca el motor de forma residente y expone su endpoint OpenAI
  ④ lo publica como servidor MCP "inferbench" para Claude Desktop / Cursor / etc.

v1：エンジンは llamacpp（ネイティブで常に利用可能）で、一度に提供できるモデルは1つだけです（単一スロット）。API はエンジンに依存しない設計で、ほかのエンジンは今後追加される予定です。

1つのアプリ、2つのモード

InferBench は2つのアプリではなく、1つに統合されたアプリです。設定 → モード / 機能から、各モードをトグルで有効または無効にできます。

• Benchmark — ダッシュボード、エンジン、モデル、ベンチマーク、履歴。
• Serve / MCP — Serveビュー。

どちらもデフォルトでONです。モードを無効にすると、その項目はサイドバーから消えます（設定は localStorage に保存されます）。両方を同時に無効にはできません。常に少なくとも1つのモードが有効です。

Serveビュー

1. カタログからモデルを選ぶか、ハードウェアに合ったモデルをおすすめをクリックします。量子化方式は**Auto（最適）**のままにするか、手動で指定します。
2. Serveをクリックします。必要に応じて InferBench がダウンロードしてエンジンを起動し、readyになるまでフェーズと進行状況を表示して、モデルの OpenAI エンドポイントを提示します。
3. 統合されたミニチャットで試します。
4. MCPで接続を開くと、Claude Desktop / Cursor 用の設定スニペット、または HTTP URL をコピーできます。
5. 停止すると VRAM が解放されます。

Claude Desktop / Cursor の接続

InferBench は**inferbench**という MCP サーバーを、2つのトランスポートで公開します。

• stdio — クライアントがバックエンドのサイドカーを --mcp フラグ付きで起動します。Claude Desktop の設定（claude_desktop_config.json）または Cursor に、次の内容を貼り付けます。

  {
    "mcpServers": {
      "inferbench": {
        "command": "C:\\ruta\\a\\inferbench-backend.exe",
        "args": ["--mcp"]
      }
    }
  }
  

  ServeビューのMCPで接続パネルには、実際のパスが入力済みのスニペットが表示されます。

• HTTP — HTTP 経由で MCP を利用するクライアントの場合は、次の URL を指定します。

  http://localhost:7777/mcp
  

stdio トランスポートは独自のエンジンを起動しません。バックエンドへのプロキシとして動作します。そのため、MCP 経由でモデルを提供するには、InferBench アプリを開いておく必要があります。アプリが開いていない場合、ツールは失敗するのではなく、「InferBench が開いていません…」という明確なエラーを返します。

MCP ツール：list_models、recommend_models、get_hardware、serve_model、serve_status、chat、stop_model、および generate_image（提供中のモデルが画像モデルの場合）。各ツールの動作、スニペット、トラブルシューティングを含む完全なガイドは、**docs/MCP.md**にあります。

---

画像生成

InferBench はテキスト LLM にとどまらず、まったく同じパターンを再利用してローカルの画像モデルもオーケストレーションします。テキストでは llama.cpp のネイティブバイナリと GGUF を使いますが、画像では拡散モデル版の stable-diffusion.cpp（GitHub リリースの CUDA プリコンパイル済みバイナリ、Hugging Face の GGUF / safetensors の重み、およびそのHTTP サーバー）を使います。InferBench は引き続きオーケストレーションを担う仲介役として、重みを選び、不足分（FLUX の補助ファイルも含む）をダウンロードし、sd-server を常駐起動して生成をルーティングします。

Eliges un modelo de imagen → InferBench:
  ① descarga el binario de stable-diffusion.cpp (release oficial GitHub + DLLs CUDA)
  ② descarga los pesos GGUF/safetensors (y los auxiliares t5xxl/clip_l/vae de FLUX)
  ③ arranca sd-server de forma residente (puerto 7861) y expone su API de imagen
  ④ genera con tu prompt y te devuelve el PNG — desde la app o por MCP (generate_image)

これは既存のServeモード内で動作し（新しいモードではありません）、単一スロットを共有します。つまり、1つの GPU で同時に提供できるモデルは、テキストまたは画像のどちらか1つです。

配信と生成

Serve ビューでは、セレクターに画像モデルが含まれます（モダリティ別にグループ化されています）。 画像モデルを配信すると、ミニチャットの代わりにGenerateCardが表示されます。プロンプト、任意のネガティブプロンプト、steps（スライダー、デフォルトは20）、プリセット付きのサイズ （512×512 / 768×768 / 1024×1024）、seed（ランダムボタン付き）、生成ボタンがあり、 画像のプレビューと生成時間も表示されます。API では、 POST /api/serve/generate（server の AUTOMATIC1111 互換 API /sdapi/v1/txt2img への プロキシ、レスポンスは images: [PNG base64]）を使用します。画像モデルが ready でない場合は → HTTP 409。 MCP では、ツール generate_image が画像を返し、Claude Desktop に表示させます。

モデル（8 GB での正直な要件）

モデル	ファイル	VRAM の目安（8 GB）
SD 1.5 / SD-Turbo	単一ファイル	~2–4 GB · 余裕で収まります（デフォルトで保証）
SDXL	単一ファイル	~6–8 GB · 1024×1024 ではぎりぎりです
FLUX.1-schnell (Q4)	複数ファイル（diffusion + t5xxl + clip_l + vae）	~7–8 GB · 上限ぎりぎりです（ショーケース）

動画（Wan2.1/Wan2.2、LTX — stable-diffusion.cpp ではすでにサポート済み）は フェーズ2で対応予定です。このリリースは画像のみです。ベンチマークのパイプラインに変更はありません。生成指標はまだありません。

完全なガイド（モデル、量子化、FLUX の補助ファイル、トラブルシューティング）は **docs/IMAGE.md**をご覧ください。

---

スタック

レイヤー	テクノロジー
デスクトップアプリ	Electron 42
フロントエンド	React 18 + Vite 8 + TailwindCSS + Recharts + lucide-react
バックエンド	FastAPI (Python 3.11) + uvicorn + sse-starlette
永続化	SQLModel 経由の SQLite
GPU 検出	psutil + pynvml + system_profiler / rocm-smi
コンテナー	Docker SDK for Python
ネイティブランタイム	subprocess.Popen + GitHub の公式バイナリ
パッケージング	electron-builder + PyInstaller

---

サポートされているエンジン

エンジン	種類	ネイティブモード	Docker モード	モデルの自動ダウンロード
llamacpp	ローカル	✅ 公式バイナリ	✅	✅ HuggingFace GGUF
stablediffusion	ローカル	✅ 公式バイナリ（sd.cpp）	—	✅ HuggingFace GGUF/safetensors
ollama	ローカル	✅ Ollama デーモン	✅	✅ Ollama レジストリ
vllm	ローカル	—	✅（NVIDIA GPU）	✅ HF（コンテナ内）
sglang	ローカル	—	✅（NVIDIA GPU）	✅ HF（コンテナ内）
tgi	ローカル	—	✅（NVIDIA GPU）	✅ HF（コンテナ内）
openai	API	n/a	n/a	n/a
anthropic	API	n/a	n/a	n/a
openrouter	API	n/a	n/a	n/a
nvidia	API	n/a	n/a	n/a

すべてのローカルエンジンには、完全なアダプター（エンジンごとのコマンド構築、自動ブートストラップ、独自の最適化スキーマ）が用意されています。stablediffusion（stable-diffusion.cpp、ネイティブ）は画像エンジンです。HTTP サーバーを :7861 で起動して拡散モデルを提供します。ベンチマークではなく、画像を生成します（画像生成を参照）。vLLM/SGLang/TGI は Docker 専用で、NVIDIA GPU が必要です。モデルはコンテナが HuggingFace からダウンロードします（リポジトリ ID を渡します）。クラウド API は API キーで利用できます（サンプリングパラメーターのみで、ローカル最適化はありません）。OpenAI / OpenRouter / NVIDIA は OpenAI 互換エンドポイント /v1/chat/completions を使用します。Anthropic はネイティブ API（/v1/messages、x-api-key + anthropic-version ヘッダー、独立した system）を使用し、OpenAI 互換ではありません。

投機的デコーディング（DFLASH）：vLLM と SGLang は、block-diffusion の ドラフト モデルを使った高速化に対応しています（DFLASH、品質を損なわず 6～8 倍高速化）。Benchmark で vLLM/SGLang を選択し、DFLASH を有効にしてドラフトモデルを指定してください（例：z-lab/Qwen3.5-35B-A3B-DFlash）。公式に対応しているのは SGLang です。vLLM では対応ビルドが必要です。モデルとドラフトの両方に VRAM が必要なため、小型 GPU では利用できません。

検証状況： 5 つのローカルエンジン（llamacpp、ollama、vllm、sglang、tgi）は、NVIDIA GPU（RTX 3070、8 GB）で、本番ランナーによるエンドツーエンド検証済みです（ブートストラップ → 起動 → 実際の推論で tps>0 を確認 → コンテナを残さず停止）。vLLM/SGLang は、空きメモリがない GPU でも失敗しないよう、実際の空き容量に応じて VRAM の使用割合を調整します。

---

適用される最適化（llama.cpp）

デフォルトでは core/optimizer.py に基づいています。

• 最適な量子化：収まるまで高品質から低品質へ（Q8 → Q2）順に試します
• run ごとのプラン（optimizer.plan_llamacpp_run）：最大コンテキストと ngl は、実際に実行される quant と、選択された有効な KV に基づいて計算されます（optimizer が選択するはずだった quant に基づくのではありません）。以前は異なる quant の実行時に OOM が発生したり、圧縮を活用できなかったりすることがありました
• 実際のアーキテクチャの正確な KV キャッシュ（n_layer·n_head_kv·head_dim）に基づく最大コンテキストの自動設定 — GQA/MQA に対応
• KV キャッシュの圧縮（-ctk -ctv）：f16 / q8_0 / q4_0（K/V を個別に設定でき、プリセットもあります）。KV の量子化には -fa on が強制されます（llama.cpp で必須です）。⚠️ K の q4_0 は強めの設定で、小型モデルでは生成品質が低下したり、生成に失敗したりする可能性があります。q8_0 が最適なバランスです
• KV を RAM に配置（--no-kv-offload、Extreme プリセット）：VRAM を解放し、コンテキストの上限を RAM に委ねます
• 小型 GPU での MoE モデル向け MoE オフロード（--n-cpu-moe N）
• モデル全体が VRAM に収まる場合は、Flash Attention（-fa on）、mlock + --no-mmap
• スレッド数 = 物理コア数 · batch-size 2048 + ubatch-size 512
• engine_opts による全面的なオーバーライド（フラグの重複なし：optimizer が基本設定を適用し、ユーザーのオーバーライドが優先されます）

---

自動ダウンロード対応モデルカタログ

backend/data/models.json には126 個のモデル（テキスト 124 個＋拡散画像モデル 2 個）が記載されています。hf_gguf が設定されているモデルは、Hugging Face から自動ダウンロードされます。主なモデルは次のとおりです。

• Llama 3 / 3.1 / 3.2 / 3.3（1B → 70B）、Nemotron、Hermes、Tulu、Dolphin
• Qwen 2.5 / 3（0.5B → 72B）、Coder、Math、QwQ 32B（推論）、MoE 30B-A3B
• Gemma 2 および Gemma 3（1B → 27B）
• Mistral 7B、Nemo、Small 3/3.1 24B、Ministral、Codestral、Mixtral（MoE）
• Phi 2 / 3 / 3.5 / 4（＋ mini、＋ MoE）
• DeepSeek R1 蒸留モデル、Coder、Coder-V2-Lite（MoE）
• ビジョン：Qwen2-VL、Qwen2.5-VL、MiniCPM-V
• コード：Code Llama、CodeGemma、StarCoder2、Yi-Coder、OpenCoder、Stable Code
• その他：Granite（IBM）、Falcon3、GLM-4、EXAONE、InternLM、OLMo、Aya/Command-R（Cohere）、SmolLM2、SOLAR、Zephyr…

**架空のデータはありません。**各エントリーは追加前に HuggingFace で検証されます。GGUF リポジトリが存在すること、file_template が公開済みの実ファイルから導出されていること、Q4_K_M で解決できることを確認します。検証ツールは backend/scripts/ にあります（verify_models.py ＋ merge_models.py）。カタログを安全に拡張するには、このツールを実行してください。シャードに分割された巨大なモデル（-00001-of-000NN.gguf、例：DeepSeek-V3、Llama 4 70B 以上）にも対応しています。カタログで hf_gguf.multipart を指定すると、ダウンロード時にすべてのシャードが結合されます（llama.cpp は同じディレクトリ内にある分割ファイルを読み込みます）。

---

インストール（開発）

要件

• Node.js 20+：https://nodejs.org/
• Python 3.11+：https://www.python.org/
• uv：curl -LsSf https://astral.sh/uv/install.sh | sh
• (任意) Docker エンジンを使用する場合は Docker Desktop
• (任意) GPU アクセラレーションを使用する場合は NVIDIA ドライバー（アプリが検出し、CUDA ビルドをダウンロードします）

開発モードで起動

git clone https://github.com/JoniMartin27/inferbench.git
cd inferbench

# Backend (terminal A)
cd backend
uv venv --python 3.11
.venv\Scripts\activate
uv pip install -e .
uvicorn main:app --reload --port 7777

# Frontend (terminal B)
cd frontend
npm install
npm run electron:dev

アプリが Electron のウィンドウで開きます。サイドバーにはバックエンドの状態が表示され、各ビュー間を移動できます。

---

パッケージ化

Python バックエンドは PyInstaller で実行ファイルにパッケージ化され、Electron インストーラーにサイドカーとして組み込まれます。パッケージ化されたアプリは、インストール先のマシンに Python を必要としません。

# Iconos de marca (solo si cambia frontend/public/favicon.svg — el resultado se commitea)
mkdir C:\tmp\ib-icons; cd C:\tmp\ib-icons; npm i puppeteer-core@23
$env:IB_TOOLS_DIR="C:\tmp\ib-icons"; node <repo>\scripts\make-icons.mjs

# Construir el sidecar
scripts\build-sidecar.ps1     # Windows
bash scripts/build-sidecar.sh # macOS / Linux

# Instalador
cd frontend
npm run electron:build

出力先は frontend/release/ です。

• Windows → InferBench-Setup-<version>.exe（NSIS）
• macOS → InferBench-*.dmg
• Linux → InferBench-*.AppImage

ワンクリック起動

Windows インストーラーはワンクリックでユーザー単位（UAC なし）でインストールできます。デスクトップとスタートメニューにブランドアイコン付きのショートカットを作成し、完了後にアプリを起動します。 そのショートカットをダブルクリックすると、すべてが起動します。Electron がバックエンドのサイドカーを起動し、ウィンドウがすぐに表示され、応答があり次第 UI が :7777 に接続します。 手動で起動する必要はありません。

初回だけでなく常に正常に動作するための仕組み（frontend/electron/main.js）：

• 単一インスタンス：2 回目のダブルクリックでは、別のバックエンドを起動して :7777 のポートを取り合うのではなく、既存のウィンドウにフォーカスします。
• 正常なバックエンドの再利用： :7777 ですでに応答している InferBench がある場合（サイドカーが残る強制終了後など）、アプリは再利用します。そうしないと、バインドエラーで終了する別のバックエンドを起動することになります。
• 正常終了：終了時には taskkill /T を使ってサイドカーのプロセスツリーを同期的に終了します。before-quit は非同期処理を待たないため、通常の spawn では Electron が先に終了し、バックエンドが孤立してポートを占有したままになります。
• %APPDATA%\InferBench\logs\backend.log にサイドカーのログを記録します。パッケージ化された GUI アプリにはコンソールがないため、起動に失敗しても痕跡が残らないことがあります。サイドカーの exe が見つからない場合は、無言で終了する代わりにエラーダイアログも表示されます。
• ポートは INFERBENCH_PORT 経由で渡されます（backend/main.py が読み取ります）。

---

アーキテクチャ

┌──────────────────────────────────────────────────┐
│  Electron app (React + Tailwind + Recharts)      │
│   Dashboard · Motores · Modelos · Benchmark      │
│   Historial (con comparación) · Serve · Ajustes  │
└──────────────────────┬───────────────────────────┘
                       │ HTTP REST + SSE
┌──────────────────────▼───────────────────────────┐
│  FastAPI backend  (localhost:7777)               │
│   /api/health         · /api/hardware            │
│   /api/engines/*      · /api/models/*            │
│   /api/benchmark/*    · /api/history/*           │
│   /api/optimize       · /api/benchmark/sweep     │
│   /api/serve/*        · /mcp  (servidor MCP)     │
└────┬───────────────────────────────────┬─────────┘
     │                                   │
     │ subprocess.Popen                  │ Docker SDK
     ▼                                   ▼
┌──────────────────┐              ┌──────────────────┐
│  Native runtime  │              │  Docker runtime  │
│  llama-server    │              │  ollama/vllm/...  │
│  (GitHub release)│              │  (Docker images)  │
└──────────────────┘              └──────────────────┘
     │
     ▼
┌──────────────────────────────────────────────────┐
│  GGUF cache: %APPDATA%/InferBench/models/        │
│  (auto-descarga desde Hugging Face)              │
└──────────────────────────────────────────────────┘

---

リポジトリ構成

inferbench/
├── backend/
│   ├── api/             # routers FastAPI
│   ├── core/
│   │   ├── hardware.py        # detección CPU/RAM/GPU (cacheada)
│   │   ├── docker_mgr.py      # Docker SDK wrapper
│   │   ├── native_runtime.py  # subprocess wrapper
│   │   ├── binary_manager.py  # descarga binarios desde GitHub
│   │   ├── model_manager.py   # descarga GGUF desde HF
│   │   ├── local_models.py    # escaneo de GGUFs locales
│   │   ├── gguf_reader.py     # lee metadata GGUF (arch, params reales…)
│   │   ├── compat.py          # cálculos de compatibilidad
│   │   ├── optimizer.py       # config óptima + recomendaciones + by-compression
│   │   ├── benchmark.py       # runner + SSE + scorer de calidad + LLM-judge
│   │   └── models_catalog.py
│   ├── scripts/
│   │   ├── verify_models.py   # verifica repos GGUF contra HF y deriva metadata
│   │   └── merge_models.py    # valida y fusiona modelos nuevos en el catálogo
│   ├── engines/
│   │   ├── base.py            # Engine ABC (native + docker)
│   │   ├── llamacpp.py
│   │   └── registry.py
│   ├── data/
│   │   ├── models.json        # catálogo
│   │   └── prompts.json       # suite benchmark
│   ├── db.py                  # SQLModel
│   ├── main.py
│   └── pyproject.toml
│
├── frontend/
│   ├── electron/
│   │   ├── main.js            # proceso main + sidecar
│   │   └── preload.js
│   └── src/
│       ├── App.jsx            # layout + sidebar
│       ├── api.js             # cliente HTTP + suscripción SSE
│       ├── components/ui.jsx  # primitivas
│       └── views/
│           ├── Dashboard.jsx
│           ├── EnginesView.jsx
│           ├── ModelsView.jsx       # tabla compat + ⚡ optimize
│           ├── BenchmarkView.jsx    # incluye sweep + RunningPanel SSE
│           ├── HistoryView.jsx      # multi-select + comparación
│           └── SettingsView.jsx
│
├── scripts/
│   ├── build-sidecar.ps1
│   └── build-sidecar.sh
└── docker/
    └── docker-compose.yml      # referencia

---

プロンプトスイート

backend/data/prompts.json では、3段階の難易度に分けた13個のプロンプトを定義しています。それぞれに検証可能なスコアラーがあります（トークンのF1ではありません）。品質は実際の正確さで測定します。難易度の段階分けには意図があります。全員が100点を取るテストセットでは、誰も順位付けできません。

ID	難易度	タスク	採点方法	トークン数
chat	易	太陽からの順に惑星を並べる	8惑星すべて ＋順序どおり ＋準惑星なし	128
reasoning	中	4人で家賃を分担する（複数ステップの計算）	金額がそれぞれ 該当する人に割り当てられている ＋合計＋結果行が完全一致＋均等分担にしない	512
code	中	merge_intervals（標準ライブラリのみ）	5つのケースでコードを 実行 →合格率	512
summary	中	何も付け加えずに要約する	重要な事実6つ＋箇条書きはちょうど5項目＋割合や架空のブランド名なし	384
logic	難	4人のランナーの到着順を推論する	指定された形式で4つの順位を回答し、5人目をでっち上げない	512
instructions	難	3つの首都を厳密な形式で回答する	N: City 形式で3つすべてを回答＋よくある誤答の首都（シドニー、イスタンブール、トロント）なし	128
json-extract	難	メモをJSONに変換する	キーが完全一致＋合計を 計算（61,00）＋Markdownのフェンスなし	256
unanswerable	難	テキストに答えが書かれていない質問	記載がないと答え、テキスト中の数値を使い回さない	192
code-hard	難	重複値と負数に対応する summarize_ranges	8つの境界ケースでコードを 実行	640
long-context	難	約4,7kトークン内にある3つのコード：取り消し済み、期限切れ、有効なものが1つずつ	有効なものを答え、誤答の選択肢はどれも答えない	48
long-context-count	難	120件のうち INCIDENT レコード7件を数える	7と、数字だけで回答	48
vision-scene	中	3色の図形を3つ説明する	形＋色＋個数＋色と形の対応＋図形をでっち上げない	128
vision-count	中	オブジェクトを数える	数＋形＋色＋ほかの図形をでっち上げない	64

vision-* プロンプトは ビジョンモデル（mmproj 使用）のみで実行され、それ以外では省略されます。画像の正解データは既知です（data/vision_*.png、scripts/make_vision_test.py で生成）。code* プロンプトでは、モデルの出力をサンドボックス付きの分離されたサブプロセスで 実行 します（python -I、一時的なcwd、タイムアウト、リソース制限、ネットワークなし、破壊的なシステムコールなし）。デフォルトで有効です。INFERBENCH_CODE_EXEC=0 で無効にできます（その場合、これらのプロンプトは省略され、0点として採点されることもありません）。

採点方法：重み付きチェック

各プロンプトでは checks を宣言します。重み付きチェックは5種類あります。any（同義語）、number（数値全体 と正しい対象への割り当て）、order（指定された順序）、regex（厳密な形式）、absent（誤答の選択肢やハルシネーション。減点対象）です。スコアは通過した重みの割合です。SSEイベント quality には failed が含まれ、どのチェックに具体的に失敗したかを確認できます。これにより、数字をそのまま信じるのではなく、スコアを監査できます。

これは、誤った回答も正解として扱っていた、単語だけのチェックリストに代わるものです。実際の履歴で測定したところ、chat の満点回答38件のうち5件は、問題文で順序を求めていたにもかかわらず、惑星の 順序が間違っていました。また、250 が 2500 の正解としてカウントされていました。

モデルだけでなくベンチマークも検証する

• backend/tests/test_checks_scorer.py では、各プロンプトの模範回答が100点を取ることと、典型的な失敗回答が60点以下に収まることを求めています。誰も合格できない採点基準も、何でも合格にする基準と同じくらい破綻しています。
• python backend/scripts/audit_scoring.py --compare は、保存済みの履歴を再採点し（読み取り専用）、プロンプトごとに異なる点数がいくつ出るか、満点の割合、最も頻繁に失敗するチェック項目を報告します。あるプロンプトで点数が2種類しか出ない、または40％が満点を取る場合、識別力が失われているため、採点基準を厳しくする必要があります。
• 各結果には prompt_version と scorer が保存されます。設問または採点基準を変更したら version を上げてください。そうしないと、異なる実行の点数を比較しても意味がありません（実際に、異なる2つの質問への回答を含む chat の行で起きました）。

統計的な厳密さ（単一サンプルではなく）

各プロンプトをN回（デフォルトは3回、INFERBENCH_BENCH_ITERS で設定可能）測定します。測定前には、エンジンのキャッシュやJITを温めるウォームアップ実行を1回行い、その結果は破棄します。報告される数値は、N個のサンプルの中央値と標準偏差です。単一の測定値では（特にTTFTにおいて）ノイズが大きいためです。llama.cppでは、tok/sの算出にクライアント側からの計測ではなく、エンジン内部のタイミング情報（predicted_per_second / prompt_per_second）を使用します。トークンごとのHTTPジッターはありません。INFERBENCH_BENCH_NO_WARMUP=1 を設定すると、ウォームアップを無効にできます。

プロンプトごとに測定するメトリクス（N個のサンプルの中央値）：

• TTFT（ms）：最初のトークンが出るまでの時間。標準偏差は ttft_std
• decode tok/s：生成フェーズにおける1秒あたりのトークン数。標準偏差は tps_std
• prefill tok/s：プロンプトの処理速度（decodeとは別に測定）
• VRAM peak（GB）：実行中のピーク値。pynvml 経由で取得
• RAM peak（GB）：ピーク値。psutil 経由で取得
• 品質（0～100）：品質評価を参照
• コスト：クラウドAPIのみ（トークン数×価格で算出）
• n_samples：数値の根拠となる有効サンプル数

---

品質評価

品質スコア（0～100）には複数のモードがあります（TTFT と tok/s は常にエンジンの実測値です）。

モード	仕組み	使用する場面
参照（オフライン） · デフォルト	回答を参照回答と比較します。トークンの F1 recall-weighted ＋ 数値の完全一致再現率 ＋ 接頭辞ステミング ＋ 退化したテキストへのペナルティです。純粋な Python で動作し、GPU／モデル／ネットワークは不要です	どのコンピューターでも動作します。期待される回答があるタスク（推論、コード、要約）に適しており、自由形式のタスク（チャット）では近似的な評価になります
属性チェックリスト · ビジョンと事実	プロンプトで同義語のグループを定義します（正解データ：形、色、数など）。スコアは回答に含まれる属性の割合です。単語境界と接頭辞で照合します（形態変化を許容しますが、「500」は「1500」の中では一致しません）。アクセントに強く、2言語（ES／EN）に対応しています。ネットワークは不要です	ビジョン（モデルが画像を正しく見たかを測定）や、検証可能な事実を含むすべてのタスク（reasoning、summary、chat、vision-*）
コード実行 · コードタスク	生成されたコードを、隔離されたサンドボックス付きサブプロセス（python -I、一時的な cwd、タイムアウト、rlimits、ネットワークなし、破壊的なシステムコールなし）で、実際のテストケース（HumanEval 形式）に対して実行します。スコアは合格したケースの割合です。テキストの類似性ではなく、コードが実際に動作するかを測定します	コードタスク（code）。デフォルトで有効です。INFERBENCH_CODE_EXEC=0で無効にできます（プロンプトを省略し、スコアは 0 にしません）
LLM-as-a-judge（ローカルエンジン）	エンジン自身が回答を採点します（0～100 の評価基準）	十分な能力のあるモデル（≥7-8B）でのみ信頼できます。小型モデル（1-3B）はスコアが 0 に収束します。評価者と評価対象が同じモデルのため、偏りがあります
LLM-as-a-judge（外部 API）	OpenAI 互換のクラウドモデル（例：gpt-4o-mini）が評価します	最も信頼性が高く、公平です。API キーが必要です

デフォルトがオフラインなのは、GPU や API のないマシンでも動作するようにするためです。keywordsを含むプロンプトでは、チェックリストが自動的に使用されます（画像を見ない LLM-as-a-judge で置き換えることはできません）。LLM-as-a-judge は、自由形式のテキストタスクを確実に評価するための任意の追加機能です。

---

主要なエンドポイント

メソッド	パス	説明
GET	/api/health	ステータス + Docker 情報
GET	/api/hardware	CPU、RAM、GPU
GET	/api/engines	ランタイムの利用可否を含むエンジン一覧
POST	/api/engines/{id}/install	SSE：ネイティブバイナリをダウンロード
POST	/api/engines/{id}/start	エンジンを起動（未インストールの場合は自動インストール）
POST	/api/engines/{id}/stop	エンジンを停止
GET	/api/models	カタログ
GET	/api/models/local	ディスク上のローカル GGUF（メタデータの実際のパラメーターを含む）
GET	/api/models/compat/all?engine=X	モデルごとの互換性
POST	/api/optimize	最適な設定
GET	/api/optimize/recommendations?top=N	ハードウェアで実行可能な、最も高性能なモデル
GET	/api/optimize/by-compression?context_len=N	各 KV 圧縮プリセットで収まる、最も高性能なモデル
POST	/api/benchmark/run	実行を開始し、run_id を返す
GET	/api/benchmark/{run_id}/stream	進行状況の SSE
POST	/api/benchmark/{run_id}/stop	実行中の処理をキャンセル
POST	/api/benchmark/sweep	異なる量子化で N 回の実行を開始
GET	/api/history	実行一覧
GET	/api/history/compare/runs?ids=A,B,C	比較用の複数実行の詳細
POST	/api/serve/load	常駐モデルのサービングを開始（ブロックせず、バックグラウンドで起動）
GET	/api/serve/status	サービングスロットの状態（フェーズ、モデル、量子化、エンドポイント）
POST	/api/serve/chat	サービング中のモデルへのチャットプロキシ（テキスト）
POST	/api/serve/generate	サービング中の画像モデルで画像を生成（画像モデルが ready でない場合は 409）
POST	/api/serve/unload	サービング中のエンジンを停止し、VRAM を解放
—	/mcp	Claude Desktop / Cursor 向け MCP サーバー（HTTP ストリーミング）— docs/MCP.md を参照

---

キャッシュ（再ダウンロードされません）

• バイナリ：%APPDATA%\InferBench\binaries\<engine>\（Windows）または ~/.inferbench/binaries/（Linux/Mac）
• GGUF モデル：%APPDATA%\InferBench\models\<repo>\<file>.gguf
• DB：コードから実行する場合は backend/data/inferbench.sqlite、パッケージ化されたアプリでは %APPDATA%\InferBench\inferbench.sqlite。INFERBENCH_DB_PATH はどちらよりも優先されます（テストハーネスがデータに触れないように使用します）
• ネイティブエンジンのログ：%APPDATA%\InferBench\logs\<engine>.log

履歴の実行状態

done（緑）・error（赤）・running（実行中）・interrupted（アンバー）。

起動時に、バックエンドは以前の実行で running のまま残った実行を終了します。アプリが途中で閉じられた場合やバックエンドがクラッシュした場合、実行していたプロセスはすでに存在しないためです。すべてのプロンプトの結果がそろっている実行は、中断としてマークされません。最後の状態変更だけが行われずに実行自体は完了しているため、done として復元されます。また起動時には、結果がすべてそろっているにもかかわらず interrupted とマークされた実行を（べき等に）修復し、誤った状態が残っているインストール環境でも履歴を正確に保ちます。

---

マイルストーンの状況

	マイルストーン	状況
M1	ハードウェア検出（NVIDIA·AMD·Apple·CPUのみ）	✅
M2	Docker マネージャー + Engine 抽象化 + llama.cpp	✅
M3	モデルカタログ + 互換性計算と max_ctx	✅
M4	ベンチマーク + SSE + SQLite 永続化	✅
M5	Electron + Vite + Tailwind フロントエンド	✅
M6	完全な UI（6 つのビュー）	✅
M7	SSE ライブパネル	✅
M8	自動オプティマイザー + ⚡ ボタン	✅
M9	パッケージ化（設定）	✅
ボーナス	エンドツーエンドの自動ブートストラップ（ダウンロード + 起動 + ベンチマーク）	✅
ボーナス	Docker を使わないネイティブモード + CUDA DLL のダウンロード	✅
ボーナス	HuggingFace から GGUF を自動ダウンロード	✅
ボーナス	マルチ量子化スイープ + 並べて比較	✅
ボーナス	実行中の停止	✅
ボーナス	HF で検証済みの 126 モデルのカタログ + 拡張ツール	✅
ボーナス	メタデータからローカル GGUF の実際のパラメーターを取得（量子化方式に依存しない）	✅
ボーナス	KV 圧縮の説明 + 圧縮率が高いモデルの一覧表	✅
ボーナス	リファレンスベースのオフライン品質評価 + LLM による判定（ローカル / API）	✅
ボーナス	メタデータから正確な KV キャッシュ（n_head_kv/head_dim、GQA/MQA を検出）をカタログ内の 124 個のテキストモデルのうち 123 個で取得	✅
ボーナス	実際のビジョン（マルチモーダル）：mmproj をダウンロードし、llama-server で --mmproj を指定して実際の画像を含むプロンプトを実行	✅
ボーナス	Serve / MCP モード：最適な量子化モデルを常駐させて提供し、MCP（stdio + HTTP）経由で Claude Desktop / Cursor に公開	✅
ボーナス	stable-diffusion.cpp によるローカルの画像生成：画像モデルを提供して生成（POST /api/serve/generate + MCP ツール generate_image）	✅

---

保留中の項目 / 次のステップ

• テスト範囲の拡大（backend/tests/ に compat、optimizer、quality、gguf_reader、multimodal、security、api、gpu_safety、keys、lookspan、multipart、speculative、benchmark_rigor、serve、mcp、image_serve の 122 件のテストがあります）
• Docker エンジン（vLLM/SGLang）でのビジョンサポートと API 経由のマルチモーダル対応（gpt-4o）。現在、実際のビジョン処理はネイティブの llamacpp で実行されます
• 動画生成（フェーズ 2）：stable-diffusion.cpp はすでに Wan2.1/Wan2.2 と LTX をサポートしていますが、統合が必要です（現在は画像のみ）。また、ベンチマークモードでの生成メトリクスも必要です
• llama.cpp のチューニング用フラグのうち、cache-reuse、--prio-batch、その他を実装する

---

参考ドキュメント

• PROJECT_BRIEF.md — ビジョン、アーキテクチャ、エンジンごとの最適化スキーマ、互換性の計算式
• docs/MCP.md — Serve / MCP モード：MCP サーバーのツール、stdio/HTTP トランスポート、Claude Desktop / Cursor の設定、トラブルシューティング
• docs/IMAGE.md — stable-diffusion.cpp による画像生成：サポート対象モデル、VRAM 要件、FLUX の補助ファイル、トラブルシューティング
• docs/COMMUNITY-ROADMAP.md — コミュニティ向けロードマップ（ユーザーから要望のあった優先改善項目）
• CLAUDE.md — 開発規約と M1–M9 のマイルストーン計画

---

貢献

PR を歓迎します。環境のセットアップ、lint/tests の実行方法、規約については CONTRIBUTING.md をお読みください。最初の貢献に適した項目は、ollama/vllm/sglang/tgi の実際のアダプターや、compat.py/optimizer.py のテスト拡充です。大きな変更を行う場合は、方針を相談するため、事前に issue を作成してください。

このプロジェクトでは行動規範を採用しています。

セキュリティ

脆弱性を見つけた場合は、公開 issue を作成しないでください。SECURITY.md に従ってください。このプロジェクトではセキュリティ監査を実施済みです（セキュリティ状況は良好で、指摘事項は修正済みです）。

ライセンス

MIT © 2026 Jonathan Martin.

---

InferBench は、オープンソースツールのポートフォリオ（Trace、lookspan、claudescope、launchpad など）を統括するスタジオ、Fervon の一部です。Fervon のブランドアイデンティティはランディングページに適用中です — feat/fervon-theme ブランチをご覧ください。