Importer un modèle GGUF dans Ollama

Deux façons d’importer un modèle GGUF dans Ollama

Il existe deux façons d’importer un modèle GGUF dans Ollama. La bonne méthode dépend de l’emplacement actuel du fichier. Si le modèle se trouve dans un dépôt Hugging Face, une seule commande ollama run le télécharge et l’exécute, sans utiliser de Modelfile. Si le fichier .gguf se trouve déjà sur le disque du serveur, créez un Modelfile de deux lignes, puis exécutez ollama create.

Les deux méthodes aboutissent au même résultat : un modèle nommé dans votre bibliothèque Ollama locale, que ollama run et l’API Ollama peuvent servir. Utilisez la première méthode lorsque le fichier a été publié par un tiers. Utilisez la seconde si vous avez quantifié vous-même le modèle, si le fichier est arrivé via scp ou rsync, ou si la machine ne peut pas accéder à Hugging Face.

Un fichier GGUF est un fichier binaire unique qui contient les poids, le tokenizer et les métadonnées du modèle. C’est le format lu par llama.cpp. Ollama repose sur llama.cpp, ce qui explique pourquoi presque tous les modèles open source disposent d’une conversion GGUF réalisée par la communauté. Ollama ne charge pas directement un dossier de poids .safetensors. L’étape de conversion est donc nécessaire.

Tout ce qui suit suppose qu’Ollama est déjà installé et que son service est en cours d’exécution. Si ce n’est pas le cas, commencez par installer Ollama sur un VPS, puis revenez ici. Exécutez d’abord ollama list. Si la commande renvoie un tableau, même vide, au lieu d’une erreur de connexion, le serveur fonctionne et la suite de ce guide devrait fonctionner.

Route 1 : exécuter un fichier GGUF depuis Hugging Face sans Modelfile

Ollama peut récupérer directement un fichier GGUF depuis un dépôt Hugging Face. La commande utilise le chemin du dépôt précédé du préfixe hf.co/ :

ollama run hf.co/{username}/{repository}

hf.co et huggingface.co fonctionnent tous deux comme nom de domaine. Voici un exemple réel tiré de la documentation Hugging Face :

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

La première exécution télécharge le fichier. L’invite de chat n’apparaît donc qu’une fois le téléchargement terminé. Ensuite, le modèle est enregistré dans votre bibliothèque locale et démarre rapidement. Ouvrez un second shell et exécutez ollama list pour voir le nom sous lequel il a été enregistré. Ce nom correspond à la chaîne hf.co/... complète avec son tag, ce qui est long à saisir à chaque fois. Donnez-lui un alias court :

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

Cette méthode fonctionne uniquement avec les dépôts qui contiennent réellement des fichiers GGUF. Un dépôt qui publie uniquement des poids .safetensors ne fournit rien qu’Ollama puisse récupérer. Vous devez alors effectuer l’étape de conversion décrite plus loin.

Quelle quantification Ollama sélectionne-t-il ?

La documentation Ollama de Hugging Face, consultée le 25 août 2026, est explicite au sujet de la valeur par défaut : « Par défaut, le schéma de quantification Q4_K_M est utilisé lorsqu’il est présent dans le dépôt du modèle. Sinon, nous sélectionnons par défaut un type de quantification raisonnable présent dans le dépôt. » Un dépôt qui publie dix quants vous fournit donc Q4_K_M. Si le dépôt ne contient pas Q4_K_M, Ollama sélectionne un autre type à votre place. Relisez cette page avant de vous y fier, car les valeurs par défaut peuvent changer.

Pour demander un quant précis, ajoutez-le comme tag :

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

Le nom de la quantification ne tient pas compte de la casse. :iq3_m et :IQ3_M désignent donc la même chose. Vous pouvez également utiliser le nom de fichier exact comme tag. C’est la forme la plus sûre lorsque les noms courts d’un dépôt sont ambigus. Le tag doit désigner un fichier qui existe dans ce dépôt. Ouvrez donc l’onglet Files and versions et relevez les vrais noms de fichier avant d’en saisir un. Le choix du quant dépend de la mémoire disponible et de la qualité souhaitée. La différence entre Q4, Q8 et FP16 explique précisément cet arbitrage.

Deuxième méthode : importer un fichier .gguf depuis votre propre disque

Lorsque le fichier se trouve déjà sur le serveur, vous avez besoin d’un Modelfile. Il peut tenir sur une seule ligne. Créez un répertoire, placez-y le Modelfile, puis indiquez ce fichier à FROM :

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

Enregistrez ce contenu sous Modelfile, puis construisez le modèle :

ollama create my-model

