Gradio Server：将自定义前端与 Gradio 后端集成

Hugging Face 已推出 gradio.Server，这是一款工具，允许开发者使用 React、Svelte 或原生 HTML/JS 等框架构建完全自定义的前端，同时利用 Gradio 的后端基础设施。这使得能够创建需要超出 Gradio 标准组件的 UI 能力的复杂 Web 应用，而不牺牲 Gradio 的排队系统、并发管理以及与 Hugging Face Spaces ZeroGPU 的集成。

gradio.Server 技术架构

gradio.Server 扩展了 FastAPI，提供了完整的 FastAPI 应用功能——包括自定义路由、中间件和灵活的响应类型——同时集成了 Gradio 的 API 引擎。这种混合方式允许开发者在标准 FastAPI 路由（例如用于提供静态 HTML 的 @app.get("/")）与专用的 Gradio API 端点共存。

@app.api() 的作用

与标准 FastAPI 路由（例如 @app.post()）不同，@app.api() 装饰器会将函数包装进 Gradio 的排队引擎。这带来了若干关键的技术优势：

• 并发控制：请求被串行化，以防止多个用户同时竞争 GPU 资源，从而避免应用崩溃或输出损坏。
• ZeroGPU 集成：与 @spaces.GPU 一起使用时，GPU 分配会在 Hugging Face Spaces 上自动处理。
• 客户端兼容性：使用 @app.api() 定义的端点天然兼容 gradio_client，允许其他应用或脚本以编程方式调用后端。

实现示例：Text Behind Image

为了演示这些能力，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 灵活性	需要自定义 UI，且必须离开 Gradio 生态系统	自定义 UI 可与 Gradio 的后端引擎结合使用
静态内容	Gradio 应用无法原生提供静态 HTML	@app.get("/") 允许提供任意静态内容
API 访问	gradio_client 仅限于基于组件的应用	@app.api() 端点完全兼容客户端
基础设施	只能在 Gradio 基础设施和设计自由之间二选一	开发者可同时获得两者

未来扩展

除了自定义前端，gradio.Server 还引入了以下支持：

• MCP 工具注册：使用 @app.mcp.tool() 进行工具集成。
• SSE 流式：通过 Server-Sent Events 实现实时更新。
• 批处理：改进大规模请求的处理。
• 多页应用：管理跨多个页面共享状态的模式。