Installation de Qwen3.8-27B à partir de zéro : Guide de déploiement local et d'optimisation des performances sur Mac

Qwen3.8-27B est arrivé.

Les Mac ordinaires ont une chance de le faire tourner.

Mémoire, vitesse, contexte—

Ce guide explique tout d'un coup.

Deux informations sont récemment entrées en collision.

Le 14 août, Qwen3.8-27B a officiellement ouvert ses poids. Moins de deux semaines plus tard, Apple a dévoilé le nouveau Mac Studio équipé des M5 Max et M5 Ultra, mettant en avant les performances IA locales et jusqu'à 512 Go de mémoire unifiée.

Après avoir lu ces présentations, il est facile d'avoir l'illusion : pour faire tourner Qwen3.8-27B sur un Mac, faut-il aussi acheter le dernier Mac Studio, ou même viser directement l'Ultra ?

En réalité, ce n'est pas si exagéré.

Par le passé, les modèles Dense 27B n'étaient effectivement pas le premier choix des utilisateurs locaux. La caractéristique des modèles Dense est que pour chaque token généré, tous les paramètres principaux doivent être lus et calculés. Sur des appareils de la classe 24 Go, même après quantification, cela tient tout juste en mémoire, et les premiers tests de la communauté montraient souvent seulement un à deux chiffres de tokens par seconde.

En comparaison, les modèles MoE comme le 35B-A3B, bien qu'ayant plus de paramètres totaux, n'activent qu'environ 3 milliards de paramètres par génération, ce qui les rend potentiellement plusieurs fois plus rapides. Pour les Agents qui doivent lire du code en continu, appeler des outils et modifier des fichiers à plusieurs reprises, quelle que soit la puissance du modèle, si chaque tour prend beaucoup de temps, il est difficile d'en faire un outil quotidien. Par conséquent, de nombreux utilisateurs locaux privilégiaient auparavant les MoE.

Maintenant, la situation commence à changer.

Les formats de quantification, les frameworks d'inférence Apple Silicon et les nouvelles générations de méthodes d'accélération du décodage arrivent progressivement à maturité, donnant aux modèles Dense 27B leur première chance d'équilibrer capacité et vitesse. Vous n'avez pas nécessairement besoin du dernier Ultra : les Mac de 24 Go et 32 Go peuvent commencer avec la version 4 bits, tandis que ceux disposant de 48 Go ou plus ont des options plus flexibles.

La vraie question n'est plus simplement « peut-il charger », mais comment choisir la version de quantification, contrôler le contexte et la mémoire, et régler la vitesse de génération pour qu'elle soit vraiment utilisable.

Cet article réalisera un déploiement reproductible de A à Z : d'abord calculer les besoins en mémoire, puis exécuter la vitesse de base sans accélération, enfin effectuer des tests A/B avec la même tâche, et lancer le modèle en tant qu'API locale que les clients OpenAI et Anthropic peuvent appeler.

Si vous ne prévoyez pas de déployer maintenant, je suggère de le mettre en favori. Lorsque vous passerez à un Mac avec plus de mémoire plus tard, ou que vous préparerez à connecter des modèles locaux à des Agents de code, des bases de connaissances et des flux de travail d'automatisation, suivez simplement ce guide.

Conclusion d'abord : votre Mac peut-il le faire tourner ?

En ne regardant que la mémoire unifiée, vous pouvez utiliser ce tableau pour décider :

Ce tableau n'est pas la limite absolue de « le modèle peut-il être allumé », mais une suggestion pour « peut-il fonctionner de manière stable ».

Certains Mac de 24 Go peuvent effectivement charger du 4 bits, mais un chargement réussi ne signifie pas qu'il convient à une utilisation à long terme. macOS, les navigateurs, les outils de développement, les tampons d'exécution du modèle, les caches de contexte et les modèles de brouillon DFlash 2 se disputent tous la même mémoire unifiée. Le modèle peut sembler correct au démarrage, mais la panne la plus courante se produit lorsqu'il commence à swapper après avoir saisi un long morceau de code.

De plus, ce tutoriel ne s'applique qu'à Apple Silicon, qui comprend les séries M1, M2, M3, M4 et M5. Les Mac Intel ne suivent pas cette voie MLX.

Qu'est-ce que 27B exactement ? Corriger une idée reçue courante

Le 'B' dans le nom du modèle signifie Billion (milliard).

Donc 27B signifie environ 27 milliards de paramètres, pas 270 milliards.

Vous pouvez considérer les paramètres comme un vaste ensemble de nombres conservés après l'entraînement. Pour chaque token que le modèle génère, il doit lire et calculer ces nombres pour déterminer quel devrait être le token suivant. 27B, c'est comme une machine avec 27 milliards de boutons : l'entraînement est chargé de régler les boutons aux bonnes positions, et l'inférence locale est chargée de charger ces boutons en mémoire et de les lire en continu.

Qwen3.8-27B est un modèle Dense. Dense peut être simplement compris comme : pour chaque token généré, les paramètres principaux participent au calcul.

