⚠️Fehlerbehebung & FAQs

Tipps zur Lösung von Problemen und häufig gestellte Fragen.

Wenn Sie weiterhin Probleme mit Versionen oder Abhängigkeiten haben, verwenden Sie bitte unser Docker-Image welches alles vorinstalliert enthält.

Versuchen Sie stets, Unsloth zu aktualisieren, wenn Sie Probleme feststellen.

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

Feinabstimmung eines neuen Modells, das von Unsloth nicht unterstützt wird?

Unsloth funktioniert mit jedem Modell, das von transformersunterstützt wird. Wenn ein Modell nicht in unseren Uploads vorhanden ist oder nicht sofort läuft, wird es in der Regel trotzdem unterstützt; einige neuere Modelle benötigen aufgrund unserer Optimierungen möglicherweise nur eine kleine manuelle Anpassung.

In den meisten Fällen können Sie die Kompatibilität aktivieren, indem Sie trust_remote_code=True in Ihrem Feinabstimmungs-Skript setzen. Hier ein Beispiel mit 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, # Verwenden Sie 4bit, um Speicher zu reduzieren. False für 16bit LoRA.
    auto_model = AutoModel,
    trust_remote_code = True, # Aktivieren, um neue Modelle zu unterstützen
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # True oder "unsloth" für langen Kontext
)

Das Ausführen in Unsloth funktioniert gut, aber nach dem Export und dem Ausführen auf anderen Plattformen sind die Ergebnisse schlecht

Manchmal kann es vorkommen, dass Ihr Modell in Unsloth läuft und gute Ergebnisse liefert, aber wenn Sie es auf einer anderen Plattform wie Ollama oder vLLM verwenden, die Ergebnisse schlecht sind oder Sie Kauderwelsch bzw. endlose/unendliche Generierungen erhalten oder wiederholte Ausgaben.

• Die häufigste Ursache für diesen Fehler ist die Verwendung einer inkorrekten Chat-Vorlage. Es ist entscheidend, dieselbe Chat-Vorlage zu verwenden, die beim Training des Modells in Unsloth verwendet wurde und später, wenn Sie es in einem anderen Framework wie llama.cpp oder Ollama ausführen. Beim Inferencing aus einem gespeicherten Modell ist es wichtig, die korrekte Vorlage anzuwenden.

• Es kann auch daran liegen, dass Ihre Inferenz-Engine ein unnötiges "Start der Sequenz"-Token hinzufügt (oder im Gegenteil dessen Fehlen), also prüfen Sie bitte beide Hypothesen!

• Verwenden Sie unsere konversationellen Notebooks, um die Chat-Vorlage zu erzwingen - das behebt die meisten Probleme.

  • Qwen-3 14B Konversationelles Notebook In Colab öffnen

  • Gemma-3 4B Konversationelles Notebook In Colab öffnen

  • Llama-3.2 3B Konversationelles Notebook In Colab öffnen

  • Phi-4 14B Konversationelles Notebook In Colab öffnen

  • Mistral v0.3 7B Konversationelles Notebook In Colab öffnen

  • Weitere Notebooks in unseren Notebook-Dokumenten

Speichern in GGUF / vLLM 16bit stürzt ab

Sie können versuchen, die maximale GPU-Nutzung während des Speicherns zu verringern, indem Sie maximum_memory_usage.

Der Standardwert ist model.save_pretrained(..., maximum_memory_usage = 0.75). Reduzieren Sie ihn z. B. auf 0,5, um 50 % des maximalen GPU-Speichers oder weniger zu verwenden. Dies kann OOM-Abstürze beim Speichern reduzieren.

Wie speichere ich manuell in GGUF?

Speichern Sie Ihr Modell zuerst in 16bit via:

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

Kompilieren Sie llama.cpp aus dem Quellcode wie unten:

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

Speichern Sie dann das Modell in F16:

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

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

Warum ist Q8_K_XL langsamer als Q8_0 GGUF?

