Hugging Face ile Görsel Sınıflandırma Modeli Kullanımı

Makine öğrenmesi dünyasına adım atmak isteyenler için görsel sınıflandırma, hem anlaşılması kolay hem de pratikte son derece kullanışlı bir başlangıç noktasıdır. Bir sunucuda çalışan servis olsun, bir CI/CD pipeline’ına entegre edilmiş kalite kontrol sistemi olsun ya da basit bir komut satırı aracı olsun, Hugging Face’in vision modelleri bu işleri놀랍도록 kolaylaştırıyor. Bu rehberde, sıfırdan başlayarak production ortamına kadar görsel sınıflandırma modellerini nasıl kuracağınızı ve kullanacağınızı adım adım ele alacağız.

Ortam Hazırlığı ve Gereksinimler

Başlamadan önce sisteminizin hazır olduğundan emin olmanız gerekiyor. GPU’lu bir makine ideal olsa da, bu rehberdeki örneklerin tamamı CPU üzerinde de çalışır. Ancak production ortamında performans için CUDA destekli bir GPU şiddetle tavsiye edilir.

Önce Python ortamınızı izole edin. Sistem Python’una dokunmamak, ileride yaşanacak bağımlılık cehennemini önler.

# Python virtual environment oluştur
python3 -m venv huggingface-vision
source huggingface-vision/bin/activate

# Temel paketleri kur
pip install transformers torch torchvision pillow accelerate
pip install timm  # PyTorch Image Models kütüphanesi
pip install datasets  # Hugging Face datasets

# Versiyonları doğrula
python3 -c "import transformers; print(transformers.__version__)"
python3 -c "import torch; print(torch.__version__)"
python3 -c "import torch; print('CUDA:', torch.cuda.is_available())"

GPU kullanıyorsanız CUDA sürümünüzle uyumlu PyTorch kurmanız kritik önem taşıyor. nvidia-smi çıktısındaki CUDA sürümünü not edin ve PyTorch’un resmi sitesinden uygun komutu alın.

# NVIDIA GPU varsa CUDA bilgisini kontrol et
nvidia-smi
nvcc --version

# CUDA 11.8 için örnek kurulum
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

İlk Model İndirme: ViT ile Tanışın

Hugging Face’in en popüler vision modeli Vision Transformer, yani ViT’tir. Google tarafından geliştirilen bu mimari, transformer’ların görüntü işlemeye uyarlanmış halidir. İlk denememizi basit tutuyoruz.

# vision_test.py
from transformers import ViTImageProcessor, ViTForImageClassification
from PIL import Image
import requests
import torch

# Model ve işlemciyi yükle
model_name = "google/vit-base-patch16-224"
processor = ViTImageProcessor.from_pretrained(model_name)
model = ViTForImageClassification.from_pretrained(model_name)

# Test görseli indir (internet bağlantısı gerekli)
url = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg"
image = Image.open(requests.get(url, stream=True).raw)

# Görseli işle ve modele gönder
inputs = processor(images=image, return_tensors="pt")
with torch.no_grad():
    outputs = model(**inputs)

# Sonuçları al ve yorumla
logits = outputs.logits
predicted_class_idx = logits.argmax(-1).item()
print(f"Tahmin edilen sınıf: {model.config.id2label[predicted_class_idx]}")

# Top-5 sonuçları göster
probabilities = torch.nn.functional.softmax(logits, dim=-1)[0]
top5 = torch.topk(probabilities, 5)
for i, (idx, prob) in enumerate(zip(top5.indices, top5.values)):
    print(f"{i+1}. {model.config.id2label[idx.item()]}: {prob.item()*100:.2f}%")

Bu script’i çalıştırdığınızda Hugging Face model repository’sinden yaklaşık 330MB’lık model indirilir ve varsayılan olarak ~/.cache/huggingface/ dizinine kaydedilir.

Cache Yönetimi ve Offline Kullanım

Production ortamında internet bağlantısının her zaman mevcut olmayabileceğini ya da her başlatmada model indirmek istemeyeceğinizi düşünün. Hugging Face bu konuda esnek bir yapı sunuyor.

# Cache dizinini kontrol et
ls -la ~/.cache/huggingface/hub/
du -sh ~/.cache/huggingface/

