gradio.Server erweitert FastAPI um Gradio-Funktionen wie API-Queuing, SSE-Streaming, Concurrency Control und Kompatibilität mit gradio_client. Damit lassen sich eigene Frontends mit Frameworks wie React, Svelte oder plain HTML/JS bauen und zugleich Gradio-Backend-Funktionen sowie Hosting auf Hugging Face Spaces nutzen.
Als Beispiel dient die Anwendung „Text Behind Image“. Dabei wird ein Foto hochgeladen, der Hintergrund mit einem ML-Modell entfernt und anschließend Text zwischen Vordergrund und Hintergrund platziert. Die Anwendung benötigt eine Drag-and-drop-Canvas mit mehreren Ebenen, viele Steuerelemente für die Textgestaltung, ein ML-Backend für die Freistellung und einen PNG-Export im Browser. Laut Beitrag lässt sich eine solche Oberfläche nicht mit Gradio-Komponenten ausdrücken, während die Backend-Funktionen von Gradio weiterhin genutzt werden sollen.
Das gezeigte Backend umfasst rund 50 Zeilen Python. Verwendet werden unter anderem FastAPI, gradio.Server, spaces.GPU, PyTorch, PIL, torchvision und das Modell ZhengPeng7/BiRefNet über AutoModelForImageSegmentation. Das Modell wird beim Start geladen, nach CUDA verschoben und für die Segmentierung genutzt. Die Funktion zur Freistellung erzeugt aus dem Eingabebild eine Transparenzmaske und speichert das Ergebnis als PNG.
Der API-Endpunkt wird mit @app.api(name="remove_background") definiert. Dadurch läuft der Aufruf über Gradios Queue-Engine. Im Beitrag wird dies dem Ansatz einer normalen @app.post()-Route in FastAPI gegenübergestellt: Wenn mehrere Nutzer gleichzeitig zugreifen, könnten Anfragen ohne Concurrency Management um die GPU konkurrieren. Mit @app.api() werden Anfragen serialisiert, die Parallelität kontrolliert und auf ZeroGPU-Spaces die GPU-Zuweisung über @spaces.GPU automatisch behandelt.
Zugleich bleiben normale FastAPI-Routen möglich. Im Beispiel liefert @app.get("/") eine HTML-Seite aus, sodass API-Endpunkte und klassische Webrouten in derselben Anwendung nebeneinander existieren. Weil Server eine FastAPI-App ist, stehen außerdem benutzerdefinierte Routen, Middleware, Datei-Uploads und beliebige Response-Typen zur Verfügung.
Der Beitrag zeigt auch die programmatische Nutzung über gradio_client. Ein mit @app.api() definierter Endpunkt kann direkt aus anderen Apps oder Skripten aufgerufen werden. Im Beispiel wird das Space ysharma/text-behind-image per Client angesprochen und der Endpunkt /remove_background mit einer Bilddatei aufgerufen.
Das Frontend der Beispielanwendung besteht aus einer eigenständigen HTML-Datei mit etwa 1300 Zeilen und verwendet kein React, keinen Build-Schritt und keinen Bundler. Genannt werden eine Drei-Ebenen-Canvas aus Hintergrundbild, Textebene und freigestelltem Vordergrund mit CSS-z-index, Drag-and-drop-Positionierung über Pointer Events, ein Bedienfeld mit mehr als 20 Parametern und clientseitiger PNG-Export per <canvas>-Compositing. Zu den Parametern zählen unter anderem Schriftfamilie mit mehr als 25 Fonts, Größe, Gewicht, Abstand, Farbe, Opazität, Hintergrundfüllung, Stroke, Shadow, 3D-Extrusion, Rotation, Skew und CSS-Perspective-Transforms.
Die Kommunikation zwischen Frontend und Backend erfolgt über den Gradio JS Client statt über ein direktes fetch(). Im Beispiel verbindet sich das Frontend mit dem lokalen Ursprung und ruft /remove_background auf. Laut Beitrag ist dieser Punkt entscheidend, weil der Aufruf dadurch durch Gradios Queue läuft. So werden Parallelität und GPU-Zugriffe verwaltet; außerdem könnten Queue-Position oder Fortschritt angezeigt werden. Text-Rendering, Ebenen-Compositing und Export bleiben im Browser.
Der Beitrag beschreibt gradio.Server damit als Backend-Framework für Fälle, in denen Gradio nicht für die Oberfläche verwendet wird. Wer die Gradio-Oberfläche nutzen möchte, kann weiterhin mit gr.Blocks, gr.Interface oder gr.ChatInterface arbeiten. Wer eine eigene Oberfläche benötigt, kann gradio.Server mit einem beliebigen Frontend kombinieren und dabei Spaces-Hosting, API-Queuing, gradio_client und weitere Funktionen des Hugging-Face-Ökosystems nutzen.
Abschließend verweist der Text auf weitere Themen, die noch nicht im Detail behandelt werden, darunter MCP-Tool-Registrierung mit @app.mcp.tool(), SSE-Streaming für Echtzeit-Updates, Batch Processing und Muster für mehrseitige Anwendungen mit geteiltem Zustand.
