Ein einfaches Machine Learning Projekt zum Trainieren eines Modells, das Bilder in verschiedene Kategorien einteilt (z.B. Katze vs. Hund).

Dieses Projekt verwendet Deep Learning (künstliche neuronale Netze) um Bilder automatisch zu klassifizieren.

Unterstützte Systeme:

• 🖥️ Windows mit NVIDIA GPU (CUDA)
• 🐧 Linux mit NVIDIA GPU (CUDA)
• 💻 Windows/Linux mit CPU
• 🍎 MacBook Pro mit Apple Silicon (M1, M2, M3) - nutzt GPU automatisch! ✨

Ein Modell trainieren, das neue Bilder sieht und automatisch erkennt, welche Kategorie sie gehören.

1. Training: Zeige dem Modell hunderte von Bildern mit Kategorien-Beschriftungen
2. Lernen: Das Modell passt seine "Gehirngewichte" an, um Muster zu erkennen
3. Vorhersage: Neue Bilder können sofort klassifiziert werden

GPU-Beschleunigung:

• Scripts erkennen automatisch ob GPU vorhanden ist
• NVIDIA GPU (10-100x schneller als CPU)
• Apple Silicon GPU (4-5x schneller als CPU)

pip install torch torchvision sklearn pillow

Spezial für MacBook Pro mit Apple Silicon (M1/M2/M3):

# PyTorch mit Metal Performance Shaders (GPU-Beschleunigung)
pip install torch torchvision torchaudio

# Überprüfe dass alles funktioniert
python -c "import torch; print('MPS available:', torch.backends.mps.is_available())"

Die Scripts erkennen automatisch ob eine GPU vorhanden ist und nutzen sie! ✨

Erstelle diese Ordnerstruktur:

data/
├── train/
│   ├── katze/
│   │   ├── foto1.jpg
│   │   ├── foto2.jpg
│   │   └── ...
│   └── hund/
│       ├── foto1.jpg
│       ├── foto2.jpg
│       └── ...
└── val/
    ├── katze/
    │   └── ...
    └── hund/
        └── ...

Tipps:

• Mindestens 50-100 Bilder pro Klasse
• Training: 70-80% der Bilder
• Validierung: 20-30% der Bilder (zum Testen während Training)
• https://www.kaggle.com/datasets/crawford/cat-dataset

python train.py

Das Script wird:

• 📂 Bilder laden und vorbereiten
• 🧠 Ein neuronales Netzwerk erstellen
• 🚀 Mit Trainingsdaten trainieren (15 Epochen)
• 📊 Nach jeder Epoche die Genauigkeit testen
• ✅ Das beste Modell speichern

Beispiel-Ausgabe:

📂 Lade Trainingsdaten...
Klassen gefunden: ['katze' 'hund']

🧠 Erstelle Modell...

🚀 Starte Training für 15 Epochen...

[Epoche 01/15] Training: Loss=0.6543, Accuracy=0.658 | Validierung: Loss=0.4321, Accuracy=0.782
✅ Neues bestes Modell! (Accuracy: 0.782)

[Epoche 02/15] Training: Loss=0.4123, Accuracy=0.789 | Validierung: Loss=0.3210, Accuracy=0.821
✅ Neues bestes Modell! (Accuracy: 0.821)

...

python predict.py foto_einer_katze.jpg

Beispiel-Ausgabe:

🤔 Analysiere Bild...
📷 Bild geladen: foto_einer_katze.jpg

============================================================
🎯 VORHERSAGE-ERGEBNIS
============================================================

✨ Das Bild zeigt wahrscheinlich: katze
   Sicherheit: 94.5%

📊 Wahrscheinlichkeiten für alle Klassen:
   katze           | ███████████████████████████░░ | 94.5%
   hund            | ██░░░░░░░░░░░░░░░░░░░░░░░░░░ | 5.5%

Du kannst auch einen Webserver starten, um Vorhersagen über eine Web-API zu machen!

