Importer un modèle GGUF de Hugging Face dans Ollama

#Pourquoi importer un GGUF de Hugging Face

Ollama maintient une bibliothèque de modèles pratiques (ollama.com/library), mais elle est volontairement restreinte : les mainteneurs y publient les modèles les plus demandés, dans des quantifications choisies pour eux. Dès que vous cherchez un fine-tune spécialisé, une version tout juste sortie, un modèle en français ou une quantification précise, il faut aller la chercher sur Hugging Face — la plus grande plateforme de partage de modèles open-weight.

Le format GGUF (successeur de GGML) est celui qu'Ollama comprend nativement : un fichier unique qui contient les poids quantifiés, le tokenizer et les métadonnées du modèle. Des contributeurs comme TheBloke, bartowski ou unsloth publient des milliers de GGUF prêts à l'emploi, souvent dans une dizaine de quantifications par modèle. Savoir les importer débloque tout cet écosystème dans votre installation Ollama.

Modèles récents

Un modèle publié hier sur Hugging Face est utilisable avant même d'apparaître dans la bibliothèque officielle d'Ollama.

Fine-tunes de niche

Modèles spécialisés (code, médecine, jeu de rôle, français) que personne n'a pris la peine de packager officiellement.

Quantification précise

Choisir exactement le niveau (Q4_K_M, Q5_K_M, Q8_0…) qui rentre dans votre VRAM, plutôt que la seule variante par défaut.

Modèles privés

Vos propres fine-tunes ou GGUF téléchargés, importés localement via un Modelfile.

#Prérequis

Ollama installé

Version récente (0.5+) pour le support natif de hf.co. Le daemon écoute par défaut sur http://localhost:11434. Vérifiez avec « ollama --version ».

Une connexion internet

Pour la méthode directe qui télécharge depuis Hugging Face. Ensuite le modèle tourne 100 % en local.

Assez de VRAM ou de RAM

Repère en Q4 : un 7B tient dans ~5 Go, un 14B dans ~9 Go, un 32B dans ~19 Go, un 70B dans ~40 Go. Sans GPU, c'est la RAM qui compte, en plus lent.

Le nom d'un dépôt GGUF

Par exemple bartowski/Qwen2.5-7B-Instruct-GGUF. Repérez-le dans l'URL de la page Hugging Face du modèle.

Pour trouver un dépôt GGUF, la recherche Hugging Face accepte un filtre par format. Cherchez le nom du modèle et ajoutez « GGUF », ou filtrez sur la bibliothèque « GGUF » dans la barre latérale. Ouvrez l'onglet « Files and versions » : vous y verrez la liste des fichiers .gguf, un par quantification, avec leur taille en Go — une information précieuse pour la suite.

#Méthode directe : ollama run hf.co/...

C'est de loin la façon la plus simple d'importer un modèle GGUF de Hugging Face dans Ollama. Depuis la version 0.5, Ollama sait tirer un GGUF directement depuis un dépôt Hugging Face en une seule commande, sans télécharger le fichier à la main ni écrire de Modelfile. La syntaxe reprend le chemin du dépôt préfixé par hf.co/.

# Format : ollama run hf.co/{utilisateur}/{depot}
ollama run hf.co/bartowski/Qwen2.5-7B-Instruct-GGUF

Sans précision, Ollama choisit une quantification par défaut (généralement Q4_K_M si elle existe dans le dépôt). Pour cibler une quantification précise, ajoutez-la après deux-points, exactement comme un tag de modèle classique. Le nom du tag correspond au suffixe du fichier .gguf, insensible à la casse.

# Choisir explicitement Q5_K_M
ollama run hf.co/bartowski/Qwen2.5-7B-Instruct-GGUF:Q5_K_M

# Ou une version plus légère pour une petite carte
ollama run hf.co/bartowski/Qwen2.5-7B-Instruct-GGUF:Q4_K_M

Ollama télécharge le fichier, l'enregistre dans son stockage local et démarre la conversation. Le modèle apparaît ensuite dans « ollama list » sous son nom complet hf.co/... et se relance instantanément. Vous pouvez lui donner un alias plus court avec « ollama cp » si le nom vous semble trop long à taper.

