inferbench

---

¿Quieres correr LLMs en local pero no sabes qué cuantización te entra en tu GPU, ni a cuántos tok/s va a ir, ni qué motor es más rápido para tu hardware? InferBench lo responde por ti, midiendo de verdad — sin números inventados.

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

Ejemplo real

RTX 3070 · 8 GB VRAM · 32 GB RAM — corriendo SmolLM2-360M Q8_0 con llama.cpp nativo:

Métrica	Resultado
TTFT	588 ms
Throughput	272 tok/s
VRAM pico	2.47 GB
Calidad (offline scorer)	75 / 100
Contexto automático	8 192 tokens

Números sacados del runner de producción — sin datos inventados.

---

Descargar

Coge el instalador para tu sistema desde la página de Releases — no necesitas Python ni Node instalados, el backend va embebido como sidecar:

Sistema	Archivo
Windows	InferBench Setup *.exe (NSIS)
macOS	InferBench-*.dmg
Linux	InferBench-*.AppImage

¿Prefieres compilarlo tú? Salta a Instalación (desarrollo).

---

Features

• Auto-bootstrap end-to-end: 1 click → binario + modelo + arranque + benchmark + cleanup
• Modo nativo (sin Docker) para llama.cpp: descarga release pre-compilada de GitHub (auto-detecta CUDA, descarga también las DLLs del runtime)
• Modo Docker disponible para cualquier motor que lo requiera
• Detección automática de hardware: CPU, RAM, GPU (NVIDIA via NVML, AMD via rocm-smi, Apple Silicon via system_profiler). Cacheada para que el listado de compatibilidad sea instantáneo (~4 ms para todo el catálogo)
• Catálogo de 126 modelos con auto-descarga GGUF desde HF, todos verificados contra HuggingFace (incluye visión, código, reasoning, MoE y difusión de imagen). Ver Catálogo
• Escaneo de GGUFs locales: detecta modelos de LM Studio, Ollama, HF cache, etc., con cuenta de parámetros real leída de la metadata GGUF (independiente del quant)
• Visión real (multimodal): para modelos de visión (Qwen2-VL, Qwen2.5-VL, MiniCPM-V) descarga el mmproj, arranca llama-server con --mmproj y benchmarkea un prompt con imagen real vía la API de visión OpenAI-compatible. También en APIs (gpt-4o, claude) y motores Docker (vLLM sirve el modelo de visión) — aunque vLLM con un modelo de visión necesita bastante VRAM (un 2B no entra holgado en 8 GB; en local, llama.cpp es la ruta fiable a poca VRAM)
• Optimizador: dado tu hardware + modelo + motor, calcula la mejor cuantización, KV-cache, contexto máximo, MoE offload, flags
• Compresión de KV-cache explicada: 5 presets (Calidad→Extremo) con qué hace / en qué afecta / qué permite, + tabla de los modelos más potentes que caben con cada compresión para tu hardware
• Evaluación de calidad en 3 modos: scorer offline basado en referencia (sin GPU/API, corre en cualquier PC), LLM-judge con el motor local, o LLM-judge por API externa. Ver Calidad
• Modo sweep: lanza el mismo modelo con N cuantizaciones distintas en cola
• Comparación: selecciona varias runs del historial, ve métricas y gráficos lado a lado
• SSE en vivo: progreso de descargas (con %), TTFT, tok/s actual, log estilo terminal

---

Serve / MCP

Además de benchmarkear, InferBench puede servir un modelo cuantizado de forma residente y exponerlo a cualquier app por MCP (Model Context Protocol). Reusa la misma tubería del benchmark (detección de hardware → optimizador → descarga de GGUF → arranque del motor): InferBench actúa de intermediario que orquesta los modelos, elige la cuantización óptima para tu hardware, descarga el GGUF, arranca el motor y enruta la inferencia.

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: motor llamacpp (nativo, siempre disponible) y un solo modelo servido a la vez (slot único). La API es agnóstica de motor; otros motores llegarán después.

Una sola app, dos modos

InferBench es una app unificada, no dos. Desde Ajustes → Modos / Features activas o desactivas cada modo con un toggle:

• Benchmark — Dashboard, Motores, Modelos, Benchmark, Historial.
• Serve / MCP — la vista Serve.

