Amal-David/mlx-porting-skill

MLX-Modellportierung und -optimierung

Mission

Erstellen einer korrekten, reproduzierbaren, architekturbewussten MLX-Implementierung. Korrektheit hat Vorrang vor Geschwindigkeit. Jede Geschwindigkeits- oder Speicherbehauptung muss Hardware, Softwareversionen, Arbeitslast, Baseline und Qualitätskriterium nennen.

Unverhandelbare Regeln

1. Führe während der Aufnahme keinen nicht vertrauenswürdigen Modellcode aus. Überprüfe JSON, safetensors-Header, Quelldateien und Lizenzen statisch. Behandle auto_map, benutzerdefinierte Module, Installationshaken und trust_remote_code als Review-Gates.
2. Fixiere die Quelle. Erfasse Repository, Revision, Modelldateien, Tokenizer/Processor-Revision, Lizenz und Prüfsumme oder Artefakt-Manifest.
3. Erstelle vor dem Portieren ein Quell-Orakel. Friere deterministische Fixtures ein und erfasse Zwischentensoren an sinnvollen Grenzen.
4. Portiere zuerst den kleinsten Eager-Pfad. Keine Quantisierung, Kompilierung, benutzerdefinierte Kernel, Batching oder spekulative Dekodierung, bis grundlegende Parität erreicht ist.
5. Ändere jeweils eine Optimierungsdimension. Führe ein Mess- und Rückfallprotokoll.
6. Bevorzuge native MLX-Operationen. Versuche zuerst integrierte Fused-Operationen, Layoutänderungen, Cache-Design und mx.compile, bevor du einen benutzerdefinierten Metal-Kernel schreibst.
7. Übersetze CUDA-Folklore nicht mechanisch. Eine CUDA-Technik ist erst ein Forschungskandidat, wenn ihr Metal/MLX-Engpass und ihre Implementierung nachgewiesen sind.
8. Verstecke Qualitätsverluste niemals hinter Durchsatz. Verwende bei Audio-, Sprach-, Bild- und generativen Modellen aufgabenspezifische Qualitätsprüfungen zusätzlich zu Toleranzen für Tensoren.
9. Veröffentliche keine konvertierten Gewichte ohne Lizenz- und Herkunftsprüfung. Bewahre die ursprüngliche Modellkarte, Quellenangabe, Generierungskonfiguration, Tokenizer/Processor-Dateien und das Konvertierungsrezept auf.
10. Tägliche Forschungsautomatisierung dient nur dem Review. Sie kann Kandidaten sammeln und bewerten, darf aber nicht stillschweigend Runbooks überschreiben oder Empfehlungen zusammenführen.

Arbeitsablauf

1. Inspizieren und klassifizieren

Führe aus:

python3 scripts/inspect_model.py MODELL_ODER_VERZEICHNIS --output inspection.json
python3 scripts/make_port_plan.py inspection.json --output PORT_PLAN.md
python3 scripts/recommend_optimizations.py inspection.json --markdown OPTIMIERUNGEN.md

Lies Aufnahme und Routing. Bestätige:

• Aufgabe und Modelldomäne;
• Architekturfamilie und rekurrenten/Cache-Zustand;
• Quell-Framework und benutzerdefinierte Operationen;
• Parameteranzahl, dtypes, tied/shared-Gewichte, Shards und Adapter;
• Vorverarbeitung, Tokenisierung, Sampling und Nachbearbeitung;
• Lizenz und Remote-Code-Risiko;
• Ziel-Mac, Speicherbudget, Latenz-/Durchsatz-Ziel und Qualitätsziel.

Beginne nicht mit der Implementierung, wenn die Architektur, die Quellrevision oder das Evaluierungsziel mehrdeutig bleibt. Halte Unsicherheiten in PORT_PLAN.md fest, anstatt zu raten.

2. Wähle die nächste bewährte MLX-Referenz

Konsultiere Modellunterstützungskarte und assets/architectures.yaml.