Par défaut, ollama create lit un fichier nommé Modelfile dans le répertoire courant. Utilisez -f si votre fichier porte un autre nom ou se trouve ailleurs, comme dans ollama create my-model -f /home/you/models/my-model/Modelfile. Exécutez ollama create --help pour afficher ce flag et sa valeur par défaut dans votre build. Le chemin indiqué dans FROM peut être absolu ou relatif au Modelfile. Ainsi, FROM ./my-model-Q4_K_M.gguf fonctionne lorsque les deux fichiers se trouvent dans le même répertoire. Un chemin absolu élimine toute ambiguïté.

Vérifiez le résultat avant de lui faire confiance :

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list doit maintenant inclure my-model. ollama show my-model affiche l’architecture, le nombre de paramètres, la longueur du contexte et la quantification qu’Ollama a lus dans les métadonnées du fichier. Lisez ces valeurs au lieu de vous fier au nom du fichier, car ce nom est une simple chaîne saisie manuellement. Si le modèle répond à votre prompt de test en langage normal, puis s’arrête, l’import a fonctionné. Dans le cas contraire, consultez la section consacrée au template ci-dessous, car c’est presque toujours la cause du problème.

Concernant l’espace disque, sachez que ollama create copie le fichier GGUF dans son propre stockage de modèles au lieu de référencer l’emplacement du fichier. Les poids occupent donc deux fois l’espace disque jusqu’à la suppression de l’original. Supprimez le fichier source lorsque ollama run my-model fonctionne, ou conservez-le à un emplacement où cette duplication ne vous coûte pas d’espace. emplacement des modèles Ollama sur le disque décrit l’organisation du stockage et la procédure pour le déplacer.

Quand --quantize s’applique et quand ce n’est pas le cas

ollama create possède un flag --quantize. Celui-ci ne sert que dans un cas : un modèle source en FP16 ou FP32, c’est-à-dire avec des poids en précision complète. La documentation d’importation d’Ollama indique q8_0 ainsi que les variantes k-means q4_K_S et q4_K_M comme cibles.

ollama create --quantize q4_K_M my-model

N’utilisez pas ce flag avec un fichier déjà quantifié. Un .gguf dont le nom contient Q4_K_M ou Q5_K_S a déjà subi cette étape, et le flag n’a donc rien à faire. La quantification est une conversion à sens unique vers une précision inférieure. Il n’est donc pas possible de passer de Q4 à Q8. Si votre source est un dépôt Hugging Face contenant des fichiers .safetensors, convertissez-les d’abord avec convert_hf_to_gguf.py du dépôt llama.cpp. C’est l’outil indiqué par la documentation Ollama. Importez ensuite le fichier GGUF produit par ce script. Relation entre Ollama et llama.cpp explique pourquoi le script de conversion appartient à l’autre projet.

Pourquoi un GGUF importé renvoie-t-il du texte incohérent ou ne s’arrête-t-il jamais ?

C’est le problème que la plupart des tutoriels d’importation ignorent, et c’est celui que vous rencontrerez. Les symptômes donnent l’impression que le modèle est défectueux. Des tokens de contrôle apparaissent sous forme de texte visible dans la réponse, par exemple des chaînes comme <|im_start|>assistant ou <|end|>. Le modèle répond, puis écrit une nouvelle question utilisateur et y répond également. La génération continue jusqu’à ce que vous appuyiez sur Ctrl+C.

Le modèle fonctionne correctement. Le chat template est incorrect. Un chat template est l’enveloppe qui transforme votre message en la séquence exacte de tokens sur laquelle le modèle a été entraîné, avec ses propres marqueurs indiquant la fin du prompt système et le début du tour utilisateur. Ollama en sélectionne un pour vous : la documentation indique qu’un template « sera sélectionné automatiquement dans une liste de templates couramment utilisés », selon les métadonnées tokenizer.chat_template intégrées au fichier GGUF. Lorsque ces métadonnées sont absentes ou ne correspondent à aucun template de la liste, Ollama utilise une enveloppe générique. Le modèle reçoit alors un prompt qui ne ressemble à rien de ce qu’il a vu pendant son entraînement. Il ne rencontre donc jamais le marqueur de fin de tour sur lequel il a appris à s’arrêter.

Affichez le template réellement sélectionné par Ollama :

ollama show --template my-model
ollama show --modelfile my-model

Un template vide ou manifestement générique le confirme. Écrivez vous-même le template dans le Modelfile :

FROM /home/you/models/my-model-Q4_K_M.gguf

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

PARAMETER stop "<|end|>"

Reconstruisez le modèle avec ollama create my-model, puis envoyez à nouveau le même prompt de test. Le paramètre stop constitue votre filet de sécurité : il indique à Ollama d’arrêter la génération lorsqu’une chaîne donnée apparaît. Le symptôme de génération interminable disparaît ainsi, même pendant que vous ajustez encore l’enveloppe. Si la réponse continue parce qu’aucun des marqueurs indiqués n’apparaît, une limite num_predict l’arrête après un nombre fixe de tokens, quel que soit le contenu produit par le template.

