⚠️Dépannage et FAQ

Conseils pour résoudre les problèmes et questions fréquentes.

Si vous rencontrez toujours des problèmes avec les versions ou les dépendances, veuillez utiliser notre image Docker qui contiendra tout préinstallé.

Essayez toujours de mettre à jour Unsloth si vous rencontrez des problèmes.

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

Affiner un nouveau modèle non pris en charge par Unsloth ?

Unsloth fonctionne avec n’importe quel modèle pris en charge par transformers. Si un modèle ne figure pas dans nos téléchargements ou ne fonctionne pas immédiatement, il est généralement quand même pris en charge ; certains modèles plus récents peuvent simplement nécessiter un petit ajustement manuel en raison de nos optimisations.

Dans la plupart des cas, vous pouvez activer la compatibilité en définissant trust_remote_code=True dans votre script de fine-tuning. Voici un exemple utilisant DeepSeek-OCR:

from huggingface_hub import snapshot_download
snapshot_download("unsloth/DeepSeek-OCR", local_dir = "deepseek_ocr")
model, tokenizer = FastVisionModel.from_pretrained(
    "./deepseek_ocr",
    load_in_4bit = False, # Utiliser le 4bit pour réduire l’utilisation de la mémoire. False pour LoRA 16bit.
    auto_model = AutoModel,
    trust_remote_code = True, # Activer pour prendre en charge les nouveaux modèles
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # True ou "unsloth" pour long contexte
)

L’exécution dans Unsloth fonctionne bien, mais après l’exportation et l’exécution sur d’autres plateformes, les résultats sont médiocres

Il peut parfois arriver que votre modèle s’exécute et produise de bons résultats dans Unsloth, mais lorsque vous l’utilisez sur une autre plateforme comme Ollama ou vLLM, les résultats sont médiocres ou vous pouvez obtenir du charabia, des générations infinies/sans fin ou des sorties répétées.

• La cause la plus courante de cette erreur est l’utilisation d’un mauvais modèle de chat. Il est essentiel d’utiliser le MÊME modèle de chat qui a été utilisé lors de l’entraînement du modèle dans Unsloth et ensuite lorsque vous l’exécutez dans un autre framework, tel que llama.cpp ou Ollama. Lors de l’inférence à partir d’un modèle enregistré, il est crucial d’appliquer le bon modèle.

• Cela peut aussi être dû au fait que votre moteur d’inférence ajoute un jeton de « début de séquence » inutile (ou, à l’inverse, qu’il n’en ajoute pas), alors assurez-vous de vérifier les deux hypothèses !

• Utilisez nos notebooks conversationnels pour forcer le modèle de chat - cela résoudra la plupart des problèmes.

  • Notebook conversationnel Qwen-3 14B Ouvrir dans Colab

  • Notebook conversationnel Gemma-3 4B Ouvrir dans Colab

  • Notebook conversationnel Llama-3.2 3B Ouvrir dans Colab

  • Notebook conversationnel Phi-4 14B Ouvrir dans Colab

  • Notebook conversationnel Mistral v0.3 7B Ouvrir dans Colab

  • Plus de notebooks dans notre documentation des notebooks

L’enregistrement en GGUF / vLLM 16 bits plante

Vous pouvez essayer de réduire l’utilisation maximale du GPU pendant l’enregistrement en modifiant maximum_memory_usage.

La valeur par défaut est model.save_pretrained(..., maximum_memory_usage = 0.75). Réduisez-la par exemple à 0,5 pour utiliser 50 % du pic de mémoire du GPU ou moins. Cela peut réduire les plantages OOM pendant l’enregistrement.

Comment enregistrer manuellement en GGUF ?

Enregistrez d’abord votre modèle en 16 bits via :

model.save_pretrained_merged("merged_model", tokenizer, save_method = "merged_16bit",)

Compilez llama.cpp à partir des sources comme ci-dessous :

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=ON -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp

Ensuite, enregistrez le modèle en F16 :

python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-F16.gguf --outtype f16 \
    --split-max-size 50G

# Pour BF16 :
python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-BF16.gguf --outtype bf16 \
    --split-max-size 50G
    
# Pour Q8_0 :
python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-Q8_0.gguf --outtype q8_0 \
    --split-max-size 50G

Pourquoi Q8_K_XL est-il plus lent que Q8_0 GGUF ?

Sur les appareils Mac, il semble que BF16 puisse être plus lent que F16. Q8_K_XL convertit certaines couches en BF16, d’où le ralentissement. Nous modifions activement notre processus de conversion afin de faire de F16 le choix par défaut pour Q8_K_XL et de réduire les pertes de performance.