C'est différent des modèles MoE avec A3B ou A10B dans leur nom. Par exemple, un modèle 35B-A3B peut stocker 35 milliards de paramètres au total, mais n'en active qu'environ 3 milliards à chaque fois. Il doit encore préparer l'espace de stockage pour tous les poids, mais le calcul et la lecture mémoire par token sont beaucoup plus faibles.

Par conséquent, vous ne pouvez pas supposer que deux modèles ont une vitesse, une utilisation mémoire et des niveaux de capacité similaires simplement parce qu'ils disent tous les deux « environ 30B ». Les paramètres totaux, les paramètres actifs, l'architecture du modèle et la précision de quantification doivent être considérés ensemble.

Qwen3.8-27B n'est pas un modèle traditionnel à « attention totale sur chaque couche ». La fiche officielle du modèle montre qu'il se compose de 64 couches, utilisant une architecture hybride de Gated DeltaNet et Gated Attention : environ toutes les 3 couches d'attention linéaire sont entrecoupées d'une couche d'attention standard. Il prend en charge nativement un contexte de 262 144 tokens, possède des capacités de compréhension d'image et de vidéo, a le mode de réflexion activé par défaut et permet d'ajuster la profondeur de raisonnement via reasoning_effort.

Ces capacités expliquent pourquoi il est adapté au code, à la recherche, aux longues tâches et aux Agents ; elles expliquent aussi pourquoi vous ne pouvez pas simplement regarder « 27B » lors du déploiement.

Quel est son niveau de capacité ?

Si l'on catégorise grossièrement les modèles locaux sur les ordinateurs personnels :

• 3B–8B : Démarrage rapide, faible occupation, adapté aux Q&A générales, à l'extraction simple et aux appels d'outils légers ; les tâches complexes ont tendance à dérailler.
• 14B–30B : Actuellement la gamme de haute qualité la plus pratique, commence à gérer de manière fiable la génération de code, le traitement de longs textes, l'analyse structurée et le travail d'Agent.
• 70B et plus Dense : La stabilité globale est souvent plus forte, mais les besoins en capacité mémoire et en bande passante augmentent considérablement, et les coûts de déploiement personnel sont beaucoup plus élevés.

Qwen3.8-27B se situe exactement à la position où « les appareils personnels peuvent raisonnablement déployer, et la capacité est suffisante pour entrer dans les flux de travail de production ».

Dans la fiche officielle du modèle, il a obtenu 61,7 sur SWE-bench Pro et 73,0 sur Terminal Bench 2,1 ; dans le même tableau, Opus 4.6 Max a obtenu respectivement 53,4 et 78,2. Ce résultat indique que sur certaines tâches de codage et d'Agent terminal, Qwen3.8-27B est qualifié pour être discuté dans le même tableau que les fleurons propriétaires.

Mais ne réécrivez pas cela comme « 27B dépasse complètement les fleurons propriétaires ».

Les benchmarks sont affectés par les prompts, les paramètres d'échantillonnage, les environnements d'outils, les frameworks de test et les budgets d'inférence. La fiche officielle du modèle a également divulgué les harnais utilisés pour différents tests. Un score plus élevé signifie seulement qu'il a mieux performé dans ces conditions de test spécifiques, pas qu'il est en tête en termes d'étendue des connaissances, de raisonnement ouvert, de stabilité des longs textes, de capacités visuelles et de flux de travail réels.

Un positionnement plus précis est : ce n'est pas un remplacement complet des fleurons propriétaires, mais c'est un modèle local qui peut sérieusement faire avancer le travail.

Le véritable facteur décisif est le calcul de la mémoire

Beaucoup de gens assimilent directement « nombre de paramètres du modèle » à « mémoire d'exécution » : 27B, donc 27 Go sont nécessaires.

Ce calcul est erroné. Le nombre de paramètres doit être multiplié par le nombre de bits que chaque paramètre occupe.

En calculant approximativement pour 27 milliards de paramètres :

• BF16 : 2 octets par paramètre, poids d'origine environ 54 Go.
• 8 bits : Environ 1 octet par paramètre, valeur théorique environ 27 Go.
• 4 bits : Environ 0,5 octet par paramètre, valeur théorique environ 13,5 Go.

Les valeurs théoriques ne comptent que les poids principaux. Les référentiels de modèles réels incluent également les échelles de quantification, les configurations, les vocabulaires, les composants visuels, etc. La version communautaire MLX sur Hugging Face est d'environ 16,1 Go pour le 4 bits et 29,5 Go pour le 8 bits. Une conversion communautaire BF16 texte indique explicitement environ 54 Go.

C'est juste « la taille du fichier », pas « ce qu'il occupe après le démarrage ». Le modèle consommera au moins quatre types d'espace lors de son exécution.

1. Cache de Contexte

Le modèle doit se souvenir de ce qu'il a déjà lu, sinon il devrait tout recalculer à partir de zéro pour chaque nouveau token. La partie attention standard utilise le KV Cache, et les couches d'attention linéaire ont leurs propres états.

Plus le contexte est long, plus le cache est grand. Les tests du projet mlx-dspark montrent que pour Qwen3.8-27B à 128K de contexte, le cache pourrait ajouter environ 11 Go ; un contexte complet de 256K pourrait ajouter environ 23 Go.