Le template doit être un template Go, pas un template Jinja. La documentation Hugging Face l’indique explicitement. C’est important, car le champ tokenizer.chat_template du dépôt d’origine du modèle contient du Jinja. Un simple copier-coller ne fonctionne pas. La syntaxe d’Ollama utilise trois variables : {{ .System }} pour le prompt système, {{ .Prompt }} pour le message utilisateur et {{ .Response }} pour la réponse du modèle. Recherchez les vrais marqueurs de tour du modèle dans sa model card ou dans son tokenizer_config.json, puis réécrivez-les manuellement avec cette syntaxe Go.

Un raccourci permet d’éviter la majeure partie de ce travail. De nombreux modèles utilisent le même format de prompt. Si un autre modèle de votre bibliothèque utilise ce format, exécutez ollama show --template avec celui-ci et copiez le résultat.

Les fichiers template, system et params dans un dépôt Hugging Face

La méthode Hugging Face offre les mêmes réglages via des fichiers du dépôt plutôt que via des instructions dans un Modelfile. Si vous possédez le dépôt ou publiez votre propre quantification, ajoutez-y ces fichiers : chaque ollama run hf.co/... les utilise.

• Un fichier nommé template contient le template Go. Même règle : Go, pas Jinja.
• Un fichier nommé system contient le prompt système.
• Un fichier nommé params contient les paramètres d’échantillonnage, au format JSON.

Un fichier params minimal :

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

Lorsque vous ne possédez pas le dépôt, vous ne pouvez pas ajouter ces fichiers. Téléchargez le modèle une fois, exécutez ollama show --modelfile hf.co/... pour exporter ce qui vous a été fourni, puis enregistrez cette sortie comme Modelfile. Sa ligne FROM pointe vers le blob qu’Ollama a déjà téléchargé. Vous pouvez donc modifier les lignes TEMPLATE et PARAMETER, puis exécuter ollama create pour créer une copie locale corrigée sans rien télécharger à nouveau. C’est la méthode standard pour corriger la quantification défectueuse d’un tiers.

Comment importer un dépôt GGUF privé

Un dépôt privé nécessite la clé SSH d’Ollama sur votre compte Hugging Face. La méthode documentée pour cette procédure utilise une clé SSH et non un jeton d’API. Un jeton que vous possédez déjà ne permettra donc pas d’y accéder.

Affichez la clé publique. Sur un serveur Linux où Ollama a été installé avec le script officiel, le service s’exécute avec l’utilisateur ollama. La clé se trouve donc dans le répertoire personnel de cet utilisateur :

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

Si vous démarrez ollama serve vous-même avec votre propre utilisateur, le chemin est ~/.ollama/id_ed25519.pub à la place. Copiez la ligne complète, ouvrez les paramètres de votre compte Hugging Face à l’adresse https://huggingface.co/settings/keys, puis ajoutez-la comme nouvelle clé SSH. La commande habituelle fonctionne ensuite avec vos dépôts privés :

ollama run hf.co/{username}/{repository}

Si le pull échoue encore après l’ajout de la clé, vous avez probablement affiché le mauvais fichier. C’est le serveur qui effectue le téléchargement et présente sa propre clé. Un serveur démarré par systemd ne lit jamais le fichier ~/.ollama de votre utilisateur. La clé située dans votre répertoire personnel n’est donc pas celle que Hugging Face voit.

Le modèle tiendra-t-il sur votre VPS ?

Le nombre déterminant est la taille du fichier sur le disque, plus la mémoire nécessaire à votre fenêtre de contexte. Les poids sont chargés en mémoire et occupent presque autant d’espace que dans le fichier. L’allocation du contexte s’ajoute à cette taille et augmente avec le nombre de tokens autorisés. Exécutez ollama list pour lire la taille enregistrée par Ollama pour le modèle. Comparez-la à free -h sur le serveur. Gardez une marge pour le système d’exploitation et les autres services exécutés par le serveur. Si vous préférez consulter ces calculs déjà effectués sur un modèle réel, exécuter Nemotron 3.5 Lightning sur un VPS indique le tag exact à télécharger, la RAM nécessaire et les performances d’un serveur utilisant uniquement le CPU.

Le contexte est souvent oublié. Un modèle qui se charge avec la fenêtre par défaut peut échouer après l’augmentation de num_ctx, car l’allocation évolue avec la taille de fenêtre demandée. Définir num_ctx et comprendre son coût en mémoire présente le dimensionnement. Lorsque la taille totale est trop importante, la solution consiste généralement à utiliser une quantification plus petite du même modèle. C’est le compromis présenté dans la comparaison entre Q4 et Q8.

