wshobson/quantized-export

Quantisierter Export

Die letzte Station, nachdem checkpoint-promotion einen PROMOTE-Befund abgegeben hat: Ein Checkpoint, der die vierstufige Hürde bestanden hat, wird erst dann eingesetzt, wenn er im richtigen Format für die Ziel-Laufzeit exportiert wurde und nach dem Export noch funktioniert. Ein REJECT-Befund erreicht dieses Skill nie – der Export beginnt nur mit einem promoteden Checkpoint.

Eingabe: Ein promoteder Checkpoint (oder LoRA-Adapter) plus die Ziel-Einsatzoberfläche – GPU-Klasse, Serving-Stack und ob Long-Context/Code/Math-Workloads im Rahmen sind. Ausgabeformat: Ein exportiertes Artefakt im gewählten Format plus einen Smoke-Test-Diff-Bericht, der 3-5 Gold-Ausgaben vor und nach dem Export vergleicht.

Format-Map

Wähle das Format nach Hardware- und Deploy-Form, nicht aus Gewohnheit – die falsche Wahl verschwendet entweder Durchsatzreserven oder bricht bei bestimmten Workloads stillschweigend (siehe Workload-Overrides).

• FP8 ist der Standard auf Hopper-Klasse GPUs und neuer. Es erhält eine nahezu bf16-Qualität bei etwa halbem Speicher und ist die sichere erste Wahl, wann immer die Ziel-GPU es unterstützt und keine Edge-Device-Einschränkung vorliegt.
• AWQ INT4 zielt auf ältere GPUs ab, die keine FP8-Hardware unterstützen. GPTQ ist für neue Deployments überholt – greife bei einem frischen Export nicht darauf zurück; AWQ hat bei gleicher Bitbreite eine bessere Genauigkeitserhaltung und breitere aktuelle Tooling-Unterstützung.
• GGUF mit Q4_K_M-Quantisierung, erstellt mit einem imatrix, ist das Edge/llama.cpp-Format. Verwende es für lokales oder CPU-nahes Deployment, nicht für GPU-Serving-Durchsatz – es optimiert auf Speicherfußabdruck, nicht auf Tokens/Sekunde auf einer Rechenzentrums-GPU.
• NVFP4 ist ausschließlich für Blackwell-at-Scale-Deployments gedacht – und explizit NICHT auf GB10. NVFP4 auf SM121 (GB10) läuft ~32% langsamer als FP8, weil die Hardware keinen nativen cvt.e2m1x2-Pfad hat, es sei denn, der Kernel wird als sm_121a kompiliert. Die Wahl von NVFP4 auf einem GB10-Ziel ist ein Rückschritt, kein Upgrade – wähle dort stattdessen FP8.
• Merged vs. LoRA-only ist eine separate Achse vom Quant-Format. Ein merged Export faltet den Adapter in die Basisgewichte: größeres Artefakt, keine Basis-Modell-Abhängigkeit zur Serve-Zeit. LoRA-only behält den Adapter separat: viel kleineres Artefakt, aber der Serving-Stack muss genau das gleiche Basismodell daneben laden – ein falsches oder falsches-Revisions-Base ändert stillschweigend die Ausgaben. Wähle merged, wenn Artefakt-Portabilität wichtiger ist als Speicher; wähle LoRA-only, wenn Speicherfußabdruck oder Multi-Adapter-Serving wichtiger ist.

Ausgewählte Beispiele

Der Kern des Format-Auswahl-Tradeoffs, als Nachschlagetabelle für häufige Szenarien:

Ziel	Workload	Format
Rechenzentrums-GPU	generischer Chat	FP8
Rechenzentrums-GPU	Long-Context/Code/Math	FP8 oder W8A8 – niemals INT4
Ältere GPU-Generation	generisch	AWQ INT4
Edge-Gerät / Laptop	llama.cpp-Serving	GGUF Q4_K_M + imatrix
GB10	beliebiger Workload	FP8 via vLLM Nightly, oder GGUF via llama.cpp lokal – NVFP4 überspringen

# schnelles Entscheidungs-Snippet – siehe die Tabelle oben für die vollständige Karte
hopper_or_newer: fp8
older_gpu: awq-int4
edge_llama_cpp: gguf-q4_k_m+imatrix
gb10_any_workload: fp8-vllm-nightly   # niemals nvfp4 auf GB10

Workload-Overrides

Die Format-Map oben ist ein Standard, keine Regel, die jeden Workload überlebt. Long-Context-, Code- und Math-Workloads brechen bei INT4 – Quantisierungsfehler akkumulieren sich über lange Sequenzen und präzise Token-Level-Argumentation in einer Weise, die bei kurzen, generischen Prompts nicht auftritt. Für jede dieser drei Workload-Klassen bleibe bei FP8 oder W8A8, selbst wenn die Ziel-Hardware sonst INT4 aus Kostengründen rechtfertigen würde.

