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 个 token

数据来自生产环境的运行结果——没有编造数据。

---

下载

从发布页面下载适用于你系统的安装程序——无需安装 Python 或 Node，后端已作为 sidecar 内置：

系统	文件
Windows	InferBench Setup *.exe (NSIS)
macOS	InferBench-*.dmg
Linux	InferBench-*.AppImage

想自己编译？请跳转到安装（开发）。

---

功能

• 端到端自动引导：点击 1 次 → 二进制文件 + 模型 + 启动 + 基准测试 + 清理
• llama.cpp 原生模式（无需 Docker）：从 GitHub 下载预编译版本（自动检测 CUDA，也会下载运行时 DLL）
• Docker 模式：适用于任何需要它的引擎
• 自动检测硬件：CPU、RAM、GPU（NVIDIA 通过 NVML、AMD 通过 rocm-smi、Apple Silicon 通过 system_profiler）。检测结果会缓存，因此兼容性列表可瞬间加载（扫描整个目录仅需约 4 ms）
• 包含 126 个模型的目录，支持从 HF 自动下载 GGUF，所有模型均已通过 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 显存中宽裕运行；本地运行时，llama.cpp 是低 VRAM 环境下可靠的选择）
• 优化器：根据硬件、模型和引擎，计算最佳量化方式、KV 缓存、最大上下文长度、MoE 卸载方案和标志
• KV 缓存压缩说明：提供 5 种预设（从“质量”到“极限”），说明每种压缩的作用、影响和用途；另有表格列出你的硬件在每种压缩方式下可运行的最强模型
• 3 种质量评估模式：基于参考答案的离线评分器（无需 GPU/API，可在任何 PC 上运行）、使用本地引擎的 LLM 裁判，或通过外部 API 使用 LLM 裁判。参见质量评估
• Sweep 模式：将同一模型的 N 种不同量化配置排队启动
• 比较：从历史记录中选择多次运行，并排查看指标和图表
• 实时 SSE：下载进度（含百分比）、TTFT、当前 tok/s、终端风格日志
• 可靠下载：下载数十 GB 的 GGUF 文件时支持自动重试（指数退避）；网络中断时可通过 Range 请求头从部分下载处续传
• 将 API 密钥存储在操作系统密钥环中：在系统凭据管理器中保存 OpenAI/Anthropic/OpenRouter/NVIDIA 密钥（设置 → API 密钥）；基准测试会自动使用这些密钥，绝不会将其写入磁盘
• 使用 lookspan 进行可观测性监控（可选启用）：如果定义了 LOOKSPAN_ENDPOINT，每次基准测试运行都会作为一个 trace 导出到 lookspan（根 span + 每个提示词对应一个 llm_call，包含真实的 TTFT、tok/s、VRAM 和质量数据）。尽力而为：网络故障绝不会中断基准测试
• 随时停止：取消引导、下载或运行
• 持久化：使用 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（原生，始终可用），且一次只能提供一个模型（单槽位）。API 与引擎无关；其他引擎将在之后推出。

一个应用，两种模式

InferBench 是一个统一的应用，而不是两个。从设置 → 模式 / 功能中，你可以通过切换开关启用或停用每种模式：

• Benchmark — 仪表板、引擎、模型、基准测试、历史记录。
• Serve / MCP — Serve 视图。

两种模式默认都为 ON。停用某种模式后，其条目会从侧边栏中消失（偏好设置保存在 localStorage 中）。你不能同时停用两种模式：始终至少保留一种模式。

Serve 视图

1. 从目录中选择一个模型，或点击为我的硬件推荐；将量化设置为 Auto（最佳），或手动指定。
2. 点击提供服务：InferBench 会下载模型（如有需要）并启动引擎，显示直到 ready 的阶段和进度，并提供该模型的 OpenAI 端点。
3. 在集成的迷你聊天窗口中试用。
4. 打开通过 MCP 连接，复制可直接用于 Claude Desktop / Cursor 的配置代码片段，或复制 HTTP URL。
5. 点击停止以释放 VRAM。

连接 Claude Desktop / Cursor

InferBench 会提供一个名为 inferbench 的 MCP 服务，支持两种传输方式：

