La prise en charge de GGUF par vLLM existe, mais la configuration appropriée dépend de votre version de vLLM, du point de contrôle GGUF et de son tokenizer. La documentation stable actuelle oriente les utilisateurs vers le vllm-gguf-plugin distinct ; les anciens tutoriels décrivent un chargeur intégré. Commencez par identifier votre pile installée, puis validez un petit modèle avant de passer à une charge de travail de production.
Ce guide se concentre sur le chargement et le service corrects d’un point de contrôle GGUF. Pour choisir entre GGUF, AWQ, GPTQ et FP8, consultez notre guide plus complet sur la quantification de vLLM.
Ce que signifie aujourd’hui la prise en charge de GGUF par vLLM
GGUF est un format de fichier de modèle. Un nom de fichier se terminant par .gguf ne prouve pas qu’un environnement d’exécution prend en charge toutes les architectures, tous les types de quantification ou tous les composants auxiliaires qu’il contient. Considérez la compatibilité comme une combinaison de runtime + plugin + architecture du modèle + quantification + tokenizer + matériel.
La documentation vLLM GGUF actuelle décrit une approche expérimentale avec des limitations de performances et de fonctionnalités. Elle documente un sélecteur Hugging Face repo_id:quant_type ainsi que les fichiers locaux, et recommande d’utiliser le tokenizer du modèle d’origine. Cela diffère des instructions de la v0.8.4, qui décrivent l’ancien flux de travail basé sur des fichiers locaux. Faites correspondre la documentation à la version que vous exécutez réellement.
| Ce que vous avez trouvé | Élément à vérifier ensuite |
|---|---|
| Une installation stable récente | Si le plugin GGUF est installé dans le même environnement Python que vLLM |
| Un ancien conteneur ou une version épinglée | Sa documentation versionnée ; évitez de mélanger un ancien chargeur avec des options actuelles |
| Un GGUF qui fonctionne dans un autre runtime | L’architecture, le mappage des tenseurs, le tokenizer et les fonctionnalités requises dans votre pile vLLM |
Un exemple utilisant --omni |
Si vous utilisez vLLM-Omni plutôt que le chemin de service de texte présenté dans ce guide |
Le guide GGUF de vLLM-Omni couvre des configurations multimodales distinctes et des adaptateurs spécifiques aux modèles. Ses exemples de diffusion ne constituent pas une commande directement utilisable pour un serveur vLLM uniquement textuel.
1. Consignez l’environnement avant d’installer quoi que ce soit
Utilisez un environnement de test propre sur la machine GPU prévue. Vérifiez d’abord que l’installation de base de vLLM correspond à cette machine à l’aide des instructions officielles d’installation GPU. La réussite de l’installation d’un package Python ne suffit pas à établir la compatibilité avec le pilote ou le périphérique.
Consignez les versions des packages sans importer de modèle :
from importlib.metadata import version, PackageNotFoundError
for package in ("vllm", "vllm-gguf-plugin", "torch", "transformers"):
try:
print(package, version(package))
except PackageNotFoundError:
print(package, "not installed")
Sur un hôte NVIDIA, consignez également nvidia-smi, le modèle de GPU, la mémoire disponible et le tag de l’image de conteneur ou le fichier de verrouillage de l’environnement. Conservez ces informations avec la révision du dépôt du modèle et le nom de la quantification. Si une future mise à niveau échoue, ces détails permettront de comparer deux environnements connus au lieu de deviner quelle dépendance a changé.
2. Installez le plugin GGUF dans l’environnement de service
Une fois un environnement vLLM compatible préparé, la documentation stable actuelle donne cette commande d’installation du package :
uv pip install vllm-gguf-plugin
Vérifiez que uv opère sur l’environnement contenant l’exécutable vllm. Installer un plugin dans un environnement virtuel et lancer un serveur depuis un autre ne rendra pas le plugin disponible pour ce serveur.
Pour une compilation depuis les sources, suivez les instructions d’installation du dépôt du plugin. Elles nécessitent une boîte à outils CUDA ou ROCm et compilent avec l’installation PyTorch utilisée par vLLM ; pour cette raison, leur installation modifiable documentée désactive l’isolation de compilation. Utilisez les instructions du dépôt correspondant à la révision choisie plutôt que d’ajouter des options de compilateur sans rapport jusqu’à ce qu’une compilation réussisse.
Le dépôt du plugin répertorie également les familles de modèles et les quantifications testées en génération. Utilisez ces tests comme point de départ pour un premier canari. Ils ne prouvent pas que chaque conversion GGUF de chaque modèle fonctionne.
3. Chargez un petit point de contrôle avec un tokenizer explicite
La commande suivante utilise le petit exemple Qwen documenté par le projet du plugin, ajoute un écouteur local uniquement et attribue à l’API un nom de modèle prévisible :
vllm serve Qwen/Qwen3-0.6B-GGUF:Q8_0 \
--tokenizer Qwen/Qwen3-0.6B \
--served-model-name gguf-canary \
--host 127.0.0.1 \
--port 8000
Il s’agit d’un test rapide de compatibilité, et non d’une évaluation des performances. Il télécharge les ressources du modèle et nécessite un runtime et un périphérique pris en charge. N’interprétez pas le choix du petit point de contrôle comme un modèle recommandé pour votre application.
Pour un fichier local, remplacez le sélecteur de modèle par votre chemin GGUF réel et conservez le tokenizer correspondant au modèle de base. Vérifiez que le fichier est complet et que toute gestion de fichiers fractionnés est prise en charge par votre version installée avant de le servir. Renommer un checkpoint arbitraire ne convertit pas son format.
Si les métadonnées de configuration ne peuvent pas être résolues, la documentation actuelle propose --hf-config-path comme entrée de configuration explicite. Utilisez une configuration qui appartient réellement à l'architecture de base du checkpoint. Une configuration pratique mais sans rapport peut transformer un échec de chargement clair en erreurs de tenseurs ou de sortie plus difficiles à diagnostiquer.
4. Séparez les vérifications de chargement, d'API et de sortie
Une fois que le serveur indique qu'il est prêt, interrogez sa liste de modèles depuis un second terminal :
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
Envoyez ensuite une petite complétion au nom servi explicitement :
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"gguf-canary","prompt":"The capital of France is","max_tokens":16,"temperature":0}'
La documentation du serveur compatible OpenAI décrit les endpoints pris en charge et le comportement des requêtes. Une complétion simple permet de garder la première vérification indépendante de la configuration du modèle de chat. Une fois celle-ci réussie, testez individuellement votre véritable modèle de chat, vos exigences de sortie structurée, le streaming et les autres fonctionnalités de l'application.
Conservez trois résultats distincts dans votre dossier de déploiement :
- Chargement : les poids et le tokenizer s'initialisent sans erreurs de couche non prise en charge ni de tenseur.
- Service : l'endpoint requis renvoie une réponse valide pour le nom de modèle servi.
- Utilisation : les sorties satisfont un petit ensemble de critères de correction propres à l'application.
Une réponse HTTP 200 ne valide que la partie API. Un texte vide, des jetons répétés, un formatage incorrect ou des réponses erronées aux tâches nécessitent encore une investigation. Gardez le serveur initial lié à localhost ; ajoutez vos contrôles habituels d'authentification et de réseau avant de l'exposer à d'autres clients.
Résolution des problèmes selon la première étape en échec
| Symptôme | À vérifier en premier | Prochaine modification contrôlée |
|---|---|---|
| Le plugin ou la méthode de quantification n'est pas reconnu | Environnement Python actif et versions des paquets installés | Reproduire dans un environnement compatible propre |
| L'importation échoue avec une erreur binaire ou de symbole | Alignement de la compilation de PyTorch, CUDA/ROCm et du plugin | Reconstruire en suivant la procédure documentée du plugin |
| Le sélecteur de modèle ou de quantification est introuvable | Orthographe du dépôt, quantification sélectionnée, autorisations, intégralité du téléchargement | Essayer le petit checkpoint documenté du projet |
| Les noms ou les formes des tenseurs ne correspondent pas | Architecture du modèle, provenance de la conversion, configuration | Utiliser une conversion prise en charge du même modèle de base |
| Le chargement se bloque autour du tokenizer | Identité et révision du tokenizer | Fournir explicitement le tokenizer correspondant au modèle de base |
| La complétion fonctionne mais le chat échoue | Modèle de chat et format de requête de l'application | Tester une requête de chat minimale avant d'ajouter des fonctionnalités supplémentaires |
| Le modèle se charge mais manque de mémoire sous trafic | Longueurs de contexte, requêtes actives, mémoire d'exécution, cache KV | Réduire une dimension de la charge de travail et répéter le même test |
Enregistrez la première erreur significative et la commande exacte. Modifier simultanément le modèle, le tokenizer, le pilote et la concurrence peut supprimer une erreur tout en masquant sa cause.
Décidez de conserver ou non GGUF après les vérifications de compatibilité
Un fichier plus petit est utile lorsque le stockage des poids ou la mémoire constitue votre contrainte. Cela ne démontre pas un avantage en matière de latence. Comparez le même modèle de base et le même ensemble de tâches à un checkpoint alternatif pris en charge avant de choisir un format de service.
Utilisez les longueurs d'entrée, les longueurs de sortie et les niveaux de requêtes simultanées attendus. Enregistrez la réussite des tâches, le délai jusqu'au premier jeton, la latence de queue, le débit et le pic de mémoire. L'CLI de benchmark de service officielle peut générer un trafic contrôlé ; ses options et ses jeux de données doivent correspondre à votre version installée. Un test de stress synthétique et un test d'acceptation d'application répondent à des questions différentes ; conservez donc les deux résultats séparément.
Si les fonctionnalités ou les sorties requises de GGUF échouent, demandez-vous d'abord si vous avez besoin de ce checkpoint exact. Lorsqu'un autre format satisfait la charge de travail avec moins d'incertitude opérationnelle, une conversion ou une autre distribution prise en charge peut être le choix le plus simple. Conservez notre comparaison des formats comme aide plus générale à la décision au lieu de répéter ici une étude complète de la quantification.
Planifiez la capacité GPU cloud à partir de la charge de travail validée
Une fois que le modèle a passé les vérifications ci-dessus, dimensionnez un environnement GPU en fonction des besoins de mémoire et de concurrence testés. Cloud GPU Compute de Flatkey propose des options de location de GPU NVIDIA. Vérifiez la configuration disponible, la région, la capacité, les détails d'accès et les conditions de location pour le test envisagé. Ce guide ne prétend pas que l'exemple a été évalué sur une location Flatkey ni qu'une carte particulière est toujours disponible.
Préparez une courte note de transmission : révision du modèle, quantification, versions logicielles, besoins estimés en espace disque, limite de contexte, concurrence cible et seuils d’acceptation. Cela concrétise la discussion sur l’infrastructure et évite de confondre un problème de compatibilité logicielle avec la nécessité de louer un GPU plus puissant.
Questions fréquemment posées
vLLM prend-il en charge tous les modèles GGUF ?
Non. Validez conjointement l’architecture, la quantification, le tokenizer, le matériel et les fonctionnalités. La prise en charge d’un format de fichier ne signifie pas une prise en charge universelle de tous les modèles stockés dans ce format.
Pourquoi les anciens guides indiquent-ils de fournir un fichier local ?
Ils peuvent décrire une version antérieure. La documentation versionnée de vLLM et les recommandations actuelles relatives aux plugins peuvent présenter des chemins de chargement différents. Utilisez les instructions correspondant à votre pile installée.
Puis-je réutiliser le tokenizer d’un autre modèle ?
Utilisez le tokenizer appartenant au modèle de base du checkpoint, sauf si son éditeur documente explicitement un autre choix compatible. Un serveur qui démarre avec un tokenizer sans rapport peut tout de même produire des résultats incorrects.
Un chargement réussi suffit-il pour la production ?
Non. Effectuez des vérifications complètes des points de terminaison, de la qualité des tâches, des fonctionnalités et de la charge réaliste. La réponse pratique à la prise en charge de GGUF par vLLM est une configuration reproductible qui réussit les validations, et non une simple installation réussie du package.
