SETUP.md

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

# 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

# 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

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:

# 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ı

# Logları kontrol et
modal app logs flux2-turbo-lora-explorer

---

Özelleştirme

Yeni LoRA Eklemek

modal_backend/flux_api.py dosyasında:

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:

@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

   @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