README.md

---
title: Qwen Soloband Advanced - Image2Image + LoRA
emoji: 🎨
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "5.9.1"
app_file: app.py
pinned: true
license: apache-2.0
suggested_hardware: a10g-large
suggested_storage: medium
models:
  - Gerchegg/Qwen-Soloband-Diffusers
tags:
  - image-generation
  - image-to-image
  - lora
  - qwen
  - diffusers
short_description: Text2Image and Image2Image with LoRA support
preload_from_hub:
  - Gerchegg/Qwen-Soloband-Diffusers
---

# 🎨 Qwen Soloband Advanced

**Комплексная система генерации изображений** на базе Qwen-Image DiT с полным набором инструментов для профессиональной работы.

## 🆕 Что нового в версии 2.0

- ⚙️ **10+ Schedulers/Samplers** - Выбор алгоритма генерации (DPM++, Euler, UniPC и др.)
- 🎯 **Поддержка алиасов** - Короткие имена для API (`dpmpp_2m_karras`, `euler_a`)
- 🔧 **Кастомные модели** - Задавайте MODEL_REPO через переменную окружения
- 📦 **RunPod скрипты** - Автоматическая установка одной командой
- 📚 **Улучшенная документация** - Полное руководство по развертыванию

## 🚀 Основные возможности

### 📝 Text-to-Image
Генерация изображений из текстовых описаний:
- 🎨 Кастомная fine-tuned модель Qwen-Soloband
- 📐 Разрешения от 512×512 до 2048×2048
- ⚙️ Полный контроль параметров (steps, CFG, seed)
- 🎯 Оптимизированные настройки для лучшего качества

### 🔄 Image-to-Image
Модификация и трансформация существующих изображений:
- 🖼️ Загрузка любых изображений (PNG, JPG, WebP)
- 🎚️ **Denoising Strength** (0.0-1.0) - точный контроль степени изменения
- 🎨 Сохранение структуры при изменении стиля
- ✨ Улучшение качества, стилизация, художественная трансформация

### 🎭 LoRA Styles
Динамическая загрузка стилей для разнообразия:
- 📸 **Realism** - фотореалистичные изображения
- 🎌 **Anime** - современный японский стиль аниме
- 🎚️ **LoRA Scale** (0.0-2.0) - интенсивность стиля
- 📁 **Локальные LoRA** - Загрузка из `/workspace/loras/`

---

## 🚀 Quick Start на RunPod

### Одна команда - полная установка:

```bash
export HF_HUB_ENABLE_HF_TRANSFER=0 && \
pip install -q huggingface_hub[cli] && \
hf auth login --token ВАШ_ТОКЕН && \
cd /workspace && \
hf download Gerchegg/Qwen-ImageForFlo-Advanced --repo-type space --local-dir Qwen-ImageForFlo-Advanced && \
cd Qwen-ImageForFlo-Advanced && \
pip install -r requirements.txt && \
python app.py
```

**📖 Полная инструкция:** См. [RUNPOD_DEPLOYMENT.md](./RUNPOD_DEPLOYMENT.md)

### Или используйте скрипт:

```bash
wget https://huggingface.co/spaces/Gerchegg/Qwen-ImageForFlo-Advanced/resolve/main/quick_start.sh
chmod +x quick_start.sh
HF_TOKEN="ВАШ_ТОКЕН" ./quick_start.sh
```

---

## 🔌 API Usage

### Text-to-Image API

```python
from gradio_client import Client

client = Client("Gerchegg/Qwen-ImageForFlo-Advanced")

result = client.predict(
    prompt="SB_AI, a beautiful landscape",
    negative_prompt="blurry, low quality",
    width=1664,
    height=928,
    seed=42,
    randomize_seed=False,
    guidance_scale=2.5,
    num_inference_steps=40,
    lora_name="None",  # или "Realism", "Anime"
    lora_scale=1.0,
    scheduler_name="DPM++ 2M Karras",  # 🆕 Выбор scheduler/sampler
    api_name="/text2img"
)

image, seed = result
```

### Image-to-Image API

