From 164e8fcd3d2b7c2e1e8c11aa819f27110df8035a Mon Sep 17 00:00:00 2001 From: mozempk Date: Thu, 27 Aug 2026 12:28:03 +0200 Subject: [PATCH] docs: run-book for Mac setup, spike and commissioning --- README.md | 3 +- docs/RUNBOOK.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 docs/RUNBOOK.md diff --git a/README.md b/README.md index 535979e..925bc05 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,8 @@ configurazione. | Caratteri | 22 famiglie OFL/Apache incluse nel pacchetto ([THIRD-PARTY-FONTS.md](THIRD-PARTY-FONTS.md)) | Dettagli verificati sperimentalmente in [`docs/typst-verified.md`](docs/typst-verified.md); -requisiti di sistema e assunzioni non verificate in [`docs/platform-notes.md`](docs/platform-notes.md). +requisiti di sistema e assunzioni non verificate in [`docs/platform-notes.md`](docs/platform-notes.md); +procedura di installazione e collaudo in [`docs/RUNBOOK.md`](docs/RUNBOOK.md). ## Licenza diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md new file mode 100644 index 0000000..7a0d3d8 --- /dev/null +++ b/docs/RUNBOOK.md @@ -0,0 +1,161 @@ +# 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) + +```bash +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. + +```bash +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**. + +```bash +# 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//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//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 + +```bash +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 + +```bash +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 + +```bash +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`](platform-notes.md).