Documentación

VRAMPilot se instala como un paquete Python y no necesita nada más: sin instalación de llama.cpp, sin descarga manual de un binario llama-server. Esta página cubre la instalación, el funcionamiento de la escala de recuperación, lo que se persiste, el comportamiento del watchdog y los requisitos previos.

Instalación

pipx install vrampilot          # o: pip install vrampilot

Ejecútalo sobre un modelo:

vrampilot tu-modelo.gguf --ctx 8192       # CLI: plan -> arranque -> recuperación -> servicio
vrampilot-web                             # UI web: pega una ruta .gguf -> Launch -> chat

La interfaz web escucha en http://127.0.0.1:8770. Ambos puntos de entrada terminan en un endpoint compatible con OpenAI utilizable por cualquier cliente. La forma de módulo también funciona: python -m vrampilot.cli / python -m vrampilot.web.

Cómo funciona la escala de recuperación

Cuando el servidor no arranca (o arranca pero no puede generar ningún token), VRAMPilot lee el log de error, lo clasifica como out-of-memory, retrocede un peldaño y reintenta. El orden está diseñado para preservar la mayor capacidad posible:

  1. La precisión del KV-cache primero (f16 -> q8_0 -> q4_0). Esto reduce el KV-cache manteniendo tu contexto completo. Es lossy en el razonamiento largo — el informe lo dice.
  2. Luego reducir el contexto — dividido a la mitad hasta que quepa.
  3. Luego descargar más hacia la CPU — más expert-offload MoE, o menos capas GPU para los modelos densos.
  4. El suelo — si nada cabe, lo dice honestamente en lugar de fingir.

Ejemplo validado (traza en bruto en validation/RESULTS.md): ante una configuración deliberadamente imposible con 262144 de contexto, se recuperó a 131072 de contexto — 4x más de lo que un repliegue solo sobre el contexto habría conservado — y sirvió una respuesta real.

El detector de OOM reconoce las cadenas de error de CUDA, Vulkan, ROCm y Metal.

Persistencia

Cada configuración que realmente ha arrancado se persiste por (huella de la máquina, hash de la cabecera del modelo, contexto solicitado) en una base SQLite local, ~/.governor/configs.db (el motor conserva el nombre «governor» a propósito). En append-only: una configuración que ya no funciona se conserva en el historial, nunca se sobrescribe. El siguiente lanzamiento arranca directamente sobre la configuración conocida-buena; un cambio de driver o de GPU invalida la entrada y desencadena un nuevo plan.

Por qué importa: un intento fallido cuesta una carga completa del modelo — medida en ~220 s por intento para un modelo MoE de 9,5 Go cargado con --no-mmap en el disco de la máquina del gate. La caché existe para no pagar eso nunca dos veces.

Controles de transparencia:

vrampilot configs list              # inspeccionar todo lo que recuerda
vrampilot modelo.gguf --no-cache    # ignorar la caché, forzar un nuevo plan

Nada sale de tu máquina.

Comportamiento del watchdog

Mientras el servidor está en marcha, el watchdog cubre el agotamiento de la VRAM durante una generación — por ejemplo, abres otra aplicación GPU en plena transmisión.

Límite conocido: llama.cpp no sabe reducir en caliente el KV-cache de un servidor en marcha; la única acción en runtime es por tanto ese reinicio controlado. Si el upstream entrega el redimensionamiento en caliente del KV, VRAMPilot lo adoptará y retirará el reinicio para esa vía.

Requisitos previos

Python 3.9+ es el único requisito previo declarado de la instalación pip/pipx — todo lo demás (incluido el binario del motor de inferencia) se descarga y se verifica en el primer lanzamiento.