Verwende diese Reihenfolge:

1. offizielle MLX / MLX-LM-Implementierung;
2. aktive MLX-VLM- oder MLX-Audio-Implementierung mit Tests;
3. aktive Drittanbieter-MLX-Implementierung;
4. Upstream-Quellimplementierung plus Architekturpapier;
5. Forschungsprototyp, der eine neue MLX-Implementierung erfordert.

Verwende architektonische Muster wieder, nicht kopierte Annahmen. Überprüfe Konfigurationssemantik und Tensor-Layouts anhand der fixierten Quelle.

3. Erstelle das Quell-Orakel

Befolge Parität und Testen:

• setze deterministische Seeds und Inferenzmodus;
• speichere exakte Eingaben nach der Vorverarbeitung;
• erfasse Form/dtype/Statistiken und ausgewählte Tensoren nach Embeddings/Frontends, jeder Blockgruppe, Engpass, Cache-Aktualisierung, Logits/Latents und Decoder/Vocoder-Ausgabe;
• speichere Quellausgaben in portablen .npz-, .json- oder .wav-Fixtures;
• protokolliere Toleranzen nach dtype und Operation;
• füge mindestens einen minimalen, einen gewöhnlichen und einen Grenzfall ein.

4. Implementiere den minimalen Eager-MLX-Graphen

Lies Kern-Portierungsmethode und das passende Architektur-Runbook:

• Dense-Decoder-Transformer
• Mixture-of-Experts-Transformer
• Encoder-Transformer
• Encoder-Decoder-Transformer
• SSM, rekurrent und hybrid
• Diffusion und Flow
• Vision-Language und Omni
• Neuraler Audio-Codec
• Autoregressives Audio-LM / TTS
• Flow- oder Diffusions-TTS
• Vocoder
• ASR
• Streaming-Sprache
• Separation und Verbesserung

Einschränkungen der ersten Implementierung:

• nur Gleitkomma-Gewichte;
• Batch-Größe eins, es sei denn, Batching ist inhärent;
• kein compile-Decorator;
• keine benutzerdefinierten Kernel;
• explizite Zustands- und Cache-Objekte;
• Formbehauptungen um jede nichttriviale Transformation;
• umkehrbares Gewichtskarten-Manifest.

5. Konvertiere Gewichte deterministisch

Erstelle eine Gewichtskarte mit Quellschlüssel, Zielschlüssel, Quellform, Zielform, Transformation, dtype und Tie/Share-Regel. Validiere sie:

python3 scripts/validate_weight_map.py   --source source-manifest.json   --target target-manifest.json   --mapping WEIGHT_MAP.json

Verlasse dich niemals auf strict=False zur Ladezeit, um fehlende oder zusätzliche Gewichte zu verbergen. Kategorisiere jede Ausnahme als absichtlich ignoriert, generiert, geteilt oder nicht unterstützt.

6. Bestehe die Paritätsleiter

Verwende scripts/compare_tensors.py und bestehe in dieser Reihenfolge:

1. Konfigurations- und Vorverarbeitungsparität;
2. Gewichtsabdeckung und Parität der transformierten Form;
3. Parität einzelner Primitive/Blöcke;
4. stufenweise Zwischenparität;
5. Ende-zu-Ende-deterministische Parität;
6. Aufgabenqualitätsparität;
7. Cache/Zustands- und inkrementelle Generierungsparität;
8. Grenz-, Langzeiteingabe-, Streaming- und Batch-Parität.

Wenn die Parität fehlschlägt, verwende das Fehleratlas. Optimiere keinen fehlschlagenden Graphen.

7. Profiliere vor der Auswahl von Optimierungen

Lies Benchmarking. Trenne:

• Prefill/Encoder/Frontend-Zeit;
• Pro-Token- oder Pro-Frame-Dekodierzeit;
• Codec/Vocoder/Nachbearbeitungszeit;
• Kompilierungs- und Erster-Lauf-Kosten;
• Spitzen- und stationären Speicher;
• Datenbewegung, Synchronisation und Python-Overhead.

