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, vous écrivez un Modelfile de deux lignes, puis vous 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 si 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 joindre 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, et Ollama repose sur llama.cpp. C’est pourquoi presque tous les modèles open source disposent d’une conversion GGUF produite par la communauté. Ollama peut également importer un répertoire de poids .safetensors, mais il s’agit d’une autre méthode. La section consacrée à --quantize ci-dessous indique quand l’utiliser.

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 le reste de ce guide s’exécutera correctement.

Première méthode : 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 les 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 disponible dans votre bibliothèque locale et démarre rapidement. Ouvrez un deuxième shell et exécutez ollama list pour voir le nom sous lequel il a été enregistré. Ce nom correspond à toute la chaîne hf.co/... 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 aucun fichier récupérable par cette méthode. Vous devez alors utiliser l’une des importations locales décrites plus loin.

Quelle quantification Ollama sélectionne-t-il ?

La documentation Ollama de Hugging Face, consultée le 10 octobre 2026, précise le comportement 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 choisissons par défaut un type de quantification raisonnable présent dans le dépôt. » Un dépôt qui publie dix quantifications vous fournit donc Q4_K_M. Si le dépôt ne contient pas Q4_K_M, Ollama choisit une autre quantification à votre place. Consultez de nouveau cette page avant de vous y fier, car les valeurs par défaut peuvent changer.

Pour demander une quantification précise, ajoutez-la 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 n’est pas sensible à la casse. :iq3_m et :IQ3_M désignent donc la même quantification. Vous pouvez également utiliser le nom exact du fichier comme tag. C’est la forme la plus sûre lorsque les noms courts du 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 de la quantification dépend de la mémoire disponible et de la qualité recherchée. la différence entre Q4, Q8 et FP16 explique précisément ce compromis.

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-le sous le nom Modelfile, puis créez 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 le flag et sa valeur par défaut dans votre build. Le chemin indiqué dans FROM peut être absolu ou relatif au Modelfile ; FROM ./my-model-Q4_K_M.gguf fonctionne donc 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 quantization qu’Ollama a lue dans les métadonnées du fichier. Fiez-vous à ces valeurs plutôt qu’au nom du fichier, car un nom de fichier est une 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 sur les templates ci-dessous : c’est presque toujours la cause du problème.

Un point important concerne l’espace disque : ollama create copie le GGUF dans le model store d’Ollama au lieu de référencer le fichier à son emplacement d’origine. Les weights occupent donc deux fois l’espace disque jusqu’à la suppression de l’original. Supprimez le fichier source une fois que ollama run my-model fonctionne, ou conservez-le dans un emplacement dont le stockage ne vous est pas facturé deux fois. où Ollama conserve ses modèles sur le disque décrit l’organisation des fichiers et la procédure de déplacement.

Quand --quantize s’applique, et quand il ne s’applique pas

ollama create possède un flag --quantize, qui ne s’applique aujourd’hui qu’à un seul cas : un modèle importé depuis un répertoire de weights .safetensors. Dans le source actuel d’Ollama, vérifié le 10 October 2026, son texte d’aide est "Quantize safetensors model to this level (e.g. nvfp4)", et les valeurs acceptées sont int4, int8, nvfp4, mxfp4 et mxfp8. Les noms de quantization GGUF tels que q8_0 ou q4_K_M sont refusés comme types non pris en charge. La documentation d’import d’Ollama est explicite concernant les GGUF : "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

Cette commande suppose que la ligne FROM du Modelfile pointe vers le répertoire contenant les fichiers .safetensors.

Ne transmettez pas ce flag lorsque FROM désigne un .gguf, quelle que soit sa précision. Un GGUF FP16 ou FP32 est refusé de la même manière qu’un fichier Q4_K_M, avec une erreur commençant par "create-time quantization is only supported for safetensors imports". Un .gguf dont le nom contient Q4_K_M ou Q5_K_S a déjà été quantized ; la précision supprimée ne peut pas être restaurée. Le llama-quantize de llama.cpp peut réencoder un tel fichier dans un autre type, notamment Q8_0, lorsque vous lui transmettez --allow-requantize, mais son manuel avertit que cela "can severely reduce quality compared to quantizing from 16bit or 32bit", et un fichier Q4 réécrit en Q8 est plus volumineux sans être meilleur. Pour réduire un GGUF en pleine précision, exécutez d’abord llama-quantize sur ce fichier. C’est l’outil recommandé par la documentation d’Ollama. Importez ensuite le fichier qu’il produit. Si votre source est un dépôt Hugging Face contenant des fichiers .safetensors, vous pouvez soit indiquer ce répertoire à FROM et laisser ollama create l’importer, avec --quantize si vous voulez le réduire, soit le convertir avec convert_hf_to_gguf.py depuis le dépôt llama.cpp, puis importer le GGUF produit par ce script. Comment Ollama et llama.cpp s’articulent explique pourquoi ces outils appartiennent à 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, tandis que ollama run hf.co/{username}/{repository}:{quantization} sélectionne une quantification précise. Un Modelfile est uniquement nécessaire 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 10 octobre 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 la contrôler. Vérifiez ce que vous avez réellement reçu avec ollama show <model>. Cette commande affiche la quantification provenant des métadonnées du fichier, et non de 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 voit alors 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, avant d’exécuter à nouveau ollama create. Écrivez-le comme 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 fonctionne uniquement lors de l’import de fichiers safetensors avec ollama create. Cette option refuse toute source GGUF, y compris les fichiers FP16 ou FP32, avec une erreur indiquant que les modèles GGUF doivent être quantifiés avant leur import. Un fichier dont le nom contient déjà une quantification, comme Q4_K_M, a déjà été converti. Le quantifier à nouveau ne permet pas de récupérer la précision perdue : llama-quantize --allow-requantize peut le réécrire en Q8_0, mais le résultat est plus volumineux sans être meilleur. Pour obtenir un fichier plus petit à partir d’un GGUF en pleine précision, exécutez llama-quantize de llama.cpp dessus, puis importez le résultat.

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 lorsque 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 ceux d’une organisation dont vous êtes membre.