```python
result = client.predict(
    input_image="path/to/image.png",  # PIL Image или path
    prompt="Transform this into a painting",
    negative_prompt="blurry, low quality",
    strength=0.75,  # 0.0-1.0, больше = сильнее изменение
    seed=42,
    randomize_seed=False,
    guidance_scale=2.5,
    num_inference_steps=40,
    lora_name="None",
    lora_scale=1.0,
    scheduler_name="Euler Ancestral",  # 🆕 Выбор scheduler/sampler
    api_name="/img2img"
)

image, seed = result
```


## 💡 Примеры использования

### Text-to-Image
```
Prompt: "SB_AI, a beautiful mountain landscape at sunset, detailed"
Size: 1664×928
Steps: 40, CFG: 2.5
LoRA: None
```

### Image-to-Image
```
Input: фото человека
Prompt: "Transform into oil painting style"
Strength: 0.75 (сохранить структуру, изменить стиль)
LoRA: Analog Film
```


## 🎛️ Доступные Schedulers (Samplers)

⚠️ **Важно:** Qwen-Image использует **Flow Matching**, а не классическую diffusion!  
Работают только **FlowMatchEulerDiscreteScheduler** с различными параметрами shift.

### ✅ Протестированные и рабочие schedulers:

| Scheduler | Время | Speedup | Алиас | Рекомендация |
|-----------|-------|---------|-------|--------------|
| **Flow Euler (Shift 0.5)** | **33.8s** | **1.00x** | `flow_euler_shift05` | 🥇 **САМЫЙ БЫСТРЫЙ** (по умолчанию) |
| Flow Euler (Shift 2.0) | 34.6s | 1.02x | `flow_euler_shift20` | 🥈 Быстрый + детали |
| Flow Euler (Shift 1.5) | 38.8s | 1.15x | `flow_euler_shift15` | 🥉 Баланс |
| Flow Euler (Default) | 40.2s | 1.19x | `flow_euler` | Стандарт (shift=1.0) |

*Время указано для 1024×1024, 40 steps на ZeroGPU*

### Использование

**В интерфейсе:**  
Выберите в dropdown "Sampler/Scheduler"

**В API (полное имя):**
```python
scheduler_name="Flow Euler (Shift 0.5)"  # Самый быстрый!
```

**В API (алиас):**
```python
scheduler_name="flow_euler_shift05"  # Короткий вариант
```

**Примеры:**
```python
# Для быстрой генерации (рекомендуется)
scheduler_name="Flow Euler (Shift 0.5)"
num_inference_steps=40
# Время: ~34s

# Для максимума деталей
scheduler_name="Flow Euler (Shift 2.0)"
num_inference_steps=50
# Время: ~43s

# Стандартный
scheduler_name="Flow Euler (Default)"
num_inference_steps=40
# Время: ~40s
```

### 📊 Влияние Shift параметра:

- **Shift 0.5:** Больше шагов в начале → быстрее
- **Shift 2.0:** Равномернее распределение → детальнее
- **Разница:** 19% между самым быстрым и самым медленным

### 🔬 Почему только Flow Euler?

Qwen-Image это **Flow Matching** модель. Pipeline автоматически передает `sigmas` параметр в `scheduler.set_timesteps()`. Только `FlowMatchEulerDiscreteScheduler` полностью совместим с этой архитектурой.

**Не работают:** DPM++, обычный Euler, Ancestral, UniPC, DDIM - все это классические diffusion schedulers.

---

## 🎭 Доступные LoRA

### 🌐 HuggingFace Hub LoRA (2 предустановленных):

| Name | Trigger Word | Description |
|------|--------------|-------------|
| **Realism** | "Super Realism portrait of" | Фотореалистичные изображения |
| **Anime** | "Japanese modern anime style, " | Современное аниме |

💡 **Ленивая загрузка**: Hub LoRA скачиваются только при использовании, затем кэшируются.

### 📁 Локальные LoRA (рекомендуемый способ):

**Положите ваши .safetensors файлы в `/workspace/loras/`** - они автоматически появятся в списке!