Auf Mac-Geräten scheint BF16 langsamer als F16 zu sein. Q8_K_XL wandelt einige Schichten in BF16 hoch (upcasts), was die Verlangsamung erklärt. Wir ändern aktiv unseren Konvertierungsprozess, um F16 als Standard für Q8_K_XL zu verwenden, um Leistungseinbußen zu reduzieren.

Wie man Evaluation durchführt

Um die Evaluation in Ihrem Trainingslauf einzurichten, müssen Sie zuerst Ihr Dataset in einen Trainings- und einen Testsplit aufteilen. Sie sollten immer die Auswahl des Datasets mischen, andernfalls ist Ihre Evaluation falsch!

new_dataset = dataset.train_test_split(
    test_size = 0.01, # 1% als Testgröße; kann auch eine ganze Zahl für die Anzahl der Zeilen sein
    shuffle = True, # Sollte immer auf True gesetzt werden!
    seed = 3407,
)

train_dataset = new_dataset["train"] # Dataset fürs Training
eval_dataset = new_dataset["test"] # Dataset für die Evaluation

Dann können wir die Trainingsargumente so einstellen, dass die Evaluation aktiviert wird. Erinnerung: Evaluation kann sehr, sehr langsam sein, besonders wenn Sie eval_steps = 1 setzen, was bedeutet, dass Sie bei jedem einzelnen Schritt evaluieren. Wenn Sie das tun, versuchen Sie, die Größe des eval_dataset auf z. B. 100 Zeilen oder so zu reduzieren.

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,         # Setzen Sie dies, um den Speicherverbrauch zu reduzieren
        per_device_eval_batch_size = 2,# Erhöhen dieses Werts verwendet mehr Speicher
        eval_accumulation_steps = 4,   # Sie können dies erhöhen anstelle der batch_size
        eval_strategy = "steps",       # Führt Evaluation alle paar Schritte oder Epochen aus.
        eval_steps = 1,                # Wie viele Evaluationsläufe pro Anzahl der Trainingsschritte
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)
trainer.train()

Evaluationsschleife – Out of Memory oder Absturz.

Ein häufiges Problem bei OOM ist, dass Sie Ihre Batch-Größe zu hoch gesetzt haben. Setzen Sie sie niedriger als 2, um weniger VRAM zu verwenden. Verwenden Sie außerdem fp16_full_eval=True um für die Evaluation float16 zu verwenden, was den Speicherbedarf halbiert.

Teilen Sie zuerst Ihr Trainingsdataset in einen Trainings- und einen Testsplit. Setzen Sie die Trainer-Einstellungen für die Evaluation auf:

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"],
    ...
)

Dies verhindert OOMs und macht es etwas schneller. Sie können auch bf16_full_eval=True für bf16-Maschinen verwenden. Standardmäßig sollte Unsloth diese Flags seit Juni 2025 standardmäßig gesetzt haben.

Wie mache ich Early Stopping?

Wenn Sie den Feinabstimmungs-/Trainingslauf stoppen möchten, weil der Evaluationsverlust nicht sinkt, können Sie Early Stopping verwenden, das den Trainingsprozess beendet. Verwenden Sie EarlyStoppingCallback.

Wie üblich richten Sie Ihren Trainer und Ihren Evaluations-Datensatz ein. Das Folgende wird verwendet, um den Trainingslauf zu stoppen, wenn der eval_loss (der Evaluationsverlust) sich nach etwa 3 Schritten nicht verringert.

dataset = load_dataset("HuggingFaceH4/Multilingual-Thinking", split="train")
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        output_dir = "training_checkpoints", # Speicherort der gespeicherten Checkpoints für Early Stopping
        save_strategy = "steps",             # Modell alle N Schritte speichern
        save_steps = 10,                     # wie viele Schritte bis wir das Modell speichern
        save_total_limit = 3,                # nur 3 gespeicherte Checkpoints behalten, um Festplattenspeicher zu sparen
        eval_strategy = "steps",             # alle N Schritte evaluieren
        eval_steps = 10,                     # wie viele Schritte bis wir eine Evaluation durchführen
        load_best_model_at_end = True,       # MUSS für Early Stopping verwendet werden
        metric_for_best_model = "eval_loss", # Metrik, auf der wir Early Stopping basieren wollen
        greater_is_better = False,           # je niedriger der Evaluationsverlust, desto besser
    ),
    model = model,
    tokenizer = tokenizer,
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
)

