Gradio Server：將自訂前端與 Gradio 後端整合

Hugging Face 推出了 gradio.Server，這是一個工具，允許開發者使用 React、Svelte 或純 HTML/JS 等框架打造完全自訂的前端，同時利用 Gradio 的後端基礎設施。這使得能夠建立需要超越 Gradio 標準元件的 UI 功能的複雜網路應用程式，而不必犧牲 Gradio 的排隊系統、併發管理，以及與 Hugging Face Spaces ZeroGPU 的整合。

gradio.Server 技術架構

gradio.Server 繼承自 FastAPI，提供完整的 FastAPI 應用功能——包括自訂路由、middleware 與彈性回應類型——同時整合 Gradio 的 API 引擎。這種混合方式讓開發者能同時使用標準 FastAPI 路由（例如 @app.get("/") 用於提供靜態 HTML）與專門的 Gradio API 端點。

@app.api() 的角色

與標準 FastAPI 路由（例如 @app.post()）不同，@app.api() 裝飾器會將函式包裹在 Gradio 的排隊引擎中。這帶來了多項關鍵的技術優勢：

• 併發控制：請求會被序列化，以防止多位使用者同時競爭 GPU 資源，從而避免應用程式崩潰或輸出損壞。
• ZeroGPU 整合：搭配 @spaces.GPU 使用時，GPU 分配會在 Hugging Face Spaces 上自動處理。
• 客戶端相容性：使用 @app.api() 定義的端點與 gradio_client 原生相容，允許其他應用程式或腳本以程式方式呼叫後端。

實作範例：文字置於影像之後

為了展示這些功能，Hugging Face 開發了「Text Behind Image」這個編輯器，可從照片中去除背景，並允許使用者在前景主體與背景之間放置風格化文字。

後端實作

後端以大約 50 行 Python 程式碼實作。它使用 BiRefNet 模型進行影像分割，以產生透明遮罩。remove_background 函式以 @app.api() 裝飾，以確保其被排隊並由 Gradio 引擎管理，同時標準的 FastAPI 路由提供 index.html 前端。

前端實作

前端是一個自包含的純 HTML/CSS/JS 應用程式，具備以下特色：

• 分層渲染：透過 CSS z-index 管理的三層畫布（背景、文字與前景）。
• 豐富控制面板：超過 20 個文字樣式參數，包含 3D 擠出、透視變換與字體管理。
• Gradio JS 客戶端：前端使用 Gradio JS 客戶端與後端通訊。透過此客戶端取代原始的 fetch() 呼叫，應用程式得以保留對 Gradio 排隊的存取，確保併發管理與 GPU 請求不會衝突。

比較：標準 Gradio 與 gradio.Server

gradio.Server 消除了設計自由與基礎設施穩定性之間的取捨。

功能	使用 gradio.Server 前	使用 gradio.Server 後
UI 靈活性	必須離開 Gradio 生態系統才能使用自訂 UI	自訂 UI 可與 Gradio 後端引擎結合
靜態內容	Gradio 應用程式無法原生提供靜態 HTML	@app.get("/") 允許提供任何靜態內容
API 存取	gradio_client 僅限於基於元件的應用程式	@app.api() 端點完全相容於客戶端
基礎設施	必須在 Gradio 基礎設施與設計自由之間做選擇	開發者可同時獲得兩者

未來擴充

除了自訂前端之外，gradio.Server 也提供以下支援：

• MCP 工具註冊：使用 @app.mcp.tool() 進行工具整合。
• SSE 串流：透過 Server-Sent Events 實現即時更新。
• 批次處理：提升大規模請求的處理能力。
• 多頁面應用程式：管理跨多頁面共享狀態的模式。