# FLUX LoRA Explorer - Complete Setup Guide

Bu rehber Modal.com + HuggingFace Space kurulumunu adım adım anlatıyor.

## Mimari

```
┌─────────────────────────────────────────────────────────────┐
│                    HuggingFace Space                        │
│                    (Gradio UI - Free)                       │
│                                                             │
│  - Kullanıcı arayüzü                                       │
│  - Style seçimi                                            │
│  - Parametre kontrolü                                      │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTP API
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Modal.com Backend                        │
│                    (GPU - Pay per use)                      │
│                                                             │
│  - FLUX model yükleme                                      │
│  - LoRA uygulama                                           │
│  - Image generation                                        │
│  - A100/H100 GPU                                           │
└─────────────────────────────────────────────────────────────┘
```

## Maliyet

| Bileşen | Maliyet |
|---------|---------|
| HuggingFace Space | **Ücretsiz** (CPU Basic) |
| Modal.com A100 | ~$2.50/saat (sadece kullanırken) |
| Modal.com H100 | ~$3.95/saat (sadece kullanırken) |
| Modal Free Credits | **$30/ay ücretsiz** |

**Örnek**: 1 image ~10 saniye = ~$0.007 (A100 ile)

---

## ADIM 1: Modal.com Kurulumu

### 1.1 Modal Hesabı Oluştur

1. https://modal.com adresine git
2. "Get Started" ile kayıt ol (GitHub ile giriş önerilir)
3. Ücretsiz $30/ay kredin otomatik tanımlanır

### 1.2 Modal CLI Kur

```bash
# Modal CLI'ı kur
pip install modal

# Modal'a login ol
modal setup
```

### 1.3 HuggingFace Token Oluştur

FLUX.1-dev gated bir model, HF token gerekli:

1. https://huggingface.co/settings/tokens adresine git
2. "New token" → "Read" yetkisi ver
3. Token'ı kopyala

### 1.4 Modal Secret Oluştur

```bash
# HuggingFace token'ını Modal'a ekle
modal secret create huggingface-secret HF_TOKEN=hf_xxxxxxxxxxxxx
```

### 1.5 FLUX Model'i Kabul Et

1. https://huggingface.co/black-forest-labs/FLUX.1-dev adresine git
2. "Agree and access repository" butonuna tıkla

### 1.6 Modal Backend'i Deploy Et

```bash
cd modal_backend

# Test et (local)
modal run flux_api.py --prompt "a cute cat" --lora "none"

# Deploy et (production)
modal deploy flux_api.py
```

Deploy sonrası şöyle bir output alacaksın:
```
✓ Created web endpoint flux2-turbo-lora-explorer.Flux2TurboLoRA.api_generate
  https://YOUR_WORKSPACE--flux2-turbo-lora-explorer-flux2turbolora-api-generate.modal.run
```

**Bu URL'i not al!** HuggingFace Space'e ekleyeceğiz.

---

## ADIM 2: HuggingFace Space Kurulumu

### 2.1 Yeni Space Oluştur

1. https://huggingface.co/new-space adresine git
2. Doldur:
   - **Space name**: `FLUX-LoRA-Explorer`
   - **SDK**: `Gradio`
   - **Hardware**: `CPU basic` (ücretsiz)
   - **Visibility**: Public

### 2.2 Space Secrets Ekle

Space Settings → Variables and secrets:

| Secret Name | Value | Açıklama |
|-------------|-------|----------|
| `MODAL_ENDPOINT` | `https://YOUR_WORKSPACE--flux2-turbo...` | Modal API URL |
| `MODAL_TOKEN_ID` | (opsiyonel) | Modal auth için |
| `MODAL_TOKEN_SECRET` | (opsiyonel) | Modal auth için |

### 2.3 Dosyaları Yükle

**Git ile:**
```bash
# Space'i klonla
git clone https://huggingface.co/spaces/YOUR_USERNAME/FLUX-LoRA-Explorer
cd FLUX-LoRA-Explorer

# Dosyaları kopyala
cp /path/to/fal-flux-hf-space/app.py .
cp /path/to/fal-flux-hf-space/requirements.txt .
cp /path/to/fal-flux-hf-space/README.md .

# Push et
git add .
git commit -m "Initial commit: FLUX LoRA Explorer"
git push
```

**Veya Web UI ile:**
1. Space'in "Files" sekmesine git
2. "Add file" → "Upload files"
3. `app.py`, `requirements.txt`, `README.md` yükle

### 2.4 Build'i Bekle

Space otomatik build edecek. Logs sekmesinden takip edebilirsin.

---

## ADIM 3: Test Et

1. HuggingFace Space URL'ine git
2. Bir prompt gir: "a beautiful sunset over mountains"
3. Style seç: "Anime"
4. "Generate" butonuna tıkla
5. ~30-60 saniye bekle (ilk seferde cold start olabilir)

---

## Sorun Giderme

### "Modal endpoint not configured"
→ Space Secrets'ta `MODAL_ENDPOINT` ekledin mi?

### "Request timed out"
→ İlk request cold start sürüyor (~60 saniye). Tekrar dene.

### "403 Forbidden" veya "401 Unauthorized"
→ HuggingFace token'ın Modal secret'a doğru eklendi mi?
→ FLUX.1-dev model'i kabul ettin mi?

### Modal deploy hatası
```bash
# Logları kontrol et
modal app logs flux2-turbo-lora-explorer
```

---

## Özelleştirme

### Yeni LoRA Eklemek

`modal_backend/flux_api.py` dosyasında:
```python
STYLE_LORAS = {
    "none": None,
    "anime": "alvdansen/flux-koda",
    "your_new_style": "huggingface/lora-repo-id",  # Yeni ekle
    ...
}
```

Sonra `app.py`'de aynı style'ı ekle.

### GPU Değiştirmek

`flux_api.py`:
```python
@app.cls(
    gpu="H100",  # veya "A100", "A10G", "L4"
    ...
)
```

| GPU | VRAM | Hız | Maliyet |
|-----|------|-----|---------|
| H100 | 80GB | En hızlı | ~$3.95/sa |
| A100 | 80GB | Çok hızlı | ~$2.50/sa |
| A10G | 24GB | Orta | ~$1.10/sa |
| L4 | 24GB | Yavaş | ~$0.80/sa |

FLUX için A100 veya H100 önerilir.

---

## Maliyeti Minimize Etmek

1. **scaledown_window**: Container'ı 15 dakika sonra kapat
   ```python
   @app.cls(scaledown_window=15 * 60, ...)
   ```

2. **Cold start kabul et**: Her zaman sıcak tutma, ilk request için bekle

3. **A100 kullan**: H100 yerine A100 %40 daha ucuz

4. **Batch işlem**: Birden fazla resmi tek request'te üret

---

## Dosya Yapısı

```
fal-flux-hf-space/
├── app.py                    # HuggingFace Gradio UI
├── requirements.txt          # HF Space dependencies
├── README.md                 # HF Space metadata
├── SETUP.md                  # Bu dosya
├── .gitignore
└── modal_backend/
    ├── flux_api.py          # Modal GPU backend
    └── requirements.txt     # Modal dependencies (local test için)
```

---

## Sonraki Adımlar

1. ✅ Modal backend deploy edildi
2. ✅ HuggingFace Space oluşturuldu
3. 🔜 Custom LoRA'lar ekle
4. 🔜 Image-to-Image özelliği ekle
5. 🔜 ControlNet desteği ekle

---

## Yardım

- Modal Docs: https://modal.com/docs
- HuggingFace Spaces: https://huggingface.co/docs/hub/spaces
- FLUX Diffusers: https://huggingface.co/docs/diffusers/main/en/api/pipelines/flux