README.md

metadata

title: Universal Model Character LoRA Studio
emoji: 🎨
colorFrom: gray
colorTo: green
sdk: gradio
hf_oauth: true
fullWidth: true
sdk_version: 6.31.0
python_version: '3.12'
app_file: app.py
pinned: true
short_description: Run waveshaker's 𝗠𝗢𝗦𝗦/𝗞𝗿𝗲𝗮𝟮/𝗔𝗻𝗶𝗺𝗮/𝗙𝗟𝗨𝗫/𝗣𝗼𝗻𝘆 LoRAs

---

⚡ Universal LoRA Studio

---

⚙️ System Architecture

This Space is a specialized, on-demand inference engine designed to run Waveshaker's character LoRAs on ZeroGPU. To overcome Hugging Face's cross-space CORS restrictions and ZeroGPU's billing constraints, I use a decoupled "Proxy-Driven" architecture with a blazing-fast native frontend.

🏗️ System Topology

Layer	Core Components	Role & Responsibility
🖥️ Client	• Native HTML/JS • REST API Calls	Authenticates users, provides a native UI, and submits generation parameters via a lightweight HTTP payload.
🧠 Proxy & Scheduler Layer (FastAPI + Gradio)	• Dummy Probe • ContextVar • Singleton Executor • Threading Lock (_exec_lock)	Bypasses the ZeroGPU scanner, passes the x-ip-token accurately, serializes incoming tasks, and enforces hard boundary limits (1536px).
⚡ Execution Layer (ZeroGPU + ComfyUI)	• Binary Tensor Fast-Path • RAM_PRESSURE Cache • WebP + EXIF Injection	Executes the pipeline using custom zero-copy tensor loading. Relies entirely on ComfyUI's native LRU cache for multi-model hot-swapping without OOM.

🔄 Request Lifecycle

[User] ──(OAuth Login)──► [Native Studio UI]
                               │
                               │ (POST Model & LoRA Params)
                               ▼
                 [FastAPI Routing & Thread Scheduler]
                 ├── HTTPException (Enforces 1536px limit)
                 ├── ContextVar (Binds x-ip-token accurately)
                 └── Background Thread (Appends to Queue)
                               │
                               │ (Task pops from queue)
                               ▼
                 [Gradio + ZeroGPU Probe (@spaces.GPU duration=40)]
                 ├── Dummy Probe (Retains quota & allocates slot)
                 └── Threading Lock (Serializes jobs via _exec_lock)
                               │
                               │ (Passes to Singleton Executor)
                               ▼
                       [ComfyUI Core Engine]
                 ├── Fast-Path Loader (Zero-copy numpy for INT8)
                 ├── RAM_PRESSURE Cache (Seamless hot-swapping)
                 └── WebP + Binary EXIF Injection
                               │
                               ▼
                 [Static `/output/` Mount] ──► [Browser Renders Image]

📝 One-Sentence Summary

A decoupled "Proxy-Driven" architecture: a native frontend passes LoRA parameters via URL, while a Gradio proxy bypasses cross-space CORS and ZeroGPU billing constraints. It serves generated images as physical WebP URLs with custom-injected ComfyUI EXIF metadata, delivering accurate billing.

📜 Architecture Evolution

• v0.1 (The FastAPI Initiation): The initial dual-track setup. FastAPI handled data routing, while Gradio rendered the UI. Due to cross-space CORS restrictions and a lack of x-ip-token handling, the frontend fell into the ZeroGPU anonymous pool.
• v0.2 (The Gradio-Injection Era): A modular reconstruction (core/, frontend/, ui/). Introduced the task_runner for precise background scheduling and logging. To retain ZeroGPU billing, I hid Gradio components and injected native HTML/CSS/JS via Python. This successfully kept the GPU quota but introduced frontend performance bottlenecks and UI state sync issues.
• v0.3 (The Decoupled Proxy UI): A new refactor. A 100% native static web UI is decoupled from the FastAPI backend. I implemented a dummy Gradio probe to trick the ZeroGPU scanner and used ContextVar to perfectly pass through the x-ip-token. Featuring a dual-Space sync mechanism (frontend_cache), it delivers faster loading,accurate ZeroGPU billing, and a pure native frontend experience.
• v0.4 (The Performance Hardened Era): A brutal optimization phase to eliminate the 50s+ cold-start latency and multi-model memory leaks under ZeroGPU.
  • Binary Tensor Fast-Path: Bypassed ComfyUI's native slow loading path by intercepting load_torch_file and implementing numpy zero-copy for large INT8/ConvRot tensors.
  • Lazy Execution & Native Cache: Removed aggressive empty_cache and manual GC interventions. Relied entirely on ComfyUI's native RAM_PRESSURE (LRU 8, 16GB RAM limit) to orchestrate multi-model hot-swapping smoothly.
  • Queue-Aware Billing: Adjusted @spaces.GPU(duration=40) to gracefully handle ZeroGPU queueing spikes during consecutive architecture switching.
  • Safety Boundaries: Enforced hard pixel and edge limits (1536px) at both frontend and FastAPI levels to prevent OOM and timeout kills.
  • Result: Cold-start load time dropped from 24s to **6.5s**. Cross-architecture hot-swapping (e.g., Flux 1536 → MOSS 1536) stabilized under 15s total, completely eliminating the "ghost 35s" timeouts.

---

🔗 Ecosystem Links

• 🖼️ Browse the LoRA Gallery - Explore 1000+ community characters.
• 📊 Dataset

_{Engineered by waveshaker. Running on ZeroGPU. Duplicated and modified from 2i/pornmaster-krea2.}