Portage et optimisation de modèles MLX

Que fait Portage et optimisation de modèles MLX ?

Mission

Produire une implémentation MLX correcte, reproductible et consciente de l'architecture. La correction prime sur la vitesse. Toute affirmation de vitesse ou de mémoire doit nommer le matériel, les versions logicielles, la charge de travail, la référence et le seuil de qualité.

Règles non négociables

1. N'exécutez pas de code de modèle non fiable pendant la phase d'intake. Inspectez statiquement les fichiers JSON, les en-têtes safetensors, les fichiers source et les licences. Considérez auto_map, les modules personnalisés, les hooks d'installation et trust_remote_code comme des points de contrôle de révision.
2. Figez la source. Enregistrez le dépôt, la révision, les fichiers du modèle, la révision du tokenizer/processor, la licence et la somme de contrôle ou le manifeste de l'artefact.
3. Construisez un oracle source avant le portage. Figez des fixtures déterministes et capturez les tenseurs intermédiaires à des frontières significatives.
4. Portez d'abord le chemin eager le plus petit. Pas de quantification, compilation, noyaux personnalisés, batching ou décodage spéculatif tant que la parité de base n'est pas atteinte.
5. Modifiez une seule dimension d'optimisation à la fois. Tenez un registre des mesures et des retours en arrière.
6. Privilégiez les opérations MLX natives. Essayez les opérations fusionnées intégrées, les changements de disposition, la conception de cache et mx.compile avant un noyau Metal personnalisé.
7. Ne traduisez pas mécaniquement les pratiques CUDA. Une technique CUDA n'est qu'un candidat à la recherche tant que son goulot d'étranglement Metal/MLX et son implémentation ne sont pas démontrés.
8. Ne masquez jamais les régressions de qualité derrière le débit. Pour les modèles audio, linguistiques, visuels et génératifs, utilisez des contrôles de qualité spécifiques à la tâche en plus des tolérances tensorielles.
9. Ne publiez pas de poids convertis sans vérification de licence et de provenance. Conservez la fiche modèle originale, l'attribution, la configuration de génération, les fichiers tokenizer/processor et la recette de conversion.
10. L'automatisation quotidienne de la recherche est en mode révision uniquement. Elle peut collecter et classer des candidats, mais ne doit pas réécrire silencieusement les runbooks ni fusionner les recommandations.

Flux de travail

1. Inspecter et classer

Exécutez :

python3 scripts/inspect_model.py MODEL_OR_DIRECTORY --output inspection.json
python3 scripts/make_port_plan.py inspection.json --output PORT_PLAN.md
python3 scripts/recommend_optimizations.py inspection.json --markdown OPTIMIZATIONS.md

Lisez intake et routage. Confirmez :

• la tâche et le domaine du modèle ;
• la famille d'architecture et l'état récurrent/cache ;
• le framework source et les opérations personnalisées ;
• le nombre de paramètres, les dtypes, les poids liés/partagés, les fragments et les adaptateurs ;
• le prétraitement, la tokenisation, l'échantillonnage et le post-traitement ;
• la licence et le risque de code distant ;
• le Mac cible, le budget mémoire, l'objectif de latence/débit et l'objectif de qualité.

Ne commencez pas l'implémentation si l'architecture, la révision source ou la cible d'évaluation reste ambiguë. Enregistrez les incertitudes dans PORT_PLAN.md plutôt que de deviner.

2. Sélectionner la référence MLX éprouvée la plus proche

Consultez la carte de support des modèles et assets/architectures.yaml.

Utilisez cet ordre :

1. implémentation officielle MLX / MLX-LM ;
2. implémentation active MLX-VLM ou MLX-Audio avec tests ;
3. implémentation MLX tierce active ;
4. implémentation source amont plus article d'architecture ;
5. prototype de recherche nécessitant une nouvelle implémentation MLX.

Réutilisez les motifs architecturaux, pas les hypothèses recopiées. Vérifiez la sémantique de la configuration et les dispositions des tenseurs par rapport à la source figée.

3. Établir l'oracle source

Suivez parité et tests :

• définissez des graines déterministes et le mode inférence ;
• sauvegardez les entrées exactes après le prétraitement ;
• capturez la forme/dtype/statistiques et les tenseurs sélectionnés après les embeddings/frontaux, chaque groupe de blocs, le goulot d'étranglement, la mise à jour du cache, les logits/latences et la sortie du décodeur/vocodeur ;
• sauvegardez les sorties source dans des fixtures portables .npz, .json ou .wav ;
• enregistrez les tolérances par dtype et opération ;
• incluez au moins un cas minimal, un cas ordinaire et un cas limite.

4. Implémenter le graphe MLX eager minimal

Lisez méthode de portage de base et le runbook d'architecture correspondant :

• Transformeur décodeur dense
• Transformeur Mixture-of-Experts
• Transformeur encodeur
• Transformeur encodeur-décodeur
• SSM, récurrent et hybride
• Diffusion et flow
• Vision-langage et omni
• Codec audio neural
• Modèle LM audio autorégressif / TTS
• Flow ou diffusion TTS
• Vocodeur
• ASR
• Parole en streaming
• Séparation et amélioration