• stdio — 客户端使用 --mcp 标志启动后端 sidecar。将以下内容粘贴到 Claude Desktop 的配置文件（claude_desktop_config.json）或 Cursor 的配置中：

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

  Serve 视图中的通过 MCP 连接面板会提供已填入实际路径的代码片段。

• HTTP — 对于通过 HTTP 使用 MCP 的客户端，请连接至：

  http://localhost:7777/mcp
  

stdio 传输不会启动自己的引擎：它会代理到后端。因此，InferBench 应用必须保持打开，才能通过 MCP 提供模型服务。如果应用未打开，工具会返回清晰的错误（“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 releases 的预编译 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 模式中（不是新模式），并共用单槽位：一块 GPU 一次只能运行一个服务模型，可以是文本模型，也可以是图像模型。

服务与生成

在 Serve 视图中，选择器包含图像模型（按模态分组）。 服务图像模型时，迷你聊天窗口会替换为 GenerateCard：提示词、可选的负面 提示词、steps（滑块，默认值为 20）、带预设值的尺寸 （512×512 / 768×768 / 1024×1024）、seed（带随机按钮）和生成按钮，并显示图像 预览和生成时间。API： POST /api/serve/generate（代理到服务端兼容 AUTOMATIC1111 API 的 /sdapi/v1/txt2img， 响应为 images: [PNG base64]）；如果没有处于 ready 状态的图像模型 → HTTP 409。 通过 MCP，工具 generate_image 会返回图像，供 Claude Desktop 显示。

模型（诚实列出 8 GB 显存下的要求）

模型	文件	显存约值（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

所有本地引擎都有完整的适配器（每个引擎独立构建命令、自动引导和专属优化 schema）。stablediffusion（stable-diffusion.cpp，原生）是图像引擎：它通过 :7861 上的 HTTP 服务提供扩散模型——不运行基准测试，而是生成图像（参见图像生成）。vLLM/SGLang/TGI 仅支持 Docker，且需要 NVIDIA GPU；模型由容器直接从 HuggingFace 下载（我们传入 repo id）。云端 API 使用你的 API key（仅支持采样参数，不进行本地优化）：OpenAI / OpenRouter / NVIDIA 使用 OpenAI 兼容端点 /v1/chat/completions；Anthropic 使用其原生 API（/v1/messages、x-api-key + anthropic-version 请求头，system 单独传入），与 OpenAI 不兼容。

Speculative decoding（DFLASH）：vLLM 和 SGLang 支持使用 block-diffusion draft 模型加速（DFLASH，提速 6-8×，且不损失质量）。在 Benchmark 中，选择 vLLM/SGLang 后启用 DFLASH，并指定 draft 模型（例如 z-lab/Qwen3.5-35B-A3B-DFlash）。SGLang 是官方方案；vLLM 需要使用包含相应支持的构建版本。它需要为模型和 draft 模型预留显存，因此不适用于小型 GPU。

验证状态：生产 runner 已在 NVIDIA GPU（RTX 3070，8 GB）上对全部 5 个本地引擎（llamacpp、ollama、vllm、sglang、tgi）完成端到端验证（引导 → 启动 → 实际推理且 tps>0 → 停止且无容器残留）。vLLM/SGLang 会根据实际可用显存调整显存占比，以避免在显存非空的 GPU 上运行失败。

---

已应用的优化（llama.cpp）

默认基于 core/optimizer.py：

• 最佳量化：按质量从高到低迭代（Q8 → Q2），直到能够装入
• 按运行规划（optimizer.plan_llamacpp_run）：最大上下文和 ngl 根据实际运行的 quant以及选定的有效 KV计算（而非 optimizer 原本会选择的 quant）——此前运行不同的 quant 时可能导致 OOM，或无法充分利用压缩
• 基于实际架构的精确 KV-cache（n_layer·n_head_kv·head_dim）自动计算最大上下文——涵盖 GQA/MQA
• KV-cache 压缩（-ctk -ctv）：f16 / q8_0 / q4_0（支持 K/V 独立设置和预设）。量化 KV 会强制启用 -fa on（llama.cpp 的要求）。⚠️ K 使用 q4_0 较为激进，可能降低或破坏小型模型的生成效果；q8_0 是最佳折中
• 将 KV 放入 RAM（--no-kv-offload，极限预设）：释放显存，上下文限制改由 RAM 决定
• MoE 卸载（--n-cpu-moe N），适用于小型 GPU 上的 MoE 模型
• Flash Attention（-fa on）；当模型可以完全装入显存时，启用 mlock + --no-mmap
• 线程数 = 物理核心数 · batch-size 2048 + ubatch-size 512
• 通过 engine_opts 完全覆盖（不重复 flag：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 打包为可执行文件，并作为 sidecar 嵌入 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 会启动后端 sidecar，窗口会立即显示，UI 会在服务响应后连接到 :7777。 无需手动启动任何组件。