Ambos vienen ON por defecto. Al desactivar un modo, sus ítems desaparecen de la barra lateral (la preferencia se guarda en localStorage). Nunca puedes desactivar los dos a la vez: siempre queda al menos uno.

La vista Serve

1. Elige un modelo del catálogo o pulsa recomendar para mi hardware; deja la cuantización en Auto (óptimo) o fíjala a mano.
2. Pulsa Servir: InferBench descarga (si hace falta) y arranca el motor, mostrando la fase y el progreso hasta ready, y te da el endpoint OpenAI del modelo.
3. Pruébalo en el mini-chat integrado.
4. Abre Conectar por MCP para copiar el snippet de configuración listo para Claude Desktop / Cursor, o la URL HTTP.
5. Parar libera la VRAM.

Conectar Claude Desktop / Cursor

InferBench expone un servidor MCP llamado inferbench con dos transportes:

• stdio — el cliente lanza el sidecar del backend con el flag --mcp. Pega esto en la config de Claude Desktop (claude_desktop_config.json) o de Cursor:

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

  El panel Conectar por MCP de la vista Serve te da el snippet con la ruta real ya rellenada.

• HTTP — para clientes que hablan MCP sobre HTTP, apunta a:

  http://localhost:7777/mcp
  

El transporte stdio no arranca su propio motor: hace de proxy al backend. Por eso la app InferBench debe estar abierta para servir un modelo por MCP. Si no lo está, las tools devuelven un error claro ("InferBench no está abierto…") en vez de fallar.

Tools MCP: list_models, recommend_models, get_hardware, serve_model, serve_status, chat, stop_model y generate_image (si el modelo servido es de imagen). La guía completa (qué hace cada tool, snippets y troubleshooting) está en docs/MCP.md.

---

Generación de imagen

InferBench no se queda en LLM de texto: orquesta también modelos de imagen locales, reutilizando exactamente el mismo patrón. Donde para texto usa el binario nativo de llama.cpp + GGUF, para imagen usa su hermano de difusión, stable-diffusion.cpp (binario CUDA precompilado de los releases de GitHub + pesos GGUF/safetensors de Hugging Face + su server HTTP). InferBench sigue siendo el intermediario que orquesta: elige los pesos, descarga lo que falte (incluidos los archivos auxiliares de FLUX), arranca sd-server de forma residente y enruta la generación.

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)

Vive dentro del modo Serve existente (no es un modo nuevo) y comparte el slot único: una GPU = un modelo servido a la vez, sea de texto o de imagen.

Servir y generar

En la vista Serve, el selector incluye los modelos de imagen (agrupados por modalidad). Al servir uno de imagen, en vez del mini-chat aparece un GenerateCard: prompt, negative prompt opcional, steps (slider, 20 por defecto), tamaño con presets (512×512 / 768×768 / 1024×1024), seed (con botón aleatorio) y botón Generar, con preview de la imagen y el tiempo de generación. Por API: POST /api/serve/generate (proxy a la API AUTOMATIC1111-compatible /sdapi/v1/txt2img del server, respuesta images: [PNG base64]); si no hay modelo de imagen ready → HTTP 409. Por MCP, la tool generate_image devuelve la imagen para que Claude Desktop la muestre.

Modelos (requisitos honestos en 8 GB)

Modelo	Archivos	VRAM aprox. (8 GB)
SD 1.5 / SD-Turbo	single-file	~2–4 GB · entra holgado (default garantizado)
SDXL	single-file	~6–8 GB · ajustado a 1024×1024
FLUX.1-schnell (Q4)	multi-archivo (diffusion + t5xxl + clip_l + vae)	~7–8 GB · al límite (showcase)

El vídeo (Wan2.1/Wan2.2, LTX — ya soportados por stable-diffusion.cpp) llega en una fase 2; esta entrega es solo imagen. El pipeline de benchmark no cambia: no hay métricas de generación todavía.

La guía completa (modelos, cuantización, archivos auxiliares de FLUX y troubleshooting) está en docs/IMAGE.md.

---

Stack

Capa	Tecnología
App de escritorio	Electron 42
Frontend	React 18 + Vite 8 + TailwindCSS + Recharts + lucide-react
Backend	FastAPI (Python 3.11) + uvicorn + sse-starlette
Persistencia	SQLite vía SQLModel
GPU detection	psutil + pynvml + system_profiler / rocm-smi
Containers	Docker SDK for Python
Native runtime	subprocess.Popen + binarios oficiales de GitHub
Empaquetado	electron-builder + PyInstaller