C'est pourquoi « le modèle supporte 262K » ne signifie pas qu'un Mac de 24 Go devrait ouvrir 262K. La limite de capacité est ce que le modèle peut gérer, pas le confort par défaut de votre machine.

2. Tampon d'Exécution et Activations Temporaires

L'étape où le modèle lit un long prompt s'appelle Prefill. Pendant cette étape, une grande quantité d'entrée doit être traitée en une seule fois, et la mémoire et la pression de calcul peuvent soudainement augmenter. Une capture d'écran de la mémoire lorsque vous dites simplement « bonjour » ne représente pas la situation après avoir collé 20 000 tokens de code.

3. macOS et Autres Applications

Le CPU et le GPU d'Apple Silicon partagent la mémoire unifiée, ce qui est la base de l'efficacité de MLX et la raison pour laquelle les budgets mémoire doivent être conservateurs. Le modèle, le système, Chrome, Cursor, Docker et d'autres programmes se disputent tous l'espace dans le même pool.

4. Modèle de Brouillon DFlash 2

DFlash 2 n'est pas un interrupteur gratuit. Il nécessite de charger un modèle de brouillon supplémentaire et le cache correspondant. Le projet fournit une référence de longueur de chat de pointe : environ 18 Go pour le modèle cible 4 bits plus le brouillon, et environ 29 Go pour le 8 bits. Cela ne réserve toujours pas d'espace pour macOS.

Par conséquent, la formule complète devrait être :

Mémoire Réelle = Poids du Modèle + Cache de Contexte + Tampon d'Exécution + Modèle de Brouillon + macOS et Autres Apps

Comprendre cette formule est plus important que de se souvenir de la vitesse de l'ordinateur d'un blogueur.

4 bits, 8 bits, BF16 : Comment choisir ?

La quantification peut être comprise comme l'enregistrement des paramètres du modèle de manière plus compacte. Plus les bits sont bas, plus le modèle économise de la mémoire, et c'est généralement plus rapide ; le coût est une perte de précision.

Pour les utilisateurs Mac ordinaires, je suggère de choisir ainsi :

24 Go / 32 Go : Commencez directement avec du 4 bits

Référentiel du modèle :

1mlx-community/Qwen3.8-27B-4bit

Le fichier 4 bits fait environ 16,1 Go. 24 Go peuvent essayer, mais vous devez activement fermer les grandes applications en arrière-plan et commencer avec un contexte de 8K à 16K. 32 Go sera plus adapté à un usage quotidien.

Ne continuez pas à empiler du contexte ultra-long et DFlash 2 simplement parce que 24 Go « peut charger ». Faites-le fonctionner de manière stable d'abord, puis ajoutez des variables une par une.

48 Go / 64 Go : Envisagez le 8 bits

Référentiel du modèle :

1mlx-community/Qwen3.8-27B-8bit

Le fichier 8 bits fait environ 29,5 Go. 48 Go est un point de départ réaliste, et 64 Go sera plus confortable. Si vous accordez plus d'importance à la vitesse, à l'espace de contexte et à la marge système, 64 Go peut également continuer à utiliser du 4 bits ; il n'est pas nécessaire de forcer le 8 bits juste pour « une précision plus élevée ».

BF16 : Ne traitez pas « peut tenir » comme « adapté à l'utilisation »

Les poids texte BF16 sont déjà d'environ 54 Go. Un Mac de 64 Go est théoriquement proche de pouvoir le contenir, mais après avoir ajouté le système, le cache et le tampon, la marge sera très faible. Pour une utilisation à long terme réelle, il est préférable d'envisager 96 Go et plus.

Pour la plupart des gens, la différence d'expérience entre le 4 bits et le 8 bits est bien moindre que la différence causée par « le début du swap dû à une mémoire insuffisante ». Une fois que le swap continu se produit, aucune précision de quantification ne peut sauver la vitesse de réponse.

Préparation au Déploiement : Vérifier la Puce, la Mémoire et le Disque

D'abord, ouvrez le terminal et confirmez les informations de la machine :

1system_profiler SPHardwareDataType

Vous devez voir une puce Apple de la série M et la capacité de mémoire unifiée.

Ensuite, vérifiez le disque :

1df -h .

Il est recommandé de laisser au moins deux fois le volume du modèle en espace disponible. Le processus de téléchargement peut générer un cache, suivi de modèles de brouillon, de plusieurs versions de quantification et de journaux. Il est préférable de préparer plus de 35 Go d'espace libre pour le 4 bits et plus de 60 Go pour le 8 bits.

Ce tutoriel utilise uv pour gérer l'environnement Python. S'il n'est pas installé :

1brew install uv

Créez un répertoire indépendant et un environnement virtuel :

1mkdir -p qwen38-local/models
2cd qwen38-local
3
4uv venv .venv
5source .venv/bin/activate

L'avantage de cela n'est pas seulement « d'avoir l'air professionnel », mais d'éviter la pollution mutuelle des dépendances entre MLX, Transformers et d'autres projets. Si vous ne voulez pas l'utiliser plus tard, supprimez simplement ce répertoire de projet.

Installez les outils nécessaires :

1uv pip install -U huggingface_hub mlx-dspark