Verwende:

python3 scripts/benchmark_command.py --warmup 2 --runs 8 --output benchmark.json -- BEFEHL ...

8. Wende die Optimierungsleiter an

Konsultiere assets/optimization_guidance.yaml, assets/recommendation-taxonomy.yaml, assets/techniques.yaml und lade nur relevante Leitfäden:

1. MLX-Laufzeit, Kompilierung und Kernel
2. Attention und KV-Cache
3. Dekodierung und Serving
4. Quantisierung
5. Training und Feintuning

Standardreihenfolge:

1. unbeabsichtigte Auswertungen und Host-Übertragungen entfernen;
2. korrekten dtype und Tensor-Layout verwenden;
3. native Fused-Operationen und schnelle SDPA verwenden;
4. Allokationen reduzieren und Zustands-/Cache-Aktualisierungen explizit machen;
5. stabile Regionen kompilieren und Rekompilierung kontrollieren;
6. Prefill/Frontends chunken oder streamen, wenn die Architektur es erlaubt;
7. KV/Cache-Richtlinie und Batching optimieren;
8. Gewichte quantisieren, dann KV/Zustand falls gerechtfertigt;
9. spekulative oder Multi-Token-Dekodierung nur für kompatible autoregressive Pfade hinzufügen;
10. benutzerdefinierten Metal-Kernel erst nach Profilerstellung schreiben, die einen verbleibenden Kernel-Engpass beweist.

Für jede Änderung protokolliere Hypothese, Diff, Korrektheitsergebnis, Benchmarkergebnis, Speicherergebnis, Qualitätsergebnis und Entscheidung behalten/zurücknehmen.

9. Paketieren und veröffentlichen

Befolge Paketierung und Veröffentlichung. Füge hinzu:

• fixierte Quelle und Konvertierungsbefehl;
• kompatible MLX- und Bibliotheksversionen;
• Modell/Konfiguration/Tokenizer/Processor-Dateien;
• genaues Quantisierungsrezept und Ausnahmen;
• deterministischer Smoke-Test;
• Benchmark-Protokoll und Rohdaten;
• bekannte Einschränkungen;
• ursprüngliche Lizenz und Quellenangabe;
• keine nicht unterstützten Formulierungen wie „schneller“ oder „verlustfrei“.

10. Gib einen Engineering-Bericht zurück

Die endgültige Antwort muss zusammenfassen:

• Architektur und ausgewähltes Runbook;
• Quellrevision und Nachweisreferenzen;
• Implementierungs- und Gewichtskartenstatus;
• Paritätsmatrix;
• Baseline- und optimierte Metriken;
• akzeptierte und abgelehnte Optimierungen;
• verbleibende Risiken und nicht unterstützte Pfade;
• reproduzierbare Befehle und Artefaktstandorte.

Verwende die Vorlagen in assets/.

Wann aufhören

Stoppe und berichte, anstatt zu improvisieren, wenn:

• die Quelllizenz die angeforderte Verteilung verbietet;
• erforderliches Quellverhalten nur in nicht überprüftem Remote-Code existiert;
• Parität nach den stufenweisen Prüfungen nicht lokalisiert werden kann;
• eine Optimierung einen Mikrobenchmark verbessert, aber die Ende-zu-Ende-Latenz, den Speicher oder die Qualität verschlechtert;
• einem benutzerdefinierten Kernel ein portabler Fallback oder ausreichende Tests fehlen;
• Hardware, MLX-Version, Arbeitslast oder Qualitätsziel in einer Leistungsbehauptung fehlen.

Wartung

Für Quellüberprüfung, Sicherheit und die tägliche Kandidaten-Pipeline lies Wartung und Herkunft. Führe scripts/audit_skill.py und scripts/validate_sources.py aus, bevor du dieses Skill verteilst.