以下细节确保它始终正常工作，而不只是首次启动时正常（frontend/electron/main.js）：

• 单实例：再次双击时会聚焦已有窗口，而不是启动另一个会争用 :7777 的后端。
• 复用健康的后端：如果已有 InferBench 正在 :7777 响应（强制关闭后 sidecar 仍在运行时经常会出现这种情况），应用会复用它，而不是启动另一个随后因不可见的绑定错误而退出的后端。
• 干净退出：退出时会通过 taskkill /T 同步终止 sidecar 进程树——before-quit 不会等待异步任务；使用普通的 spawn 时，Electron 会先退出，导致后端成为占用端口的孤儿进程。
• sidecar 日志位于 %APPDATA%\InferBench\logs\backend.log：打包后的 GUI 应用没有控制台，因此启动失败时不会留下任何记录。如果 sidecar 的 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 定义了 13 个提示词，分为三个难度层级。每个提示词都有可验证的评分器（不是基于 token 的 F1）：质量衡量的是实际正确性。难度层级经过精心设计——如果一套测试中所有人都得 100 分，就无法区分他们。

ID	难度	任务	评分方式	Token 数
chat	简单	按距太阳由近及远排列行星	8 颗行星且顺序正确，并且不包含矮行星	128
reasoning	中等	4 人分摊房租（多步数学题）	每笔金额分配给对应的人，加上总额、精确的结果行，并且不能按平均分摊	512
code	中等	merge_intervals（仅限标准库）	对 5 个用例执行代码 → 通过率	512
summary	中等	总结且不得添加内容	6 个关键事实、恰好 5 个要点，不得编造百分比或品牌	384
logic	困难	推断 4 名跑步者的到达顺序	4 个名次，使用指定格式，不得编造第五名	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 个 token 中查找 3 个代码：一个已撤销、一个已过期、一个有效	给出有效代码，且不包含任何干扰项	48
long-context-count	困难	在 120 条记录中统计 7 条 INCIDENT 记录	回答 7，且只写数字	48
vision-scene	中等	描述 3 个不同颜色的图形	形状、颜色、数量、颜色与形状对应，且不得编造图形	128
vision-count	中等	统计物体	数量、形状、颜色，且不得编造其他图形	64

vision-* 提示词仅在视觉模型上运行（需要 mmproj）；其他模型会跳过这些提示词。图像的真实标注已知（data/vision_*.png，由 scripts/make_vision_test.py 生成）。code* 提示词会在隔离的沙盒子进程中执行模型输出（python -I、临时工作目录、超时限制、资源限制、无网络、禁止破坏性系统调用）。此功能默认启用；设置 INFERBENCH_CODE_EXEC=0 可将其关闭（此时会跳过这些提示词，而非将其评分为 0）。

评分方式：加权检查

每个提示词都会声明 checks：带权重的检查项，分为五种类型——any（同义词）、number（完整数字且分配给正确的人）、order（指定顺序）、regex（精确格式）和 absent（干扰项和幻觉，会扣分）。得分为通过检查项的权重占比；SSE quality 事件中包含 failed：具体失败的检查项，因此可以审计评分，而不必盲信一个数字。

这取代了仅检查关键词的清单，因为后者会将错误答案判为正确。根据真实历史记录统计：chat 的 38 个完美答案中，有 5 个虽然题目要求按顺序排列，却把行星排错了顺序；而在 2500 中，250 也会被算作正确。

验证评分标准，而不只是模型