mlx-dspark nécessite actuellement Apple Silicon et Python 3.10 ou supérieur, et installera automatiquement mlx-lm, mlx-vlm et les dépendances MLX appropriées.

Téléchargement du Modèle : Ne cliquez pas sur les fichiers un par un dans le navigateur

Les grands modèles sont généralement divisés en plusieurs fragments de poids. Les télécharger un par un dans un navigateur est sujet aux interruptions, aux fichiers manquants et à la reprise peu pratique. Une méthode plus fiable consiste à utiliser la commande officielle hf de Hugging Face.

Commande de Téléchargement 4 bits

1MODEL_DIR="$PWD/models/Qwen3.8-27B-4bit"
2
3hf download mlx-community/Qwen3.8-27B-4bit \
4  --local-dir "$MODEL_DIR"

Commande de Téléchargement 8 bits

1MODEL_DIR="$PWD/models/Qwen3.8-27B-8bit"
2
3hf download mlx-community/Qwen3.8-27B-8bit \
4  --local-dir "$MODEL_DIR"

La nouvelle version de Hugging Face Hub utilise des téléchargements par morceaux Xet, qui par défaut s'adaptent à la concurrence en fonction du réseau. La plupart des gens n'ont pas besoin de copier l'ancienne configuration hf_transfer des tutoriels précédents.

Vous pourriez également voir ce commutateur de « téléchargement haute performance » :

1HF_XET_HIGH_PERFORMANCE=1 hf download ...

Ne l'activez pas aveuglément. La documentation officielle de Hugging Face indique qu'il augmente la concurrence, la mise en mémoire tampon et l'utilisation du CPU, ce qui le rend plus adapté aux machines à haute bande passante avec au moins 64 Go de mémoire. Les Mac à faible mémoire pourraient en fait être plus lents en raison de la contention des ressources. Les machines de 24 Go et 32 Go doivent d'abord utiliser les paramètres par défaut.

Après le téléchargement, vérifiez la taille du répertoire :

1du -sh "$MODEL_DIR"

Premier Lancement : Testez d'abord la Vitesse de Base, ne vous précipitez pas pour Activer DFlash 2

L'erreur la plus courante lors du déploiement de modèles locaux est d'activer dix options d'optimisation à la fois. À la fin, cela peut fonctionner rapidement, mais vous ne savez pas à qui attribuer le mérite ; si cela fonctionne lentement, vous ne savez pas qui désactiver.

Le bon ordre est d'exécuter d'abord une référence.

Préparez un prompt fixe, de préférence proche de votre travail réel. Par exemple, si vous l'utilisez principalement pour le codage, vous pouvez utiliser :

1Veuillez implémenter un cache thread-safe en Python qui prend en charge le temps d'expiration et l'éviction LRU. Expliquez d'abord la conception, puis fournissez le code complet et les tests.

Test de référence :

1mlx-dspark generate \
2  --model "$MODEL_DIR" \
3  --mode baseline \
4  --prompt "Veuillez implémenter un cache thread-safe en Python qui prend en charge le temps d'expiration et l'éviction LRU. Expliquez d'abord la conception, puis fournissez le code complet et les tests." \
5  --max-new-tokens 600

Enregistrez quatre nombres :

1. Temps de chargement du modèle.
2. Vitesse de traitement du prompt (Prefill tok/s).
3. Temps jusqu'au premier token (TTFT).
4. Vitesse de génération formelle (generation tok/s).

La vitesse de génération détermine « à quelle vitesse les mots sortent un par un », tandis que Prefill et TTFT déterminent « combien de temps vous devez attendre après avoir appuyé sur Entrée ». Pour les Agents de code, chaque tour peut nécessiter la relecture d'une grande quantité de prompts système et de code, donc Prefill affecte souvent l'expérience utilisateur plus que la vitesse de génération pure.

Pendant le test, ouvrez également « Moniteur d'activité → Mémoire » pour observer la pression mémoire et le Swap. Le jaune ne signifie pas nécessairement un problème immédiat, mais si le Swap continue d'augmenter, cela signifie que cette configuration n'a pas de marge stable.

Ne vous contentez pas d'exécuter 50 tokens. Les réponses courtes feront que le temps de chargement et d'échauffement représentera une proportion trop élevée et ne montrera pas la vitesse réelle pendant la génération continue. Il est recommandé de générer au moins 400 à 1000 tokens.

Comment DFlash 2 rend-il le 27B plus rapide ?

Le décodage ordinaire est séquentiel. Qwen3.8-27B génère un token, le modèle cible complet s'exécute une fois ; génère le suivant, et s'exécute à nouveau. Générer 1000 tokens nécessite environ 1000 tours consécutifs.

DFlash 2 ajoute un modèle de brouillon plus léger. Le modèle de brouillon propose d'abord un ensemble de tokens candidats en parallèle, puis le modèle principal 27B les vérifie collectivement. Les suppositions correctes peuvent être acceptées plusieurs à la fois, tandis que les incorrectes sont corrigées par le modèle principal.

Vous pouvez le considérer comme :