pip install uvicorn fastapi python-multipart

uvicorn serve_model:app --reload --host 0.0.0.0 --port 8000

Ausgabe:

INFO:     Uvicorn running on http://0.0.0.0:8000

🚀 WEBSERVER STARTET
============================================================

Um den Server zu starten, führe aus:
  uvicorn serve_model:app --reload --host 0.0.0.0 --port 8000

Dann öffne im Browser:
  http://localhost:8000/docs

Öffne: http://localhost:8000/docs

Du siehst eine interaktive Dokumentation (Swagger UI):

1. Klicke auf POST /predict
2. Klicke auf "Try it out"
3. Klicke auf "Choose File" und wähle ein Bild
4. Klicke "Execute"
5. Sehe das Ergebnis!

Beispiel-Antwort:

{
  "label": "katze",
  "confidence": 0.945,
  "probabilities": {
    "katze": 0.945,
    "hund": 0.055
  }
}

import requests

# Bild hochladen und klassifizieren
response = requests.post(
    'http://localhost:8000/predict',
    files={'file': open('foto.jpg', 'rb')}
)

# Ergebnis anschauen
print(response.json())
# Ausgabe: {'label': 'katze', 'confidence': 0.945, ...}

curl -X POST -F '[email protected]' http://localhost:8000/predict

• http://localhost:8000/docs - Interaktive Swagger UI
• http://localhost:8000/redoc - Alternative Dokumentation
• http://localhost:8000/ - API-Informationen

Es gibt auch eine HTML-Seite mit grafischer Oberfläche statt nur der API!

uvicorn serve_model:app --reload --host 0.0.0.0 --port 8000

Öffne die HTML-Datei im Browser:

file:///C:/Users/sezgin/PycharmProjects/cat/web/index.html

Oder starte einen einfachen HTTP-Server:

# Python 3
python -m http.server 8080 --directory web

# Dann öffne im Browser:
# http://localhost:8080

1. Öffne die Seite im Browser
2. Klicke auf "Choose File"
3. Wähle ein Bild (JPG, PNG, etc.)
4. Das Bild wird sofort analysiert ✨
5. Sehe die Vorhersage und die Konfidenz!

Alle Scripts (train.py, predict.py, serve_model.py) erkennen automatisch:

1. Ist eine NVIDIA GPU vorhanden? → Nutze CUDA (schnellste Option)
2. Ist Apple Silicon vorhanden? → Nutze MPS (sehr schnell auf Mac)
3. Sonst → Nutze CPU (langsamer)

$ python train.py

🖥️  Trainiere auf: Apple Silicon GPU (MPS)
   Device: mps

📂 Lade Trainingsdaten...

F: Warum ist mein Mac manchmal langsamer?

Beim ersten Run kompiliert PyTorch den GPU-Code. Das dauert extra 10-20 Sekunden. Danach ist es viel schneller!

F: Kann ich GPU-Memory Fehler beheben?

Ja! Reduziere BATCH_SIZE in train.py:

BATCH_SIZE = 32  # statt 128

F: Funktioniert auch auf Intel Mac?

Intel Macs können nur CPU nutzen (kein Metal Performance Shaders). Überlege auf einem neueren Mac zu trainieren oder nutze GPU Cloud Services.

F: Was ist Metal Performance Shaders (MPS)?

Apples GPU-API für schnelle Berechnungen. Ähnlich wie CUDA von NVIDIA, aber für Apple Silicon. PyTorch nutzt es automatisch wenn torch.backends.mps.is_available() True ist.

Ein neuronales Netzwerk ist ein "Gehirn" aus vielen verbundenen Neuronen:

Eingabe (Bild)  →  [Neuron-Schichten]  →  Ausgabe (Kategorie)
                    • Schicht 1
                    • Schicht 2
                    • ...
                    • Output-Schicht

Jedes Neuron hat eine Gewicht (wie wichtig ist dieser Input?). Beim Training passen wir diese Gewichte an.

