Come eseguire GLM-5.3-Flash su un MacBook Pro: Il playbook MLX 2bit-Lite

Eseguire GLM-5.3-Flash su un MacBook Pro significa esattamente una macchina: una 128 GB M4/M5 Max MacBook Pro che esegue la 2bit-lite build della nostra conversione MLX, con il limite di memoria wired di macOS aumentato. Se il tuo MacBook Pro ha meno di 128 GB — un M4 Pro da 36 GB, un M4 Max da 48 GB — questo playbook non fa per te; vai all'ultima sezione e instrada invece l'API hostata z-ai/glm-5.3-flash. GLM-5.3-Flash (i pesi su zai-org/GLM-5.3-Flash) è il modello Mixture-of-Experts da 320 miliardi di parametri di Z.ai con 18B attivi per token — rilasciato il 26 agosto 2026, il primo GLM-​5 nativamente multimodale — e anche la build più piccola del nostro porting MLX richiede ~102 GB di pesi e ~112 GB di memoria. Questo è l'intero mercato, e non abbiamo intenzione di ammorbidirlo.

Questa è documentazione di prima parte, non un articolo di lancio: i pesi qui sotto sono la build di OrcaRouter (orcarouter/GLM-5.3-Flash-MLX, MIT), prodotta con il nostro metodo di quantizzazione OrcaSAQ senza calibrazione. L'abbiamo rilasciata il 26 agosto e il giorno dopo abbiamo corretto pubblicamente la rotta, perché il range di quantizzazione originale non rendeva l'uso su MacBook Pro pratico per la maggior parte delle persone — la build 2-bit normale richiedeva ancora ~160 GB, che nessun laptop possiede. Il 27 agosto abbiamo ricostruito la variante più piccola come 2bit-lite specificamente per adattarsi a un MacBook Pro da 128 GB, e questo articolo è il resoconto onesto di ciò che si ottiene e di ciò che costa. Ogni numero contrassegnato come nota di campo qui sotto è stato misurato sul nostro run di verifica con una singola H200; niente qui è un benchmark del fornitore. Dove ripetiamo pratiche della community — il comando wired-memory, il versionamento di mlx-vlm — lo etichettiamo come tale.

Quale build si adatta a quale Mac (leggi questo prima di scaricare qualsiasi cosa)

Le cinque build nel repository corrispondono ciascuna a un valore minimo di RAM. Su un MacBook Pro, "quale build" ha esattamente una risposta — tutto ciò che è sopra 2bit-lite è una conversazione da Mac Studio:

• 6-bit — ~296 GB di pesi / ~320 GB di RAM / quasi lossless. Solo Mac Studio con 512 GB.

• 4-bit — ~204 GB / ~224 GB / il nostro default consigliato. Mac Studio 256 GB. Questo è ciò che la root del repository rispecchia.

• 3-bit — ~184 GB / ~200 GB. Mac Studio 256 GB.

• 2-bit — ~145 GB / ~160 GB. Mac Studio 192 GB. Questa era la build più piccola che abbiamo pubblicato il primo giorno, ed è stato l'errore.

• 2bit-lite — ~102 GB / ~112 GB. L'unica build che sta in una macchina da 128 GB — un MacBook Pro M4/M5 Max da 128 GB, oppure un Mac Studio o un Mac mini da 128 GB. Qualsiasi laptop Apple Silicon da 128 GB (M3 Max o successivo) è la stessa storia, solo più lento.

La trappola nascosta in quella scaletta: il comando di download predefinito del README scarica la build a 4 bit (~204 GB), che è il default giusto per una macchina da 256 GB e inutile su un portatile. Se segui il comando predefinito su un MacBook Pro, ti ritrovi con un modello che non riesce ad allocare. Il percorso 2bit-lite richiede un esplicito --include, descritto di seguito.

C'è anche un tetto massimo che incontrerai prima ancora che i calcoli precedenti entrino in gioco. macOS non consente a un processo di utilizzare tutta la memoria unificata di un Mac da 128 GB; il tetto predefinito utilizzabile dalla GPU è di circa 91–96 GB (ricavato tramite reverse engineering dalla community e confermato in diversi articoli su configurazioni MLX per modelli di grandi dimensioni). Questo valore è inferiore ai ~102 GB dei soli pesi, quindi anche la versione 2bit-lite non verrà caricata finché non aumenti il limite della memoria cablata. Questo passaggio è obbligatorio ed è trattato nella Sezione 4.