• Validiere dieses Override nicht mit MMLU oder ähnlichen breiten Wissens-Benchmarks – sie betonen die Fehlerart nicht. Messe mit den tatsächlichen Task-Evals – den Goldenen und Gradern aus eval-harness-first, ausgeführt durch das exportierte Artefakt – weil INT4-Degradation bei Long-Context, Code oder Math als aufgabenspezifische Fehler (verlorener Kontext, kaputte Syntax, Rechenfehler) auftritt, lange bevor sie einen Wissens-Benchmark verschiebt.
• Wenn ein Task-Eval nach einem INT4-Export bei einer dieser drei Workload-Klassen zurückgeht, ist die Lösung das Wechseln des Formats, nicht das Neuanpassen des Quantisierungsrezepts – AWQ- und GPTQ-Varianten bei gleicher Bitbreite teilen den gleichen Akkumulationsfehler-Fehlermodus bei diesen Workloads.

Der Smoke-Test

Exportfehler sind auf Dateiebene still – ein fehlerhafter Export erzeugt trotzdem ein ladbares Artefakt, daher beweisen Datei-existenz-Prüfungen nichts. Der Smoke-Test ist für jeden Export obligatorisch, ohne Ausnahme für ein Format, das „einfach funktionieren sollte“:

1. Lade das exportierte Artefakt in seiner tatsächlichen Ziel-Laufzeit – vLLM für FP8/AWQ, llama.cpp für GGUF, nicht eine kurze Sanity-Prüfung in einem anderen Framework als dem, das es in Produktion bedient.
2. Führe 3–5 Gold-Prompts durch – nimm diese aus demselben eval/goldens.jsonl, das eval-harness-first verwaltet, nicht aus einem frischen Ad-hoc-Satz.
3. Vergleiche jede Ausgabe mit der Pre-Export-Generation für denselben Prompt, dieselben deterministischen Sampling-Einstellungen – Greedy-Decoding (Temperatur 0) und einen festen Seed, beibehalten und wiederverwendet zwischen den Pre- und Post-Export-Durchläufen, nicht nur nominell identische Konfiguration. Bei einem verlustfreien Export ist Byte-Match die Hürde – jeder Unterschied ist ein Fehler. Bei einem verlustbehafteten (quantisierten) Export ist Byte-Match voraussichtlich fehlgeschlagen; die Hürde ist stattdessen die Übereinstimmung der Task-Grader-Befunde – siehe references/export-commands.md 's Smoke-Test-Script-Skeleton.

Führe dies als eine Hürde aus, nicht als manuelle Prüfung:

python smoke_test.py "$EXPORT_PATH" \
    eval/goldens.jsonl pre-export-outputs.jsonl
# non-zero exit on any pre/post mismatch

Fehlersignaturen

Wie Exportfehler tatsächlich aussehen, nicht nur ein sauberes Bestanden/Nicht-Bestanden-Flag:

• Template-Mismatch erscheint als verstümmelte oder zusammenhanglose Ausgabe – das Chat-Template, das in den Export eingebacken ist, stimmt nicht mit dem überein, gegen das der Checkpoint trainiert und evaluiert wurde, sodass Wendepunkte oder spezielle Tokens an der falschen Stelle landen.
• Falsche Quantisierung auf lm_head angewendet erscheint als nicht-vorlagenkonforme oder semantisch sinnlose Ausgabe, die trotzdem flüssig aussieht – der Ausgabekopf verlor an Genauigkeit, die er brauchte, obwohl der Rest des Netzwerks sauber quantisiert wurde.

Liefere niemals einen Export aus, der diesen Schritt übersprungen hat – der PROMOTE-Befund eines Checkpoints sagt, dass der nicht-exportierte Checkpoint gut ist; er sagt nichts über die Export-Pipeline. Führe ihn bei jedem Update der Quant-Methode oder Runtime-Version erneut aus, nicht nur nach dem ersten Export. Ausführbare Befehlssequenzen für jedes Format plus das Smoke-Test-Script-Skeleton: references/export-commands.md.

Verwandte Skills

• checkpoint-promotion – die einzige gültige Upstream-Quelle für dieses Skill. Ein Checkpoint ohne PROMOTE-Befund erreicht den Export nicht.
• eval-harness-first – verwaltet das eval/goldens.jsonl, aus dem der Smoke-Test dieses Skills seine 3–5 Prompts bezieht, sowie die Task-Evals, die der Abschnitt Workload-Overrides für die Long-Context-/Code-/Math-Validierung benötigt.
• finetuning-method-selection – sein references/model-catalog.md ist der Ort, um Hardware-Klassen-Annahmen (welche GPU-Generationen ein Basismodell anzielt) zu überprüfen, bevor ein Format aus der Format-Map oben ausgewählt wird.

Spark-Benutzer: Auf GB10 funktioniert GGUF via llama.cpp gut für lokales Serving, und FP8-Serving via vLLM Nightly-Builds ist der andere bewährte Pfad – NVFP4 ist das eine Format, das dort vermieden werden sollte (siehe Ausnahme in der Format-Map oben). Sobald das dgx-spark-ops-Plugin installiert ist, verweise Spark-spezifisches Serving und thermische Fragen an seine Skills, anstatt sie hier neu abzuleiten.