huggingface/peft: Adapter statt Volltraining, mit Grenzen

Welches Problem peft löst und für wen es gedacht ist

Das Repository adressiert einen konkreten Kostenpunkt: Vollständiges Fine-Tuning großer vortrainierter Modelle ist laut README oft prohibitively costly due to their scale. Wer ein 7B- oder 12B-Modell auf eine eigene Aufgabe anpassen will, muss normalerweise alle Gewichte aktualisieren und damit den gesamten Optimierungszustand im Speicher halten. peft dreht das um. Es trainiert nur eine kleine Zahl zusätzlicher Parameter und lässt die Basismodelle unverändert. Die Zielgruppe sind Anwender, die vortrainierte Modelle auf eine umrissene Domäne nachziehen wollen, ohne einen Cluster zu reservieren. Das README nennt als Beispiel das bigscience/mt0-large-Modell, bei dem nur 0.19% der Parameter trainiert werden. Der Nutzen liegt nicht in besserer Qualität, sondern in kleinerem Speicherbedarf und kleineren Checkpoints.

Der Mechanismus: Basismodell einfrieren, Adapter anhängen

Der Ablauf ist im Quickstart klar erkennbar. Zuerst wird das Basismodell geladen, dann eine Konfiguration erzeugt, und schließlich kapselt get_peft_model das Modell zusammen mit dieser Konfiguration. Ab diesem Punkt sind die ursprünglichen Gewichte nicht mehr das Trainingsziel. Stattdessen werden Adaptergewichte an ausgewählten Modulen eingehängt und trainiert. Bei LoRA steuern r und lora_alpha die Größe und Skalierung dieser Adapter, während task_type festlegt, für welche Art von Aufgabe das Modell vorbereitet wird. Welche Module überhaupt einen Adapter erhalten, bestimmt target_modules; bleibt der Parameter weg, wählt die Bibliothek eine Standardmenge. Nach dem Training schreibt save_pretrained nur die Adapter in ein Verzeichnis wie qwen2.5-3b-lora. Für die Inferenz wird das Basismodell erneut geladen und mit PeftModel.from_pretrained um denselben Adapter ergänzt. Diese Trennung erklärt, warum das README von einem finalen Checkpoint von 19MB gegenüber 11GB beim vollständigen bigscience/T0_3B spricht. Der Preis dafür: Basismodell und Adapter müssen im Deployment zusammenpassen, sonst lädt nichts.

Speicherwerte, die das Repository selbst nennt

Das README enthält eine Tabelle mit Speicherbedarf für das Dataset ought/raft/twitter_complaints auf einer A100 mit 80GB und mehr als 64GB CPU-RAM. Für bigscience/T0_3B (3B Parameter) nennt sie 47.14GB GPU bei Volltraining, 14.4GB GPU mit PEFT-LoRA in PyTorch und 9.8GB GPU mit 17.8GB CPU bei PEFT-LoRA mit DeepSpeed und CPU-Offloading. Für bigscience/mt0-xxl (12B Parameter) steht beim Volltraining OOM GPU, mit PEFT-LoRA 56GB GPU und mit Offloading 22GB GPU bei 52GB CPU. bigscience/bloomz-7b1 (7B Parameter) läuft beim Volltraining ebenfalls in OOM, mit LoRA bei 32GB GPU. Diese Zahlen sind Angaben des Projekts, keine unabhängige Messung. Zwei Dinge fallen auf. Erstens verschiebt CPU-Offloading den Speicher nur, es erzeugt ihn nicht: mt0-xxl braucht mit Offloading 52GB CPU-RAM. Zweitens sind die 12B- und 7B-Spalten beim Volltraining schlicht leer, weil sie auf dieser Hardware nicht laufen. Genau das ist das Verkaufsargument.

Inbetriebnahme mit pip, LoraConfig und get_peft_model

Die Installation ist ein einzelner Befehl: pip install peft. Der Quickstart lädt anschließend ein Modell über AutoModelForCausalLM.from_pretrained mit device_map und übergibt es zusammen mit einer LoraConfig an get_peft_model. Die Konfiguration im Beispiel setzt r=16, lora_alpha=32 und task_type=TaskType.CAUSAL_LM. Danach zeigt model.print_trainable_parameters() die Aufteilung, im Beispiel 3,686,400 trainierbare von 3,089,625,088 Parametern, also 0.1193 Prozent. Gespeichert wird mit model.save_pretrained("qwen2.5-3b-lora"). Für die Inferenz lädt der Code das Basismodell erneut, ruft PeftModel.from_pretrained(model, "qwen2.5-3b-lora") auf und generiert mit model.generate. Wer die Zielmodule selbst festlegen will, aktiviert die auskommentierte Zeile target_modules=["q_proj", "v_proj", ...]. Das ist der einzige Hebel im gezeigten Beispiel, der die Qualität direkt beeinflusst, und er ist standardmäßig nicht gesetzt.