Installa mlx-vlm — e solo mlx-vlm

GLM-5.3-Flash è un modello visione-linguaggio, quindi funziona con mlx-vlm, non con mlx-lm. Questo è l'errore più comune in cui le persone si imbattono, quindi lo diciamo subito: mlx-lm è per modelli solo testuali; eseguire un modello multimodale con esso produce un errore di caricamento confusionario. Installa il pacchetto VLM alla versione 0.6.17 o superiore:

pip install -U "mlx-vlm>=0.6.17"

Il pin della versione non è decorativo. glm5_next — l'architettura ibrida sparse-plus-linear-attention alla base di GLM-5.3-Flash — è arrivata in mlx-vlm solo il giorno stesso del rilascio del modello (26 agosto 2026), e qualsiasi versione precedente non riconoscerà la configurazione. L'architettura è importante anche per un secondo motivo: si tratta di una topologia completamente nuova, e i porting della prima ondata avevano veri bug di correttezza che un output fluente non avrebbe rivelato. Un audit della community sul percorso runtime MLX iniziale di glm5_next ne ha trovati e corretti quattro — un clamp SwiGLU non applicato su ogni blocco FFN, tensori di iper-connessione vincolati alla varietà convertiti al dtype sbagliato (che corrompeva silenziosamente la matrice di mixing dell'attenzione), due discrepanze di epsilon nelle norme di attenzione e logit del router in bf16 dove il riferimento usa float32. Dopo le correzioni, i valori numerici corrispondevano al riferimento con una precisione di circa 1e-7. Il consiglio per te: tieni mlx-vlm aggiornato e tratta con sospetto la primissima release di qualsiasi porting di nuova architettura.

Scarica i pesi: i flag di esclusione e ciò che devi effettivamente includere.

La radice del repository rispecchia la build a 4 bit e tutte e cinque le varianti sono fornite come sottocartelle. Il comando predefinito scarica la radice e usa --exclude così nessuna delle cinque cartelle delle varianti (che complessivamente sono dell'ordine di 800 GB) viene scaricata:

hf download orcarouter/GLM-5.3-Flash-MLX --local-dir ./GLM-5.3-Flash-MLX --exclude "2bit-lite/*" "2-bit/*" "3-bit/*" "4-bit/*" "6-bit/*"

Su un MacBook Pro quel comando è sbagliato per te — ti dà la root a 4 bit. Per un laptop da 128 GB, recupera solo la 2bit-lite sottocartella:

hf download orcarouter/GLM-5.3-Flash-MLX --include "2bit-lite/*" --local-dir ./GLM-5.3-Flash-MLX

Quello è il download da ~102 GB, ed è autonomo — la cartella 2bit-lite/ contiene la propria config.json, così punti il generatore direttamente ad essa. Se hf non è nel tuo PATH, installalo: pip install -U huggingface_hub. Prima di iniziare, assicurati di avere ~110 GB di spazio libero su disco e che il tuo Mac non abbia solo gli ultimi 100 GB liberi — MLX mappa in memoria i pesi, e con un SSD quasi pieno queste configurazioni muoiono a metà download.

Aumenta il limite della memoria vincolata — il passaggio che tutti dimenticano

Questo è il passo decisivo su un MacBook Pro da 128 GB, e la scheda README dà per scontato che tu lo conosca, invece di scrivere esplicitamente il comando. Il limite predefinito del working-set Metal su un Mac da 128 GB è di circa 91–96 GB, che è al di sotto dei ~102 GB dei pesi 2bit-lite — quindi senza questo passaggio il modello non riesce ad allocare la memoria e il caricamento muore. La soluzione standard della community è un sysctl che alza in megabyte il tetto della memoria wired della GPU:

sudo sysctl iogpu.wired_limit_mb=114688

Questo imposta un tetto di ~112 GB, lasciando circa 14 GB come riserva per il sistema operativo. Su macchine con 128 GB, i valori riscontrati nella community vanno da ~114688 (112 GB) fino a ~122880 (120 GB); non portarlo al massimo — macOS ha bisogno di margine, altrimenti si verificano balbettii del window server e rallentamenti di sistema sotto pressione di memoria. Dopo averlo impostato, carica il modello e tieni d'occhio Activity Monitor: se la pressione di memoria diventa gialla, riduci il valore.

Due note pratiche, entrambe frutto della pratica della community piuttosto che delle nostre note sul campo. Prima di tutto, il sysctl si azzera al riavvio e si applica alla sessione del terminale in cui lo imposti, quindi prevedi di rieseguirlo (o di scriptarlo tramite un LaunchAgent) — dimenticarlo dopo un riavvio è il classico errore "ieri funzionava". In secondo luogo, MLX espone anche un controllo in-process, mlx.core.metal.set_wired_limit(bytes), su macOS 15.0 e versioni successive; deve rimanere al di sotto del tetto del sysctl, ed è l'opzione più portabile se stai scrivendo script per un notebook. Qualunque dei due tu usi, l'effetto è lo stesso: senza di esso, qui non funziona nulla.

Eseguilo: testo, immagine e l'API Python.

Con i pesi in posizione e il limite alzato, la generazione è un solo comando. Testo:

python -m mlx_vlm.generate --model ./GLM-5.3-Flash-MLX/2bit-lite --prompt "Spiega l'entanglement quantistico in una sola frase." --max-tokens 256

L'input di immagini funziona allo stesso modo con un --image flag — è qui che il modello multimodale dimostra il suo valore su un laptop, poiché la torre di visione rimane a precisione più alta nel layout OrcaSAQ:

python -m mlx_vlm.generate --model ./GLM-5.3-Flash-MLX/2bit-lite --image photo.jpg --prompt "Descrivi questa immagine." --max-tokens 256

Per uno script, l'API Python ha la stessa forma che gli utenti mlx-vlm conoscono:

from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template model, processor = load("./GLM-5.3-Flash-MLX/2bit-lite") prompt = apply_chat_template(processor, model.config, "Descrivi questa immagine.", num_images=1) print(generate(model, processor, prompt, ["photo.jpg"], max_tokens=256, verbose=True))

Mantieni --max-tokens modesto. Nella nostra prova di campo su H200, 2bit-lite gira a circa 10 tok/s, quindi una risposta da 1.024 token significa già due minuti di attesa — e negli output lunghi il budget KV e il crollo della qualità si fanno sentire (più sotto). Su un portatile dovresti aspettarti che risulti più lento, non più veloce, finché non esiste un valore misurato.

La qualità che stai effettivamente ottenendo (la scala misurata)

Ecco la parte onesta del playbook, e non la edulcoreremo. OrcaSAQ degrada con grazia fino a 3 bit, poi il costo sale rapidamente. Rispetto al riferimento FP8 (perplessità 2.7797):

• 6-bit — perplessità 2,7864 (+0,24%), concordanza del token top-1 del 97,76%. Quasi senza perdite, come pubblicizzato.

• 4-bit — perplexity 2.8620 (+2,96%), top-1 96,13%. Il valore predefinito consigliato.

• 3-bit — perplexity 3.0566 (+9,96%), top-1 92,06%. Aggressivo ma utilizzabile.

• 2-bit — perplexity 4.3622 (+56.9%), top-1 86.56%. Un costo reale.

• 2bit-lite — perplexity 6.7018 (+141%), top-1 77.19%. La build più piccola, e l'unica che un MacBook Pro può contenere.

Questi sono numeri misurati dalla nostra pipeline di conversione. 2bit-lite è una regressione di perplexity del 141% e una concordanza dei token top-1 inferiore al 78% — stai eseguendo un modello chiaramente degradato, e le modalità di errore di seguito sono ciò a cui assomiglia tale degradazione nella pratica. È una demo brillante e un assistente ragionevole per domande brevi; non è un sostituto del modello a piena precisione.

Sulla velocità, ti dobbiamo la stessa onestà. La nota sul campo pubblicata è la H200: ~10 tok/s, multi-turn stabile, Q&A quotidiano e testo breve vanno bene. Non abbiamo ancora un dato misurato per MacBook Pro con 2bit-lite, e non abbiamo intenzione di inventarne uno — il throughput di Apple Silicon qui dipende dalla larghezza di banda della memoria, dalla termica e dalla copertura dei kernel MLX per l'attenzione ibrida, nessuno dei quali abbiamo misurato per questa build su questo laptop. Il dato Apple Silicon pubblicato più vicino a cui possiamo indirizzarti è un ~450 tok/s indipendente per una build GLM-5.3-Flash a 4 bit su un Mac da 512 GB con un runtime MLX diverso — una build diversa, una precisione diversa e una macchina desktop, quindi non considerarlo nemmeno il tuo numero. Prevedi lentezza; sii piacevolmente sorpreso se non sarà così.

Cache KV e contesto lungo: occhio al margine

GLM-5.3-Flash vanta una finestra di contesto da 1 milione di token. Quel numero è irrilevante su questo hardware, e una guida che sostenesse il contrario ti farebbe un disservizio. La nota pratica è di una riga: dai al runtime un budget KV sufficiente per la lunghezza target. Su una singola H200, la 2bit-lite lascia circa 39 GB di margine per la cache KV dopo il caricamento dei pesi. Su un MacBook Pro da 128 GB i conti sono più duri: ~102 GB di pesi contro un tetto di ~112 GB lasciano circa 26 GB prima del working set di macOS — e i layer di attenzione lineare ibrida rendono piccola l'impronta KV di questo modello rispetto a un modello denso di queste dimensioni, ma cresce comunque linearmente con il contesto.

I consigli lato server provenienti dalla comunità più ampia confermano il punto: una configurazione che si carica bene con un contesto di 8K può esaurire la memoria a 128K. Sul laptop, mantieni i contesti brevi — qualche migliaio di token di Q&A o una singola immagine — e non cercare di fargli leggere un libro. Nel momento in cui un carico di lavoro richiede davvero un contesto lungo, ti trovi nell'ultima sezione di questo articolo.

La generazione di codice lungo non è affidabile con 2bit-lite (leggilo due volte)

Questa è la sezione senza la quale un how-to che nasconde i suoi modi di errore sarebbe inutile, quindi merita un titolo a parte. Le note di campo H200 sono inequivocabili: le domande e risposte di tutti i giorni e i testi brevi vengono bene, mentre la generazione di codice lungo non è affidabile a questa precisione. Tre modalità di errore riprodotte durante la nostra verifica:

• Cicli di ripetizione — il modello inizia a ripetere le stesse righe o blocchi invece di progredire, di solito dopo qualche centinaio di token.

• Codice collante mancante — import, collegamenti e gestione degli errori tralasciati silenziosamente. La funzione generata sembra corretta se isolata, ma non viene eseguita, perché l’impalcatura circostante è semplicemente assente.

• Riscrittura instabile — invece di una modifica minima, il modello riscrive grandi porzioni di un file e i turni successivi non concordano con l'output dei precedenti.

Questi sono riproducibili su 2bit-lite e sono esattamente le cose che una concordanza top-1 del 77% prevede. Quello che fanno in realtà i professionisti che tengono a portata di mano la build del laptop:

• Usalo per spiegare, sintetizzare, rispondere a domande e comprendere le immagini — lavori brevi in cui è davvero efficace.

• Se devi chiedere del codice, chiedi una piccola funzione alla volta con una firma esplicita, e verifica ciascuna prima di proseguire. Non consegnargli un intero file e chiedere una funzionalità.

• Per qualsiasi cosa di lunga durata — un modulo completo, un refactoring, una lunga sessione di agente — instrada verso l'API full-precision. Non è un workaround; è l'architettura corretta, ed è l'ultima sezione.

Quando non farlo affatto: chiama invece z-ai/glm-5.3-flash

La regola onesta: esegui 2bit-lite su un MacBook Pro M4/M5 Max da 128 GB solo quando vuoi specificamente un modello multimodale da 320B su un laptop che puoi portare con te — Q&A offline, documenti privati, comprensione delle immagini senza che nulla lasci la macchina. Scegli l'API per tutto il resto:

• Qualsiasi MacBook Pro con meno di 128 GB — non esiste una build per te. Non tentare di caricarla; usa l'API.

• Generazione di codice lungo o ragionamento su contesti lunghi — 2bit-lite fallisce esattamente in questo, puntualmente. Usa l'API.

• Lavoro sensibile alla qualità — 77,19% di accordo top-1 e +141% di perplexity sono un calo reale, non un errore di arrotondamento. Usa l'API.

• Throughput garantito o latenza prevedibile — non esiste ancora un valore misurato su laptop, e il campo nota è 10 tok/s. Usa l'API.

Il modello ospitato è z-ai/glm-5.3-flash, servito a piena precisione su OrcaRouter al prezzo attuale di Z.ai — $0,07 per milione di token di input e $0,25 per milione di token di output al momento in cui scriviamo (prezzo di lancio; la lista pubblicata da Z.ai è $0,15 / $0,50). Questo è il prezzo dichiarato dal fornitore e viene inoltrato senza alcun ricarico, quindi un taglio di prezzo di Z.ai si riflette sul nostro lato lo stesso giorno. Ottieni una sola chiave API che consente di raggiungere anche gli altri 200+ modelli che instradiamo, e il failover automatico fa sì che un esperimento con questo nuovo modello non scommetta il tuo percorso di produzione su un singolo fornitore. Nello stesso tempo necessario per scaricare 102 GB e attendere la prima generazione a freddo, l'API ha già risposto a una settimana di domande — e risponde a piena precisione.

L'inferenza locale vale la pena quando il motivo è locale — privacy, lavoro offline, nessun limite di richieste, una demo che funziona a batteria. Non vale la pena in termini di costi o qualità per nessun altro motivo, e non vale affatto la pena su una macchina con meno di 128 GB.

Domande frequenti

Un Mac da 64 GB o 96 GB può eseguire GLM-5.3-Flash localmente? No. La build più piccola, 2bit-lite, richiede un minimo di circa 112 GB dopo l'overhead di macOS, e anche una macchina con 128 GB deve alzare il limite della memoria wired per caricarlo. Se il tuo Mac ha meno di 128 GB, il percorso locale non esiste; instrada invece z-ai/glm-5.3-flash attraverso l'API.

Ho installato mlx-vlm e il modello non riesce a caricarsi: qual è il problema? Le due cause più comuni, in ordine: una versione inferiore alla 0.6.17, che precede il supporto per glm5_next e non riconosce l'architettura; e il limite della memoria wired non aumentato, perché la build da ~102 GB non riesce ad allocare sotto il tetto predefinito di Metal di ~91–96 GB su un Mac da 128 GB. Risolvi entrambe (aggiorna il pacchetto, esegui sysctl) e si carica.

Il build locale 2bit-lite è lo stesso modello dell'API z-ai/glm-5.3-flash?Stessi pesi sottostanti di GLM-5.3-Flash, ma non la stessa qualità. 2bit-lite è una quantizzazione a 2 bit con una concordanza token top-1 del 77.19% rispetto al riferimento FP8, e la generazione di codice lungo è inaffidabile. L'API serve precisione completa. Sono intercambiabili solo per lavori brevi e poco sensibili alla qualità.

La versione da 30 secondi

Una sola macchina, una sola build, un sysctl obbligatorio. Se hai un MacBook Pro M4/M5 Max da 128 GB: installa mlx-vlm>=0.6.17, scarica solo 2bit-lite/ (~102 GB), aumenta il limite della memoria wired con sudo sysctl iogpu.wired_limit_mb=114688, ed esegui mlx_vlm.generate — per domande e risposte, testo breve e immagini. Accetta che la generazione di codice lungo non sia affidabile a questa precisione, che non sia ancora stato misurato il throughput su laptop, e che un Mac da 128 GB sia il minimo, non lo standard. Se una di queste avvertenze è un problema — o se il tuo Mac ha meno di 128 GB — lo stesso modello a piena precisione è a una sola chiamata API su z-ai/glm-5.3-flash.

Non sei su un Mac da 128 GB? z-ai/glm-5.3-flash serve lo stesso modello a piena precisione su OrcaRouter — una sola chiave API, prezzi del provider passati senza alcun ricarico e nessun download da 102 GB.