# Özel cache dizini ayarla (sunucu ortamı için)
export HF_HOME=/data/ml-models/huggingface
export TRANSFORMERS_CACHE=/data/ml-models/huggingface/transformers

# Bu değişkenleri kalıcı yap
echo 'export HF_HOME=/data/ml-models/huggingface' >> ~/.bashrc
echo 'export TRANSFORMERS_CACHE=/data/ml-models/huggingface/transformers' >> ~/.bashrc
source ~/.bashrc

# Modeli manuel olarak belirtilen dizine indir
python3 -c "
from transformers import ViTImageProcessor, ViTForImageClassification
model_name = 'google/vit-base-patch16-224'
processor = ViTImageProcessor.from_pretrained(model_name, cache_dir='/data/ml-models/huggingface')
model = ViTForImageClassification.from_pretrained(model_name, cache_dir='/data/ml-models/huggingface')
print('Model başarıyla indirildi ve cache'e kaydedildi.')
"

Offline kullanım için modeli kaydetmek ve yerel dizinden yüklemek en sağlıklı yaklaşımdır.

# model_save.py - Modeli yerel dizine kaydet
from transformers import ViTImageProcessor, ViTForImageClassification

model_name = "google/vit-base-patch16-224"
save_path = "/data/ml-models/vit-base-224"

# Model ve processor'ı indir
processor = ViTImageProcessor.from_pretrained(model_name)
model = ViTForImageClassification.from_pretrained(model_name)

# Yerel diske kaydet
processor.save_pretrained(save_path)
model.save_pretrained(save_path)
print(f"Model {save_path} dizinine kaydedildi.")

# Yerel diskten yükle (artık internet gerekmez)
processor_local = ViTImageProcessor.from_pretrained(save_path)
model_local = ViTForImageClassification.from_pretrained(save_path)
print("Model yerel diskten başarıyla yüklendi.")

Farklı Vision Modelleri ile Karşılaştırma

ViT dışında Hugging Face’de onlarca farklı vision modeli bulunur. Her birinin güçlü ve zayıf yönleri var. Pratik bir sysadmin olarak hangi modelin iş için uygun olduğunu bilmek önemli.

google/vit-base-patch16-224: Genel amaçlı, dengeli performans. 86M parametre. microsoft/resnet-50: Klasik CNN mimarisi, daha hızlı inference. Hafif sistemler için ideal. facebook/convnext-base: Modern CNN, ViT ile rekabet edebilir doğruluk. Edge deployment için uygun. google/efficientnet-b4: Boyut ve doğruluk dengesi mükemmel. Mobil ve IoT için. openai/clip-vit-base-patch32: Zero-shot classification yapabiliyor. Etiket tanımlamak gerekmez.

# pipeline_comparison.py - Farklı modelleri pipeline ile test et
from transformers import pipeline
from PIL import Image
import time
import requests

# Test görseli
url = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg"
image = Image.open(requests.get(url, stream=True).raw)

models = [
    "google/vit-base-patch16-224",
    "microsoft/resnet-50",
]

for model_name in models:
    print(f"nModel: {model_name}")
    classifier = pipeline("image-classification", model=model_name)
    
    start = time.time()
    results = classifier(image, top_k=3)
    elapsed = time.time() - start
    
    print(f"Inference süresi: {elapsed:.3f} saniye")
    for result in results:
        print(f"  - {result['label']}: {result['score']*100:.2f}%")

Gerçek Dünya Senaryosu: Üretim Hattı Kalite Kontrol Sistemi

Bir gıda fabrikasında üretim hattındaki ürünlerin kalite kontrolünü otomatize etmek istediğinizi düşünün. Kamera sisteminden gelen görüntüler belirli aralıklarla bir dizine düşüyor ve siz bu görüntüleri sınıflandırıp raporlamak istiyorsunuz.

#!/usr/bin/env python3
# quality_control_service.py

import os
import sys
import json
import time
import logging
from pathlib import Path
from datetime import datetime
from transformers import pipeline
from PIL import Image

# Logging yapılandırması
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('/var/log/quality_control.log'),
        logging.StreamHandler(sys.stdout)
    ]
)
logger = logging.getLogger(__name__)