---

Motores soportados

Motor	Tipo	Modo nativo	Modo Docker	Auto-descarga modelo
llamacpp	local	✅ binarios oficiales	✅	✅ HuggingFace GGUF
stablediffusion	local	✅ binarios oficiales (sd.cpp)	—	✅ HuggingFace GGUF/safetensors
ollama	local	✅ daemon Ollama	✅	✅ registro Ollama
vllm	local	—	✅ (GPU NVIDIA)	✅ HF (en contenedor)
sglang	local	—	✅ (GPU NVIDIA)	✅ HF (en contenedor)
tgi	local	—	✅ (GPU NVIDIA)	✅ HF (en contenedor)
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

Todos los motores locales tienen adaptador completo (build de comando por motor, bootstrap automático y schema de optimización propio). stablediffusion (stable-diffusion.cpp, nativo) es el motor de imagen: sirve un modelo de difusión por su server HTTP en :7861 — no benchmarkea, genera (ver Generación de imagen). vLLM/SGLang/TGI son Docker-only y requieren GPU NVIDIA; el modelo lo descarga el propio contenedor desde HuggingFace (le pasamos el repo id). Las APIs cloud funcionan con tu API key (sólo parámetros de sampling, sin optimización local): OpenAI / OpenRouter / NVIDIA usan el endpoint OpenAI-compatible /v1/chat/completions; Anthropic usa su API nativa (/v1/messages, header x-api-key + anthropic-version, system aparte), no es OpenAI-compatible.

Speculative decoding (DFLASH): vLLM y SGLang aceptan acelerar con un modelo draft block-diffusion (DFLASH, 6-8× sin pérdida de calidad). En Benchmark, con vLLM/SGLang seleccionado, activa DFLASH e indica el modelo draft (p.ej. z-lab/Qwen3.5-35B-A3B-DFlash). SGLang es la ruta oficial; vLLM necesita una build con soporte. Requiere VRAM para el modelo y el draft, así que no entra en GPUs pequeñas.

Estado de verificación: los 5 motores locales (llamacpp, ollama, vllm, sglang, tgi) verificados end-to-end por el runner de producción (bootstrap → arranque → inferencia real con tps>0 → parada sin contenedores colgados) en GPU NVIDIA (RTX 3070, 8 GB). vLLM/SGLang ajustan la fracción de VRAM a la memoria libre real para no fallar en GPUs no vacías.

---

Optimizaciones aplicadas (llama.cpp)

Por defecto, basadas en core/optimizer.py:

• Cuantización óptima: itera de mayor a menor calidad (Q8 → Q2) hasta que cabe
• Plan por run (optimizer.plan_llamacpp_run): el contexto máximo y ngl se calculan para el quant que de verdad se ejecuta y la KV efectiva elegida (no para el quant que el optimizer habría elegido) — antes podía dar OOM al correr un quant distinto, o desaprovechar la compresión
• Contexto máximo automático con KV-cache exacta de la arquitectura real (n_layer·n_head_kv·head_dim) — captura GQA/MQA
• KV-cache compresión (-ctk -ctv): f16 / q8_0 / q4_0 (+ K/V independientes y presets). La KV cuantizada fuerza -fa on (llama.cpp lo exige). ⚠️ q4_0 en K es agresivo y puede degradar/romper la generación en modelos pequeños; q8_0 es el punto dulce
• KV en RAM (--no-kv-offload, preset Extremo): libera VRAM y el contexto pasa a limitarlo la RAM
• MoE offload (--n-cpu-moe N) para modelos MoE en GPUs pequeñas
• Flash Attention (-fa on), mlock + --no-mmap cuando el modelo cabe entero en VRAM
• Threads = núcleos físicos · batch-size 2048 + ubatch-size 512
• Override total via engine_opts (sin duplicar flags: el optimizer pone la base, tus overrides mandan)

---

Catálogo de modelos con auto-descarga

backend/data/models.json lista 126 modelos (124 de texto + 2 de imagen por difusión). Los que tienen hf_gguf configurado se auto-descargan desde Hugging Face. Cubre, entre otros:

• 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 (reasoning), MoE 30B-A3B
• Gemma 2 y 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 distills, Coder, Coder-V2-Lite (MoE)
• Visión: Qwen2-VL, Qwen2.5-VL, MiniCPM-V
• Código: Code Llama, CodeGemma, StarCoder2, Yi-Coder, OpenCoder, Stable Code
• Más: Granite (IBM), Falcon3, GLM-4, EXAONE, InternLM, OLMo, Aya/Command-R (Cohere), SmolLM2, SOLAR, Zephyr…

Sin datos inventados. Cada entrada se verifica contra HuggingFace antes de añadirse: el repo GGUF existe, el file_template se deriva de los archivos reales publicados y se comprueba que el Q4_K_M resuelve. La herramienta está en backend/scripts/ (verify_models.py + merge_models.py); ejecútala para ampliar el catálogo de forma segura. Los modelos enormes partidos en shards (-00001-of-000NN.gguf, p.ej. DeepSeek-V3, Llama 4 70B+) también se soportan: el catálogo marca hf_gguf.multipart y la descarga junta todos los shards (llama.cpp carga las hermanas del mismo directorio).

---

Instalación (desarrollo)

Requisitos

• Node.js 20+: https://nodejs.org/
• Python 3.11+: https://www.python.org/
• uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• (Opcional) Docker Desktop si vas a usar motores Docker
• (Opcional) Driver NVIDIA si quieres acceleración GPU (la app detecta y descarga la build CUDA)

Arrancar en dev

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

Se abre la app en una ventana Electron. La sidebar muestra la salud del backend y navega entre vistas.

---

Empaquetado

El backend Python se empaqueta como ejecutable con PyInstaller y se embebe como sidecar en el instalador Electron. La app empaquetada no requiere Python en la máquina destino.

# 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

Salida en frontend/release/:

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

Arranque de un solo click

El instalador de Windows es one-click y por usuario (sin UAC): crea acceso directo en el escritorio y en el menú inicio, ambos con el icono de marca, y abre la app al terminar. Un doble click en ese acceso directo levanta todo: Electron arranca el sidecar del backend, la ventana aparece de inmediato y la UI se engancha al :7777 en cuanto responde. No hay que arrancar nada a mano.

Detalles que hacen que eso funcione siempre, no solo la primera vez (frontend/electron/main.js):

• Instancia única: un segundo doble click enfoca la ventana existente en vez de levantar otro backend peleando por el :7777.
• Reuso de backend sano: si ya hay un InferBench respondiendo en el :7777 (típico tras un cierre forzado, donde el sidecar sobrevive), la app lo reutiliza en lugar de arrancar otro que moriría con un error de bind invisible.
• Cierre limpio: al salir se mata el árbol del sidecar con taskkill /T de forma síncrona — before-quit no espera trabajo asíncrono, y con un spawn normal Electron se moría antes y dejaba el backend huérfano ocupando el puerto.
• Log del sidecar en %APPDATA%\InferBench\logs\backend.log: en una app GUI empaquetada no hay consola, así que un arranque fallido dejaría cero rastro. Si el exe del sidecar falta, además sale un diálogo de error en vez de un cierre silencioso.
• El puerto se pasa por INFERBENCH_PORT (que es lo que lee backend/main.py).

---

Arquitectura

┌──────────────────────────────────────────────────┐
│  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)              │
└──────────────────────────────────────────────────┘

---

Estructura del repo

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

---

Suite de prompts

backend/data/prompts.json define 13 prompts en tres tramos de dificultad. Cada uno tiene un scorer verificable (no F1 de tokens): la calidad mide corrección real. Los tramos son deliberados — una batería donde todo el mundo saca 100 no ordena a nadie.

