深入 Gradio Server Mode用 FastAPI 后端引擎驱动完全自定义的前端【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio导读gradio.ServerServer Mode是 Gradio 为只要后端、不要默认 UI的场景提供的官方方案直接实例化一个内置了 Gradio API 引擎的 FastAPI 应用从而在保留排队queue、SSE 流式输出、MCP 工具、ZeroGPU 与 Hugging Face Spaces 托管等全部后端能力的同时自由选择或不选择任何前端——无论是 React 应用、纯 HTML 页面还是 vibe-coded 前端。读完本文你将掌握Server的适用场景、最小可运行示例、自定义 FastAPI 路由、MCP 工具暴露方式以及并发与流式输出的精确控制。本指南正文源文件为 guides/09_gradio-clients-and-lite/08_server-mode.md可运行的完整示例位于 demo/server_app/run.py核心实现位于 gradio/server.py。什么是gradio.ServerFastAPI 外壳 Gradio API 引擎传统上gr.Blocks、gr.ChatInterface或gr.Interface会同时生成 Gradio 自带的前端组件与后端 API。而 Server Mode 的思路完全不同gradio.Server本身就是一个FastAPI 应用它继承自gradio.routes.App进而继承 FastAPI 的App内置了 Gradio 的 API 引擎。这意味着你得到的是一个带排队和SSE 流式输出的 Gradio API 端点默认位于/gradio_api/call/endpoint_name自动生成的 API 文档/gradio_api/info以及继承 FastAPI 的/docs、/openapi.json可直接用名称调用的 Python / JavaScript 客户端与普通 Gradio 应用完全一致的后端能力队列、MCP 工具、ZeroGPU、Hugging Face Spaces 托管。从源码上看Server在 FastAPI 之上只新增了三样东西见 gradio/server.py 的类文档字符串与属性定义api()装饰器注册走队列与 SSE 的 Gradio API 端点、mcp命名空间.tool()/.resource()/.prompt()装饰器见 gradio/server.py、以及launch()在内部创建一个Blocks(modeserver)把所有延迟注册的 API 端点挂载后启动服务见 gradio/server.py。注意仓库中另有 gradio/http_server.py 里的class Server(uvicorn.Server)那是 uvicorn 的 HTTP 服务器封装与本文的 API 层gradio.Server不是同一个概念阅读源码时不要混淆。何时该用gradio.Server何时继续用gr.Blocks官方指南明确给出了判断标准。当以下情况任意一条成立时应该用gradio.Server替代gr.Blocks你想要一个完全自定义的前端 UI自己的 HTML、React、Svelte 等甚至 vibe-coded但由 Gradio 后端驱动你需要完整的 FastAPI 控制能力——自定义 GET/POST 路由、中间件、依赖注入与 Gradio 的 API 端点共存你要构建一个托管在 Spaces 上的服务带或不带 ZeroGPU但并不需要 Gradio 自带组件。反过来如果你对 Gradio 内置 UI 组件满意就继续使用gr.Blocks、gr.ChatInterface或gr.Interface不必引入 Server Mode 的复杂度。安装gradio.Server包含在 Gradio 主包中无需额外安装。只有当需要使用 MCP 支持时才需要安装额外依赖pip install gradio[mcp]在仓库中MCP 相关实现位于 gradio/mcp.py其依赖项如mcp库由gradio[mcp]这个 extra 引入对应 requirements-mcp.txt。最小示例单端点、零 UI最简单的 Server Mode 应用就是一个 API 端点加一次启动调用from gradio import Server app Server() app.api(namehello) def hello(name: str) - str: return fHello, {name}! app.launch()运行这段脚本后你立刻获得位于/gradio_api/call/hello的 Gradio API 端点带排队与 SSE 流式输出自动生成的 API 文档/gradio_api/info可直接按名称/hello调用的 Python 与 JavaScript 客户端。用 Gradio Python 客户端即可测试from gradio_client import Client client Client(http://localhost:7860) result client.predict(World, api_name/hello) print(result) # Hello, World!类型注解不是装饰api()的契约从类型推导Server.api()的实现细节gradio/server.py与gradio.events.api即gr.api()gradio/events.py完全同源它会把被装饰函数注册到内部 Blocks 的延迟列表_deferred_apis中等到launch()时才真正挂载。关键约束是API 函数的每个参数都必须有类型注解。源码在 gradio/events.py 中明确校验if any(param[3] is None for param in fn_params): raise ValueError( API endpoints must have type hints. Please specify a type hint for all parameters. )因为api()的输入输出 schema 完全由函数签名的类型推导而来通过python_type_to_json_schema把 Python 类型转为 JSON Schema而不是像传统组件那样由组件配置决定。相应地app.api()也继承了gr.api()的全部行为参数name、description、queue、batch、max_batch_size、concurrency_limit、concurrency_id、api_visibility、time_limit、stream_every见 gradio/server.py具体语义下文会展开。自定义路由FastAPI 的全部能力任你使用由于gradio.Server就是 FastAPI 应用你可以直接添加任意路由。需要明确一点你的自定义路由优先于 Gradio 默认路由——例如GET /会替换 Gradio 的默认 UI 页面。from gradio import Server from fastapi.responses import HTMLResponse app Server() app.api(namehello) def hello(name: str) - str: return fHello, {name}! app.get(/, response_classHTMLResponse) async def homepage(): return h1Welcome to my API/h1 app.get(/health) async def health(): return {status: ok} app.launch()除此之外所有标准 FastAPI 特性在Server实例上同样可用包括app.add_middleware()、app.include_router()、依赖注入、异常处理器等。FastAPI 提供的文档元数据参数在Server()构造函数里也全部开放例如titleOpenAPI 文档标题默认FastAPI、version、summary、description、openapi_url默认/openapi.json、docs_url默认/docs可设None关闭、lifespan、root_path等详见 gradio/server.py 的参数列表。注意 Server 的launch()签名与Blocks.launch()保持一致gradio/server.py因而支持server_name、server_port、share、auth、ssl_keyfile/ssl_certfile、allowed_paths、blocked_paths、max_file_size等全套参数返回(fastapi_app, local_url, share_url)三元组。MCP 工具一个装饰器暴露给 MCP 客户端要把 API 端点同时暴露为 MCP 工具只需要叠加app.mcp.tool()装饰器并在launch()时传入mcp_serverTruefrom gradio import Server app Server() app.mcp.tool(namehello) app.api(namehello) def hello(name: str) - str: Greet someone by name. return fHello, {name}! app.launch(mcp_serverTrue)app.mcp.tool()与app.api()是相互独立的装饰器——你可以只做 API-only 端点也可以只做 MCP-only 工具两者叠加时该函数就同时可以通过 HTTP API 和 MCP 协议被调用。MCP 命名空间还额外提供了app.mcp.resource()与app.mcp.prompt()装饰器见 gradio/server.py分别用于注册 MCP 资源和提示词模板。完整示例自绘 HTML JS 客户端 REST MCP文档中的$code_server_app对应仓库内可直接运行的完整示例 demo/server_app/run.py它把上述所有能力串在一起python run.py运行后在浏览器打开http://localhost:7860。核心代码结构如下from gradio import Server from fastapi.responses import HTMLResponse app Server() app.mcp.tool(nameadd) app.api(nameadd) def add(a: int, b: int) - int: Add two numbers together. return a b app.mcp.tool(namemultiply) app.api(namemultiply) def multiply(a: int, b: int) - int: Multiply two numbers together. return a * b app.get(/, response_classHTMLResponse) async def homepage(): # 一个自带 script typemodule 的纯 HTML 计算器页面 ... if __name__ __main__: app.launch(mcp_serverTrue)这个页面里自定义 HTML 通过 CDN 引入的gradio/clientJavaScript 库调用两个 Gradia API 端点script typemodule import { client } from https://cdn.jsdelivr.net/npm/gradio/client/dist/index.min.js; const app await client(location.origin); window.run async (ep) { const a parseInt(document.getElementById(a).value), b parseInt(document.getElementById(b).value); document.getElementById(out).textContent (await app.predict(/ ep, { a, b })).data; }; /script同一批端点同时可用三种方式访问REST API/gradio_api/call/add、/gradio_api/call/multiply用 curl 或其他 HTTP 客户端即可调用MCP 工具由mcp_serverTrue启动的 MCP 服务实现细节见 gradio/mcp.py浏览器内 JS 客户端由首页 HTML 调用。关于 JavaScript 客户端的完整使用方式可参考同一章节下的 guides/09_gradio-clients-and-lite/02_getting-started-with-the-js-client.md。ZeroGPU 的重要提示如果你的 Server 应用使用ZeroGPU那么必须通过gradio/client从浏览器调用 Gradio API 端点——因为 JavaScript 客户端会转发 Hugging Face iframe 的认证头auth headers这是 ZeroGPU 配额处理的依赖条件。若绕过浏览器直接从后端发起请求将无法正确处理 ZeroGPU 的配额逻辑。并发与流式app.api()与gr.api()同源参数app.api()支持与gr.api()完全一致的并发与流式选项app.api(namegenerate, concurrency_limit2, stream_every0.5) async def generate(prompt: str): for token in model.generate(prompt): yield token生成器generator函数的结果会自动通过 SSE 流式输出与普通 Gradio 应用里的流式行为一致服务端的路由与事件推送实现位于 gradio/routes.py其中/gradio_api/call/...端点格式与流式返回结构都能在 gradio/routes.py 附近找到对应实现。下面对api()的核心参数做一份完整的速查依据 gradio/events.py 的官方参数文档整理参数默认值作用api_nameNone端点在 API 文档中的名称为None时使用函数名。客户端调用时需带前导/如api_name/hellodescription/api_descriptionNone端点描述为None时取函数 docstring为False则不显示concurrency_limitdefault同一端点可同时运行的最大调用数。None表示不限制default表示使用默认并发上限由Blocks.queue()的default_concurrency_limit决定其本身默认为 1concurrency_idNone并发组 id共享同一concurrency_id的事件共用最低设置的并发上限queueTrue是否进入队列False表示即使队列开启也不排队None表示跟随应用设置batchFalse为True时函数应处理一批输入每个参数接收一个等长列表最长max_batch_size并必须返回各输出分量对应的列表元组max_batch_size4仅batchTrue时生效单次最多合并的输入数api_visibilitypublicpublic文档可见、客户端可调、private隐藏且 Gradio 客户端不可调、undocumented文档隐藏但可调stream_every0.5流式场景下 chunk 发送的间隔秒time_limitNone函数运行的时限主要供.stream()事件使用关于concurrency_limit的默认值需要特别强调默认是1因为许多跑在 GPU 上的 ML 负载同一时刻只能服务一个用户。但如果你调用的是外部 API如 LLM 服务可以放心提高上限或设为None采用 FastAPI 的默认无限制行为。从源码结构看app.api()在launch()前只是把(fn, kwargs)追加进_deferred_apisgradio/server.py直到launch()才在Blocks(modeserver)上下文中统一调用gr_api(fnfn, **api_kwargs)gradio/server.py。这带来一个实用推论端点函数可以在app.launch()之前任意时刻注册装饰器之间互不干扰可以像上文那样按需叠加 MCP 装饰器。注册后启动过程会设置环境变量GRADIO_SERVER_MODE_ENABLED1gradio/server.py供路由层识别当前运行在 Server Mode。小结Server Mode 的最佳实践清单选型需要完全自定义前端HTML/React/Svelte 或 vibe-coded UI、需要完整 FastAPI 控制、或要在 Spaces 上托管无组件服务时选择gradio.Server否则保持gr.Blocks/gr.Interface即可。类型必填app.api()注册的函数所有参数必须带类型注解端点的输入输出 schema 由类型直接推导。路由优先级自定义路由如GET /会覆盖 Gradio 默认路由中间件、依赖注入、异常处理器等 FastAPI 特性全部可用。MCP安装gradio[mcp]用app.mcp.tool()可叠加app.api()并以mcp_serverTrue启动。并发与流式生成器天然 SSE 流式输出GPU 负载保持concurrency_limit1默认外部 API 场景可上调或设None。ZeroGPU务必经由gradio/client从浏览器调用 API以携带 ZeroGPU 配额所需的 Hugging Face iframe 认证头。若想进一步查阅Server的 API 细节可直接阅读仓库中的实现与文档字符串gradio/server.py其 Docstring 中标注的官方演示为server_app即 demo/server_app/run.py对应指南正是本文件。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考