**Преимущества локальных LoRA**:
- ✅ Не скачиваются с интернета (быстрее)
- ✅ Приватные (только у вас)
- ✅ Полный контроль версий
- ✅ Можно использовать любые кастомные LoRA

**Пример**:
```bash
/workspace/loras/
├── my_custom_style.safetensors     → появится как "my_custom_style"
├── portrait_lora.safetensors       → появится как "portrait_lora"
└── anime_v2.safetensors            → появится как "anime_v2"
```

**API использование**:
```python
# Используйте имя файла (без расширения)
result = client.predict(
    prompt="SB_AI, a portrait",
    lora_name="my_custom_style",  # Имя вашего локального файла
    lora_scale=1.0,
    api_name="/text2img"
)
```

💡 **Hub LoRA** автоматически добавляют trigger words. **Локальные LoRA** - без trigger words.

## 📊 Параметры

### Denoising Strength (Image2Image)
- **0.0-0.3**: Минимальные изменения, сохранение деталей
- **0.4-0.6**: Умеренные изменения, баланс
- **0.7-0.9**: Сильные изменения, новое изображение
- **1.0**: Полная перерисовка

### LoRA Scale
- **0.0**: Без эффекта
- **0.5**: Слабый эффект стиля
- **1.0**: Нормальный эффект (рекомендуется)
- **1.5-2.0**: Сильный эффект стиля

## 🔧 Технические детали

### Модели:
- **Base**: Gerchegg/Qwen-Soloband-Diffusers (по умолчанию)
- **LoRAs**: Различные (загружаются динамически)
- **Custom Models**: Поддержка через переменную окружения `MODEL_REPO`

### Использование кастомной модели:

```bash
# Через переменную окружения
MODEL_REPO="username/custom-qwen-model" python app.py

# Или экспортировать
export MODEL_REPO="username/custom-qwen-model"
python app.py
```

**Требования к кастомной модели:**
- Совместимость с Qwen-Image архитектурой
- Формат diffusers
- Включает: vae, text_encoder, tokenizer, transformer, scheduler

### Оптимизации:
- VAE tiling для больших изображений
- VAE slicing для batch
- Автоматическое управление LoRA

## 💰 Требования

- **GPU**: A40 (48GB) или A100 (80GB)
- **VRAM**: ~40GB для базовой модели
- **Storage**: ~45GB (модель)

## 📚 Дополнительная информация

- **Base Model**: [Qwen-Soloband-Diffusers](https://huggingface.co/Gerchegg/Qwen-Soloband-Diffusers)
- **Qwen-Image**: [Qwen/Qwen-Image](https://huggingface.co/Qwen/Qwen-Image)
- **Diffusers Docs**: [Image-to-Image Guide](https://huggingface.co/docs/diffusers/using-diffusers/img2img)
- **LoRA Explorer**: [Qwen-Image-LoRA-Explorer](https://huggingface.co/spaces/multimodalart/Qwen-Image-LoRA-Explorer)

## ⚠️ Важные замечания

### Image2Image для Qwen
Этот Space использует специализированный `QwenImageImg2ImgPipeline` для корректной работы с Qwen-Image архитектурой. В отличие от обычных Stable Diffusion моделей, Qwen-Image требует:
- Специальное кодирование изображений через `AutoencoderKLQwenImage`
- Параметр `true_cfg_scale` вместо `guidance_scale`
- Специальную упаковку латентов (packing 2x2)

### LoRA (Hub + Local)

- **Hub LoRA (2)**: Realism, Anime - скачиваются ПРИ ИСПОЛЬЗОВАНИИ, затем кэшируются
- **Local LoRA**: Любые .safetensors в `/workspace/loras/` - автоматически обнаруживаются
- Ленивая загрузка - не скачиваются и не занимают VRAM до использования
- Полная поддержка в API по имени

## 📝 License

Apache 2.0

## 🔧 Technical Notes

✅ **Image2Image**: Использует правильный `QwenImageImg2ImgPipeline` для Qwen-Image архитектуры  
✅ **Performance**: ~0.91s на шаг денойзинга на A100 GPU  
✅ **Optimization**: VAE tiling и slicing включены для экономии памяти