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 上轻松生成逼真的图像。