# Dépannage et FAQ Si vous rencontrez toujours des problèmes avec les versions ou les dépendances, veuillez utiliser notre [image Docker](https://unsloth.ai/docs/fr/commencer/install/docker) qui aura tout préinstallé. {% hint style="success" %} **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` {% endhint %} ### Affiner un nouveau modèle non pris en charge par Unsloth ? Unsloth fonctionne avec tout modèle pris en charge par `transformers`. Si un modèle n’est pas dans nos uploads ou ne fonctionne pas directement, il est généralement encore pris en charge ; certains modèles plus récents peuvent juste 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](https://unsloth.ai/docs/fr/modeles/tutorials/deepseek-ocr-how-to-run-and-fine-tune): 
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, # Use 4bit to reduce memory use. False for 16bit LoRA.
    auto_model = AutoModel,
    trust_remote_code = True, # Activez pour prendre en charge de nouveaux modèles
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # True or "unsloth" for long context
)
### Exécuter dans Unsloth fonctionne bien, mais après exportation et exécution sur d'autres plates-formes, les résultats sont médiocres Vous pouvez parfois rencontrer un problème où votre modèle s'exécute et produit de bons résultats sur Unsloth, mais lorsque vous l'utilisez sur une autre plate-forme comme Ollama ou vLLM, les résultats sont médiocres ou vous obtenez des charabias, des générations sans fin/infinies *ou* sorties répétées**.** * La cause la plus courante de cette erreur est l'utilisation d'un **modèle de chat incorrect****.** 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 plus tard 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 « début de séquence » inutile (ou au contraire l'absence de celui-ci) ; assurez-vous donc 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**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_\(14B\)-Reasoning-Conversational.ipynb) * Notebook conversationnel Gemma-3 4B [**Ouvrir dans Colab**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3_\(4B\).ipynb) * Notebook conversationnel Llama-3.2 3B [**Ouvrir dans Colab**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Llama3.2_\(1B_and_3B\)-Conversational.ipynb) * Notebook conversationnel Phi-4 14B [**Ouvrir dans Colab**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Phi_4-Conversational.ipynb) * Notebook conversationnel Mistral v0.3 7B [**Ouvrir dans Colab**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Mistral_v0.3_\(7B\)-Conversational.ipynb) * **Plus de notebooks dans notre** [**docs des notebooks**](https://unsloth.ai/docs/fr/commencer/unsloth-notebooks) ### Enregistrer en GGUF / vLLM 16 bits plante Vous pouvez essayer de réduire l'utilisation GPU maximale 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 % de la mémoire GPU de pointe ou moins. Cela peut réduire les plantages OOM pendant l'enregistrement. ### Comment enregistrer manuellement au format GGUF ? Enregistrez d'abord votre modèle en 16 bits via : ```python model.save_pretrained_merged("merged_model", tokenizer, save_method = "merged_16bit",) ``` Compilez llama.cpp depuis la source comme ci-dessous : ```bash apt-get update apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y git clone https://github.com/ggerganov/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 : ```bash python llama.cpp/convert_hf_to_gguf.py merged_model \ --outfile model-F16.gguf --outtype f16 \ --split-max-size 50G ``` ```bash # 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 le BF16 puisse être plus lent que le F16. Q8\_K\_XL surclasse certaines couches en BF16, d'où le ralentissement. Nous modifions activement notre processus de conversion pour faire du F16 le choix par défaut pour Q8\_K\_XL afin de réduire les pertes de performance. ### Comment faire l'évaluation Pour configurer l'évaluation dans votre session d'entraînement, vous devez d'abord diviser 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 ! ```python new_dataset = dataset.train_test_split( test_size = 0.01, # 1% pour la taille du test peut aussi être un entier pour le nombre de lignes shuffle = True, # Doit toujours être réglé 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 à, par exemple, 100 lignes ou quelque chose comme ça. ```python from trl import SFTTrainer, SFTConfig trainer = SFTTrainer( args = SFTConfig( fp16_full_eval = True, # Réglez 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 batch_size eval_strategy = "steps", # Exécute l'éval tous les quelques pas ou époques. eval_steps = 1, # Combien d'évaluations effectuées par nombre d'étapes d'entraînement ), train_dataset = new_dataset["train"], eval_dataset = new_dataset["test"], ... ) trainer.train() ``` ### Boucle d'évaluation - Mémoire insuffisante ou plantage. Un problème courant lorsque vous avez un OOM est que vous avez défini votre taille de lot trop élevée. Réduisez-la en dessous de 2 pour utiliser moins de VRAM. Utilisez aussi `fp16_full_eval=True` pour utiliser le float16 pour l'évaluation, ce qui réduit la mémoire de moitié. Divisez d'abord votre jeu de données d'entraînement en un ensemble d'entraînement et un ensemble de test. Réglez les paramètres du trainer pour l'évaluation comme suit : ```python 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"], ... ) ``` Ceci évitera les OOM et rendra cela quelque peu plus rapide. Vous pouvez aussi utiliser `bf16_full_eval=True` pour les machines bf16. Par défaut, Unsloth devrait avoir activé ces drapeaux par défaut à partir de juin 2025. ### Comment faire un Early Stopping ? Si vous voulez arrêter le finetuning / l'entraînement parce que la perte d'évaluation ne diminue pas, vous pouvez utiliser l'arrêt précoce (early stopping) qui interrompt le processus d'entraînement. Utilisez `EarlyStoppingCallback`. Comme d'habitude, configurez votre trainer et votre jeu de données d'évaluation. Ce qui suit est utilisé pour arrêter l'exécution d'entraînement si la `eval_loss` (la perte d'évaluation) ne diminue pas après environ 3 étapes. ```python 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 checkpoints sauvegardés pour l'arrêt précoce save_strategy = "steps", # sauvegarder le modèle toutes les N étapes save_steps = 10, # combien d'étapes avant de sauvegarder le modèle save_total_limit = 3, # ne conserver que 3 checkpoints sauvegardés pour économiser de l'espace disque eval_strategy = "steps", # évaluer toutes les N étapes eval_steps = 10, # combien d'étapes avant de faire l'évaluation load_best_model_at_end = True, # DOIT ÊTRE UTILISÉ pour l'arrêt précoce metric_for_best_model = "eval_loss", # métrique sur laquelle nous voulons effectuer l'arrêt précoce greater_is_better = False, # plus la perte d'éval est faible, mieux c'est ), trainer = Trainer( tokenizer = tokenizer, train_dataset = new_dataset["train"], eval_dataset = new_dataset["test"], ) ``` Nous ajoutons ensuite le callback qui peut également être personnalisé : ```python from transformers import EarlyStoppingCallback early_stopping_callback = EarlyStoppingCallback( early_stopping_patience = 3, # Combien d'étapes nous attendrons si la perte d'éval ne diminue pas # Par exemple la perte peut augmenter, mais diminuer après 3 étapes early_stopping_threshold = 0.0, # Peut être réglé plus haut - définit de combien la perte doit diminuer avant # que nous considérions l'arrêt précoce. Par ex. 0.01 signifie si la perte était # 0.02 puis 0.01, nous envisageons d'arrêter prématurément l'exécution. ) trainer.add_callback(early_stopping_callback) ``` Ensuite 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 rapides pour forcer les téléchargements à être synchrones et afficher davantage de messages d'erreur. Utilisez simplement `UNSLOTH_STABLE_DOWNLOADS=1` avant tout import Unsloth. ```python import os os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1" from unsloth import FastLanguageModel ``` ### RuntimeError : CUDA error: device-side assert triggered Redémarrez et exécutez tout, mais placez ceci au début avant tout import Unsloth. Veuillez aussi signaler un bug dès que possible, merci ! ```python 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é. Il est connu que cela augmente la précision d'environ 1 % ou plus. Voir notre [**Guide des hyperparamètres LoRA**](https://unsloth.ai/docs/fr/commencer/fine-tuning-llms-guide/lora-hyperparameters-guide) pour plus de détails. Pour les modèles de type Llama 3.1, 3.2, 3.3, veuillez utiliser ce qui suit : ```python 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 Gemma 2, 3. 3n modèles, utilisez ce qui suit : ```python from unsloth.chat_templates import train_on_responses_only trainer = train_on_responses_only( trainer, instruction_part = "user\n", response_part = "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` prend généralement \~5 minutes (ou plus) pour se chauffer et terminer la compilation. Assurez-vous de mesurer le débit **après** qu'il soit entièrement chargé car sur des exécutions plus longues, Unsloth devrait être beaucoup plus rapide. Pour désactiver, utilisez : ```python import os os.environ["UNSLOTH_COMPILE_DISABLE"] = "1" ``` ### Certains poids de Gemma3nForConditionalGeneration n'ont pas été initialisés à partir du checkpoint du modèle Ceci est une erreur critique, car cela signifie que certains poids ne sont pas correctement analysés, ce qui provoquera des sorties incorrectes. Cela peut généralement être résolu en mettant à jour Unsloth `pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo` Ensuite mettez à jour transformers et timm : `pip install --upgrade --force-reinstall --no-cache-dir --no-deps transformers timm` Cependant, si le problème persiste, veuillez signaler un bug dès que possible ! ### NotImplementedError : Un paramètre régional UTF-8 est requis. ANSI détecté Voir Dans une nouvelle cellule, exécutez ce qui suit : ```python import locale locale.getpreferredencoding = lambda: "UTF-8" ``` ### Citer Unsloth Si vous citez l'utilisation de nos uploads de modèles, utilisez le Bibtex ci-dessous. Ceci est pour 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}} } ``` [^1]: Activez cette ligne de code et voyez si cela fonctionne.