Documentation

VRAMPilot s'installe comme un paquet Python et n'a besoin de rien d'autre : pas d'installation de llama.cpp, pas de téléchargement manuel d'un binaire llama-server. Cette page couvre l'installation, le fonctionnement de l'échelle de récupération, ce qui est persisté, le comportement du watchdog, et les prérequis.

Installation

pipx install vrampilot          # ou : pip install vrampilot

Lancez-le sur un modèle :

vrampilot votre-modele.gguf --ctx 8192    # CLI : plan -> lancement -> récupération -> service
vrampilot-web                             # UI web : collez un chemin .gguf -> Launch -> chat

L'interface web écoute sur http://127.0.0.1:8770. Les deux points d'entrée aboutissent à un endpoint compatible OpenAI utilisable par n'importe quel client. La forme module fonctionne aussi : python -m vrampilot.cli / python -m vrampilot.web.

Comment fonctionne l'échelle de récupération

Quand le serveur ne démarre pas (ou démarre mais ne peut pas générer de token), VRAMPilot lit le log d'erreur, le classifie comme out-of-memory, se replie d'un cran, et réessaie. L'ordre est conçu pour préserver le plus de capacité :

  1. La précision du KV-cache d'abord (f16 -> q8_0 -> q4_0). Cela réduit le KV-cache tout en gardant votre contexte complet. C'est lossy sur le raisonnement long — le rapport le dit.
  2. Puis réduire le contexte — divisé par deux jusqu'à ce que ça tienne.
  3. Puis décharger davantage vers le CPU — plus d'expert-offload MoE, ou moins de couches GPU pour les modèles denses.
  4. Le plancher — si rien ne tient, il le dit honnêtement au lieu de faire semblant.

Exemple validé (trace brute dans validation/RESULTS.md) : face à une configuration volontairement impossible à 262144 de contexte, il a récupéré à 131072 de contexte — 4x plus qu'un repli sur le seul contexte n'en aurait gardé — et a servi une vraie réponse.

Le détecteur d'OOM reconnaît les chaînes d'erreur CUDA, Vulkan, ROCm et Metal.

Persistance

Chaque configuration qui a réellement démarré est persistée par (empreinte machine, hash de l'en-tête du modèle, contexte demandé) dans une base SQLite locale, ~/.governor/configs.db (le moteur garde le nom « governor » à dessein). En append-only : une configuration qui ne marche plus est gardée en historique, jamais écrasée. Le lancement suivant démarre directement sur la configuration connue-bonne ; un changement de driver ou de GPU invalide l'entrée et déclenche un nouveau plan.

Pourquoi c'est important : une tentative ratée coûte un chargement complet du modèle — mesuré à ~220 s par tentative pour un modèle MoE de 9,5 Go chargé avec --no-mmap sur le disque de la machine du gate. Le cache existe pour ne jamais payer ça deux fois.

Contrôles de transparence :

vrampilot configs list              # inspecter tout ce qu'il retient
vrampilot modele.gguf --no-cache    # ignorer le cache, forcer un nouveau plan

Rien ne quitte votre machine.

Comportement du watchdog

Pendant que le serveur tourne, le watchdog couvre l'épuisement de la VRAM pendant une génération — par exemple, vous ouvrez une autre application GPU en plein stream.

Limite connue : llama.cpp ne sait pas réduire à chaud le KV-cache d'un serveur en marche ; la seule action runtime est donc ce redémarrage contrôlé. Si l'amont livre le redimensionnement à chaud du KV, VRAMPilot l'adoptera et retirera le redémarrage pour ce chemin.

Prérequis

Python 3.9+ est l'unique prérequis déclaré de l'installation pip/pipx — tout le reste (y compris le binaire du moteur d'inférence) est téléchargé et vérifié au premier lancement.