# Copier vers un alias court
ollama cp hf.co/bartowski/Qwen2.5-7B-Instruct-GGUF:Q4_K_M qwen-fr

# Désormais utilisable simplement
ollama run qwen-fr

#Choisir la bonne quantification selon sa VRAM

Un même modèle est publié en plusieurs quantifications : c'est le compromis central entre qualité et mémoire. Plus la quantification est agressive (moins de bits par poids), plus le fichier est petit et plus il tient sur une carte modeste — au prix d'une légère perte de précision. Le bon réflexe est de choisir la quantification la plus haute qui rentre confortablement dans votre VRAM.

Q4_K_M — recommandé

Le meilleur compromis pour la grande majorité des usages. Perte de qualité quasi imperceptible, empreinte mémoire réduite. À choisir par défaut si vous hésitez.

Q5_K_M — un cran au-dessus

Légèrement plus lourd, légèrement plus précis. Intéressant si votre VRAM a de la marge et que vous voulez le maximum de qualité sans passer au 8 bits.

Q8_0 — quasi sans perte

Très proche du modèle non quantifié, mais environ deux fois plus lourd que le Q4. Réservé aux cas où la moindre dégradation compte et où la VRAM ne manque pas.

FP16 — pleine précision

Le modèle non quantifié, le plus lourd. Rarement nécessaire pour de l'inférence locale : Q8_0 suffit presque toujours et divise la mémoire par deux.

Pour estimer si une quantification rentre, fiez-vous à la taille du fichier .gguf affichée sur Hugging Face, plus une marge d'environ 1 à 2 Go pour le contexte et le système. Voici les repères VRAM en Q4_K_M par taille de modèle, et les GPU typiques qui les font tourner.

3B ≈ 2 Go

Tourne partout, même sur une carte d'entrée ou en CPU. Idéal RTX 3060 12 Go avec du contexte à revendre.

7B ≈ 5 Go

Confortable sur RTX 3060 12 Go, RTX 4070 12 Go. Le format le plus polyvalent pour un usage quotidien.

14B ≈ 9 Go

RTX 4070 12 Go (juste), RTX 4080 16 Go à l'aise. Bon palier qualité pour le raisonnement et le code.

32B ≈ 19 Go

RTX 4090 24 Go, ou Mac M4 Pro à mémoire unifiée. Le haut de gamme accessible en poste de travail.

70B ≈ 40 Go

Nécessite 48 Go+ : Mac Studio à grosse mémoire unifiée ou multi-GPU. Passez en Q4 voire plus agressif.

#Méthode Modelfile : FROM fichier.gguf

La méthode directe suppose que le GGUF est sur Hugging Face et accessible en ligne. Mais si vous avez déjà téléchargé un fichier .gguf à la main, produit le vôtre avec llama.cpp, ou que vous voulez personnaliser le modèle (system prompt, paramètres), il faut passer par un Modelfile. C'est un petit fichier texte, à la manière d'un Dockerfile, qui décrit comment construire un modèle Ollama à partir d'un GGUF local.

La directive centrale est FROM, qui pointe vers le chemin du fichier .gguf. Créez un fichier nommé « Modelfile » (sans extension) à côté de votre GGUF, avec au minimum cette ligne.

FROM ./mon-modele.Q4_K_M.gguf

Puis construisez le modèle avec « ollama create », en lui donnant le nom de votre choix. Ollama lit le GGUF, l'enregistre dans son stockage et le rend disponible comme n'importe quel autre modèle.

# Construire le modèle depuis le Modelfile du dossier courant
ollama create mon-modele -f ./Modelfile

# Le lancer
ollama run mon-modele

Un Modelfile complet peut aller bien plus loin : fixer un system prompt, régler les paramètres d'échantillonnage, et surtout définir le TEMPLATE — le format de chat attendu par le modèle. C'est là que se règlent la plupart des problèmes de qualité, comme on le voit dans la section suivante.

FROM ./mon-modele.Q4_K_M.gguf

# System prompt par défaut
SYSTEM """Tu es un assistant francophone concis et précis."""

# Paramètres d'inférence
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER stop "<|im_end|>"

# Template de chat (exemple format ChatML)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

#Corriger un chat template cassé

