跳到正文
Hugging Face Blog·· 2026-04-01精選AI 評分68

Gradio 介紹 gradio.Server,讓自訂前端使用 Gradio 後端

Any Custom Frontend with Gradio's Backend

AI 導讀

Gradio 介紹 gradio.Server,讓自訂前端可使用 Gradio 的後端能力,同時採用自選的前端框架。gradio.Server 擴展 FastAPI,提供自訂路由等功能,並加入 Gradio 的佇列、SSE 串流、並發控制和 gradio_client 相容性。

推薦理由

文章以圖像去背示例展示如何讓自訂 HTML/CSS/JS 前端透過 gradio.Server 使用 Gradio 佇列、並發控制與 ZeroGPU,提供兼顧介面自由度和後端管理的實作參考。

正文 · 繁體中文

幾星期前,我們介紹了使用 gr.HTML一次過打造完整網頁應用程式:在 Gradio 內完全以自訂 HTML、CSS 和 JavaScript 建立豐富的互動前端。這解鎖了不少可能性。但如果這還不夠呢?

如果你想完全使用自己的前端框架來開發,例如 React、Svelte,甚至純 HTML/JS,同時繼續使用 Gradio 的排隊系統、API 基礎設施、MCP 支援,以及 Spaces 上的 ZeroGPU,該怎麼辦?

這正是 gradio.Server要解決的問題。它改變了 Gradio 和 Hugging Face Spaces 的可能性。

我們想打造甚麼

Text Behind Image:一款編輯器,讓你上載相片,再由 ML 模型移除背景,然後把風格化文字放在前景主體與背景之間。文字看起來就像位於圖片中人物或物件的後方。

這需要:

  • 具備分層繪製功能的拖放畫布(背景 → 文字 → 前景)
  • 功能豐富的控制面板,設有字體大小、粗幼、字距、顏色、不透明度、描邊、陰影、3D 擠出、透視變換等滑桿
  • 可執行背景移除模型並傳回透明 PNG 的後端 ML 端點
  • 在用戶端匯出為 PNG

Gradio 元件無法呈現這種 UI,因為它實際上是一個完整的網頁應用程式。不過,我們仍想使用 Gradio 的後端能力:排隊、並行管理、ZeroGPU 支援,以及無須煩惱基礎設施便可託管在 HF Spaces。

登場的是 gradio.Server

gradio.Server以 FastAPI 為基礎擴展而成。它提供 FastAPI 的全部能力(自訂路由、中介軟件、檔案上載、任何回應類型),並在此之上加入 Gradio 的 API 引擎:排隊、SSE 串流、並行控制,以及兼容 gradio_client。

以下是 Text Behind Image 的完整後端:

import os
import torch
from PIL import Image
from torchvision import transforms
from transformers import AutoModelForImageSegmentation
from gradio import Server
from gradio.data_classes import FileData
from fastapi.responses import HTMLResponse
import spaces

torch.set_float32_matmul_precision("high")

birefnet = AutoModelForImageSegmentation.from_pretrained(
    "ZhengPeng7/BiRefNet", trust_remote_code=True
)
birefnet.to("cuda")
birefnet.float()

transform_image = transforms.Compose([
    transforms.Resize((1024, 1024)),
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
])

app = Server()


@spaces.GPU
def segment(image: Image.Image) -> Image.Image:
    """Run BiRefNet segmentation to produce a transparency mask."""
    image_size = image.size
    input_images = transform_image(image).unsqueeze(0).to("cuda")
    with torch.no_grad():
        preds = birefnet(input_images)[-1].sigmoid().cpu()
    pred = preds[0].squeeze()
    mask = transforms.ToPILImage()(pred).resize(image_size)
    image.putalpha(mask)
    return image


@app.api(name="remove_background")
def remove_background(image_path: FileData) -> FileData:
    """Remove background from an image. Returns transparent PNG."""
    im = Image.open(image_path["path"]).convert("RGB")
    result = segment(im)
    out_path = image_path["path"].rsplit(".", 1)[0] + ".png"
    result.save(out_path)
    return FileData(path=out_path)


@app.get("/", response_class=HTMLResponse)
async def homepage():
    html_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "index.html")
    with open(html_path, "r", encoding="utf-8") as f:
        return f.read()