• Le modèle de brouillon est un assistant chargé de rédiger rapidement.
• Le modèle principal 27B est le rédacteur en chef ayant le pouvoir de décision final.
• Plus l'assistant devine correctement à la suite, moins le rédacteur en chef doit effectuer de tours complets.

Le modèle de brouillon ne décide pas de la sortie de manière indépendante. La fiche du modèle DFlash 2 indique que sous décodage glouton, la sortie est cohérente avec le modèle cible ; lors de l'échantillonnage aléatoire, il maintient la distribution du modèle cible.

Ce n'est pas non plus garanti d'accélérer dans tous les scénarios.

Si la tâche rend le modèle de brouillon facile à prédire, comme la complétion de code ou un long texte avec un formatage stable, la longueur d'acceptation est généralement plus élevée ; si le contenu change considérablement, les réponses sont très courtes ou le caractère aléatoire de l'échantillonnage est élevé, le brouillon est souvent rejeté, et le calcul supplémentaire pourrait consommer les gains.

Activation de DFlash 2 : Laissez l'outil s'étalonner lui-même, ne copiez pas les paramètres des autres

Exécutez d'abord le benchmark intégré du projet :

1mlx-dspark benchmark \
2  --model "$MODEL_DIR" \
3  --modes dflash \
4  --caps auto \
5  --trials 3

Spécifiez explicitement --modes dflash ici car la version actuelle du benchmark teste par défaut DSpark et lookup et ne basculera pas automatiquement vers DFlash 2 de Qwen3.8-27B. La première exécution téléchargera le modèle de brouillon correspondant ; --caps auto testera les capacités de brouillon appropriées en fonction de votre Mac, du modèle cible et de la version de quantification. Les M1 Max, M4 Pro et M5 Max ont des bandes passantes mémoire et des coûts de calcul différents, donc les paramètres optimaux ne devraient pas être exactement les mêmes.

Par conséquent, il n'est pas recommandé de copier définitivement --max-draft 7 simplement parce que vous avez vu quelqu'un d'autre l'écrire. Laissez l'étalonnage automatique donner la réponse d'abord, puis retestez avec des tâches réelles.

Utilisez le même prompt pour activer le mode automatique :

1mlx-dspark generate \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --prompt "Veuillez implémenter un cache thread-safe en Python qui prend en charge le temps d'expiration et l'éviction LRU. Expliquez d'abord la conception, puis fournissez le code complet et les tests." \
5  --max-new-tokens 600

Comparez maintenant avec la référence :

• Le texte de sortie est-il cohérent ?
• Le TTFT s'est-il significativement allongé ?
• De combien le generation tok/s s'est-il amélioré ?
• Quelle est la longueur moyenne d'acceptation ?
• La mémoire de pointe et le Swap se sont-ils aggravés ?

Ces commandes utilisent le décodage glouton par défaut, donc le texte de sortie de la référence et du mode automatique devrait être cohérent, à l'exception de très rares cas d'égalité en virgule flottante. Si les réponses sont significativement différentes, vérifiez si le prompt, le mode de réflexion, les paramètres d'échantillonnage et la version du logiciel sont identiques avant de discuter de la vitesse. Lors de l'échantillonnage aléatoire, DFlash 2 maintient la distribution cible mais ne garantit pas que les mots spécifiques générés deux fois seront identiques.

Dans les benchmarks du projet mlx-dspark sur M4 Pro 48 Go, le 8 bits est passé d'environ 8,4 tok/s à 30,5 tok/s, soit une moyenne d'environ 3,63 fois ; le 4 bits est passé d'environ 14,7 tok/s à 33,8 tok/s, soit une moyenne d'environ 2,30 fois.

Ce sont des résultats dans des versions, machines, états de démarrage à chaud et prompts de test spécifiques, pas une promesse. Les propres données ventilées du projet montrent également que les ratios d'accélération diffèrent pour les tâches de chat, de code et de mathématiques.

Le critère vraiment utile n'est pas « les autres ont atteint 30 tok/s », mais si vos tâches à haute fréquence sont devenues plus rapides.

Si vous utilisez habituellement le modèle pour modifier du code, testez-le avec des tâches de modification dans des dépôts réels ; si vous l'utilisez pour écrire des articles, générez 1500 tokens en continu ; si vous voulez connecter un Agent, exécutez un appel d'outil complet. Ce n'est que si le temps total pour les tâches réelles diminue que DFlash 2 vaut la peine d'être laissé activé.

Lancement du Modèle en tant qu'API Locale

Après avoir confirmé que les modes de base et automatique sont stables, vous pouvez faire du modèle un service résident. Pour un Mac de 24 Go, limitez d'abord le contexte à 8K :

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 8192

32 Go peuvent commencer avec 16K ; après stabilisation, augmentez progressivement jusqu'à 32K :

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384

Après le démarrage du service, vérifiez l'état dans un autre terminal :

1curl http://127.0.0.1:8080/health
2curl http://127.0.0.1:8080/v1/models

/health renverra le mode réel, la limite de contexte et les avertissements mémoire ; /v1/models fournira l'ID du modèle que le client doit remplir.

Ne mélangez pas les adresses pour les deux types de clients :