La panne est explicite. Sur un VPS utilisant uniquement le CPU, l’out-of-memory killer du kernel arrête le processus. journalctl -u ollama -n 50 et dmesg indiquent le processus arrêté. Sur un serveur équipé d’un GPU, ollama ps affiche une colonne PROCESSOR. Elle indique si le modèle chargé se trouve dans la mémoire du GPU, dans la mémoire système ou réparti entre les deux. Un modèle qui déborde dans la mémoire système continue de répondre, mais lentement. Mesurer le nombre de tokens par seconde permet de convertir cette lenteur en une valeur comparable entre les différentes quantifications.

Vérifiez ce que vous avez importé

Exécutez ces quatre commandes après chaque import, dans cet ordre :

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list confirme que le modèle existe et indique la taille enregistrée par Ollama. ollama show confirme qu’Ollama a bien lu les métadonnées nécessaires dans le fichier GGUF. ollama show --modelfile confirme le template et les paramètres qu’il utilisera réellement. C’est la vérification qui permet de détecter le problème de sortie incohérente avant vos utilisateurs. L’invite de test vérifie toute la chaîne, car un modèle dont le template est incorrect échoue même sur la requête la plus courte. Une fois cette invite traitée correctement, le nom attribué au modèle est le même que celui que vous transmettez à tout autre outil qui communique avec l’API Ollama, notamment un agent de codage pointant vers votre propre serveur. Supprimez un import incorrect avec ollama rm my-model, puis recréez-le. Cette commande supprime la copie d’Ollama et laisse votre source .gguf intacte.

FAQ

Puis-je importer un GGUF dans Ollama sans écrire de Modelfile ?

Oui, si le fichier se trouve dans un dépôt Hugging Face. ollama run hf.co/{username}/{repository} le récupère et l’exécute directement, et ollama run hf.co/{username}/{repository}:{quantization} permet de sélectionner une quantification précise. Un Modelfile est nécessaire uniquement pour un .gguf déjà présent sur votre propre disque. Dans ce cas, il peut contenir la seule ligne FROM /path/to/file.gguf, suivie de ollama create my-model.

Quelle quantification Ollama télécharge-t-il si je n’en précise aucune ?

La documentation de Hugging Face, consultée le 25 août 2026, indique que Q4_K_M est utilisé lorsque cette quantification est présente dans le dépôt. Sinon, Ollama sélectionne un type de quantification raisonnable présent dans le dépôt. Ajoutez un tag tel que :Q8_0 pour contrôler ce choix. Vérifiez ce que vous avez réellement reçu avec ollama show <model>. Cette commande affiche la quantification indiquée dans les métadonnées du fichier, et non dans son nom.

Pourquoi mon modèle importé se répète-t-il ou ne s’arrête-t-il jamais de générer du texte ?

Le chat template ne correspond pas au modèle. Ollama sélectionne automatiquement un template à partir des métadonnées tokenizer.chat_template du GGUF. Lorsque ces métadonnées sont absentes ou non reconnues, Ollama utilise un wrapper générique. Le modèle ne reçoit donc jamais le marqueur de fin de tour sur lequel il a été entraîné. Affichez le template actuel avec ollama show --template <model>, puis ajoutez un bloc TEMPLATE et une ligne PARAMETER stop au Modelfile, et exécutez à nouveau ollama create. Écrivez-le sous la forme d’un template Go. Le template Jinja du dépôt d’origine ne fonctionnera pas.

Dois-je utiliser --quantize sur un GGUF que j’ai téléchargé ?

Non. --quantize convertit une source FP16 ou FP32 pendant ollama create. Un fichier dont le nom contient déjà une quantification, telle que Q4_K_M, a déjà été converti. Une nouvelle quantification ne permet pas de récupérer la précision initiale, et il n’existe aucun chemin de retour vers une précision supérieure. Utilisez ce flag uniquement si vous avez vous-même converti des safetensors en GGUF pleine précision et que vous voulez maintenant en produire une version plus compacte.

Comment récupérer un dépôt GGUF privé ?

Ajoutez la clé publique SSH d’Ollama à votre compte Hugging Face. Affichez-la avec sudo cat /usr/share/ollama/.ollama/id_ed25519.pub dans une installation Linux standard, ou avec ~/.ollama/id_ed25519.pub si vous exécutez le serveur avec votre propre utilisateur. Ajoutez-la ensuite dans la page de gestion des clés SSH de votre compte. Après cela, ollama run hf.co/{username}/{repository} fonctionne avec vos propres dépôts privés et avec les dépôts d’une organisation dont vous êtes membre.