Architektur¶

Bildgenerierung ist als containerisierte Webanwendung umgesetzt, die ein eigenständiges Frontend bereitstellt und sämtliche Bilderzeugungsaufgaben an einen externen, OpenAI-kompatiblen Inferenz-Dienst delegiert. Die Anwendung selbst hält keinen persistenten Zustand und beschränkt sich auf Eingabesammlung, Aufrufkoordination, Bildvorverarbeitung sowie die Aufbereitung der Ergebnisse für die Anzeige und den Download.

Auf einen Blick¶

Gradio-basiertes Frontend in einem schlanken Docker-Container
Synchrone Aufrufe an einen OpenAI-kompatiblen Inferenz-Dienst über HTTPS
Klare Trennung von Oberfläche, Anwendungslogik, Bildvorverarbeitung und HTTP-Kommunikation
Dynamische Endpunkt-Wahl je nach Vorhandensein von Referenzbildern (Bilderzeugungs-API oder Chat-Completion-API)
Konfiguration ausschließlich über Umgebungsvariablen (Endpunkt, Modell, API-Schlüssel)
Containerisierter Betrieb mit Healthcheck und Ausführung als unprivilegierter Benutzer

Architekturbeschreibung¶

Komponenten und Schichten¶

Die Anwendung gliedert sich in vier logische Schichten innerhalb eines einzelnen Prozesses:

Frontend-Schicht (Gradio UI): Stellt Eingabefelder, Voreinstellungen, das Akkordeon mit erweiterten Parametern, die Galerie der Ergebnisse sowie die Beispiel-Prompts bereit. Sie übersetzt Eingaben in Funktionsaufrufe und reagiert auf Änderungen der Voreinstellungen über Event-Handler.
Anwendungslogik: Entscheidet anhand der Eingaben über den zu verwendenden API-Pfad, validiert grundlegende Eingaben (z.B. Pflicht-Prompt) und steuert mehrfache Aufrufe für die parallele Variantenerzeugung.
Bildvorverarbeitung: Skaliert Referenzbilder auf eine maximale Kantenlänge, konvertiert sie je nach Farbraum nach JPEG oder PNG und erzeugt Daten-URIs für die Übergabe im Chat-Completion-Pfad. Antworten des Servers werden in unterschiedlichen Formaten (Base64, eingebettete Bilddaten, Daten-URIs, externe URLs) erkannt und in nutzbare Bildobjekte überführt.
HTTP-Kommunikationsschicht: Spricht den Inferenz-Dienst über HTTPS mit konfiguriertem Timeout und aktivierter Zertifikatsprüfung an. Sie ergänzt API-Schlüssel im Authorization-Header und unterscheidet Verbindungs-, Zeit- und HTTP-Statusfehler.

Workflow¶

flowchart TB
    Browser[Browser]

    subgraph App["Anwendungs-Container"]
        UI["Gradio UI<br/>Eingaben, Presets, Galerie"]
        Logic["Anwendungslogik<br/>Endpunkt-Wahl, Variantensteuerung"]
        Pre["Bildvorverarbeitung<br/>Skalierung, Encoding"]
        HTTP["HTTPS-Client"]
    end

    subgraph Local["Lokale Infrastruktur"]
        Server["Inferenz-Server<br/>OpenAI-kompatibel"]
        Models[("Bildmodelle<br/>Qwen-Image-2512<br/>FLUX.2-dev")]
    end

    Browser -->|Eingaben| UI
    UI --> Logic
    Logic -->|mit Referenzbildern| Pre
    Pre --> HTTP
    Logic -->|ohne Referenzbilder| HTTP
    HTTP -->"/v1/images/generations"| Server
    HTTP -->"/v1/chat/completions"| Server
    Server --> Models
    Models --> Server
    Server -->|Bilddaten| HTTP
    HTTP -->|Dekodierung| Logic
    Logic -->|Galerie| UI
    UI -->|Anzeige, Download| Browser