Comment faire l’évaluation

Pour configurer l’évaluation dans votre exécution d’entraînement, vous devez d’abord répartir votre jeu de données en un ensemble d’entraînement et un ensemble de test. Vous devriez toujours mélanger la sélection du jeu de données, sinon votre évaluation est erronée !

new_dataset = dataset.train_test_split(
    test_size = 0.01, # 1 % pour la taille de test peut aussi être un entier pour le # de lignes
    shuffle = True, # Devrait toujours être défini sur True !
    seed = 3407,
)

train_dataset = new_dataset["train"] # Jeu de données pour l’entraînement
eval_dataset = new_dataset["test"] # Jeu de données pour l’évaluation

Ensuite, nous pouvons définir les arguments d’entraînement pour activer l’évaluation. Rappel : l’évaluation peut être très, très lente, surtout si vous définissez eval_steps = 1 ce qui signifie que vous évaluez à chaque étape. Si c’est le cas, essayez de réduire la taille de eval_dataset à, disons, 100 lignes ou quelque chose comme ça.

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,         # Définissez ceci pour réduire l’utilisation de la mémoire
        per_device_eval_batch_size = 2,# L’augmenter utilisera plus de mémoire
        eval_accumulation_steps = 4,   # Vous pouvez augmenter cela à la place de la taille du lot
        eval_strategy = "steps",       # Lance l’évaluation toutes les quelques étapes ou époques.
        eval_steps = 1,                # Nombre d’évaluations effectuées par # d’étapes d’entraînement
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)
trainer.train()

Boucle d’évaluation - Manque de mémoire ou plantage.

Un problème courant lorsque vous manquez de mémoire (OOM) est que vous avez défini une taille de lot trop élevée. Réglez-la à moins de 2 pour utiliser moins de VRAM. Utilisez aussi fp16_full_eval=True pour utiliser float16 pour l’évaluation, ce qui réduit la mémoire de moitié.

Commencez par diviser votre jeu de données d’entraînement en un ensemble d’entraînement et un ensemble de test. Définissez les paramètres du formateur pour l’évaluation ainsi :

new_dataset = dataset.train_test_split(test_size = 0.01)

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        eval_strategy = "steps",
        eval_steps = 1,
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)

Cela évitera les OOM et rendra le tout un peu plus rapide. Vous pouvez aussi utiliser bf16_full_eval=True pour les machines bf16. Par défaut, Unsloth devrait avoir défini ces drapeaux par défaut à partir de juin 2025.

Comment puis-je faire de l'arrêt anticipé ?

Si vous souhaitez arrêter l’exécution de fine-tuning / d’entraînement parce que la perte d’évaluation ne diminue pas, vous pouvez utiliser l’arrêt anticipé, qui arrête le processus d’entraînement. Utilisez EarlyStoppingCallback.

Comme d'habitude, configurez votre trainer et votre ensemble de données de validation. Ce qui suit est utilisé pour arrêter l'exécution de l'entraînement si le eval_loss (la perte de validation) ne diminue pas après environ 3 étapes.

from trl import SFTConfig, SFTTrainer
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        output_dir = "training_checkpoints", # emplacement des points de contrôle enregistrés pour l'arrêt anticipé
        save_strategy = "steps",             # enregistrer le modèle toutes les N étapes
        save_steps = 10,                     # nombre d'étapes avant l'enregistrement du modèle
        save_total_limit = 3,                # ne conserver que 3 points de contrôle enregistrés pour économiser de l'espace disque
        eval_strategy = "steps",             # évaluer toutes les N étapes
        eval_steps = 10,                     # nombre d'étapes avant d'effectuer l'évaluation
        load_best_model_at_end = True,       # DOIT ÊTRE UTILISÉ pour l'arrêt anticipé
        metric_for_best_model = "eval_loss", # métrique sur laquelle nous voulons appliquer l'arrêt anticipé
        greater_is_better = False,           # plus la perte de validation est faible, mieux c'est
    ),
    model = model,
    tokenizer = tokenizer,
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
)

Nous ajoutons ensuite le callback, qui peut également être personnalisé :