1OpenAI Base URL : http://127.0.0.1:8080/v1
2Anthropic Base URL : http://127.0.0.1:8080
3Anthropic Messages route : /v1/messages

Il fournit à la fois des interfaces compatibles OpenAI et Anthropic. Les clients de chat, les outils de code et les Agents qui prennent en charge les URL de base personnalisées peuvent généralement être connectés.

Effectuez un test de conversation avec curl. L'exemple suivant utilise l'ID du modèle renvoyé pour le 4 bits ; si vous avez téléchargé le 8 bits, veuillez le remplacer par la valeur réelle renvoyée par /v1/models :

1curl http://127.0.0.1:8080/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "Qwen3.8-27B-4bit",
5    "messages": [
6      {"role": "user", "content": "Expliquez ce qu'est la mémoire unifiée en trois phrases."}
7    ],
8    "max_tokens": 200
9  }'

Lorsque vous l'utilisez uniquement sur la machine locale, 127.0.0.1 est le choix le plus sûr et le plus simple. Certains clients vous obligent à remplir une clé API ; vous pouvez remplir n'importe quelle chaîne de caractères factice. Lorsque l'authentification n'est pas activée, le service local ne la vérifiera pas.

Si vous avez besoin d'un accès LAN, alors seulement envisagez de modifier l'adresse d'écoute et le pare-feu. N'exposez pas une interface sans authentification, TLS ou limitation de débit directement sur l'internet public. Ce n'est pas parce que le modèle s'exécute localement que le service est naturellement sécurisé.

Comment définir le contexte pour que la mémoire n'explose pas ?

La méthode la plus fiable n'est pas de deviner, mais d'augmenter par étapes :

1. 24 Go commence à 8K, essayez 16K après stabilisation.
2. 32 Go commence à 16K, puis essayez 32K.
3. 48 Go / 64 Go commence à 32K, essayez 64K selon les besoins des tâches.
4. N'augmentez à 128K que lorsque vous traitez vraiment des documents ultra-longs ou de grandes bases de code.

Pour chaque niveau d'augmentation, répétez le même test : invite fixe, sortie maximale fixe, enregistrez TTFT, vitesse de génération, mémoire maximale et Swap.

"Le modèle supporte 262K" est un paramètre de capacité, pas une recommandation par défaut. Pour les discussions quotidiennes, la rédaction et la plupart des tâches de codage, 16K–32K couvrent déjà de nombreux scénarios.

Un contexte plus grand ne signifie pas plus intelligent ; entasser trop de contenu non pertinent pourrait diluer les informations clés, rendant le modèle plus lent, plus coûteux et plus sujet aux dérives.

Si le service est utilisé pour un Agent, privilégiez la conservation du Cache de Préfixe. Les invites système et les définitions d'outils pour les Agents de code sont souvent très longues ; réutiliser les préfixes entre plusieurs tours peut réduire considérablement le Prefill répété.

Comment choisir le mode de réflexion ? La variable la plus facilement négligée dans les tests

Qwen3.8 réfléchira avant de répondre par défaut. Pour les modifications de code complexes, le raisonnement mathématique, l'analyse de recherche et les tâches d'Agent multi-tours, vous pouvez conserver le mode de réflexion par défaut ; pour les discussions générales, la traduction, le résumé et la conversion de format, le processus de réflexion n'augmente souvent que le temps d'attente et les tokens de sortie.

Si vous souhaitez conserver la réflexion mais réduire la profondeur de raisonnement, utilisez la commande complète :

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384 \
5  --reasoning-effort low

Si la tâche est très directe, vous pouvez désactiver la réflexion :

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384 \
5  --no-thinking

Ces deux paramètres définissent le comportement par défaut du service. Les clients qui supportent les champs associés peuvent également les remplacer par requête, donc après avoir connecté des outils, vérifiez si le client a discrètement rétabli ses propres valeurs par défaut.

Il n'existe pas de réponse unique adaptée à toutes les tâches. "Low" peut sembler plus rapide par tour, mais pourrait amener l'Agent à réessayer à plusieurs reprises en raison d'une analyse insuffisante, rendant la tâche globale plus lente. La méthode la plus fiable reste de calculer le temps total pour la tâche complète, plutôt que de simplement comparer la première réponse.

Une règle doit être retenue : lors des tests A/B baseline vs DFlash 2, le mode de réflexion doit être identique. Si l'un a la réflexion activée et l'autre désactivée, le nombre de tokens et le chemin de la tâche changent, et la vitesse calculée n'a aucune signification comparative. Les paramètres d'échantillonnage, l'invite, la longueur maximale de sortie, le contexte et les états à froid/chaud doivent également rester cohérents.

Itinéraire de déploiement le plus court : compresser les commandes nécessaires ensemble

Ce qui a été discuté précédemment explique pourquoi chaque étape est effectuée. Si vous comprenez déjà les principes et souhaitez simplement reproduire rapidement, vous pouvez exécuter dans l'ordre suivant. L'exemple choisit 4 bits et un contexte de 8K, adapté à un démarrage prudent sur un Mac de 24 Go ; le temps réel de téléchargement et de benchmark dépend du réseau et de la puce et n'est pas inclus dans le "plus court" :