class QualityControlService:
    def __init__(self, model_path, watch_dir, output_dir, threshold=0.7):
        self.watch_dir = Path(watch_dir)
        self.output_dir = Path(output_dir)
        self.threshold = threshold
        self.processed_files = set()
        
        # Dizinleri oluştur
        self.output_dir.mkdir(parents=True, exist_ok=True)
        (self.output_dir / "passed").mkdir(exist_ok=True)
        (self.output_dir / "failed").mkdir(exist_ok=True)
        
        # Modeli yükle
        logger.info(f"Model yükleniyor: {model_path}")
        self.classifier = pipeline(
            "image-classification",
            model=model_path,
            device=0 if self._check_gpu() else -1
        )
        logger.info("Model başarıyla yüklendi.")
    
    def _check_gpu(self):
        try:
            import torch
            return torch.cuda.is_available()
        except:
            return False
    
    def process_image(self, image_path):
        try:
            image = Image.open(image_path).convert("RGB")
            results = self.classifier(image, top_k=3)
            
            top_result = results[0]
            label = top_result['label'].lower()
            score = top_result['score']
            
            # Kalite kriterine göre karar ver
            is_passed = score >= self.threshold and 'defect' not in label
            status = "passed" if is_passed else "failed"
            
            # Dosyayı ilgili dizine taşı
            dest = self.output_dir / status / Path(image_path).name
            Path(image_path).rename(dest)
            
            # Raporu kaydet
            report = {
                "timestamp": datetime.now().isoformat(),
                "file": Path(image_path).name,
                "status": status,
                "top_prediction": label,
                "confidence": round(score, 4),
                "all_predictions": results
            }
            
            report_path = self.output_dir / f"{Path(image_path).stem}_report.json"
            with open(report_path, 'w') as f:
                json.dump(report, f, indent=2)
            
            logger.info(f"İşlendi: {Path(image_path).name} -> {status} ({score*100:.1f}%)")
            return report
            
        except Exception as e:
            logger.error(f"Hata: {image_path} - {str(e)}")
            return None
    
    def watch_and_process(self, interval=5):
        logger.info(f"İzleme başladı: {self.watch_dir}")
        while True:
            image_files = list(self.watch_dir.glob("*.jpg")) + 
                         list(self.watch_dir.glob("*.png"))
            
            for image_path in image_files:
                if str(image_path) not in self.processed_files:
                    self.processed_files.add(str(image_path))
                    self.process_image(image_path)
            
            time.sleep(interval)

if __name__ == "__main__":
    service = QualityControlService(
        model_path="/data/ml-models/vit-base-224",
        watch_dir="/data/incoming/images",
        output_dir="/data/processed/images",
        threshold=0.75
    )
    service.watch_and_process()

Systemd ile Servis Olarak Çalıştırma

Kalite kontrol servisini bir systemd unit dosyası olarak kayıt edip sistem başlangıcında otomatik başlatabilirsiniz.

# /etc/systemd/system/quality-control.service dosyasını oluştur
sudo tee /etc/systemd/system/quality-control.service > /dev/null <<EOF
[Unit]
Description=AI Quality Control Vision Service
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=mlservice
Group=mlservice
WorkingDirectory=/opt/quality-control
Environment="HF_HOME=/data/ml-models/huggingface"
Environment="PYTHONUNBUFFERED=1"
ExecStart=/opt/quality-control/venv/bin/python3 /opt/quality-control/quality_control_service.py
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=quality-control

# Kaynak limitleri
LimitNOFILE=65536
MemoryLimit=8G

[Install]
WantedBy=multi-user.target
EOF

# Servisi etkinleştir ve başlat
sudo systemctl daemon-reload
sudo systemctl enable quality-control
sudo systemctl start quality-control
sudo systemctl status quality-control

# Logları takip et
journalctl -u quality-control -f

Batch Processing ile Performans Optimizasyonu

Birden fazla görüntüyü tek tek işlemek yerine batch halinde işlemek, özellikle GPU kullanırken dramatik performans artışı sağlar.

# batch_processor.py
import torch
from transformers import ViTImageProcessor, ViTForImageClassification
from PIL import Image
from pathlib import Path
import time

