PrismML-Eng/Bonsai-Image-Demo

Bonsai Image Demo – 빠른 개요

무엇인가요 – 4 B 파라미터의 Bonsai‑Image 디퓨전 모델을 사용하여 이미지를 생성하기 위한 즉시 실행 가능한 데모입니다. 세 가지 일반적인 하드웨어 스택에서 모델을 실행하기 위해 필요한 모든 것을 통합했습니다.

Apple Silicon (macOS) – mflux 포크와 MLX를 사용하여 빠른 디바이스 내 추론을 제공합니다.
NVIDIA GPU를 탑재한 Linux – Dropbox의 gemlite 백엔드와 HQQ 1비트/1.58비트 커널을 사용합니다.
NVIDIA GPU를 탑재한 Windows – triton‑windows 프로젝트를 통해 gemlite/HQQ 스택을 사용하며, WSL2가 필요하지 않습니다.

이 리포지토리는 적절한 가중치를 다운로드하고, 웹 기반 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 환경 (via `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 디퓨전 모델을 위한 완전히 스크립트화된 크로스플랫폼 환경입니다. 모델 다운로드, 환경 설정, 웹 UI와 CLI를 모두 제공하여 Apple Silicon 또는 NVIDIA GPU에서 최소한의 번거로움으로 사진처럼 생생한 이미지를 생성할 수 있습니다.