C'est le piège numéro un de l'import de GGUF. Un modèle importé peut répondre n'importe comment : phrases qui ne s'arrêtent jamais, balises bizarres dans la sortie (<|im_end|>, [INST], <end_of_turn>), réponses qui ignorent la question ou partent en boucle. Neuf fois sur dix, ce n'est pas le modèle qui est mauvais — c'est le chat template qui ne correspond pas à celui utilisé pendant son entraînement.

Chaque famille de modèles attend un format de conversation précis : ChatML (<|im_start|>) pour Qwen et beaucoup de fine-tunes, [INST]...[/INST] pour Mistral et Llama 2, <start_of_turn> pour Gemma, un format spécifique pour Llama 3. Si le GGUF embarque le mauvais template dans ses métadonnées, ou si Ollama en devine un incorrect, les réponses se dégradent. Le symptôme le plus courant : des balises de fin de tour qui apparaissent en clair dans la réponse au lieu d'arrêter la génération.

Symptôme : balises visibles

Le modèle affiche <|im_end|> ou <|eot_id|> dans sa réponse. Il manque un PARAMETER stop correspondant, ou le template n'émet pas le bon token de fin.

Symptôme : génération infinie

Le modèle ne s'arrête jamais et enchaîne les tours tout seul. Le token d'arrêt attendu n'est pas déclaré.

Symptôme : réponses incohérentes

Le modèle ignore le system prompt ou répond à côté. Le format des rôles (system/user/assistant) ne correspond pas à celui de l'entraînement.

La correction consiste à fournir le bon TEMPLATE et les bons PARAMETER stop dans un Modelfile. La source de vérité est la « model card » Hugging Face du modèle original : cherchez la section « prompt format » ou « chat template », qui indique le format exact. Pour un modèle ChatML (Qwen et dérivés), le template et les stops ressemblent à ceci.

FROM ./mon-modele.Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"

Reconstruisez ensuite avec « ollama create » et testez. Une astuce efficace pour récupérer le bon template sans le réécrire : partez d'un modèle officiel de la même famille déjà présent dans Ollama et inspectez son Modelfile généré, puis reprenez son bloc TEMPLATE.

# Voir le Modelfile complet d'un modèle officiel de la même famille
ollama show --modelfile qwen2.5:7b

# Copiez-en le bloc TEMPLATE et les PARAMETER stop
# dans votre propre Modelfile, puis reconstruisez
ollama create mon-modele -f ./Modelfile

#Dépannage

« Error: pull model manifest »

Le chemin hf.co est mal orthographié, le dépôt est privé/gated, ou votre version d'Ollama est trop ancienne. Vérifiez l'URL exacte du dépôt et mettez Ollama à jour.

Le tag de quantification n'existe pas

Ollama répond que le tag est introuvable : ouvrez « Files and versions » sur Hugging Face et copiez le suffixe exact du fichier .gguf (ex. Q4_K_M, IQ4_XS). La casse est ignorée mais le nom doit correspondre.

Modèle très lent / réponses saccadées

Le modèle déborde sur la RAM/CPU faute de VRAM. Vérifiez avec « ollama ps » s'il tourne sur GPU ou CPU, et descendez d'une quantification ou d'une taille de modèle.

Le dépôt ne contient que des safetensors

Pas de .gguf disponible : cherchez une version « GGUF » convertie par la communauté, ou convertissez vous-même le modèle avec les scripts de llama.cpp.

Sorties polluées par des balises

Chat template incorrect : voyez la section précédente, fournissez le bon TEMPLATE et les PARAMETER stop via un Modelfile.

#Pour aller plus loin

Importer un GGUF s'appuie sur deux compétences de base de l'écosystème Ollama. Ces guides du site prolongent celui-ci :

Choisir sa quantification (Q4, Q5, Q8, FP16)

Comprendre en détail le compromis qualité/mémoire pour choisir la bonne variante GGUF selon votre carte.

Personnaliser un modèle avec Ollama Modelfile

Aller plus loin avec le Modelfile : system prompts, paramètres, templates et variantes multiples d'un même modèle.

Installer Ollama : Windows, macOS et Linux

Le guide d'installation de base, à jour, si vous partez de zéro avant d'importer vos premiers GGUF.