from transformers import EarlyStoppingCallback
early_stopping_callback = EarlyStoppingCallback(
    early_stopping_patience = 3,     # Combien d'étapes nous attendrons si la perte de validation ne diminue pas
                                     # Par exemple, la perte peut augmenter, puis diminuer après 3 étapes
    early_stopping_threshold = 0.0,  # Peut être défini plus haut - définit de combien la perte doit diminuer jusqu'à
                                     # ce que nous considérions un arrêt anticipé. Par exemple, 0.01 signifie que si la perte était
                                     # 0.02 puis 0.01, nous considérons qu'il faut arrêter l'exécution de manière anticipée.
)
trainer.add_callback(early_stopping_callback)

Puis entraînez le modèle comme d'habitude via trainer.train() .

Le téléchargement reste bloqué à 90 à 95 %

Si votre modèle reste bloqué à 90, 95 % pendant longtemps, vous pouvez désactiver certains processus de téléchargement rapide afin de forcer des téléchargements synchrones et d’afficher davantage de messages d’erreur.

Utilisez simplement UNSLOTH_STABLE_DOWNLOADS=1 avant tout import d’Unsloth.

import os
os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1"

from unsloth import FastLanguageModel

RuntimeError: erreur CUDA : assertion déclenchée côté périphérique

Redémarrez et exécutez tout, mais placez ceci au début avant tout import d’Unsloth. Veuillez aussi déposer un rapport de bogue dès que possible, merci !

import os
os.environ["UNSLOTH_COMPILE_DISABLE"] = "1"
os.environ["UNSLOTH_DISABLE_FAST_GENERATION"] = "1"

Toutes les étiquettes de votre jeu de données sont à -100. Les pertes d’entraînement seront toutes à 0.

Cela signifie que votre utilisation de train_on_responses_only est incorrecte pour ce modèle particulier. train_on_responses_only vous permet de masquer la question de l’utilisateur et d’entraîner votre modèle à produire la réponse de l’assistant avec un poids plus élevé. Cela est connu pour augmenter la précision d’au moins 1 %. Consultez notre Guide des hyperparamètres LoRA pour plus de détails.

Pour les modèles de type Llama 3.1, 3.2, 3.3, veuillez utiliser ce qui suit :

from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
    trainer,
    instruction_part = "<|start_header_id|>user<|end_header_id|>\n\n",
    response_part = "<|start_header_id|>assistant<|end_header_id|>\n\n",
)

Pour les modèles Gemma 2, 3, 3n, utilisez ce qui suit :

from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
    trainer,
    instruction_part = "<start_of_turn>user\n",
    response_part = "<start_of_turn>model\n",
)

Unsloth est plus lent que prévu ?

Si votre vitesse semble plus lente au début, c’est probablement parce que torch.compile met généralement environ 5 minutes (ou plus) à se réchauffer et à terminer la compilation. Assurez-vous de mesurer le débit après qu’il est complètement chargé, car sur des exécutions plus longues, Unsloth devrait être beaucoup plus rapide.

Pour désactiver, utilisez :

import os
os.environ["UNSLOTH_COMPILE_DISABLE"] = "1"

Certaines poids de Gemma3nForConditionalGeneration n’ont pas été initialisés à partir du point de contrôle du modèle

C’est une erreur critique, car cela signifie que certains poids ne sont pas analysés correctement, ce qui entraînera des sorties incorrectes. Cela peut normalement être corrigé en mettant à jour Unsloth

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

Puis mettez à jour transformers et timm :

pip install --upgrade --force-reinstall --no-cache-dir --no-deps transformers timm

Cependant, si le problème persiste, veuillez déposer un rapport de bogue dès que possible !

NotImplementedError : un environnement linguistique UTF-8 est requis. ANSI obtenu

Voir https://github.com/googlecolab/colabtools/issues/3409

Dans une nouvelle cellule, exécutez ce qui suit :

import locale
locale.getpreferredencoding = lambda: "UTF-8"

Citer Unsloth

Si vous citez l’utilisation de nos téléchargements de modèles, utilisez le Bibtex ci-dessous. Ceci concerne Qwen3-30B-A3B-GGUF Q8_K_XL :

@misc{unsloth_2025_qwen3_30b_a3b,
  author       = {Unsloth AI and Han-Chen, Daniel and Han-Chen, Michael},
  title        = {Qwen3-30B-A3B-GGUF:Q8\_K\_XL},
  year         = {2025},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/unsloth/Qwen3-30B-A3B-GGUF}}
}

Pour citer l’utilisation de notre package Github ou notre travail en général :

@misc{unsloth,
  author       = {Unsloth AI and Han-Chen, Daniel and Han-Chen, Michael},
  title        = {Unsloth},
  year         = {2025},
  publisher    = {Github},
  howpublished = {\url{https://github.com/unslothai/unsloth}}
}