docs: run-book for Mac setup, spike and commissioning
This commit is contained in:
mozempk
@@ -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
|
||||
|
||||
|
||||
+161
@@ -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/<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
|
||||
|
||||
```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).
|
||||
Reference in New Issue
Block a user