def batch_classify(image_dir, model_path, batch_size=32):
    """Görüntüleri batch halinde işleyerek performansı artır."""
    
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    print(f"Kullanılan cihaz: {device}")
    
    processor = ViTImageProcessor.from_pretrained(model_path)
    model = ViTForImageClassification.from_pretrained(model_path)
    model.to(device)
    model.eval()
    
    image_paths = list(Path(image_dir).glob("*.jpg")) + 
                  list(Path(image_dir).glob("*.png"))
    
    total = len(image_paths)
    results = []
    
    start_time = time.time()
    
    for i in range(0, total, batch_size):
        batch_paths = image_paths[i:i+batch_size]
        batch_images = []
        
        for path in batch_paths:
            try:
                img = Image.open(path).convert("RGB")
                batch_images.append(img)
            except Exception as e:
                print(f"Görüntü açılamadı: {path} - {e}")
                continue
        
        if not batch_images:
            continue
        
        inputs = processor(images=batch_images, return_tensors="pt")
        inputs = {k: v.to(device) for k, v in inputs.items()}
        
        with torch.no_grad():
            outputs = model(**inputs)
        
        probs = torch.nn.functional.softmax(outputs.logits, dim=-1)
        top_probs, top_indices = torch.topk(probs, 3)
        
        for j, path in enumerate(batch_paths[:len(batch_images)]):
            result = {
                "file": path.name,
                "predictions": []
            }
            for prob, idx in zip(top_probs[j], top_indices[j]):
                result["predictions"].append({
                    "label": model.config.id2label[idx.item()],
                    "score": round(prob.item(), 4)
                })
            results.append(result)
        
        processed = min(i + batch_size, total)
        print(f"İlerleme: {processed}/{total} ({processed/total*100:.1f}%)")
    
    elapsed = time.time() - start_time
    print(f"nToplam süre: {elapsed:.2f}s")
    print(f"Görüntü başına ortalama: {elapsed/total*1000:.1f}ms")
    
    return results

# Kullanım
results = batch_classify(
    image_dir="/data/images",
    model_path="/data/ml-models/vit-base-224",
    batch_size=16
)

CLIP ile Zero-Shot Sınıflandırma

CLIP modeli, önceden belirlenmiş etiketlere bağlı kalmadan serbest metin açıklamalarıyla sınıflandırma yapabilmesi açısından çok farklı bir yaklaşım sunuyor. Bu özellikle yeni kategoriler için yeniden eğitim gerektirmediğinden operasyonel açıdan büyük avantaj sağlıyor.

# clip_zero_shot.py
from transformers import CLIPProcessor, CLIPModel
from PIL import Image
import torch
import requests

model_name = "openai/clip-vit-base-patch32"
model = CLIPModel.from_pretrained(model_name)
processor = CLIPProcessor.from_pretrained(model_name)

# Test görseli
url = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg"
image = Image.open(requests.get(url, stream=True).raw)

# Sınıflandırmak istediğiniz kategorileri Türkçe veya İngilizce belirtin
candidate_labels = [
    "a photo of a dog",
    "a photo of a cat",
    "a photo of a car",
    "a photo of food",
    "a photo of a building",
    "damaged product",
    "intact product"
]

inputs = processor(
    text=candidate_labels,
    images=image,
    return_tensors="pt",
    padding=True
)

with torch.no_grad():
    outputs = model(**inputs)

logits_per_image = outputs.logits_per_image
probs = logits_per_image.softmax(dim=1)[0]

print("Zero-Shot Sınıflandırma Sonuçları:")
for label, prob in sorted(zip(candidate_labels, probs), key=lambda x: x[1], reverse=True):
    print(f"  - {label}: {prob.item()*100:.2f}%")

Performans İzleme ve Monitoring

Production’da çalışan bir vision servisini izlemek için basit ama etkili bir monitoring scripti şart.

#!/bin/bash
# monitor_vision_service.sh

LOG_FILE="/var/log/quality_control.log"
ALERT_EMAIL="[email protected]"
GPU_THRESHOLD=90
MEM_THRESHOLD=85

