From 876a666e9ab0b73a73bd09f3cd198444c90ed997 Mon Sep 17 00:00:00 2001 From: m3ultra Date: Thu, 16 Jul 2026 14:00:39 +1000 Subject: [PATCH] =?UTF-8?q?HARDWARE.md:=20per-operator=20RAM=20+=20Apple?= =?UTF-8?q?=20Silicon=20tier=20guide=20(8GB=E2=86=92256GB)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLUSTER.md | 1 + HARDWARE.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 3 files changed, 66 insertions(+) create mode 100644 HARDWARE.md diff --git a/CLUSTER.md b/CLUSTER.md index 85c74ff..53b7cfe 100644 --- a/CLUSTER.md +++ b/CLUSTER.md @@ -41,3 +41,4 @@ Which node may run which operator is set in `nodes.json` (repo root, gitignored, - **prompt/image → image:** local `flux_local` (FLUX.2 Klein) → `mflux_image_edit`. fal/OpenRouter for nano-banana scene-storytelling. - **video → frames / poses:** `ffmpeg_frames`, `colmap_poses` (CPU — great M4 work). - Full matrix + prices: [AGENTS.md](AGENTS.md) · [BENCHMARKS.md](BENCHMARKS.md). +- **Which Mac runs what (RAM/hardware guide): [HARDWARE.md](HARDWARE.md)** — min + recommended RAM per operator, per Apple Silicon tier (M1 8GB → Ultra 256GB). diff --git a/HARDWARE.md b/HARDWARE.md new file mode 100644 index 0000000..b9aaa9c --- /dev/null +++ b/HARDWARE.md @@ -0,0 +1,64 @@ +# MODELBEAST hardware guide — what runs on which Mac + +Which Apple Silicon Mac can run which operator, by **unified memory (RAM)**. Numbers below are *measured on the M3 Ultra* unless marked *(est.)*; peak = peak unified memory during a run. + +## How to read this + +- **Unified memory is the gate.** CPU and GPU share one pool. A model's *peak* must fit in `RAM − ~3-5GB` (macOS + apps). For comfort without swapping, want peak **+ 8-12GB** headroom. Swapping = usable but slow. +- **Chip tier = speed, not fit.** An M1 Max 64GB *runs* the same models as an M3 Max 64GB, just slower. Rough per-generation speed: **Ultra > Max > Pro > base**, and **M5 > M4 > M3 > M2 > M1** per core. Our M1 Ultra runs the 3D stack at ~2× the M3 Ultra's time — fine for throughput, not for latency. +- **`net` operators run on *any* Mac** — an 8GB M1 mini is a perfectly good node for `fal_*` / `openrouter_image`, because the compute is in the cloud. Same for light `cpu` ops. +- **bf16 caveat (M1/M2):** M1 (and to a lesser extent M2) lack full hardware bf16. `trellis_mac` (torch-MPS, bf16) is **unverified on M1/M2 — treat as M3+**. `hunyuan3d_mlx` is fp16 MLX and runs fine on every Apple Silicon Mac with the RAM. +- **You can push the GPU memory ceiling** with `sudo sysctl iogpu.wired_limit_mb=` (e.g. raise a 128GB box's GPU cap toward ~120GB). Helps the largest models on Ultra/Max. + +## Per-operator memory (sorted light → heavy) + +| Operator | Lane | Weights | Peak RAM | Min Mac | Recommended | Notes | +|---|---|---|---|---|---|---| +| `fal_*`, `openrouter_image` | net | 0 | ~0 | **8 GB** | 8 GB | cloud compute; RAM irrelevant | +| `ffprobe` | cpu | 0 | <1 GB | 8 GB | 8 GB | trivial | +| `ffmpeg_frames` | cpu | 0 | <1 GB | 8 GB | 8 GB | frame extraction | +| `blender_convert` | cpu | 0 | 1–4 GB *(est.)* | 8 GB | 16 GB | needs Blender installed | +| `colmap_poses` | cpu | 0 | 2–8 GB *(scales w/ #images)* | 8 GB | 16 GB | needs COLMAP+GLOMAP | +| `bg_remove_local` (RMBG-2.0) | gpu | 0.8 GB | ~3 GB *(est.)* | **8 GB** | 16 GB | light; great first-step everywhere | +| `sf3d` | gpu | 3.7 GB | **~9 GB** | 16 GB | 24 GB | ~5s draft mesh | +| `seedvr2_upscale` | gpu | 6.8 GB | ~8–12 GB *(est.)* | 16 GB | 24 GB | image upscale | +| `hunyuan3d_mlx` INT4/INT8 *(self-convert)* | gpu | 1.6–3 GB | ~4–10 GB | **16 GB** | 16–24 GB | fits small Macs; see [Hunyuan guide](vendor/hunyuan3d-mlx/HARDWARE.md) | +| `flux_local` Klein 4B *(default)* | gpu | 15 GB | **18.0 GB** | 24 GB | 32 GB | 9s image, the volume workhorse | +| `flux_local` schnell-4bit | gpu | 8.9 GB | **19.1 GB** | 24 GB | 32 GB | fast FLUX.1 draft | +| `hunyuan3d_mlx` fp16 *(our default, 4096/120k)* | gpu | 13 GB | **20.2 GB** | 24 GB *(tight)* | 32 GB | Stage 1 alone ~10 GB; both stages ~20 GB | +| `trellis_mac` | gpu | 14 GB | ~15–18 GB | 24 GB | 32 GB | **M3+ (bf16)**; SOTA local mesh | +| `flux_local` FLUX.1 dev | gpu | 31 GB | **25.1 GB** | 32 GB | 48 GB | cinematic, ~2 min | +| `flux_local` Klein 9B | gpu | 32 GB | **28.4 GB** | 36 GB | 48 GB | best object accuracy in the lineup | +| `mflux_image_edit` (Qwen-Image-Edit) | gpu | 54 GB | ~30–40 GB *(est.)* | 48 GB | **64 GB+** | the heavyweight local editor | +| `brush_train` (3DGS) | gpu | 0 | scales w/ scene | 16 GB | 32 GB | Gaussian-splat training | + +## What each Mac can do, by RAM + +| RAM | Realistic role | Runs | +|---|---|---| +| **8 GB** (M1/M2/M3 base) | cloud + light node | all `net` ops, `ffmpeg`/`ffprobe`, `bg_remove_local`, a 3–4B Ollama LLM. *That's a genuinely useful fleet node.* | +| **16 GB** (base/Pro) | light local gen | above + `sf3d`, `seedvr2_upscale`, `colmap`, Hunyuan **INT4/INT8**, 7–8B Ollama. FLUX/fp16-Hunyuan/trellis won't fit. | +| **24 GB** (M2/M3 base, M4 Pro) | entry real-gen | above + `flux_local` **Klein 4B**, `hunyuan3d_mlx` fp16 *(tight)*, `trellis_mac` *(M3/M4 only)*. The practical floor for the full local 3D + image stack. | +| **32 GB** (Pro/Max) | comfortable all-round | the whole core stack with headroom: Klein 4B, hunyuan fp16 4096, trellis, FLUX dev. | +| **36–48 GB** (Max) | hero-tier images | + FLUX.1 **dev**, FLUX.2 **Klein 9B** (the accuracy king). | +| **64 GB** (Max/Ultra) | everything but the giant | + `mflux_image_edit` (Qwen 54 GB) comfortably; run two mid models resident. | +| **96–128 GB** (Ultra) | multi-model resident | several big models loaded at once; our **M1 Ultra 128 GB** tier — runs it all (mind the bf16 caveat for trellis). | +| **192–256 GB+** (Ultra) | the flex | every operator + a big local LLM (70B–235B) resident alongside — our **M3 Ultra 256 GB** primary. | + +## Our fleet, mapped + +| Node | RAM | Tier | What it serves | +|---|---|---|---| +| **M3 Ultra** | 256 GB | the flex | everything + primary/queue | +| **M1 Ultra** | 128 GB | multi-model | `hunyuan3d_mlx` (MLX-native), FLUX, sf3d, RMBG, cpu ops — *not* trellis (bf16 unverified) | +| **M4 Pro** | 24 GB | light helper | `bg_remove_local`, `ffmpeg_frames`/`ffprobe`, Ollama 7B — too small for the 18–28 GB gen models | + +## Buying / sizing rules of thumb + +- **Cheapest useful node:** any **8 GB** Apple Silicon → cloud + ffmpeg + background-removal + small LLM. +- **Cheapest *real* local-gen box:** **24 GB** (M4 Pro mini / M2-M3 24 GB) → Klein 4B images + local 3D. +- **Sweet spot for one do-everything machine:** **32–48 GB M-series Max** → the entire core stack, hero images, both local 3D models, comfortably. +- **Want Qwen image-edit or multiple big models resident:** **64 GB+**. +- **M1 owners:** prefer `hunyuan3d_mlx` over `trellis_mac` for local 3D (bf16). Everything MLX (FLUX via mflux, hunyuan) is first-class on M1. + +*Fleet policy + queue routing: [CLUSTER.md](CLUSTER.md). Measured benchmarks: [BENCHMARKS.md](BENCHMARKS.md). Hunyuan-specific RAM tiers: [vendor/hunyuan3d-mlx/HARDWARE.md](vendor/hunyuan3d-mlx/HARDWARE.md).* diff --git a/README.md b/README.md index 052c4b4..f4412fe 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ Local-first web app that turns videos, images, and 3D files into meshes, splats, mocap, and rigged characters on the M3 Ultra. See [PLAN.md](PLAN.md) for the full verified tool matrix and roadmap, and [HANDOFF.md](HANDOFF.md) for the agent build brief (phases 1–4 instructions). > 🖥️ **Multi-Mac fleet? Read [CLUSTER.md](CLUSTER.md) first** — the local-first policy, the M3/M1/M4 node roles, and how the central queue routes jobs across machines. +> 💾 **What runs on which Mac?** [HARDWARE.md](HARDWARE.md) — min/recommended RAM per operator across every Apple Silicon tier (8GB → 256GB). ## Run