• backend/tests/test_checks_scorer.py 要求每个提示词的标准答案都得 100 分，而典型错误答案不得超过 60 分。无人能通过的评分标准，和什么都能通过的评分标准一样糟糕。
• python backend/scripts/audit_scoring.py --compare 会对已保存的历史记录重新评分（只读），并报告每个提示词会产生多少种不同分数、满分比例，以及最常失败的检查项。如果某个提示词只能得出两种分数，或有 40% 的答案得 100 分，就说明它已失去区分能力，需要收紧评分标准。
• 每个结果都会保存 prompt_version 和 scorer。更改提示词或评分标准时，请递增 version：否则，比较不同 run 的分数毫无意义（这确实发生过——chat 中有些记录针对的是两个不同问题）。

统计严谨性（不只测一次）

每个提示词测量 N 次（默认为 3 次，可通过 INFERBENCH_BENCH_ITERS 配置），先丢弃一次预热运行，以填充引擎缓存并完成 JIT 编译。报告的数值为这 N 次样本的中位数及其标准差——单次测量（尤其是 TTFT）只是噪声。在 llama.cpp 中，tok/s 来自引擎内部计时数据（predicted_per_second / prompt_per_second），而非从客户端开始计时，因此不会受到每个 token 的 HTTP 抖动影响。设置 INFERBENCH_BENCH_NO_WARMUP=1 可禁用预热。

每个提示词测量的指标（N 次样本的中位数）：

• TTFT（ms）：首个 token 的耗时 — 附带标准差（ttft_std）
• decode tok/s：生成阶段每秒生成的 token 数 — 附带标准差（tps_std）
• prefill tok/s：提示词处理速度（与 decode 分开测量）
• VRAM peak（GB）：run 期间的峰值，通过 pynvml 获取
• RAM peak（GB）：峰值，通过 psutil 获取
• 质量（0-100）：参见质量评估
• 成本：仅适用于云端 API（按 token 数 × 价格计算）
• n_samples：支持这些数值的有效样本数

---

质量评估

质量评分（0-100）有多种模式（TTFT 和 tok/s 始终是引擎的实际测量值）：

模式	工作原理	使用场景
基准（离线） · 默认	将回答与参考答案进行比较：按召回率加权的 token F1 + 数字精确召回率 + 前缀词干提取 + 退化文本惩罚。纯 Python，无需 GPU/模型/网络	任何电脑都能运行。适用于有预期答案的任务（推理、代码、摘要）；对于开放式任务（聊天）则只是近似评估
属性清单 · 视觉与事实	提示词定义同义词组（真实标准：形状、颜色、数量……）；评分是回答中出现的属性占比。按词边界 + 前缀匹配（接受词形变化，但“500”不会被算作“1500”的一部分）。可耐受重音符号，支持西班牙语/英语双语。无需网络	视觉（衡量模型是否正确看见图像）以及任何包含可验证事实的任务（reasoning、summary、chat、vision-*）
代码执行 · 代码任务	在隔离的子进程中，使用沙箱（python -I、临时 cwd、超时、rlimits、无网络、无破坏性系统调用），针对真实测试用例（HumanEval 风格）执行生成的代码。评分为通过的用例百分比。衡量代码是否能运行，而非其文本相似度	代码任务（code）。默认启用；INFERBENCH_CODE_EXEC=0 可将其停用（跳过提示词，不计 0 分）
LLM 评判（本地引擎）	引擎为自己的回答评分（0-100 分制）	只有能力较强的模型（≥7-8B）才可靠；小模型（1-3B）会跌至 0 分。评判者 = 被评估模型（存在偏差）
LLM 评判（外部 API）	由兼容 OpenAI 的云端模型（例如 gpt-4o-mini）进行评判	最可靠、最公正；需要 API key

默认采用离线模式，是为了让它能在没有 GPU 或 API 的机器上运行。包含 keywords 的提示词会自动使用清单模式（不会由 LLM 评判取代，因为它看不到图像）。对于开放式文本任务，LLM 评判是可选的可靠评估增强方式。

---

关键端点

方法	路径	描述
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 文件（含实际 metadata 参数）
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 次使用不同 quants 的运行
GET	/api/history	运行列表
GET	/api/history/compare/runs?ids=A,B,C	用于对比的多次运行详情
POST	/api/serve/load	开始服务常驻模型（不会阻塞：在后台启动）
GET	/api/serve/status	服务槽位状态（阶段、模型、quant、端点）
POST	/api/serve/chat	将聊天请求代理到已服务的模型（文本）
POST	/api/serve/generate	使用已服务的图像模型生成图像（未找到 ready 状态的图像模型时返回 409）
POST	/api/serve/unload	停止已服务的引擎并释放 VRAM
—	/mcp	MCP 服务（HTTP 可流式传输），适用于 Claude Desktop / Cursor — 参见 docs/MCP.md