ID	Dif.	Tarea	Cómo se puntúa	Tokens
chat	fácil	planetas en orden desde el Sol	los 8 planetas + en orden + sin planetas enanos	128
reasoning	medio	reparto de alquiler a 4 (mates multi-paso)	cada cantidad asignada a su persona + total + línea de resultado exacta + no caer en el reparto a partes iguales	512
code	medio	merge_intervals (solo stdlib)	ejecuta el código contra 5 casos → % que pasan	512
summary	medio	resumir sin añadir nada	6 hechos clave + exactamente 5 puntos + sin porcentajes ni marcas inventadas	384
logic	difícil	deducir el orden de llegada de 4 corredores	las 4 posiciones, en el formato pedido, sin inventar una quinta	512
instructions	difícil	3 capitales, formato estricto	las 3 en formato N: Ciudad + sin las capitales equivocadas populares (Sídney, Estambul, Toronto)	128
json-extract	difícil	pasar una nota a JSON	claves exactas + total calculado (61,00) + sin fences markdown	256
unanswerable	difícil	pregunta que el texto NO responde	dice que no consta y no reutiliza la cifra del texto	192
code-hard	difícil	summarize_ranges con duplicados y negativos	ejecuta el código contra 8 casos límite	640
long-context	difícil	3 códigos en ~4,7k tokens: uno revocado, uno caducado, uno activo	da el activo y ninguno de los señuelos	48
long-context-count	difícil	contar los 7 registros entre 120

Los prompts vision-* solo corren en modelos de visión (con mmproj); para el resto se omiten. Las imágenes tienen ground-truth conocido (data/vision_*.png, generadas por scripts/make_vision_test.py). Los prompts code* ejecutan la salida del modelo en un subproceso aislado con sandbox (python -I, cwd temporal, timeout, límites de recursos, sin red, sin syscalls destructivas). Activado por defecto; desactívalo con INFERBENCH_CODE_EXEC=0 (entonces esos prompts se omiten, no se puntúan 0).

Cómo se puntúa: comprobaciones ponderadas

Cada prompt declara checks: comprobaciones con peso, de cinco tipos — any (sinónimos), number (el número completo y asignado a quien toca), order (la secuencia pedida), regex (formato exacto) y absent (señuelos y alucinaciones, que restan). La nota es la fracción del peso superada, y el evento SSE quality incluye failed: qué comprobación concreta se falló, para que la nota se pueda auditar en vez de creer un número.

Esto sustituye al checklist de solo-palabras, que daba por buenas respuestas incorrectas. Medido sobre el historial real: 5 de 38 respuestas perfectas de chat tenían los planetas desordenados aunque el enunciado pedía orden, y 250 contaba como acierto dentro de 2500.

Validar la batería, no solo los modelos

• backend/tests/test_checks_scorer.py exige que una respuesta modelo de cada prompt saque 100 y que el fallo típico se quede en ≤60. Un baremo que nadie puede aprobar está tan roto como uno que aprueba cualquier cosa.
• python backend/scripts/audit_scoring.py --compare re-puntúa el historial guardado (solo lectura) y reporta por prompt cuántas notas distintas produce, el % que se queda en el techo y qué comprobaciones fallan más. Si un prompt solo da dos notas o el 40% saca 100, ha dejado de discriminar y toca endurecerlo.
• Cada resultado guarda prompt_version y scorer. Sube version al cambiar un enunciado o un baremo: sin eso, comparar notas de runs distintas no significa nada (pasó de verdad — filas de chat con respuestas a dos preguntas diferentes).

Rigor estadístico (no una sola muestra)

Cada prompt se mide N veces (3 por defecto, configurable con INFERBENCH_BENCH_ITERS) tras descartar una pasada de warmup que llena los cachés/JIT del motor. Las cifras reportadas son la mediana de esas N muestras, con su desviación estándar — una sola medida (sobre todo de TTFT) era ruido. En llama.cpp el tok/s sale de los timings internos del motor (predicted_per_second / prompt_per_second), no de cronometrar desde el cliente: sin jitter de HTTP por token. Desactiva el warmup con INFERBENCH_BENCH_NO_WARMUP=1.

Métricas medidas por prompt (mediana de N muestras):

• TTFT (ms): tiempo al primer token — con su desviación (ttft_std)
• decode tok/s: tokens por segundo en la fase de generación — con su desviación (tps_std)
• prefill tok/s: velocidad de procesamiento del prompt (medición separada del decode)
• VRAM peak (GB): pico durante el run, vía pynvml
• RAM peak (GB): pico vía psutil
• Calidad (0-100): ver Evaluación de calidad
• Coste: solo APIs cloud (calculado de tokens × precio)
• n_samples: nº de muestras válidas que respaldan las cifras

---

Evaluación de calidad