Der Ablauf eines Durchlaufs folgt einer linearen Kette: Die Oberfläche nimmt Prompt, optionale Referenzbilder und Parameter entgegen und übergibt sie an die Anwendungslogik. Diese entscheidet anhand der Eingaben, ob der Bilderzeugungs-Endpunkt (Text-to-Image) oder der Chat-Completion-Endpunkt (Image-to-Image) genutzt wird. Im Image-to-Image-Pfad werden Referenzbilder zuvor skaliert und als eingebettete Daten in die Anfrage eingebunden. Der HTTPS-Client ruft den Inferenz-Server in der lokalen Infrastruktur auf, der seinerseits die Anfrage an das konfigurierte Bildmodell weiterleitet. Die Antwort wird je nach Format dekodiert, als PNG mit zeitstempelbasiertem Dateinamen abgelegt und in der Galerie angezeigt. Anschließend kann ein Ergebnis per Schaltfläche als Referenz für den nächsten Durchlauf übernommen werden.

Bilderzeugung und Modelle¶

Die eigentliche Bilderzeugung findet ausschließlich auf dem Inferenz-Server statt. Die Anwendung selbst lädt kein Modell und führt keine GPU-gestützte Berechnung durch. Über die zentrale Modellkonfiguration kann zwischen den unterstützten Bildmodellen Qwen-Image-2512 und black-forest-labs/FLUX.2-dev gewechselt werden, ohne dass die Anwendung neu gestartet oder angepasst werden muss; die Auswahl erfolgt durch die Modellbezeichnung in der Konfiguration des Inferenz-Servers.

Nebenläufigkeit und Robustheit¶

Die Anwendung verwendet die Gradio-eigene Aufrufwarteschlange, sodass parallele Anfragen reihenfolgenrichtig verarbeitet werden. HTTP-Aufrufe sind synchron und mit einem Zeitlimit versehen. Drei Fehlerklassen werden gesondert behandelt: Verbindungsfehler (Server nicht erreichbar), Zeitüberschreitungen (Hinweis auf reduzierte Steps oder Auflösung) und HTTP-Fehlerantworten mit gekürzter Wiedergabe der Server-Antwort. Antworten mit fehlenden oder unbekannt strukturierten Bilddaten werden ebenfalls erkannt und mit einer aussagekräftigen Meldung quittiert.

Konfiguration und Deployment¶

Die Konfiguration erfolgt vollständig über Umgebungsvariablen, die optional aus einer .env-Datei geladen werden. Wesentliche Parameter sind die Basis-URL des Inferenz-Dienstes, der API-Schlüssel und die Modellbezeichnung; ergänzend lassen sich Bind-Adresse, Port und ein Root-Pfad für den Betrieb hinter einem Reverse-Proxy setzen. Der mitgelieferte Container basiert auf einem schlanken Python-Image, installiert die Abhängigkeiten ohne Cache, kopiert die Anwendung, legt einen unprivilegierten Benutzer an und stellt den Dienst auf Port 7860 bereit. Ein eingebauter Healthcheck prüft regelmäßig die Erreichbarkeit des Webservers.

Technologie-Übersicht¶

Sprache und Laufzeit: Python 3.12
Frontend-Framework: Gradio (Version 6)
HTTP-Client: httpx mit TLS-Verifikation und konfiguriertem Zeitlimit
Bildverarbeitung: Pillow (PIL)
Konfiguration: python-dotenv
Containerisierung: Docker, schlankes Python-Basisimage, unprivilegierter Benutzer, Healthcheck
Backend-Schnittstelle: OpenAI-kompatibler Inferenz-Dienst (Endpunkte /v1/images/generations und /v1/chat/completions)
Bildmodelle: Qwen-Image-2512 sowie black-forest-labs/FLUX.2-dev
Protokoll: HTTPS, JSON-basierte Anfragen und Antworten nach OpenAI-Spezifikation