PrismML-Eng/Bonsai-Image-Demo

Bonsai Image Demo – 快速概覽

是什麼 – 一個可立即執行的示範，用於使用 Bonsai‑Image 擴散模型（4 B 參數）生成影像。它打包了在三種常見硬體架構上執行模型所需的全部內容：

Apple Silicon (macOS) – 使用 mflux 分支搭配 MLX 實現快速裝置內推論。
搭載 NVIDIA GPU 的 Linux – 使用 Dropbox 的 gemlite 後端搭配 HQQ 1 位/1.58 位內核。
搭載 NVIDIA GPU 的 Windows – 透過 triton‑windows 專案使用相同的 gemlite/HQQ 堆疊，無需 WSL2。

該倉儲提供腳本以下載合適的權重、啟動基於 Web 的 Prism Image Studio（FastAPI 後端 + Next.js 前端），或執行簡單的 CLI 進行一次性影像生成。

主要功能

功能	詳細資訊
模型變體	`ternary`（1.58 位，更高畫質）– 預設；`binary`（1 位，更小且更快）。
跨平台後端	macOS → MLX (`mflux`)；Linux/Windows → `gemlite` + `HQQ` 內核。
完整工作室 UI	FastAPI 伺服器運行於 `:8000`，Next.js UI 運行於 `:3000`（透過 `scripts/serve.sh` 一同啟動）。
CLI 生成	`scripts/generate.sh` 用於冷啟動一次性執行；`scripts/send_request.sh` 用於與正在執行的工作室通訊（保持權重常駐）。
自動依賴處理	`setup.sh` / `setup.ps1` 安裝固定版本的 Python 環境（透過 `uv`）和 Node 套件，並克隆所需的 `vendor/` 倉儲。
供應鏈安全	新於 `BONSAI_PACKAGE_MIN_AGE_DAYS`（預設 7）的套件將被拒絕，以避免未經審核的發佈。
模型下載助手	`scripts/download_model.sh` 為您的平台和變體選擇正確的權重集。
樣本尺寸	預定義的長寬比預設，用於快速（約 0.25 MP）和高品質（約 1 MP）渲染。

快速開始（macOS / Linux）

# 1️⃣ 安裝環境並下載預設的 ternary 模型
./setup.sh

# 2️⃣ 啟動工作室（後端 + UI）
./scripts/serve.sh   # 後端在 8000，UI 在 3000

# 3️⃣ 透過 UI **或** 終端生成影像
./scripts/send_request.sh -p "A snowy bonsai tree in a misty forest" --size 1248x832

Windows（PowerShell）

# 一次性策略變更以允許腳本執行
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

# 安裝並下載
.
setup.ps1

# 執行工作室
.
scripts
un.ps1   # 實際為 ./scripts/serve.ps1

# 生成影像
.
scripts
un_request.ps1 -p "A snowy bonsai tree in a misty forest" --size 1248x832

(請參閱 scripts/windows.md 了解驅動程式、vcredist 和 OOM 故障排除。)

模型與後端選擇

平台	預設後端	預設模型變體
macOS (Apple Silicon)	`mflux` + MLX	`bonsai-image-4B-ternary-mlx`
Linux (NVIDIA)	`gemlite` + HQQ	`bonsai-image-4B-ternary-gemlite`
Windows (NVIDIA)	`gemlite` + HQQ 透過 `triton-windows`	與 Linux 相同

可透過環境變數覆蓋，例如：

BONSAI_VARIANT=binary ./setup.sh
BONSAI_VARIANT=binary ./scripts/serve.sh

設定後的資料夾結構

Bonsai-image-demo/
  .venv/                     # 隔離的 Python 環境
  vendor/
    image-studio/            # FastAPI + Next.js 程式碼（自動克隆）
    mflux-prism/             # 適用於 macOS 的修補版 mflux
  models/
    bonsai-image-4B-ternary-mlx/
    bonsai-image-4B-ternary-gemlite/
    bonsai-image-4B-binary-mlx/      (可選)
    bonsai-image-4B-binary-gemlite/  (可選)
  outputs/                  # 生成的 PNG 檔案
  scripts/
    download_model.*
    serve.*
    generate.*
    send_request.*
    generate.py

TL;DR

Bonsai Image Demo 是一個完全腳本化的跨平台沙盒，用於 4 B 參數的 Bonsai 擴散模型。它處理模型下載、環境設定，並提供 Web UI 和 CLI，讓您在 Apple Silicon 或 NVIDIA GPU 上輕鬆生成逼真的影像。