app.launch(show_error=True)

就是這樣,約 50 行 Python。模型在啟動時載入,@spaces.GPU負責分配 ZeroGPU,而 gradio.Server則管理排隊和並行處理。以下逐一説明其運作方式。

為何使用 @app.api(),而非一般 FastAPI 路由?

如果這是一般 FastAPI 應用程式,你會為背景移除功能定義 @app.post()路由。只要有兩位用戶同時使用,問題便會浮現。缺乏並行管理時,兩個請求會爭用 GPU,令應用程式崩潰或傳回錯誤結果。

@app.api()正好解決這個問題。它會以 Gradio 排隊引擎包裝函式:請求會依序處理、並行受到控制,而在 ZeroGPU Spaces 上,@spaces.GPU會自動處理 GPU 分配。另外,任何 @app.api()端點也可透過 gradio_client呼叫,讓其他應用程式或指令碼以程式方式使用你的 Space:

from gradio_client import Client, handle_file
client = Client("ysharma/text-behind-image")
result = client.predict(
      image_path=handle_file("photo.jpg"),
      api_name="/remove_background"
  )

同時,@app.get("/")則是標準 FastAPI 路由,用來提供 HTML 頁面。由於 Server本身就是 FastAPI 應用程式,兩者可自然共存。

前端:純 HTML/CSS/JS

這個範例的 index.html是一個自包含、約 1300 行的網頁應用程式。沒有 React、無須建置步驟或打包工具,只有原生 HTML,並具備以下功能:

  • 三層畫布:以 CSS z-index堆疊背景圖片 → 文字層 → 前景(透明 PNG)
  • 使用指標事件拖放定位文字
  • 設有 20+ 個參數的控制面板:字體系列(25+ 款字體)、大小、粗幼、間距、顏色、不透明度、背景填色、描邊、陰影、3D 擠出的深度和角度、旋轉、傾斜,以及完整 CSS 透視變換
  • 在用戶端匯出 PNG,使用 <canvas>合成

前端透過 Gradio JS Client與後端通訊:

import { Client, handle_file } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";

const client = await Client.connect(window.location.origin);
const result = await client.predict("/remove_background", {
    image_path: handle_file(file),
});
foregroundLayer.src = result.data[0].url;  // transparent PNG

關鍵在於:前端使用 Gradio JS client,而非原始 fetch()呼叫,因此請求會經過 Gradio 排隊系統。這代表系統會管理並行處理、避免 GPU 請求互相衝突,甚至可向用戶顯示排隊位置或處理進度。其餘工作,包括文字繪製、圖層合成和匯出,都在瀏覽器中完成。

這帶來哪些新可能

以下是 在 gradio.Server出現前無法實現的功能:

之前 現在
自訂 UI 就得完全離開 Gradio 使用自訂 UI,同時使用 Gradio 後端引擎
Gradio 應用程式無法提供靜態 HTML @app.get("/")可提供任何內容
gradio_client只適用於 Gradio 元件應用程式 @app.api()端點兼容 client
必須在 Gradio 基礎設施和設計自由之間作選擇 兩者兼得

使用 gradio.Server,Gradio 亦可充當後端框架;想用時就使用它的 UI 系統,不想用時就帶上自己的前端。

如果想使用 Gradio UI,可選用 gr.Blocks、gr.Interface或 gr.ChatInterface。如果想自訂 UI,就使用 gradio.Server並帶上喜歡的前端。無論哪種方式,你都能使用 Spaces 託管、API 排隊、gradio_client存取、完整 HF 生態系統等功能。

立即試用

應用程式已在 Spaces 上線:ysharma/text-behind-image

上載一張主體清晰的相片,然後嘗試把文字放在主體後方。試試 3D 擠出、透視傾斜和描邊效果,這些效果配合起來相當不錯。

後續計劃

本文介紹了核心概念:gradio.Server讓你把任何前端與 Gradio 後端配合使用。還有更多功能值得探索,包括註冊 MCP 工具並使用 @app.mcp.tool()、提供即時更新的SSE 串流、批次處理,以及使用共享狀態建構多頁面應用程式的模式。

我們會在後續文章深入探討,敬請留意。

延伸閲讀

來源:Hugging Face Blog · huggingface.co