> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/fr/notions-de-base/troubleshooting-and-faqs.md). # Dépannage et FAQ Astuces pour résoudre les problèmes et questions fréquemment posées. Si vous rencontrez encore des problèmes avec les versions ou les dépendances, veuillez utiliser notre [image Docker](/docs/fr/commencer/install/docker.md) 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 %} ### Ajuster 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 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](/docs/fr/modeles/tutorials/deepseek-ocr-how-to-run-and-fine-tune.md): 
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, # Utilisez le 4 bits pour réduire l'utilisation de la mémoire. False pour un LoRA en 16 bits.
    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 ou "unsloth" pour un long contexte
)
### L’exécution dans Unsloth fonctionne bien, mais après exportation et 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 que vous obteniez du charabia, 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 **template de chat incorrect****.** Il est essentiel d’utiliser le MÊME template de chat que celui utilisé lors de l’entraînement du modèle dans Unsloth, puis lorsque vous l’exécutez dans un autre framework, comme llama.cpp ou Ollama. Lors de l’inférence à partir d’un modèle sauvegardé, il est crucial d’appliquer le bon template. * 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, n’en ajoute pas), alors assurez-vous de vérifier les deux hypothèses ! * **Utilisez nos notebooks conversationnels pour forcer le template 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** [**documentation des notebooks**](/docs/fr/commencer/unsloth-notebooks.md) ### 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 % de la mémoire maximale du GPU ou moins. Cela peut réduire les plantages OOM pendant l’enregistrement. ### Comment enregistrer manuellement en GGUF ? Commencez par enregistrer votre modèle en 16 bits via : ```python model.save_pretrained_merged("merged_model", tokenizer, save_method = "merged_16bit",) ``` Compilez llama.cpp à partir des sources comme ci-dessous : ```bash 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 : ```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 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 pour faire de F16 le choix par défaut pour Q8\_K\_XL afin de réduire les pertes de performances. ### Comment faire l’évaluation Pour configurer l’évaluation dans votre exécution d’entraînement, vous devez d’abord diviser votre jeu de données en ensembles d’entraînement et de test. Vous devez **toujours mélanger la sélection du jeu de données**, sinon votre évaluation est fausse ! ```python new_dataset = dataset.train_test_split( test_size = 0.01, # 1 % pour la taille de test ; peut aussi être un entier pour le nombre de lignes shuffle = True, # Doit 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. ```python from trl import SFTTrainer, SFTConfig trainer = SFTTrainer( args = SFTConfig( fp16_full_eval = True, # Définir ceci pour réduire l’utilisation de la mémoire per_device_eval_batch_size = 2,# Augmenter cette valeur utilisera plus de mémoire eval_accumulation_steps = 4, # Vous pouvez augmenter cela à la place de la batch_size eval_strategy = "steps", # Lance l’évaluation toutes les quelques étapes ou époques. eval_steps = 1, # Nombre 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 - manque de mémoire ou plantage. Un problème courant lorsque vous êtes en OOM vient du fait que vous avez défini une taille de batch trop élevée. Réduisez-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é. Divisez d’abord votre jeu de données d’entraînement en ensembles d’entraînement et de test. Définissez les paramètres du trainer pour l’évaluation sur : ```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"], ... ) ``` Cela évitera les OOM et rendra le tout un peu plus rapide. Vous pouvez également utiliser `bf16_full_eval=True` pour les machines bf16. Par défaut, Unsloth devrait avoir activé ces indicateurs par défaut depuis juin 2025. ### Comment puis-je faire de l’arrêt anticipé ? Si vous souhaitez arrêter la session de fine-tuning / d’entraînement parce que la perte d’évaluation ne diminue pas, vous pouvez utiliser l’arrêt anticipé, qui stoppe 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 de l’entraînement si la `eval_loss` (la loss d’évaluation) ne diminue pas après 3 étapes environ. ```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 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, # conserver seulement 3 checkpoints enregistrés pour économiser de l’espace disque eval_strategy = "steps", # évaluer toutes les N étapes eval_steps = 10, # nombre d’étapes avant 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 baser l’arrêt anticipé greater_is_better = False, # plus la loss d’évaluation 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 aussi être personnalisé : ```python from transformers import EarlyStoppingCallback early_stopping_callback = EarlyStoppingCallback( early_stopping_patience = 3, # Nombre d’étapes d’attente si la loss d’évaluation ne diminue pas # Par exemple, la loss peut augmenter, puis diminuer après 3 étapes early_stopping_threshold = 0.0, # Peut être défini plus haut - fixe de combien la loss doit diminuer jusqu’à # ce que nous considérions l’arrêt anticipé. Par ex. 0.01 signifie que si la loss é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) ``` 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 ou 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. ```python import os os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1" from unsloth import FastLanguageModel ``` ### RuntimeError : erreur CUDA : assert déclenché côté appareil Redémarrez et relancez tout, mais placez ceci au début avant tout import d’Unsloth. Et veuillez aussi déposer un rapport de bug dès que possible, merci ! ```python import os os.environ["UNSLOTH_COMPILE_DISABLE"] = "1" os.environ["UNSLOTH_DISABLE_FAST_GENERATION"] = "1" ``` ### Tous les labels 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**](/docs/fr/commencer/fine-tuning-llms-guide/lora-hyperparameters-guide.md) 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 les modèles Gemma 2, 3, 3n, 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 d’abord plus lente, c’est probablement parce que `torch.compile` prend généralement environ 5 minutes (ou plus) pour se réchauffer et terminer la compilation. Assurez-vous de mesurer le débit **après** une fois qu’il est 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" ``` ### Certaines des pondérations de Gemma3nForConditionalGeneration n’ont pas été initialisées à 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 provoquera 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` 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 déposer un rapport de bug dès que possible ! ### NotImplementedError: une locale UTF-8 est requise. ANSI trouvée 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 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}} } ``` [^1]: Activez cette ligne de code et voyez si cela fonctionne. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://unsloth.ai/docs/fr/notions-de-base/troubleshooting-and-faqs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.