使用 Gradio 後端構建任何自定義前端

gradio.Server：使用 Gradio 後端搭配任何自訂前端

如果您想完全使用自己的前端框架（如 React、Svelte，甚至是純 HTML/JS）來構建應用，同時仍想受益於 Gradio 的隊列系統、API 基礎設施、MCP 支援以及 Spaces 上的 ZeroGPU，該怎麼辦？

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

我們想構建什麼

「文字在圖像後方」（Text Behind Image）：這是一個編輯器，您可以上傳照片，使用機器學習模型移除背景，然後在前景主體和背景之間放置風格化的文字。文字看起來就像是位於圖像中的人物或物體後方。

這需要：

目前無法在 Gradio 組件中表達這種 UI。這是一個完整的 Web 應用程式。但我們仍然想要 Gradio 的後端能力：隊列、併發管理、ZeroGPU 支援，以及在 HF Spaces 上託管而無需擔心基礎設施問題。

進入 gradio.Server

gradio.Server 擴展了 FastAPI。它賦予您 FastAPI 的完整功能（自訂路由、中間件、檔案上傳、任何回應類型），同時在其之上添加了 Gradio 的 API 引擎：隊列、SSE 串流、併發控制以及 gradio_client 相容性。

以下是「文字在圖像後方」的完整後端代碼：

就這樣。大約 50 行 Python 代碼。模型在啟動時加載，@spaces.GPU 處理 ZeroGPU 分配，而 gradio.Server 管理隊列和併發。讓我們分解一下發生了什麼。

為什麼使用 @app.api() 而不是普通的 FastAPI 路由？

如果這是一個普通的 FastAPI 應用，您會為背景移除定義一個 @app.post() 路由。這在只有一個用戶時可行，但當兩個用戶同時訪問時，如果沒有併發管理，兩個請求會爭奪 GPU，導致應用崩潰或返回錯誤結果。

@app.api() 解決了這個問題。它用 Gradio 的隊列引擎封裝了您的函數：請求被序列化，併發得到控制，並且在 ZeroGPU Spaces 上，GPU 分配會透過 @spaces.GPU 自動處理。作為額外獎勵，任何 @app.api() 端點也可以透過 gradio_client 調用，因此其他應用或腳本可以透過程式化方式使用您的 Space：

同時，@app.get("/") 是一個標準的 FastAPI 路由，用於提供 HTML 頁面。兩者自然共存，因為 Server 本身就是一個 FastAPI 應用。

前端：純 HTML/CSS/JS

本例中的 index.html 是一個約 1300 行的獨立 Web 應用程式。沒有 React，沒有構建步驟，沒有打包工具。只是純粹的 HTML，包含：

前端使用 Gradio JS Client 與後端通訊：

這是關鍵部分：透過使用 Gradio JS 客戶端而不是原始的 fetch() 調用，前端會經過 Gradio 的隊列。這意味著併發得到了管理，GPU 請求不會衝突，您甚至可以向用戶顯示隊列位置或進度。其他一切（文字渲染、圖層合成、導出）都在瀏覽器中完成。

這開啟了什麼可能性

以下是 gradio.Server 出現之前無法實現的事情：

有了 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 的後端配對。還有更多值得探索的地方，包括使用 @app.mcp.tool() 進行 MCP 工具註冊、用於實時更新的 SSE 串流、批次處理，以及構建具有共享狀態的多頁面應用的模式。

我們將在後續文章中深入探討這些內容。敬請期待。