Eine Epoche = Das Modell sieht ALLE Trainingsdaten einmal.

• Epoche 1: Schaut alle Bilder an → passt Gewichte an
• Epoche 2: Schaut alle Bilder NOCHMAL an → passt wieder an
• ...
• Epoche 15: Zum 15. Mal alle Bilder anschauen

Mit jeder Epoche wird das Modell hoffentlich besser!

Die Confusion Matrix zeigt, wo das Modell Fehler macht:

                     Vorhersage: Katze   Vorhersage: Hund
Echte: Katze                    95                     5
Echte: Hund                     10                    90

Interpretation:

• Diagonal (95, 90): Richtige Vorhersagen ✅
• Nebendiagonal (5, 10): Fehler ❌

In diesem Beispiel:

• ✅ 95 Katzen richtig erkannt
• ❌ 5 Katzen fälschlicherweise als Hund erkannt
• ❌ 10 Hunde fälschlicherweise als Katze erkannt
• ✅ 90 Hunde richtig erkannt

Diese Metriken messen verschiedene Arten von Genauigkeit:

Precision (Präzision):

"Wenn das Modell sagt 'Katze', wie oft hat es Recht?" Precision = Richtige Katzen / (Richtige Katzen + Falsche Katzen)

Recall (Empfindlichkeit):

"Von allen echten Katzen, wie viele erkannte das Modell?" Recall = Richtige Katzen / (Richtige Katzen + Übersehene Katzen)

F1-Score:

Der Durchschnitt von Precision und Recall (ausgewogenes Maß)

Statt das Modell von Null zu trainieren, verwenden wir ein vortrainiertes Modell (ResNet18):

Vortrainiertes Modell (von Millionen Bildern gelernt)
    ↓
    ├─ Erste Schichten: Bleiben unverändert ❄️
    │   (Können bereits Kanten, Farben, Formen erkennen)
    │
    └─ Letzte Schichten: Wir trainieren neu 🔥
        (Spezialisiert für unsere Aufgabe: Katze vs. Hund)

Vorteile:

• ⚡ Viel schneller (statt Tage nur Minuten)
• 📈 Bessere Ergebnisse (brauchen weniger Daten)
• 💰 Weniger Rechenpower nötig

In train.py kannst du diese Parameter anpassen:

BATCH_SIZE = 128      # Wie viele Bilder auf einmal? (64-256 ist normal)
EPOCHS = 15           # Wie oft trainieren? (mehr = potenziell besser, aber längere Zeit)
LR = 3e-4            # Lerngeschwindigkeit (zu hoch = instabil, zu niedrig = langsam)
PATIENCE = 6         # Early Stopping: Nach wie vielen Epochen ohne Verbesserung stoppen?
IMG_SIZE = 224       # Bildgröße (224x224 ist Standard für ResNet)

Trainiert das Modell mit deinen Bildern.

Was es tut:

1. Lädt Bilder aus dem data/ Ordner
2. Bereitet sie vor (verkleinern, normalisieren)
3. Erstellt ein neuronales Netzwerk
4. Trainiert es für 15 Epochen
5. Speichert das beste Modell in artifacts/model.pt
6. Zeigt Metriken und Confusion Matrix

Output:

• artifacts/model.pt - Das trainierte Modell
• artifacts/classes.json - Die Klassennamen

Nutzt das trainierte Modell um neue Bilder vorherzusagen (Command Line).

Wie zu nutzen:

python predict.py /pfad/zu/bild.jpg

Output:

• Beste Vorhersage (z.B. "Katze")
• Konfidenz/Sicherheit (0-100%)
• Wahrscheinlichkeiten für alle Klassen
• Visualisierter Balken pro Klasse

Startet einen Webserver, der die Vorhersagen über eine API anbietet.

Was es tut:

1. Lädt das trainierte Modell
2. Startet einen FastAPI-Webserver (Port 8000)
3. Bietet zwei Wege zur Klassifizierung:
   • Browser: Interaktive Swagger UI (http://localhost:8000/docs)
   • API: Programmatisch via requests/curl

Wie zu nutzen:

# Webserver starten
uvicorn serve_model:app --reload --host 0.0.0.0 --port 8000

# Im Browser öffnen
# http://localhost:8000/docs

# Oder mit Python
import requests
response = requests.post('http://localhost:8000/predict',
  files={'file': open('bild.jpg', 'rb')})
print(response.json())

Output:

• JSON mit Vorhersage, Konfidenz und Wahrscheinlichkeiten
• Interaktive Web-Oberfläche mit Dokumentation

Eine grafische Web-Oberfläche zum Testen des Modells im Browser.

Was es tut:

1. Zeigt ein File-Upload Feld
2. Sendet das Bild zum Webserver (serve_model.py)
3. Zeigt die Vorhersage und Konfidenz direkt an
4. Zeigt Vorschau des hochgeladenen Bildes

Wie zu nutzen:

# Option 1: Direkt öffnen (lokal)
# Doppelklick auf web/index.html

# Option 2: Mit HTTP-Server
python -m http.server 8080 --directory web
# Dann Browser: http://localhost:8080

Vorrausetzungen:

• serve_model.py muss auf Port 8000 laufen
• Browser muss auf http://localhost:8000 zugreifen können

# 1️⃣  MODELL TRAINIEREN
python train.py

# 2️⃣  EINZELNES BILD KLASSIFIZIEREN (Command Line)
python predict.py foto.jpg

# 3️⃣  WEBSERVER STARTEN
uvicorn serve_model:app --reload --host 0.0.0.0 --port 8000

# 4️⃣  INTERAKTIVE API IM BROWSER
# Öffne: http://localhost:8000/docs

# 5️⃣  WEB-OBERFLÄCHE NUTZEN
# Öffne: file:///C:/Users/sezgin/PycharmProjects/cat/web/index.html

# 6️⃣  MIT PYTHON API NUTZEN
python << 'EOF'
import requests
r = requests.post('http://localhost:8000/predict',
  files={'file': open('foto.jpg', 'rb')})
print(r.json())
EOF

# 7️⃣  MIT CURL API NUTZEN
curl -X POST -F '[email protected]' http://localhost:8000/predict

Lösung: Erstelle die data/ Ordnerstruktur wie oben beschrieben.

Lösungen:

• Nutze eine GPU (NVIDIA CUDA): Model trainiert 10-100x schneller
• Reduziere Bildanzahl (weniger Daten = schnelleres Training)
• Reduziere BATCH_SIZE (weniger RAM nötig)

Lösungen:

• Mehr Bilder sammeln (mindestens 100-200 pro Klasse)
• Unterschiedlichere Bilder (verschiedene Winkel, Lichtverhältnisse)
• Trainiere mehr Epochen (erhöhe EPOCHS)
• Überprüfe ob Bilder richtig beschriftet sind

Lösungen:

• Reduziere BATCH_SIZE (z.B. von 128 auf 64)
• Reduziere Bildanzahl
• Starte andere Programme, die GRAM nutzen

Lösung: Installiere die fehlenden Dependencies:

pip install fastapi uvicorn python-multipart

Lösungen:

• Nutze einen anderen Port:

  uvicorn serve_model:app --reload --host 0.0.0.0 --port 8001

• Oder beende das andere Programm das Port 8000 nutzt

Lösungen:

• Überprüfe dass der Server wirklich läuft (sollte "Uvicorn running on..." anzeigen)
• Warte 2-3 Sekunden nach dem Start
• Versuche http://127.0.0.1:8000/docs statt localhost
• Überprüfe Firewall-Einstellungen

Lösungen:

• Überprüfe dass PyTorch korrekt installiert ist:

  python -c "import torch; print(torch.backends.mps.is_available())"

  Sollte True ausgeben

• Aktualisiere PyTorch:

  pip install --upgrade torch torchvision torchaudio

• Achte darauf dass es ein Apple Silicon Mac ist (M1, M2, M3)

  uname -m
  # Sollte "arm64" ausgeben (nicht "x86_64")

Lösungen:

• Erste 1-2 Epochen sind langsamer (JIT-Kompilation)
• Reduziere BATCH_SIZE wenn zu viel Memory genutzt wird
• Überprüfe Ressourcennutzung (Activity Monitor)
• Schließe andere Apps um RAM freizumachen

Ein Computer lernt von Beispielen statt dass man ihm jede Regel vorprogrammiert.

Beispiel: Statt "wenn Bild hat spitze Ohren → Katze" schreiben, zeigen wir dem Computer 1000 Katzen und 1000 Hunde. Er findet selbst heraus, was Katzen sind!

Machine Learning mit tiefen neuronalen Netzen (viele Schichten). Ideal für Bilder und Text!

Misst "wie falsch" die Vorhersagen sind.

• Loss = 0: Perfekt! ✨
• Loss = hoch: Sehr falsch ❌

Das Training versucht den Loss zu minimieren.

Der "Lernalgorithmus". Passt die Gewichte an um den Loss zu reduzieren. Adam ist ein beliebter Optimizer (funktioniert in den meisten Fällen gut).

API = Application Programming Interface

Eine API ermöglicht es anderen Programmen (nicht Menschen) mit deiner Anwendung zu kommunizieren.

Beispiel:

• Ohne API: Du musst python predict.py bild.jpg manuell im Terminal aufrufen
• Mit API: Ein anderes Programm kann automatisch dein Modell aufrufen und Bilder klassifizieren

HTTP API: Nutzt das gleiche Protokoll wie Webseiten (HTTP). Perfekt für Web-Anwendungen!

FastAPI = Modernes Python-Framework um Web-APIs zu bauen (schnell, einfach, dokumentiert)

Swagger UI = Interaktive Dokumentation deiner API

• Du kannst direkt im Browser APIs testen (keine separaten Tools nötig!)
• Zeigt alle verfügbaren Endpunkte und Parameter
• Gibt automatisch Beispiel-Requests und Responses

Öffne http://localhost:8000/docs um Swagger selbst auszuprobieren!

1. Experimentieren: Probiere verschiedene Klassifizierungsaufgaben
2. Mehr Klassen: Erweitere das Projekt auf 3+ Kategorien
3. Fine-Tuning: Experimentiere mit Einstellungen
4. Andere Modelle: Probiere andere Architekturen (ResNet50, EfficientNet, etc.)

• PyTorch: Deep Learning Framework
• TorchVision: Bildverarbeitung und vortrainierte Modelle
• scikit-learn: Metriken (Confusion Matrix, Classification Report)
• PIL: Bildladen und -verarbeitung

✅ DO:

• Unterschiedliche Bilder sammeln (verschiedene Winkel, Lichter, Größen)
• Train/Val Split beachten (Modell nie mit Validierungsdaten trainieren!)
• Genug Daten sammeln (mindestens 100 pro Klasse)
• Bilder vorher anschauen und prüfen (sind sie richtig beschriftet?)

❌ DON'T:

• Zu viele Klassen mit wenig Daten (3-5 Klassen mit 100+ Bildern ist gut)
• Sehr schlechte Bildqualität nutzen (zu dunkel, verschwommen, irrelevant)
• Zu lange trainieren (Overfitting: Modell merkt sich Daten statt zu lernen)
• Trainings- und Validierungsdaten vermischen

Wenn etwas nicht funktioniert:

1. Lies die Fehlermeldung genau
2. Überprüfe deine Datenstruktur
3. Schau im "Troubleshooting" oben nach

Dieses Projekt ist für Lehr- und Demonstrationszwecke gedacht.

Viel Spaß beim Trainieren! 🚀