1brew install uv
2
3mkdir -p qwen38-local/models
4cd qwen38-local
5uv venv .venv
6source .venv/bin/activate
7
8uv pip install -U huggingface_hub mlx-dspark
9
10MODEL_DIR="$PWD/models/Qwen3.8-27B-4bit"
11hf download mlx-community/Qwen3.8-27B-4bit \
12  --local-dir "$MODEL_DIR"
13
14mlx-dspark generate \
15  --model "$MODEL_DIR" \
16  --mode baseline \
17  --prompt "Expliquez la mémoire unifiée et donnez trois suggestions pour exécuter des grands modèles locaux." \
18  --max-new-tokens 400
19
20mlx-dspark benchmark \
21  --model "$MODEL_DIR" \
22  --modes dflash \
23  --caps auto \
24  --trials 3
25
26mlx-dspark serve \
27  --model "$MODEL_DIR" \
28  --mode auto \
29  --context-window 8192

L'objectif de cet ensemble de commandes est de "d'abord exécuter en toute sécurité", pas de maximiser le matériel. Après une exécution réussie, essayez les contextes 16K et 32K dans l'ordre en fonction de la marge mémoire, ou remplacez le dépôt 4 bits par 8 bits. Ne modifiez qu'une seule variable à la fois pour que les données de test soient significatives.

Une fois le service démarré, ne vous précipitez pas pour connecter des clients tiers ; accédez d'abord à /health et /v1/models. Le premier confirme l'absence d'avertissements mémoire et que le mode attendu est bien activé, tandis que le second confirme l'ID du modèle. Ensuite, complétez une longue réponse d'environ 400 tokens et observez la pression mémoire et le Swap dans le Moniteur d'Activité. Si les quatre sont normaux, remplissez alors la Base URL dans vos outils quotidiens. Ces quelques minutes de vérification peuvent éliminer la plupart des problèmes de "client ne peut pas se connecter" et de "l'ordinateur devient très lent après un certain temps".

Comment redémarrer le lendemain ?

L'environnement virtuel et MODEL_DIR ne sont effectifs que dans la session de terminal actuelle. Lorsque vous rouvrez le terminal le lendemain, vous n'avez pas besoin de retélécharger ni de réinstaller ; il suffit de retourner dans le répertoire, d'activer l'environnement et de redéclarer le chemin :

1cd qwen38-local
2source .venv/bin/activate
3MODEL_DIR="$PWD/models/Qwen3.8-27B-4bit"
4
5mlx-dspark serve \
6  --model "$MODEL_DIR" \
7  --mode auto \
8  --context-window 8192

Lors de la mise à jour des outils, exécutez dans l'environnement virtuel :

1uv pip install -U huggingface_hub mlx-dspark

Après la mise à jour, exécutez d'abord un court baseline et /health pour confirmer que le modèle peut encore être chargé avant de reprendre le service à long terme. Les outils d'inférence évoluent rapidement, et les paramètres qui fonctionnaient dans les anciennes versions ne sont pas nécessairement toujours les meilleurs, donc conserver vos propres enregistrements de référence est précieux.

Accès LAN : ajoutez au moins un verrou d'abord

L'adresse 127.0.0.1 par défaut n'est accessible que par la machine locale. Si vous souhaitez qu'un autre Mac ou iPad sur le même Wi-Fi puisse l'appeler, vous pouvez écouter sur toutes les cartes réseau et définir une clé API en même temps :

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384 \
5  --host 0.0.0.0 \
6  --api-key "Veuillez remplacer par une chaîne aléatoire suffisamment longue"

Le client remplace 127.0.0.1 par l'adresse IP LAN de ce Mac et envoie Authorization: Bearer votre_clé dans la requête. Vérifiez également le pare-feu macOS pour n'autoriser que les réseaux de confiance à accéder au port 8080.

Ce n'est encore qu'une solution LAN. Pour accéder via Internet, vous avez également besoin de TLS, d'un proxy inverse, d'un contrôle d'accès et d'une limitation de débit ; ne mappez pas 8080 directement sur le routeur. Le moyen le plus simple est de revenir au réseau domestique via un VPN de confiance, puis d'accéder au service local.

Dépannage des problèmes courants

1. Le modèle est tué par le système en cours de chargement

Confirmez d'abord que vous avez choisi la bonne version de quantification. 24 Go et 32 Go ne doivent pas télécharger par erreur du 8 bits, et ne touchez surtout pas au BF16. Fermez Docker, les machines virtuelles, un grand nombre d'onglets de navigateur et d'autres modèles locaux, puis réessayez en 4 bits.

2. Peut s'exécuter, mais le Mac devient très lent

Ouvrez le Moniteur d'Activité pour regarder le Swap. Si le Swap continue d'augmenter, raccourcissez d'abord le contexte, puis désactivez DFlash 2. Ne regardez pas seulement les chiffres du processus du modèle, car la pression de la mémoire unifiée est causée par l'ensemble du système.

3. DFlash 2 est en fait plus lent

Confirmez que les conditions de comparaison sont cohérentes : même invite, même longueur de sortie, même mode de réflexion, même démarrage à froid ou à chaud. Les réponses courtes ne sont pas adaptées pour juger des gains de décodage spéculatif. Exécutez plus de trois tours et testez avec de vraies tâches longues.

