---
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"
---
---

<div align="center">
  <h1>⚡ Universal LoRA Studio</h1>
</div>

---

### ⚙️ 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<br/>• REST API Calls | Authenticates users, provides a native UI, and submits generation parameters via a lightweight HTTP payload. |
| **🧠 Proxy & Scheduler Layer**<br/>(FastAPI + Gradio) | • **Dummy Probe**<br/>• **ContextVar**<br/>• **Singleton Executor**<br/>• 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**<br/>(ZeroGPU + ComfyUI) | • **Binary Tensor Fast-Path**<br/>• **RAM_PRESSURE Cache**<br/>• **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

```text
[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](https://huggingface.co/spaces/waveshaker/loras_gallery)** - Explore 1000+ community characters.
- 📊 **[Dataset](https://huggingface.co/datasets/waveshaker/dataset_collections)**


<div align="center">
  <sub>Engineered by <b>waveshaker</b>. Running on ZeroGPU. Duplicated and modified from <a href="https://huggingface.co/spaces/2i/pornmaster-krea2">2i/pornmaster-krea2</a>.</sub>
</div>