Run-book — installazione e collaudo sul Mac

Ordine deliberato: prima si misura, poi si installa. La fase 1 può dire che un modello non è adatto a questa macchina, e allora la configurazione cambia — meglio scoprirlo prima di scrivere pi-imgen.json.

Tutto è verificato su Linux tranne ciò che richiede hardware Apple. Quello che segue è esattamente ciò che non ho potuto misurare io.

0 · Prerequisiti (10 min)

uname -m                      # deve dire arm64
sw_vers -productVersion       # 13+ obbligatorio, 14+ per lo scontorno in un passaggio
node -v                       # >= 22.3  <-- pi-ai usa process.getBuiltinModule

⚠️ Node < 22.3 è la trappola più probabile. Su Node 20 ogni modulo che arriva a pi-ai fallisce con process.getBuiltinModule is not a function. Esiste un dist-tag legacy-node20 ma è fermo alla 0.74.2 contro la 0.84.x attuale: meglio aggiornare Node.

brew install node draw-things-cli typst
brew install ghostscript poppler qpdf     # opzionali: pre-flight di stampa

draw-things-cli è in Homebrew Core: niente tap personalizzati, niente --HEAD.

1 · Lo spike — il vero cancello (un pomeriggio)

Nessuno di questi numeri esiste pubblicamente per un M4 base. Da fare prima dell'installazione vera e propria.

1a. Il server caldo funziona davvero?

La cosa più importante di tutta la lista. Ho verificato che draw-things-cli --remote parli con gRPCServerCLI leggendo il sorgente di entrambi i lati, mai eseguendoli.

# scaricare il server (non è su Homebrew: è un asset di release)
curl -fL -o gRPCServerCLI-macOS \
  https://github.com/drawthingsai/draw-things-community/releases/download/v1.20260716.0/gRPCServerCLI-macOS
chmod +x gRPCServerCLI-macOS

./gRPCServerCLI-macOS /Volumes/<disco>/ai-models --no-tls --port 7859 --cpu-offload &

# la STESSA generazione due volte, cronometrata
time draw-things-cli generate --model z_image_turbo_1.0_i8x.ckpt \
  --prompt "autumn chestnut harvest, warm evening light, painterly" \
  --negative-prompt "text, letters, words, typography, watermark, signature" \
  --width 768 --height 1088 --steps 8 --seed 42 \
  --models-dir /Volumes/<disco>/ai-models --disable-preview \
  --remote --remote-url 127.0.0.1 --remote-port 7859 --no-remote-tls \
  --output /tmp/a.png

Se la seconda esecuzione è molto più rapida, il modello è rimasto caldo e tutto il disegno del ciclo bozza→finale regge. Se invece i tempi sono uguali, il server non sta servendo: si ripiega su draw-things-cli da solo (ogni generazione ricarica il modello) e le bozze diventano lente ma il resto funziona.

⚠️ --output è obbligatorio: senza, la CLI disegna un'anteprima nel terminale e non scrive alcun file. --disable-preview idem.

1b. Gli altri quattro numeri

Cosa	Come	Perché conta
`_i8x` vs `_q5p`	stessa generazione, due modelli	`_i8x` usa la Neural Engine dell'M4: atteso ~2x
Tiling VAE on/off a 1024²	`--config-json '{"tiledDecoding":true,...}'` vs `false`, guardando la memoria in Activity Monitor	14.03 GB → 7.18 GB di picco: è la differenza fra funzionare e andare in swap
Ingrandimento a A3/300dpi	il modello `upscale` su un 1024px	Obbligatorio per la stampa: 1024px su A3 sono ~62 dpi
img2img va in crash?	una generazione con `--image`	Bug noto #121 sui Mac da 16 GB. Se si presenta, si perde solo la modifica generativa

Annotare i tempi: servono a scegliere i passi di default.

2 · Installazione

pi install git:git.sal.giize.com/mozempk/pi-imgen
cd ~/.pi/agent/git/git.sal.giize.com/mozempk/pi-imgen
./install.sh

⚠️ Da verificare al primo colpo: che pi install git: accetti un host diverso da GitHub — tutti gli esempi documentati sono GitHub. Se non risolve, il ripiego è clonare a mano e aggiungere il percorso a extensions in ~/.pi/agent/settings.json: stesso risultato, un passaggio in più.

install.sh è ri-eseguibile: chiede dove tenere i modelli (disco esterno) e dove salvare i file, scarica i caratteri, e unisce in ~/.pi/agent/pi-imgen.json senza sovrascrivere i preset.

Il direttore artistico ha bisogno di un modello

Registrare opencode Go come provider in pi — è OpenAI-compatibile:

base URL : https://opencode.ai/zen/go/v1
API key  : $OPENCODE_API_KEY

Poi in pi-imgen.json: "directorProvider" e "directorModel".

Senza questo il direttore non ha su cosa girare. (Verificato: quell'abbonamento non contiene modelli di immagini — può essere solo il cervello, mai il pennello.)

3 · Collaudo

pi
> /doctor

/doctor parla italiano e dice cosa manca con il rimedio: disco non montato, binario assente, modello mancante, caratteri non scaricati.

Poi la prova vera:

> /poster

Un evento reale in arrivo. Il collaudo è lui che produce una locandina da solo, non una suite di test che passa.

Sul terminale: le anteprime inline richiedono iTerm2, Ghostty, WezTerm o Warp. Terminal.app di Apple non mostra immagini — i file però si aprono nel Finder comunque.

Prima di portarla in tipografia

pdfinfo -box poster.pdf     # TrimBox presente, 303x426 mm per A3+3mm
pdffonts poster.pdf         # ogni riga: emb=yes   (sub=yes è normale)

Consegnare un PDF singolo, 3 mm di abbondanza, RGB, senza crocini: va bene per la grande maggioranza delle copisterie. I crocini si attivano da configurazione solo se la tipografia li chiede (i servizi online li rifiutano).

Se qualcosa va storto

Sintomo	Causa
`process.getBuiltinModule is not a function`	Node < 22.3 → §0
Nessun file prodotto, nessun errore	Manca `--output`
"disco dei modelli non montato"	Volume esterno assente — messaggio previsto, non un bug
Crash su img2img	Bug #121 → `/poster` e `/logo` funzionano lo stesso
Scontorno non disponibile	Serve macOS 14; su 13 ripiega su rembg (non il modello di default: è CC BY-NC)
Bozze lente quanto il finale	Il server caldo non sta servendo → §1a

Dettagli e assunzioni non verificate: platform-notes.md.

6.1 KiB Raw Blame History