---

缓存（不会重新下载）

• 二进制文件：%APPDATA%\InferBench\binaries\<engine>\（Windows）或 ~/.inferbench/binaries/（Linux/Mac）
• GGUF 模型：%APPDATA%\InferBench\models\<repo>\<file>.gguf
• 数据库：从代码运行时为 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	打包（配置）	✅
Bonus	端到端自动引导（下载 + 启动 + 基准测试）	✅
Bonus	无 Docker 原生模式 + CUDA DLL 下载	✅
Bonus	从 HuggingFace 自动下载 GGUF	✅
Bonus	多量化扫描 + 并排比较	✅
Bonus	运行中停止	✅
Bonus	包含 126 个模型的目录，已通过 HF 验证 + 扩展工具	✅
Bonus	从元数据读取本地 GGUF 的实际参数（与量化方式无关）	✅
Bonus	KV 压缩说明 + 按压缩率列出的高性能模型表	✅
Bonus	基于参考的离线质量评估 + LLM 评审（本地 / API）	✅
Bonus	从元数据精确计算 KV 缓存（n_head_kv/head_dim，可识别 GQA/MQA），覆盖目录中 123/124 个文本模型	✅
Bonus	真正的视觉（多模态）：下载 mmproj，在 llama-server 中使用 --mmproj，并通过真实图像构造提示词	✅
Bonus	服务 / MCP 模式：以常驻方式提供最佳量化模型，并通过 MCP（stdio + HTTP）向 Claude Desktop / Cursor 暴露	✅
Bonus	本地图像生成，使用 stable-diffusion.cpp：提供图像模型并生成图像（POST /api/serve/generate + MCP 工具 generate_image）	✅

---

待办事项 / 后续步骤

• 扩大测试覆盖范围（backend/tests/ 中已有 122 项：compat、optimizer、quality、gguf_reader、multimodal、security、api、gpu_safety、keys、lookspan、multipart、speculative、benchmark_rigor、serve、mcp、image_serve）
• 支持 Docker 引擎（vLLM/SGLang）中的视觉功能，以及通过 API 实现多模态（gpt-4o）；目前真正的视觉功能由原生 llamacpp 实现
• 视频生成（第二阶段）：stable-diffusion.cpp 已支持 Wan2.1/Wan2.2 和 LTX；尚待集成（目前仅支持图像）。此外，还需在基准测试模式中加入生成指标
• 实现 cache-reuse、--prio-batch 及 llama.cpp 的其余调优标志

---

补充文档

• PROJECT_BRIEF.md — 项目愿景、架构、各引擎的优化 schemas、兼容性公式
• docs/MCP.md — 服务 / MCP 模式：MCP 服务工具、stdio/HTTP 传输、Claude Desktop / Cursor 配置和故障排除
• docs/IMAGE.md — 使用 stable-diffusion.cpp 生成图像：支持的模型、VRAM 要求、FLUX 辅助文件和故障排除
• docs/COMMUNITY-ROADMAP.md — 面向社区的路线图（用户提出的优先改进项）
• CLAUDE.md — 开发规范和 M1–M9 里程碑计划

---

参与贡献

欢迎提交 PR——请阅读 CONTRIBUTING.md，了解环境配置、如何运行 lint/tests 以及相关规范。适合首次贡献的内容：为 ollama/vllm/sglang/tgi 编写真正的适配器，以及为 compat.py/optimizer.py 补充更多测试。进行重大更改前，请先提交 issue，以便协商方案。

本项目遵循行为准则。

安全

发现漏洞了吗？请勿公开提交 issue——请按照 SECURITY.md 中的说明操作。本项目已通过安全审计（安全状况良好；发现的问题均已修复）。

许可证

MIT © 2026 Jonathan Martin。

---

InferBench 是 Fervon 的一部分。Fervon 是汇集开源工具作品集（Trace、lookspan、claudescope、launchpad 等）的工作室。Fervon 品牌形象正在应用于着陆页——请参见 feat/fervon-theme 分支。