PrismML-Eng/Bonsai-Image-Demo

Bonsai Image Demo – 速報

何であるか – 4 Bパラメータの Bonsai‑Image ディフュージョンモデルで画像生成を行うための即時実行可能なデモ。3つの一般的なハードウェアスタック上でモデルを実行するために必要なすべてをバンドルしています。

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	`:8000` でFastAPIサーバー、`:3000` でNext.js UI（`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

(ドライバー、vcredist、OOMトラブルシューティングについては scripts/windows.md を参照。)

モデルとバックエンドの選択

プラットフォーム	デフォルトのバックエンド	デフォルトのモデルバリアント
macOS (Apple Silicon)	`mflux` + MLX	`bonsai-image-4B-ternary-mlx`
Linux (NVIDIA)	`gemlite` + HQQ	`bonsai-image-4B-ternary-gemlite`
Windows (NVIDIA)	`gemlite` + HQQ via `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

詳細情報の入手先

ウェブサイト – https://prismml.com
Hugging Faceコレクション – https://huggingface.co/collections/prism-ml/bonsai-image
ホワイトペーパー – bonsai-image-4b-whitepaper.pdf（リポジトリ内に含まれる）
ライブデモ – README内のHugging Face Spaceリンク
コミュニティ – Discordサーバー（README内のリンク）

TL;DR

Bonsai Image Demo は、4 BパラメータのBonsaiディフュージョンモデル用の完全スクリプト化されたクロスプラットフォーム環境です。モデルダウンロード、環境設定、Web UIとCLIの両方を提供し、Apple SiliconまたはNVIDIA GPU上で、最小限の手間で写実的な画像を生成できます。