Guide
Fine-tuning sur Mac avec MLX : commandes et limites
Affiner un modèle en LoRA sur un Mac Apple Silicon avec mlx-lm : format des données, commandes de la documentation, réglages mémoire et export.
Mis à jour le
Oui, on peut affiner un modèle de langage sur un Mac à puce Apple, avec le paquet mlx-lm. Son dépôt le présente comme « un paquet Python pour générer du texte et affiner de grands modèles de langage sur Apple silicon avec MLX », sous licence MIT. Il gère LoRA, DoRA et l’affinage complet ; les modèles quantifiés servent notamment à entraîner un adaptateur en QLoRA. Il ne faut pas en déduire que tout type d’entraînement accepte toutes les représentations quantifiées. C'est une voie raisonnable pour un premier essai avec un petit modèle ; pour un gros volume ou un gros modèle, une machine à carte graphique reste le cadre habituel de la bibliothèque TRL de Hugging Face. Pour faire tourner des modèles sur Mac sans les entraîner, voir LLM local sur Mac Apple Silicon.
Ce qui suit reprend la page LORA.md du dépôt, lue le 16/11/2026. Les commandes reprennent la documentation ; remplacez les chemins et les valeurs entre chevrons avant exécution. Les chevrons non remplacés seraient interprétés par le shell.
Les fonctions documentaires et de personnalisation d’ALMA servent de point de comparaison si vous hésitez entre configuration d’un assistant et entraînement local. Gardez votre exigence d’exécution sur Mac distincte de la qualité recherchée dans les réponses.
Installer
pip install "mlx-lm[train]"
Préparer les données
mlx-lm lit un dossier contenant train.jsonl pour l'entraînement, test.jsonl pour le test, et un valid.jsonl facultatif pour la perte de validation. Un exemple par ligne. Quatre formats sont reconnus automatiquement :
| Format | Clés attendues |
|---|---|
| conversation (chat) | une liste messages d'éléments role et content |
| outils (tools) | messages plus des définitions tools |
| complétion | prompt et completion |
| texte | une seule clé text |
Les clés que le chargeur n'attend pas sont ignorées. Pour la préparation de fond (volume, qualité, découpage), voir Jeu de données.
Entraîner, tester, générer
mlx_lm.lora --model <path_to_model> --train --data <path_to_data> --iters 600
mlx_lm.lora --model <path_to_model> --adapter-path <path_to_adapters> --data <path_to_data> --test
mlx_lm.generate --model <path_to_model> --adapter-path <path_to_adapters> --prompt "<your_model_prompt>"
La deuxième commande évalue l'adaptateur sur le fichier de test, et la documentation parle de perplexité de test. Le type d'affinage se choisit avec --fine-tune-type : lora (par défaut), dora ou full. Une configuration peut aussi se mettre dans un fichier YAML : mlx_lm.lora --config /path/to/config.yaml.
Savoir quels jetons sont appris
Par défaut, la perte porte sur tous les jetons de l’exemple. L’option --mask-prompt la limite à la complétion pour les formats chat et completion. Dans une conversation, MLX considère alors le dernier message comme la complétion ; ce n’est pas le même masque que celui qui sélectionnerait toutes les réponses de l’assistant dans une conversation à plusieurs tours. Vérifiez que le dernier message est bien la réponse à apprendre.
Les adaptateurs sont enregistrés par défaut dans adapters/, ou dans le chemin choisi avec --adapter-path. Séparez les dossiers de chaque essai et conservez le modèle de base exact avec sa configuration. Le téléchargement du modèle et du jeu public utilise le réseau ; le calcul sur Mac ne signifie pas que toute la préparation fonctionne hors ligne. Les options de suivi Weights & Biases et SwanLab sont également des choix distincts d’envoi de métriques.
QLoRA : si le modèle est quantifié
La documentation indique que si --model désigne un modèle quantifié, l'entraînement se fait en QLoRA ; sinon, en LoRA classique. Le principe des deux est expliqué sur LoRA et QLoRA.
Quand la mémoire manque
La page propose, dans cet ordre d'idées :
- utiliser un modèle quantifié (QLoRA) ;
- réduire
--batch-size(4 par défaut) ; - employer
--grad-accumulation-steps <N>pour garder une taille de lot effective sans mémoire en plus ; - réduire
--num-layers(16 par défaut ; essayer 8 ou 4) ; - raccourcir les exemples ;
- activer
--grad-checkpoint, qui échange du calcul contre de la mémoire.
Elle donne un exemple pour une machine de 32 Go : mlx_lm.lora --model mistralai/Mistral-7B-v0.1 --train --batch-size 1 --num-layers 4 --data mlx-community/wikisql.
Modèles et limites
La documentation cite comme familles prises en charge : Mistral, Llama, Phi2, Mixtral, Qwen2, Gemma, OLMo, MiniCPM et InternLM2. Le dépôt décrit une optimisation pour les modèles volumineux par rapport à la mémoire disponible : verrouiller en mémoire les poids et le cache. C’est cette optimisation qui exige macOS 15.0 ou plus ; le passage ne pose pas cette version comme condition universelle pour charger tout gros modèle.
Deux limites à garder en tête. Rien de ce qui précède ne dit combien de temps durera un entraînement sur votre machine : cela dépend du modèle, du volume et du Mac, et il faut le mesurer. Et un affinage réussi sur la perte d'entraînement ne prouve rien sur la qualité réelle : mesurez sur un jeu de test mis de côté.
L’adaptateur peut être utilisé séparément, comme dans la commande de génération ci-dessus. La fusion et l’export sont une autre option : voir Fusionner un adaptateur LoRA.
Questions fréquentes
Peut-on affiner un modèle de langage sur un Mac ?
Oui. Le dépôt mlx-lm se présente comme un paquet Python pour générer du texte et affiner des modèles sur Apple silicon, avec LoRA, l'affinage complet et la prise en charge de modèles quantifiés.
Quel format de données faut-il fournir à mlx-lm ?
Des fichiers JSONL (train.jsonl, éventuellement valid.jsonl et test.jsonl) avec un exemple par ligne ; le format (conversation, prompt et completion, ou texte) est détecté automatiquement.
Que faire si la mémoire du Mac est trop juste ?
La documentation propose de passer à un modèle quantifié (QLoRA), de baisser la taille de lot, le nombre de couches entraînées ou la longueur des exemples, et d'activer le grad-checkpoint.
Références du carnet
Pages consultées pour écrire cet article :