ARCHITECTURE_HUGGINGFACE.md

🏗️ PixelForge Architektur mit HuggingFace Spaces

Übersicht

PixelForge wird als Orchestrator fungieren, der externe AI-Services via REST API orchestriert. Die Heavy-Lifting (GPU-intensive Image Generation) läuft auf HuggingFace Spaces.

┌─────────────────────────────────────────────────────────┐
│            PixelForge Frontend (React/Vite)             │
│                   http://127.0.0.1:5173                │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ HTTP Requests
                     ↓
┌─────────────────────────────────────────────────────────┐
│          PixelForge Backend (FastAPI)                   │
│           http://127.0.0.1:8008                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Provider Factory & Job Manager                 │  │
│  └────┬─────────────────────────────────────────────┘  │
└────┼──────────────────────────────────────────────────────┘
     │
     ├─ Lokale Provider (CPU):
     │  ├─ dummy: Dummy bilder
     │  ├─ localai: LocalAI Engine
     │  └─ diffusion: Stable Diffusion (lokal)
     │
     └─ Remote Provider (API/GPU):
        ├─ zimageturbo: Cloud API (Colab/RunPod) [ÜBERGANGSLÖSUNG]
        ├─ huggingface: HuggingFace Space API [ZUKÜNFTIG]
        │  ├─ Heartsync/Adult Space (erwachsene Inhalte)
        │  ├─ weitere HF Spaces...
        │  └─ Authentifizierung via HF API Token
        │
        └─ a1111: AUTOMATIC1111 API (lokal falls vorhanden)

---

Phase 1: Aktuelle State (Übergangslösung)

Colab + Z-Image Turbo als schneller Remote-Provider:

• ✅ Funktioniert sofort
• ⚠️ Session-basiert (max 12 Stunden)
• ⚠️ Colab kann jeden Moment beenden
• ✅ Kostenlos

Implementation: zimageturbo_provider.py (HTTP API Wrapper)

Zu tun jetzt:

1. Frontend testen (Modellauswahl wurde gefixt)
2. Colab Notebook hochladen & API URL setzen
3. Z-Image Turbo Provider testen

---

Phase 2: HuggingFace Space Integration (Zukünftig)

Adult_repo bleibt als eigenständige Einheit auf HuggingFace Spaces:

# Adult_repo läuft auf:
https://huggingface.co/spaces/Heartsync/Adult
# → Hat eigene GPU/Inference Engine
# → Verfügbar 24/7 (solange Space online)

Architektur:

1. Adult_repo auf HF Space (remote)

   • Gradio Interface (aber nicht für PixelForge relevant)
   • Inference Endpoint für API-Calls
   • Nutzt Z-Image Turbo Model intern

2. HuggingFace Space API Provider (neu in PixelForge)

   # Backend Provider
   class HuggingFaceSpaceProvider(IImageProvider):
       def __init__(self, space_name: str, token: str):
           self.space_name = "Heartsync/Adult"  # oder andere Spaces
           self.api_token = os.getenv("HF_API_TOKEN")
           
       def generate(self, request: ProviderRequest) -> ProviderResult:
           # POST zu HF Inference API
           # https://api-inference.huggingface.co/models/{space}
           ...
   

3. PixelForge kennt mehrere Spaces:

   • heartsync/adult → Erwachsene Inhalte
   • heartsync/anime → Anime-Style
   • custom/space → Beliebige andere Spaces

---

Vergleich: Colab vs HuggingFace Space

Aspekt	Colab	HF Space	Lokal
Setup	Jupyter Notebook	Einmal deployen	Python Virtual Env
Kosten	Kostenlos	Kostenlos (mit Limits)	Nur Hardware
Persistenz	12h max	24/7 (solange online)	24/7
GPU	T4/A100 (kostenlos)	Space-spezifisch	Deine Hardware
API-Zugriff	über Ngrok-Tunnel	HF Inference API	localhost:PORT
Startzeit	~2 min (Kernel)	instant	instant
Geeignet für	Schnelle Tests	Production	Development

---

Implementierungs-Roadmap

✅ Heute (Phase 1)

• Frontend Model-Picker repariert
• Colab Notebook erstellt
• zimageturbo_provider.py ✓
• Testen mit Colab

📅 Später (Phase 2)

• HuggingFaceSpaceProvider erstellen
• HF API Token Authentication
• Adult_repo auf HF Space deployen
• Provider registrieren & testen
• Colab durch HF Space ersetzen

🎯 Langfristig (Phase 3)

• Multi-Space Support (verschiedene Spaces wählen)
• Space Health Monitoring
• Fallback-Strategie (wenn Space down ist)
• Queue Management für lange Jobs

---

HuggingFace API Details (für später)

Space Deployment (Adult_repo)

# HF CLI installieren
pip install huggingface-hub

# Private Space erstellen (Adult content)
huggingface-cli repo create --type space Adult_repo --private

# Adult_repo hochladen
git push huggingface main

PixelForge Provider (HTTP API Call)

import requests

# HF Inference API Endpoint
url = "https://api-inference.huggingface.co/models/Heartsync/Adult"

payload = {
    "inputs": "A beautiful sunset over mountains",
}

headers = {
    "Authorization": f"Bearer {HF_API_TOKEN}"
}

response = requests.post(url, json=payload, headers=headers)
image_data = response.content  # PIL Image bytes

Alternative: Space API (wenn Gradio genutzt)

# Falls Adult_repo Gradio API exponiert
from gradio_client import Client

client = Client("https://huggingface.co/spaces/Heartsync/Adult")
result = client.predict(
    prompt="A girl in a school uniform",
    seed=42,
    api_name="/predict"
)

---

Umgebungsvariablen (Phase 2)

# HuggingFace Integration
$env:HF_API_TOKEN = "hf_xxxxxxxxxxxxxxxxxxxxx"
$env:HF_SPACE_ADULT = "Heartsync/Adult"
$env:HF_SPACE_DEFAULT = "Heartsync/Adult"
$env:HF_REQUEST_TIMEOUT = "300"  # Sekunden

# Colab (Phase 1 - temporär)
$env:ZIMAGETURBO_API_URL = "https://abc123.ngrok.io"
$env:ZIMAGETURBO_TIMEOUT = "300"

---

Adult_repo Struktur (vor Ort)

d:/VSC Codes/Bild/Adult_repo/
├── app.py                 # Gradio Interface (wird auf HF Space laufen)
├── requirements.txt       # Dependencies
├── README.md
└── .git                   # Git Repo

Wichtig: Adult_repo ist momentan nicht in PixelForge integriert!

• Es läuft später als eigenständiger Service auf HF Space
• PixelForge ruft es via HF API auf
• Keine lokale Abhängigkeit → Clean Architecture ✨

---

Nächste Schritte

Sofort (Phase 1):

# 1. Frontend aktualisieren (Done ✓)
# 2. Browser aktualisieren (F5)
# 3. Modellauswahl testen
# 4. Colab konfigurieren & testen

Später (Phase 2):

# 1. Adult_repo zu HF Space pushen
# 2. HF API Token besorgen
# 3. HuggingFaceSpaceProvider schreiben
# 4. In Factory registrieren
# 5. Testen & Colab deaktivieren

---

Fragen für Phase 2?

• Welche anderen Spaces möchtest du anbinden?
• Benötigst du Content Moderation (Safety Filter)?
• Wie sollen lange Jobs (>5min) gehandhabt werden?
• Fallback-Strategie wenn Space down ist?

---

Status: 🟢 Phase 1 bereitet sich vor Phase 2 Start: Nach Colab-Test & HF Space Deployment