Contraintes d'implémentation initiale :

• poids en virgule flottante uniquement ;
• taille de lot un, sauf si le batching est intrinsèque ;
• pas de décorateur compile ;
• pas de noyaux personnalisés ;
• objets d'état et de cache explicites ;
• assertions de forme autour de chaque transformation non triviale ;
• manifeste de carte de poids réversible.

5. Convertir les poids de manière déterministe

Créez une carte de poids avec clé source, clé cible, forme source, forme cible, transformation, dtype et règle de liaison/partage. Validez-la :

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

Ne vous fiez jamais à strict=False au moment du chargement pour dissimuler des poids manquants ou supplémentaires. Catégorisez chaque exception comme intentionnellement ignorée, générée, partagée ou non prise en charge.

6. Passer l'échelle de parité

Utilisez scripts/compare_tensors.py et passez, dans l'ordre :

1. parité de la configuration et du prétraitement ;
2. couverture des poids et parité des formes transformées ;
3. parité d'un seul bloc/primitive ;
4. parité intermédiaire par étape ;
5. parité déterministe de bout en bout ;
6. parité de qualité de tâche ;
7. parité du cache/état et de la génération incrémentielle ;
8. parité des cas limites, des longues entrées, du streaming et du batching.

En cas d'échec de parité, utilisez atlas des échecs. N'optimisez pas un graphe défaillant.

7. Profiler avant de choisir les optimisations

Lisez benchmarking. Séparez :

• le temps de préremplissage/encodeur/frontal ;
• le temps de décodage par token ou par trame ;
• le temps du codec/vocodeur/post-traitement ;
• le coût de compilation et de première exécution ;
• la mémoire maximale et en régime permanent ;
• le déplacement des données, la synchronisation et la surcharge Python.

Utilisez :

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

8. Appliquer l'échelle d'optimisation

Consultez assets/optimization_guidance.yaml, assets/recommendation-taxonomy.yaml, assets/techniques.yaml et chargez uniquement les guides pertinents :

1. Exécution, compilation et noyaux MLX
2. Attention et cache KV
3. Décodage et service
4. Quantification
5. Entraînement et fine-tuning

Ordre par défaut :

1. supprimez les évaluations involontaires et les transferts hôte ;
2. corrigez le dtype et la disposition des tenseurs ;
3. utilisez des opérations fusionnées natives et SDPA rapide ;
4. réduisez les allocations et rendez les mises à jour d'état/cache explicites ;
5. compilez les régions stables et contrôlez la recompilation ;
6. fragmentez le préremplissage/les frontaux ou streamifiez là où l'architecture le permet ;
7. optimisez la politique de cache/KV et le batching ;
8. quantifiez les poids, puis le KV/l'état si justifié ;
9. ajoutez un décodage spéculatif ou multi-token uniquement pour les chemins autorégressifs compatibles ;
10. écrivez un noyau Metal personnalisé uniquement après qu'un profilage prouve un goulot d'étranglement résiduel du noyau.

Pour chaque changement, enregistrez l'hypothèse, le diff, le résultat de correction, le résultat de benchmark, le résultat mémoire, le résultat qualité et la décision de conserver/revenir.

9. Empaqueter et publier

Suivez empaquetage et publication. Incluez :

• la source figée et la commande de conversion ;
• les versions compatibles de MLX et des bibliothèques ;
• les fichiers modèle/config/tokenizer/processor ;
• la recette exacte de quantification et les exclusions ;
• un test de fumée déterministe ;
• le protocole de benchmark et les résultats bruts ;
• les limitations connues ;
• la licence originale et l'attribution ;
• aucun terme non pris en charge comme « plus rapide » ou « sans perte ».

10. Rendre un rapport d'ingénierie

La réponse finale doit résumer :

• l'architecture et le runbook sélectionné ;
• la révision source et les références de preuve ;
• le statut de l'implémentation et de la carte de poids ;
• la matrice de parité ;
• les métriques de référence et optimisées ;
• les optimisations acceptées et rejetées ;
• les risques restants et les chemins non pris en charge ;
• les commandes reproductibles et les emplacements des artefacts.

Utilisez les modèles dans assets/.

Quand s'arrêter

Arrêtez-vous et signalez plutôt que d'improviser lorsque :

• la licence source interdit la distribution demandée ;
• le comportement source requis n'existe que dans un code distant non examiné ;
• la parité ne peut pas être localisée après les vérifications par étapes ;
• une optimisation améliore un micro-benchmark mais dégrade la latence de bout en bout, la mémoire ou la qualité ;
• un noyau personnalisé manque d'une solution de repli portable ou de tests adéquats ;
• le matériel, la version MLX, la charge de travail ou l'objectif de qualité sont absents d'une affirmation de performance.

Maintenance

Pour la révision des sources, la sécurité et le pipeline quotidien de candidats, lisez maintenance et provenance. Exécutez scripts/audit_skill.py et scripts/validate_sources.py avant de distribuer cette compétence.