Si c'est toujours plus lent, cela signifie que le taux d'acceptation de la tâche actuelle est faible, ou que la mémoire supplémentaire apportée par le modèle de brouillon a provoqué le début du swap. Le désactiver n'est pas un échec ; une baseline stable est déjà une solution efficace.

4. Le premier token est très lent, mais la génération suivante est correcte

C'est un goulot d'étranglement du Prefill. Vérifiez si l'entrée est trop longue, si un grand nombre de fichiers non pertinents sont insérés à chaque tour, et si le Cache de Préfixe est utilisé. Pour les Agents, optimiser la longueur de l'invite est souvent plus efficace que de continuer à chercher à améliorer le tok/s de génération.

5. La vitesse de téléchargement est très lente ou interrompue

Réexécutez simplement la même commande hf download pour utiliser le cache et la reprise. Ne supprimez pas le répertoire incomplet et ne recommencez pas à zéro. Lorsque l'accès à Hugging Face est instable, envisagez la route ModelScope recommandée officiellement.

6. Je veux qu'il reconnaisse les images

Faites la distinction entre "le modèle a une capacité visuelle" et "le service actuel supporte l'entrée visuelle." Le dépôt MLX susmentionné conserve les composants visuels, mais mlx-dspark fournit actuellement un service d'inférence textuelle ; le contenu image qui lui est envoyé n'entrera pas dans le modèle.

Pour tester les images, vous devez contourner temporairement DFlash 2 et utiliser mlx-vlm à la place :

1uv run python -m mlx_vlm.generate \
2  --model "$MODEL_DIR" \
3  --max-tokens 200 \
4  --temperature 0 \
5  --prompt "Veuillez décrire cette image." \
6  --image "/chemin/absolu/example.jpg"

L'entrée visuelle augmente la complexité du traitement et l'occupation mémoire. Si l'utilisation principale est le code, l'écriture et les Agents, stabilisez d'abord la chaîne textuelle, puis testez les tâches visuelles séparément.

Une séquence de déploiement la moins susceptible d'échouer

Une liste de contrôle d'exécution :

1. Confirmez qu'il s'agit d'un Mac Apple Silicon.
2. Abandonnez le 27B pour 16 Go ; choisissez 4 bits pour 24 Go/32 Go ; envisagez 8 bits pour 48 Go/64 Go.
3. Réservez suffisamment d'espace disque pour le modèle et utilisez uv pour créer un environnement indépendant.
4. Utilisez hf download pour télécharger le dépôt complet ; ne cliquez pas sur les fichiers de poids un par un dans le navigateur.
5. Exécutez d'abord une invite fixe avec --mode baseline, en enregistrant le chargement, le Prefill, le TTFT, la vitesse de génération et la mémoire.
6. Commencez avec un contexte de 8K, 16K ou 32K ; n'ouvrez pas directement le 262K complet.
7. Exécutez mlx-dspark benchmark --modes dflash --caps auto --trials 3 pour laisser l'outil s'étalonner sur votre machine.
8. Comparez baseline et auto avec exactement la même tâche réelle.
9. N'activez DFlash 2 à long terme que lorsque la vitesse est significativement améliorée et la pression mémoire stable.
10. Enfin, démarrez l'API locale et connectez les outils de code, les bases de connaissances ou les Agents.

L'importance du déploiement local ne se limite pas à économiser les frais d'API.

Lorsque Qwen3.8-27B devient un service local sur votre Mac pouvant être appelé à tout moment, vous pouvez conserver le code sensible et les documents sur votre propre machine, traiter les matériaux hors ligne, et le connecter à des tâches d'automatisation, des bases de connaissances personnelles et des workflows d'Agent longue durée.

Ma propre ligne de passage est simple : les tâches courantes ne swappent pas, la vitesse de réponse est tolérable, et je l'ouvrirai activement le lendemain. Ce n'est que lorsque ces trois conditions sont remplies que le déploiement est vraiment réussi.

Si vous l'avez déjà fait fonctionner, n'hésitez pas à laisser dans les commentaires votre "modèle de puce, mémoire unifiée, 4/8 bits, longueur de contexte, baseline et tok/s DFlash 2". S'il y a suffisamment de données, je pourrai continuer à les organiser dans un tableau de test de configuration Mac.

Si vous trouvez encore le déploiement fastidieux

J'ai organisé les commandes d'installation, les téléchargements de modèles, les tests de vitesse, l'accélération DFlash 2, le démarrage de l'API locale et le dépannage des problèmes courants abordés dans cet article en une liste de contrôle de déploiement qui peut être suivie directement :

1https://github.com/wdwxw/macRunqwen38_27b_install

Vous pouvez les copier et les exécuter dans l'ordre vous-même, ou donner directement ce dépôt GitHub à Codex ou Claude Code, lui faire lire le README.md, vérifier votre configuration Mac et effectuer l'installation selon la liste de contrôle. Ainsi, vous n'avez pas à chercher à plusieurs reprises des commandes dans un long article, et les mises à jour et le dépannage ultérieurs sont plus pratiques.