La nota de calidad (0-100) tiene varios modos (TTFT y tok/s siempre son medidas reales del motor):

Modo	Cómo funciona	Cuándo usarlo
Referencia (offline) · default	Compara la respuesta con la de referencia: F1 de tokens recall-weighted + recall exacto de números + stemming por prefijo + penalización de texto degenerado. Python puro, sin GPU/modelo/red	Funciona en cualquier ordenador. Bueno en tareas con respuesta esperada (razonamiento, código, resumen); aproximado en tareas abiertas (chat)
Checklist de atributos · visión y hechos	El prompt define grupos de sinónimos (el ground-truth: formas, colores, conteo…); la nota es la fracción de atributos que aparecen en la respuesta. Casa por límite de palabra + prefijo (acepta morfología, pero "500" no cuenta dentro de "1500"). Robusto a acentos y bilingüe (ES/EN). Sin red	Visión (mide si el modelo vio bien la imagen) y cualquier tarea con hechos verificables (reasoning, summary, chat, vision-*)
Ejecución de código · tareas de código	Ejecuta el código generado contra casos de prueba reales (estilo HumanEval) en un subproceso aislado con sandbox (python -I, cwd temporal, timeout, rlimits, sin red, sin syscalls destructivas). La nota es el % de casos que pasan. Mide si el código FUNCIONA, no su parecido textual	Tareas de código (code). Activado por defecto; INFERBENCH_CODE_EXEC=0 lo desactiva (omite el prompt, no puntúa 0)
LLM-judge (motor local)	El propio motor puntúa sus respuestas (rúbrica 0-100)	Fiable solo con modelos capaces (≥7-8B); los pequeños (1-3B) colapsan a 0. Juez = modelo evaluado (sesgo)
LLM-judge (API externa)	Un modelo cloud OpenAI-compatible (p.ej. gpt-4o-mini) juzga	Lo más fiable e imparcial; requiere API key

El default es offline a propósito para que funcione en máquinas sin GPU ni API. Los prompts con keywords usan el checklist automáticamente (no lo sustituye el LLM-judge, que no ve la imagen). El LLM-judge es la mejora opcional para juicio fiable de tareas abiertas de texto.

---

Endpoints clave

Método	Ruta	Descripción
GET	/api/health	Status + info Docker
GET	/api/hardware	CPU, RAM, GPUs
GET	/api/engines	Lista motores con runtime availability
POST	/api/engines/{id}/install	SSE: descarga binario nativo
POST	/api/engines/{id}/start	Arranca motor (auto-instala si falta)
POST	/api/engines/{id}/stop	Detiene motor
GET	/api/models	Catálogo
GET	/api/models/local	GGUFs locales en disco (con params reales de metadata)
GET	/api/models/compat/all?engine=X	Compat por modelo
POST	/api/optimize	Config óptima
GET	/api/optimize/recommendations?top=N	Modelos más potentes ejecutables en tu hardware
GET	/api/optimize/by-compression?context_len=N	Modelo más potente que cabe con cada preset de compresión KV
POST	/api/benchmark/run	Lanza run, devuelve run_id
GET	/api/benchmark/{run_id}/stream	SSE de progreso
POST	/api/benchmark/{run_id}/stop	Cancela run en curso
POST	/api/benchmark/sweep	Lanza N runs con quants distintas
GET	/api/history	Lista runs
GET	/api/history/compare/runs?ids=A,B,C	Detalle multi-run para comparación
POST	/api/serve/load	Empieza a servir un modelo residente (no bloquea: arranca en background)
GET	/api/serve/status

---

Cachés (no se redescargan)

• Binarios: %APPDATA%\InferBench\binaries\<engine>\ (Windows) o ~/.inferbench/binaries/ (Linux/Mac)
• Modelos GGUF: %APPDATA%\InferBench\models\<repo>\<file>.gguf
• DB: backend/data/inferbench.sqlite ejecutando desde el código, %APPDATA%\InferBench\inferbench.sqlite en la app empaquetada. INFERBENCH_DB_PATH manda sobre las dos (lo usa el arnés de pruebas para no poder tocar tus datos)
• Logs de motores nativos: %APPDATA%\InferBench\logs\<engine>.log

Estado de las runs en el Historial

done (verde) · error (rojo) · running (en curso) · interrupted (ámbar).