Wir fügen dann den Callback hinzu, der ebenfalls angepasst werden kann:

from transformers import EarlyStoppingCallback
early_stopping_callback = EarlyStoppingCallback(
    early_stopping_patience = 3,     # Wie viele Schritte wir warten werden, wenn der Evaluationsverlust nicht sinkt
                                     # Zum Beispiel könnte der Verlust steigen, aber nach 3 Schritten sinken
    early_stopping_threshold = 0.0,  # Kann höher gesetzt werden - legt fest, um wie viel der Verlust sinken muss, bis
                                     # wir Early Stopping in Betracht ziehen. Beispielsweise bedeutet 0.01, wenn der Verlust
                                     # 0.02 dann 0.01 war, dass wir erwägen, den Lauf vorzeitig zu beenden.
)
trainer.add_callback(early_stopping_callback)

Dann trainieren Sie das Modell wie gewohnt über trainer.train() .

Download bleibt bei 90 bis 95% hängen

Wenn Ihr Modell lange bei 90–95% hängen bleibt, bevor es weitergeht, können Sie einige schnelle Download-Prozesse deaktivieren, um Downloads synchron zu erzwingen und mehr Fehlermeldungen auszugeben.

Verwenden Sie einfach UNSLOTH_STABLE_DOWNLOADS=1 vor jeglichem Unsloth-Import.

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

from unsloth import FastLanguageModel

RuntimeError: CUDA error: device-side assert triggered

Neustarten und alles ausführen, aber setzen Sie dies ganz am Anfang, bevor irgendein Unsloth-Import erfolgt. Bitte melden Sie außerdem so schnell wie möglich einen Bug, danke!

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

Alle Labels in Ihrem Dataset sind -100. Trainingsverluste werden alle 0 sein.

Das bedeutet, dass Ihre Verwendung von train_on_responses_only für dieses spezielle Modell falsch ist. train_on_responses_only ermöglicht es Ihnen, die Nutzerfrage zu maskieren und Ihr Modell zu trainieren, die Assistenten-Antwort mit höherer Gewichtung auszugeben. Es ist bekannt, dass dies die Genauigkeit um 1% oder mehr steigert. Siehe unser LoRA-Hyperparameter-Leitfaden für weitere Details.

Für Modelle vom Typ Llama 3.1, 3.2, 3.3 verwenden Sie bitte Folgendes:

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",
)

Für Gemma 2, 3, 3n Modelle verwenden Sie das Folgende:

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 ist langsamer als erwartet?

Wenn Ihre Geschwindigkeit anfangs langsamer erscheint, liegt das wahrscheinlich daran, dass torch.compile typischerweise ~5 Minuten (oder länger) benötigt, um sich aufzuwärmen und die Kompilierung abzuschließen. Stellen Sie sicher, dass Sie den Durchsatz messen nach es vollständig geladen ist, da Unsloth bei längeren Läufen deutlich schneller sein sollte.

Zum Deaktivieren verwenden:

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

Einige Gewichte von Gemma3nForConditionalGeneration wurden nicht aus dem Modell-Checkpoint initialisiert

Dies ist ein kritischer Fehler, da dies bedeutet, dass einige Gewichte nicht korrekt geparst wurden, was zu falschen Ausgaben führt. Dies kann normalerweise durch ein Upgrade von Unsloth behoben werden

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

Dann aktualisieren Sie transformers und timm:

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

Wenn das Problem jedoch weiterhin besteht, melden Sie bitte so schnell wie möglich einen Bug!

NotImplementedError: Es wird eine UTF-8-Locale benötigt. ANSI erhalten

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

Führen Sie in einer neuen Zelle Folgendes aus:

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

Unsloth zitieren

Wenn Sie die Nutzung unserer Modell-Uploads zitieren, verwenden Sie die folgende Bibtex-Angabe. Dies gilt für 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}}
}

Um die Nutzung unseres Github-Pakets oder unserer Arbeit im Allgemeinen zu zitieren:

@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}}
}