Wo das Verfahren an seine Grenzen stößt

Die Tabelle im README macht die erste Grenze sichtbar: PEFT-LoRA mit DeepSpeed und CPU-Offloading braucht für mt0-xxl 52GB CPU-RAM und 22GB GPU. Wer beides nicht hat, kann das Modell trotzdem nicht trainieren. Die zweite Grenze ist die Qualität. Die Genauigkeitstabelle listet für die Aufgabe twitter_complaints eine Human baseline von 0.897, Flan-T5 mit 0.892 und lora-t0-3b mit 0.863. Der Adapter liegt also unter dem vollständig trainierten Vergleichsmodell, und das README räumt selbst ein, dass die Leistung von bigscience/T0_3B in dieser Tabelle nicht optimiert ist. Wer die letzten Prozentpunkte braucht, zahlt sie mit Speicher oder mit Tuning. Die dritte Grenze ist struktureller Natur: PEFT verändert das Basismodell nicht, kann also kein Wissen ersetzen, das dort fehlt. Für eine neue Sprache oder einen Fachbereich mit stark abweichendem Vokabular ist ein Adapter auf einem unpassenden Basismodell der falsche Ansatz. Und wer viele Kunden mit je eigenem Adapter bedient, muss die Lade- und Verwaltungslogik selbst bauen; das README verweist dafür auf Diffusers, ohne ein Rezept zu liefern.

Was peft von Volltraining und von Quantisierung unterscheidet

Die naheliegende Alternative ist vollständiges Fine-Tuning mit derselben Transformers-Toolchain. Der Unterschied liegt nicht in der API, sondern im Speicher: Volltraining hält Gradienten und Optimierungszustand für alle Parameter, PEFT nur für die Adapter. Deshalb steht in der Tabelle für 12B und 7B beim Volltraining OOM, während LoRA noch läuft. Der zweite Ansatz ist Quantisierung, also das Ablegen der Gewichte in niedrigerer Präzision. Das README behandelt sie nicht als Konkurrenz, sondern als Kombination: QLoRA verbindet beides, und der verlinkte PyTorch-Blogpost beschreibt das Fine-Tuning von meta-llama/Llama-2-7b-hf auf einer 16GB-GPU. Wer ohnehin quantisieren muss, um das Basismodell überhaupt zu laden, kombiniert die Verfahren. Wer dagegen ein kleines Modell auf einer einzelnen Karte vollständig trainieren kann, hat keinen Grund, die zusätzliche Indirektion über Adapter einzuführen.

Wartung, Versionen und Lizenz

Das Repository wird aktiv gepflegt: Der letzte Push liegt bei 2026-09-09, die jüngste Ausgabe ist v0.20.0 vom 2026-07-28, davor v0.19.1 und v0.19.0 im April 2026. Zwischen den Minor-Versionen lagen rund drei Monate. Wer peft produktiv einsetzt, sollte diesen Rhythmus einplanen, denn die Bibliothek hängt an Transformers, Diffusers und Accelerate, und ein Versionssprung in einem dieser Pakete kann die Adapterkompatibilität berühren. Ein Upgrade-Pfad ist im vorliegenden Material nicht dokumentiert; das ist eine Lücke, die man vor einem Produktivstart selbst schließen muss. Zur Lizenz: peft steht unter Apache-2.0. Das betrifft nur den Code der Bibliothek. Die Basismodelle, auf die Adapter trainiert werden, haben eigene Lizenzen, und ein Adapter ist ein abgeleitetes Artefakt, das diese Bedingungen berühren kann. Das README geht darauf nicht ein. Wer Adapter weitergibt, muss die Lizenz des jeweiligen Basismodells prüfen; eine Rechtsberatung ersetzt dieser Hinweis nicht.

Redaktionelles Fazit

Sinnvoll ist PEFT für Teams, die ein vortrainiertes Modell auf eine klar umrissene Aufgabe anpassen und dabei GPU-Speicher sparen müssen; wer ein Basismodell von Grund auf verändern oder sehr große Datenmengen einbringen will, fährt mit Volltraining besser. Vor dem ersten Lauf prüfen: ob die Zielmodule des Modells von target_modules erfasst werden, ob die gespeicherte Adaptergröße in das Deployment passt und welche Lizenz das Basismodell mitbringt, denn die Apache-2.0-Lizenz des Repositories gilt nur für peft selbst.

Offizielle Quellen

1. huggingface/peft on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases