Stable Diffusion ile Yüz Restore Etme: GFPGAN Entegrasyonu

Yazar:komut.io ekibi
0 Yorum

Yüz restore etme meselesine geldiğimizde, çoğu kişinin aklına hemen Photoshop filtreleri ya da telefon uygulamaları geliyor. Ama biz sysadmin’ler biliyoruz ki işi doğru yapmak istiyorsanız, pipeline’ı kendiniz kurarsınız. GFPGAN’ı Stable Diffusion Web UI’a entegre etmek, özellikle toplu görüntü işleme ve otomatik restore workflow’ları için ciddi bir güç kazandırıyor. Ben bu entegrasyonu ilk kurduğumda birkaç saatimi harcadım, siz harcamayın diye bu yazıyı yazıyorum.

GFPGAN Nedir ve Neden SD Web UI ile Kullanıyoruz?

GFPGAN, Tencent ARC Lab tarafından geliştirilen, yüz restorasyon için özelleştirilmiş bir GAN mimarisi. Adı “Generative Facial Prior GAN” kelimelerinin kısaltması. Eski, bulanık veya düşük çözünürlüklü fotoğraflardaki yüzleri, önceden eğitilmiş yüz geometrisi bilgisini kullanarak restore ediyor.

Stable Diffusion Web UI (AUTOMATIC1111 sürümünden bahsediyoruz) ile birleştiğinde şunları elde ediyorsunuz:

  • img2img workflow’larında otomatik yüz kalitesi iyileştirmesi
  • Extras sekmesinden tek tıkla toplu restore işlemi
  • Inpainting sonrası yüz bölgelerinin netleştirilmesi
  • Batch processing pipeline’larında programatik erişim

CodeFormer da benzer işi yapıyor ve zaman zaman daha iyi sonuçlar veriyor, ikisini karşılaştıracağız ama önce temeli kuralım.

Sistem Gereksinimleri ve Ön Hazırlık

Ben bu kurulumu Ubuntu 22.04 ve Windows 11 üzerinde test ettim. CUDA 11.8 ve PyTorch 2.0 kombinasyonu en stabil çalışan ortam oldu. Minimum 8GB VRAM öneriyorum, 6GB ile de çalışıyor ama model yükleme süresi uzuyor.

# Mevcut kurulumunuzu kontrol edin
nvidia-smi
python --version
pip show torch | grep Version

AUTOMATIC1111 Web UI zaten kuruluysa GFPGAN’ı ayrıca kurmak zorunda değilsiniz, Web UI bunu otomatik indiriyor. Ama model dosyasını manuel almak daha hızlı ve güvenilir:

# Web UI kurulum dizinine gidin
cd /opt/stable-diffusion-webui

# GFPGAN modelini doğru dizine indirin
wget -O models/GFPGAN/GFPGANv1.4.pth 
  https://github.com/TencentARC/GFPGAN/releases/download/v1.3.4/GFPGANv1.4.pth

# Dosya bütünlüğünü kontrol edin
sha256sum models/GFPGAN/GFPGANv1.4.pth
# Beklenen: 94d735072630ab734561130a47bc4136e76369e59c...

CodeFormer modelini de aynı anda alalım, sonradan lazım olacak:

wget -O models/Codeformer/codeformer-v0.1.0.pth 
  https://github.com/sczhou/CodeFormer/releases/download/v0.1.0/codeformer.pth

Web UI Başlatma ve GFPGAN Aktivasyonu

Web UI’ı başlatırken bazı parametreler vermek gerekiyor. Ben production’da şu konfigürasyonu kullanıyorum:

# webui-user.sh dosyasını düzenleyin (Linux)
nano webui-user.sh
#!/bin/bash
export COMMANDLINE_ARGS="--xformers --enable-insecure-extension-access 
  --api --listen --port 7860 
  --no-half-vae 
  --opt-sdp-attention"

# GPU bellek optimizasyonu için (8GB VRAM altı)
# COMMANDLINE_ARGS="... --medvram"

# 6GB altı için
# COMMANDLINE_ARGS="... --lowvram"

Windows kullanıcıları için webui-user.bat:

@echo off
set COMMANDLINE_ARGS=--xformers --api --listen --port 7860 --no-half-vae
call webui.bat

Web UI açıldıktan sonra Extras sekmesine gidin. Orada “GFPGAN” ve “CodeFormer” kutucuklarını göreceksiniz. Eğer model dosyaları doğru konumdaysa direkt aktif olacaklar.

Extras Sekmesinde GFPGAN Kullanımı

Extras sekmesi en basit kullanım senaryosu. Tek bir fotoğraf veya batch klasörü için idealdir.

Parametrelerin anlamı şu:

  • GFPGAN visibility: 0 ile 1 arasında, 1 maksimum etki demek. Genellikle 0.7-0.8 iyi bir başlangıç noktası.
  • CodeFormer visibility: GFPGAN ile aynı mantık, aynı anda ikisini de kullanabilirsiniz, ağırlıklar toplanır.
  • CodeFormer weight (fidelity): 0 orijinale sadakat, 1 kalite iyileştirme. Gerçek fotoğraflarda 0.5-0.7 dengeyi iyi tutuyor.
  • Scale: Görüntüyü büyütme katsayısı, GFPGAN’dan bağımsız çalışır (RealESRGAN kullanır).
  • Upscaler: Yüz dışı bölgeleri büyütmek için kullanılan model, R-ESRGAN 4x+ genelde en iyisi.

API Üzerinden Programatik Kullanım

İşte asıl güç buradan geliyor. Web UI’ı --api parametresiyle başlattıysanız, REST API üzerinden GFPGAN’ı çağırabilirsiniz. Bu özellikle toplu işleme script’leri ve CI/CD pipeline entegrasyonları için kritik.

#!/usr/bin/env python3
"""
GFPGAN Batch Restore Script
Web UI API üzerinden toplu yüz restorasyon
"""

import base64
import requests
import json
from pathlib import Path
import sys

WEBUI_URL = "http://localhost:7860"

def encode_image(image_path: str) -> str:
    """Görüntüyü base64'e çevirir"""
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

def restore_face(image_path: str, gfpgan_visibility: float = 0.8,
                 codeformer_visibility: float = 0.0,
                 codeformer_weight: float = 0.5,
                 upscaling_resize: int = 2) -> bytes:
    """
    Verilen görüntüye GFPGAN uygular ve sonucu döndürür
    """
    payload = {
        "resize_mode": 0,
        "show_extras_results": True,
        "gfpgan_visibility": gfpgan_visibility,
        "codeformer_visibility": codeformer_visibility,
        "codeformer_weight": codeformer_weight,
        "upscaling_resize": upscaling_resize,
        "upscaling_resize_w": 512,
        "upscaling_resize_h": 512,
        "upscaling_crop": True,
        "upscaler_1": "R-ESRGAN 4x+",
        "upscaler_2": "None",
        "extras_upscaler_2_visibility": 0,
        "upscale_first": False,
        "image": encode_image(image_path)
    }

    response = requests.post(
        f"{WEBUI_URL}/sdapi/v1/extra-single-image",
        json=payload,
        timeout=120
    )

    if response.status_code != 200:
        raise Exception(f"API hatasi: {response.status_code} - {response.text}")

    result = response.json()
    image_data = base64.b64decode(result["image"])
    return image_data


def batch_restore(input_dir: str, output_dir: str, **kwargs):
    """
    Klasördeki tüm görüntülere GFPGAN uygular
    """
    input_path = Path(input_dir)
    output_path = Path(output_dir)
    output_path.mkdir(parents=True, exist_ok=True)

    extensions = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
    images = [f for f in input_path.iterdir() if f.suffix.lower() in extensions]

    print(f"Toplam {len(images)} goruntu isleniyor...")

    for i, img_path in enumerate(images, 1):
        print(f"[{i}/{len(images)}] {img_path.name} isleniyor...")
        try:
            restored = restore_face(str(img_path), **kwargs)
            output_file = output_path / f"restored_{img_path.name}"
            with open(output_file, "wb") as f:
                f.write(restored)
            print(f"  -> {output_file} kaydedildi")
        except Exception as e:
            print(f"  HATA: {e}", file=sys.stderr)


if __name__ == "__main__":
    batch_restore(
        input_dir="./input_photos",
        output_dir="./restored_photos",
        gfpgan_visibility=0.8,
        codeformer_visibility=0.3,
        codeformer_weight=0.6,
        upscaling_resize=2
    )

Bu script’i çalıştırmadan önce requests kütüphanesinin kurulu olduğundan emin olun:

pip install requests Pillow
python restore_batch.py

img2img Pipeline’ına Entegrasyon

Asıl sihir, GFPGAN’ı img2img workflow’una dahil ettiğinizde başlıyor. Aşağıdaki script, bir görüntüyü önce img2img ile yeniden oluşturuyor, sonra GFPGAN ile yüzleri restore ediyor:

#!/usr/bin/env python3
"""
img2img + GFPGAN Pipeline
Görüntüyü yeniden oluştur, sonra yüzleri restore et
"""

import base64
import requests
from pathlib import Path

WEBUI_URL = "http://localhost:7860"

def encode_image(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode()

def img2img_with_face_restore(image_path: str, prompt: str,
                               negative_prompt: str = "",
                               denoising_strength: float = 0.4,
                               restore_faces: bool = True) -> bytes:
    """
    img2img ile görüntü oluştur, face restore aktif
    """
    payload = {
        "init_images": [encode_image(image_path)],
        "prompt": prompt,
        "negative_prompt": negative_prompt,
        "steps": 25,
        "sampler_name": "DPM++ 2M Karras",
        "cfg_scale": 7,
        "denoising_strength": denoising_strength,
        "restore_faces": restore_faces,  # GFPGAN bu flag ile devreye girer
        "width": 512,
        "height": 768,
        "n_iter": 1,
        "batch_size": 1,
    }

    resp = requests.post(f"{WEBUI_URL}/sdapi/v1/img2img", json=payload, timeout=180)
    resp.raise_for_status()

    result = resp.json()
    return base64.b64decode(result["images"][0])


# Kullanim ornegi
if __name__ == "__main__":
    output = img2img_with_face_restore(
        image_path="./eski_fotograf.jpg",
        prompt="portrait photo, high quality, sharp focus, studio lighting",
        negative_prompt="blurry, low quality, pixelated",
        denoising_strength=0.35,
        restore_faces=True
    )

    with open("./sonuc.png", "wb") as f:
        f.write(output)
    print("Tamamlandi: sonuc.png")

restore_faces: True parametresi, Web UI ayarlarında hangi model seçiliyse onu kullanıyor. Varsayılan GFPGAN, ama Settings > Face Restoration altından değiştirebilirsiniz.

Settings Üzerinden Varsayılan Konfigürasyon

Web UI’ın config.json dosyasını doğrudan düzenleyerek varsayılanları kalıcı hale getirebilirsiniz. Bu özellikle sunucu kurulumlarında işe yarıyor:

# config.json'u düzenle
nano /opt/stable-diffusion-webui/config.json
{
  "face_restoration_model": "GFPGAN",
  "code_former_weight": 0.5,
  "face_restoration_unload": false,
  "show_progressbar": true,
  "show_progress_every_n_steps": 10,
  "upscaler_for_img2img": "R-ESRGAN 4x+"
}

face_restoration_unload: false ayarı, GFPGAN modelini VRAM’de tutarak her istekte yeniden yükleme gecikmesini önlüyor. 8GB ve üzeri VRAM’de bunu açık bırakmanızı öneririm.

Systemd Service ile Otomatik Başlatma

Production ortamında Web UI’ı servis olarak çalıştırmak şart. Aksi halde sunucu yeniden başladığında her şeyi elle başlatmanız gerekiyor:

# Servis dosyasını oluştur
sudo nano /etc/systemd/system/stable-diffusion-webui.service
[Unit]
Description=Stable Diffusion Web UI with GFPGAN
After=network.target
Wants=network.target

[Service]
Type=simple
User=sduser
Group=sduser
WorkingDirectory=/opt/stable-diffusion-webui
Environment="COMMANDLINE_ARGS=--api --listen --port 7860 --xformers --no-half-vae"
ExecStart=/opt/stable-diffusion-webui/webui.sh
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
# Servisi etkinleştir ve başlat
sudo systemctl daemon-reload
sudo systemctl enable stable-diffusion-webui
sudo systemctl start stable-diffusion-webui

# Log takibi
sudo journalctl -u stable-diffusion-webui -f

Sık Karşılaşılan Hatalar ve Çözümleri

Kurulum ve kullanım sırasında en çok şu hatalarla karşılaştım:

“No face detected” hatası

GFPGAN yüz bulamazsa sessizce orijinal görüntüyü döndürüyor. Bu davranış beklenmedik sonuçlar yaratabilir. Log’larda şu mesajı görürsünüz: No face detected in the image. Çözüm: görüntüde yüz alanı yeterince büyük olmalı, küçük yüzler için önce görüntüyü crop edin.

CUDA Out of Memory

# VRAM kullanımını izleyin
watch -n 2 nvidia-smi

# Geçici çözüm: batch size'ı 1'e düşürün
# config.json içinde:
# "batch_size": 1
# Ve Web UI'ı --medvram ile başlatın

Model dosyası bulunamıyor

# Doğru konumda olduğunu kontrol edin
ls -la /opt/stable-diffusion-webui/models/GFPGAN/
# GFPGANv1.4.pth dosyası görünmeli

# İzin sorunu varsa
chmod 644 /opt/stable-diffusion-webui/models/GFPGAN/GFPGANv1.4.pth
chown sduser:sduser /opt/stable-diffusion-webui/models/GFPGAN/GFPGANv1.4.pth

API timeout hataları

Büyük görüntülerde veya düşük VRAM’de timeout gerçekleşebilir. Batch script’inizi şöyle güncelleyin:

# Timeout değerini artırın
response = requests.post(
    f"{WEBUI_URL}/sdapi/v1/extra-single-image",
    json=payload,
    timeout=300  # 5 dakika
)

GFPGAN vs CodeFormer: Hangisini Seçmeli?

İki modeli aynı anda kullanabildiğinizi söylemiştim. Ama hangisinin ne zaman daha iyi çalıştığını anlamak önemli.

Deneyimlerime göre:

  • GFPGAN 1.4: Genel restorasyonda daha hızlı, eski aile fotoğrafları için iyi
  • CodeFormer: Detay korumada daha başarılı, gerçek kişi fotoğraflarında kimliği daha iyi koruyor, ama biraz daha yavaş
  • İkisi birlikte: GFPGAN 0.5 + CodeFormer 0.5 kombinasyonu çoğu durumda her ikisinin ortalamasını veriyor

Eğer otomatik bir pipeline kuruyorsanız ve hangi fotoğrafların geleceğini bilmiyorsanız, CodeFormer visibility 0.7 ve weight 0.6 ile başlayın. Yüz kimliğini daha iyi koruduğu için daha az şikayet alırsınız.

Nginx Reverse Proxy ile Güvenli Erişim

Web UI’ı internete açık sunucuda çalıştırıyorsanız, mutlaka arkasına Nginx koyun:

# /etc/nginx/sites-available/stable-diffusion
server {
    listen 443 ssl;
    server_name sd.sirketiniz.com;

    ssl_certificate /etc/letsencrypt/live/sd.sirketiniz.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sd.sirketiniz.com/privkey.pem;

    # Büyük payload için limit artır (görüntüler büyük olabilir)
    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;

        # Basic auth ekleyin
        auth_basic "Stable Diffusion";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}
# htpasswd dosyası oluştur
sudo apt install apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd sdadmin

# Nginx'i yeniden yükle
sudo nginx -t && sudo systemctl reload nginx

Sonuç

GFPGAN entegrasyonu tek başına bakılınca basit bir “fotoğraf güzelleştirme” özelliği gibi görünüyor. Ama arkasına API erişimi, batch processing ve systemd servisi koyduğunuzda, ciddi bir görüntü işleme pipeline’ı elde ediyorsunuz. Ben bu altyapıyı, eski arşiv fotoğraflarını dijitalleştiren bir kurumun sistemine kurdum; günde binlerce fotoğrafı otomatik olarak işliyor, hiç dokunmadan.

Kritik noktaları özetleyeyim:

  • Model dosyalarını manuel indirip doğru dizine koyun, otomatik indirmeye güvenmeyin
  • Production’da her zaman --api ile başlatın ve systemd ile yönetin
  • CodeFormer ve GFPGAN’ı birlikte kullanmayı deneyin, tek başına daha iyi sonuç vermesini beklemeyin
  • VRAM sınırınızı iyi tanıyın, --medvram ve --lowvram parametrelerini gerektiğinde kullanmaktan çekinmeyin
  • API timeout’larını iş yüküne göre ayarlayın

Önümüzdeki yazıda bu pipeline’ı bir Python FastAPI servisi ile sarmallayıp, kendi uygulamalarınıza nasıl entegre edeceğinizi göstereceğim. Soru ve yorumlarınızı bekliyorum.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir