Spaces:
Running on Zero
Running on Zero
|
Download README.md from waveshaker/universal-lora-studio: direct link, hf CLI and curl.
- Browser
- Download file 5.92 kB
-
https://huggingface.co/spaces/waveshaker/universal-lora-studio/resolve/main/README.md
- Command line
-
hf download hf://spaces/waveshaker/universal-lora-studio/README.md
-
curl -L -o README.md https://huggingface.co/spaces/waveshaker/universal-lora-studio/resolve/main/README.md
5.92 kB
| 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> | |