Al arrancar, el backend cierra las runs que quedaron en running de una ejecución anterior — cerraste la app a mitad, se cayó el backend — porque el proceso que las ejecutaba ya no existe. Una run con resultados para todos sus prompts NO se marca interrumpida: terminó y solo le faltó el último cambio de estado, así que se recupera como done. Además, al arrancar se reparan (de forma idempotente) las runs marcadas interrupted que sí tienen todos sus resultados, para dejar el Historial fiel en las instalaciones donde quedaron mal marcadas.

---

Estado de hitos

	Hito	Estado
M1	Detección hardware (NVIDIA·AMD·Apple·CPU-only)	✅
M2	Gestor Docker + abstracción Engine + llama.cpp	✅
M3	Catálogo modelos + cálculos compat y max_ctx	✅
M4	Benchmark + SSE + persistencia SQLite	✅
M5	Frontend Electron + Vite + Tailwind	✅
M6	UI completa (6 vistas)	✅
M7	Panel live SSE	✅
M8	Optimizador automático + botón ⚡	✅
M9	Empaquetado (config)	✅
Bonus	Auto-bootstrap end-to-end (descarga + arranque + bench)	✅
Bonus	Modo nativo sin Docker + descarga de DLLs CUDA	✅
Bonus	Auto-descarga GGUF desde HuggingFace	✅
Bonus	Sweep multi-quant + comparación side-by-side	✅
Bonus	Stop mid-run	✅
Bonus	Catálogo de 126 modelos verificados contra HF + tooling de ampliación	✅
Bonus	Params reales de GGUFs locales desde metadata (independiente del quant)	✅
Bonus	Compresión KV explicada + tabla de modelos más potentes por compresión	✅
Bonus	Calidad offline basada en referencia + LLM-judge (local / API)	✅
Bonus	KV-cache exacta desde metadata (n_head_kv/head_dim, capta GQA/MQA) en 123/124 modelos de texto del catálogo

---

Pendientes / siguientes pasos

• Más cobertura de tests (ya hay 122 en backend/tests/: compat, optimizer, quality, gguf_reader, multimodal, security, api, gpu_safety, keys, lookspan, multipart, speculative, benchmark_rigor, serve, mcp, image_serve)
• Soporte de visión en motores Docker (vLLM/SGLang) y multimodal por API (gpt-4o); hoy la visión real corre en llamacpp nativo
• Generación de vídeo (fase 2): stable-diffusion.cpp ya soporta Wan2.1/Wan2.2 y LTX; falta integrarlo (hoy solo imagen). Y métricas de generación en el modo Benchmark
• Implementar cache-reuse, --prio-batch y resto de flags de tuning de llama.cpp

---

Documentación complementaria

• PROJECT_BRIEF.md — visión, arquitectura, schemas de optimización por motor, fórmulas de compatibilidad
• docs/MCP.md — modo Serve / MCP: tools del servidor MCP, transportes stdio/HTTP, config de Claude Desktop / Cursor y troubleshooting
• docs/IMAGE.md — generación de imagen vía stable-diffusion.cpp: modelos soportados, requisitos de VRAM, archivos auxiliares de FLUX y troubleshooting
• docs/COMMUNITY-ROADMAP.md — roadmap orientado a la comunidad (mejoras priorizadas que pide la gente)
• CLAUDE.md — convenciones de desarrollo y plan de hitos M1–M9

---

Contribuir

Las PRs son bienvenidas — lee CONTRIBUTING.md para el setup, cómo correr lint/tests y las convenciones. Buenos primeros aportes: los adaptadores reales para ollama/vllm/sglang/tgi y más tests de compat.py/optimizer.py. Abre un issue antes de un cambio grande para acordar el enfoque.

El proyecto sigue un Código de conducta.

Seguridad

¿Encontraste una vulnerabilidad? No abras un issue público — sigue SECURITY.md. El proyecto ha pasado una auditoría de seguridad (postura buena; los hallazgos están remediados).

Licencia

MIT © 2026 Jonathan Martin.

---

InferBench forma parte de Fervon, el estudio que agrupa el portfolio de herramientas open source (Trace, lookspan, claudescope, launchpad y más). La identidad de marca Fervon se está aplicando a la landing — ver la rama feat/fervon-theme.