# GPU kullanımını kontrol et
if command -v nvidia-smi &> /dev/null; then
    GPU_USAGE=$(nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader,nounits | head -1)
    GPU_MEM=$(nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader | 
              awk -F',' '{printf "%.0f", ($1/$2)*100}')
    
    echo "[$(date)] GPU Kullanimi: %${GPU_USAGE}, GPU Bellek: %${GPU_MEM}"
    
    if [ "$GPU_USAGE" -gt "$GPU_THRESHOLD" ]; then
        echo "UYARI: GPU kullanimi yüksek: %${GPU_USAGE}" | 
            mail -s "Vision Servisi GPU Uyarisi" "$ALERT_EMAIL"
    fi
fi

# Servis durumunu kontrol et
if ! systemctl is-active --quiet quality-control; then
    echo "[$(date)] HATA: quality-control servisi çalışmıyor, yeniden başlatılıyor..."
    systemctl restart quality-control
    echo "Servis yeniden başlatıldı" | 
        mail -s "Vision Servisi Yeniden Baslatildi" "$ALERT_EMAIL"
fi

# Son 5 dakikadaki işleme hızını hesapla
PROCESSED=$(grep "İşlendi" "$LOG_FILE" | 
    awk -v d="$(date -d '5 minutes ago' '+%Y-%m-%d %H:%M')" '$0 >= d' | wc -l)
echo "[$(date)] Son 5 dakikada işlenen görüntü: $PROCESSED"

# Disk alanı kontrolü
DISK_USAGE=$(df /data | awk 'NR==2 {print $5}' | tr -d '%')
if [ "$DISK_USAGE" -gt 80 ]; then
    echo "UYARI: /data disk dolulugu: %${DISK_USAGE}" | 
        mail -s "Disk Alani Uyarisi" "$ALERT_EMAIL"
fi

# Cron job olarak her 5 dakikada bir çalıştır
chmod +x /usr/local/bin/monitor_vision_service.sh
echo "*/5 * * * * root /usr/local/bin/monitor_vision_service.sh >> /var/log/vision_monitor.log 2>&1" | 
    sudo tee -a /etc/crontab

Yaygın Sorunlar ve Çözümleri

CUDA Out of Memory hatası: Batch size’ı küçültün ve torch.cuda.empty_cache() kullanın. Modeli model.half() ile FP16’ya geçirmek bellek kullanımını yaklaşık yarıya indirir.

Model indirme zaman aşımı: HF_HUB_DOWNLOAD_TIMEOUT ortam değişkenini artırın ya da huggingface-cli download komutunu kullanarak modeli önce indirin.

Yavaş CPU inference: torch.set_num_threads() ile CPU thread sayısını ayarlayın. Sunucunuzun çekirdek sayısına göre 4-8 arası genellikle optimal değerdir.

PIL görüntü modu uyumsuzluğu: Her zaman .convert("RGB") kullanın. PNG dosyaları RGBA modunda gelebilir ve bu modeli bozar.

Hugging Face rate limiting: Token oluşturup huggingface-cli login ile giriş yapın. Private modeller ve yüksek indirme limiti için gereklidir.

Sonuç

Hugging Face vision ekosistemi, sysadmin’ler için makine öğrenmesine giriş noktası olarak mükemmel bir denge sunuyor. Karmaşık model eğitimi gerektirmeden, mevcut önceden eğitilmiş modelleri birkaç satır kodla production servislerine dönüştürebilirsiniz. ViT’in genel güçlülüğü, CLIP’in esnekliği ve ResNet’in hızı arasında doğru seçimi yaparak hem kaynak kullanımını optimize edebilir hem de işinizin gereksinimlerini karşılayabilirsiniz.

Bu rehberde ele aldığımız kalite kontrol senaryosu, binlerce farklı alana uyarlanabilir. Güvenlik kamerası görüntü analizi, belge sınıflandırma, tıbbi görüntü ön işleme ya da e-ticaret ürün kategorilendirmesi bunların başında geliyor. Systemd entegrasyonu, batch işleme ve monitoring altyapısıyla birleştiğinde, bu araçlar ciddiye alınabilir production sistemleri oluşturmanıza olanak tanıyor.

Bir sonraki adım olarak kendi veri setinizle fine-tuning yapmayı ya da model quantization tekniklerini incelemeyi öneririm. Özellikle edge cihazlarda çalışacak modeller için ONNX export ve TensorRT optimizasyonu konuları oldukça derinlemesine incelenmesi gereken alanlar.

Görsel Sınıflandırma Modeli: Hugging Face Vision Rehberi