tarioch/unsloth-lora

Unsloth LoRA-Training

Trainieren Sie einen LoRA-Adapter auf einem Chat-Datensatz mit Unsloth auf einer lokalen GPU und exportieren Sie das Ergebnis als GGUF. Der Datensatz stammt vom Benutzer (dessen Erstellung problemspezifisch ist); dieses Skill beginnt mit train.jsonl und val.jsonl. Das Serving des Modells ist ein separater Schritt: Der Ausgabeordner, den dieses Skill erstellt (GGUF plus run.json), ist das, was ein Serving-Skill wie ollama-model benötigt.

Führen Sie jedes Skript über den Launcher mit dem Bash-Tool aus: ${CLAUDE_SKILL_DIR}/scripts/run <script.py> [args]. Das Skill erlaubt genau diesen Befehl, sodass er im Automatikmodus läuft; ein Skript auf andere Weise aufzurufen, wird abgelehnt. Wenn ein Launcher-Befehl nach einer neuen Nachricht vom Benutzer abgelehnt wird, rufen Sie dieses Skill erneut auf. Der Launcher führt check_data.py mit einem beliebigen Python 3 und preflight.py, train.py und export_gguf.py mit dem Python der Unsloth-Umgebung aus, und zwar im übergeordneten Ordner des --out/--run-Ordners (Unsloth schreibt einen unsloth_compiled_cache/-Ordner in das aktuelle Verzeichnis). Geben Sie jeden Pfad als absoluten Pfad an: Befehle teilen sich kein Arbeitsverzeichnis.

Bevor Sie beginnen, ermitteln Sie

• Den Datensatzordner und das Evaluierungsset, das später zum Vergleichen von Modellen verwendet wird: Es darf nicht Teil des Trainings sein. Wenn es keins gibt, schlagen Sie vor, vor dem Training Beispiele zurückzuhalten.
• Das/die Basismodell(e) als Unsloth-4-Bit-Namen (z. B. unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit). Mehrere Basismodelle bedeuten einen Ausgabeordner pro Modell und die gleichen Schritte für jedes, nacheinander (references/base-models.md).
• Die Maschine: Training benötigt eine CUDA-GPU und das Python der Unsloth-Umgebung. Fragen Sie den Benutzer nach dem Pfad dieses Python, wenn UNSLOTH_PYTHON nicht gesetzt ist und ~/.config/llm-finetune/unsloth-python nicht existiert, und schreiben Sie den Pfad als erste Zeile dieser Datei (mit seiner Zustimmung): Der Launcher liest ihn daraus.
• Den Runs-Ordner, in den die Ausgabeordner kommen, außerhalb eines Git-Checkouts. <runs> unten ist sein absoluter Pfad.

Schritte

1. Daten prüfen

${CLAUDE_SKILL_DIR}/scripts/run check_data.py <data> --eval <eval.jsonl>

Muss ok ausgeben. Es schlägt fehl bei defekten Zeilen, Konversationen, die nicht mit einer Assistant-Antwort enden, und Validierungs- oder Evaluierungsprompts, die auch im Training vorkommen, mit derselben oder einer anderen Antwort: Das Modell hat sie gesehen, daher messen sie den Recall. Die Lösung ist, sie aus der Validierung oder Evaluierung zu entfernen (oder zu korrigieren, wie die Daten aufgeteilt werden), niemals das Training zu ändern, um die Prüfung zu bestehen. Es berichtet auch, wie Systemnachrichten verwendet werden: keine, eine gemeinsame oder gemischt (siehe references/chat-formats.md).

2. Maschinenvorprüfung

${CLAUDE_SKILL_DIR}/scripts/run preflight.py --params-b <Milliarden Parameter> --out <runs>/<run>

Freier GPU-Speicher ist wichtiger als der gesamte: Spiele, ein Browser mit GPU-Beschleunigung oder ein Modell, das ein lokaler Server noch hält (ollama ps, entladen mit ollama stop <model>), können zu wenig übrig lassen. Wenn die Vorprüfung andere GPU-Nutzer auflistet, informieren Sie den Benutzer und lassen Sie ihn entscheiden, töten Sie keine Prozesse. Mit --params-b schätzt es den Bedarf (ein 3B-Modell in 4-Bit erreichte bei Sequenzlänge 1024 und Batch-Größe 4 einen Spitzenwert von 6,6 GiB, ein 7B-Modell 8,1 GiB) und gibt, wenn der freie Speicher geringer ist, das zu verwendende Paar --batch-size/--grad-accum aus. Es ist eine Schätzung aus zwei Läufen: Für andere Größen oder Sequenzlängen übergeben Sie --need-gib und beobachten Sie den Spitzenwert, den der Testlauf meldet.

Wenn ein Import fehlschlägt, ist die Umgebung defekt. Siehe references/troubleshooting.md, bevor Sie etwas neu installieren.

3. Testlauf

${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>-smoke --max-steps 2

Lesen Sie die Ausgabe, prüfen Sie nicht nur den Exit-Code:

• Das erste Beispiel wie gerendert: Die Systemzeile oben ist das, was das Modell erwarten lernt,
• die Token, die Verlust erhalten: nur die Antwort, nicht die Frage,
• Tokenlängen: Eine Trunkierungswarnung bedeutet Erhöhen von --max-seq-length oder Verwerfen von Beispielen,
• den System-Turn, den ein Server senden muss, und die Warnungen dazu. Eine Denkvorlage (Qwen3, Qwen3.5) fügt einen leeren thinking response-Block vor jede trainierte Antwort ein: Teilen Sie dem Benutzer mit, dass die App ihn in Antworten erhalten und entfernen muss.

4. Vollständiger Lauf

${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>

Läuft eine Weile (Minuten für ein paar tausend Beispiele bei einem 3B-Modell, länger für 7B). Starten Sie es mit der Hintergrundoption des Bash-Tools, anstatt eine Sitzung offen zu halten (das Tool behält die Ausgabe in einer Datei, das ist das Log: Fügen Sie keine >, ; oder && zum Befehl hinzu, die Vorabgenehmigung deckt den Launcher-Befehl genau wie gezeigt ab), und überprüfen Sie es mit ${CLAUDE_SKILL_DIR}/scripts/run train_status.py <runs>/<run>: Schritt, Verluste, der Schritt mit dem niedrigsten Validierungsverlust und die verbleibende Zeit, Stand des letzten Checkpoints. Nach einem Absturz verwenden Sie --resume. Berichten Sie Trainings- und Validierungsverlust sowie den Spitzen-GPU-Speicher. Ein Validierungsverlust weit über dem Trainingsverlust bedeutet Überanpassung: Weniger Epochen oder mehr Daten.

5. Export

${CLAUDE_SKILL_DIR}/scripts/run export_gguf.py --run <runs>/<run>

Dauert einige Minuten für ein 3B-Modell und mehr als zehn für ein 7B-Modell (Zusammenführen, Konvertieren, Quantisieren), was länger ist, als das Bash-Tool einen Vordergrundbefehl laufen lässt: Starten Sie es im Hintergrund wie das Training und warten Sie, bis es fertig ist. Es schreibt die GGUF in <run>/gguf/ und zeichnet sie in run.json mit ihrer Größe und Prüfsumme auf. Es entfernt das zusammengeführte 16-Bit-Modell (mehrere GB, --keep-merged behält es, und dann bleibt die GGUF in <run>/gguf_gguf/) und die Modell-Datei, die Unsloth neben der GGUF schreibt: Diese verwendet die Standardvorlage, nicht das Layout, das beim Training verwendet wurde, befolgen Sie also nicht Unsloths Hinweis, daraus ollama create zu machen. Erwarten Sie eine [CRITICAL]-Warnung über den Konverter von llama.cpp bei jedem Export; erklären Sie dem Benutzer, was sie bedeutet (references/troubleshooting.md), sie stoppt den Export nicht. Der Ausgabeordner ist jetzt bereit für das Serving: Fahren Sie mit dem ollama-model-Skill fort oder übergeben Sie den chat-Abschnitt von run.json an das Serving (references/run-json.md).

6. Aufräumen (vorher fragen)

Sobald das Modell exportiert und evaluiert ist, bieten Sie an, zu löschen, was nur zum Fortsetzen oder zum Überprüfen des Setups benötigt wird: <run>/checkpoints/ (für --resume, mehrere GB bei einem 7B-Modell) und den <run>-smoke-Ordner. Geben Sie an, wie viel Speicherplatz jedes benötigt, und löschen Sie nur das, dem der Benutzer zustimmt. Behalten Sie adapter/ und run.json: Sie sind klein und das, was ein neuer Export und die Versionshinweise benötigen.

Regeln

• Ändern Sie niemals den Datensatz, um eine Evaluierung besser aussehen zu lassen, und evaluieren Sie niemals auf Trainingsdaten.
• Installieren oder aktualisieren Sie keine Pakete in der Unsloth-Umgebung ohne Nachfrage: Die torch/CUDA-Kombination ist empfindlich.
• Fragen Sie vor dem Löschen von Ausgabeordnern oder Checkpoints.