# Hugging Face Spaces 与 Gradio 教程：做一个演示并托管上线

> Gradio 把一个 Python 函数变成网页，Hugging Face 的 Space 把这个网页放在一个公开地址上。本课先做一个 Gradio 应用，在你的机器上运行，再把文档里的热狗分类器发布到 Space。课程还会讲到需要什么套餐、密钥、休眠，以及共享 GPU 池 ZeroGPU。

Mindket 编辑部 · 发布于 2026-11-05 · 更新于 2026-11-05 · https://mindket.com/cn/learn/hugging-face/gradio-spaces

## 要点

- 先确认你的账号能托管什么，再决定 Space 用哪种方式运行。
- 凭据要私下交给 Space，因为公开应用的源码对所有人开放。
- 应用启动时一次性把模型放到显卡上，每次调用只申请它用得到的 GPU 秒数。
- 只在 README 里有意地修改 Gradio 版本，然后盯着重新构建的结果。

## 开始之前

你需要 Python 3.10 或更高版本、一个 Hugging Face 账号，以及第 2 课装好的 Transformers。**Gradio** 是一个开源 Python 包，能围绕任意 Python 函数搭出一个网页：输入用表单，输出用面板。在虚拟环境里用 `pip install --upgrade gradio` 安装。

**Space** 是 Hub 上一个运行应用的 git 仓库。每推送一次，应用就重新构建并重启。创建时要选它的 **SDK**，也就是它运行哪种应用：Gradio、Docker 或静态 HTML。

开始之前先看看你的套餐。静态 Space 对所有人免费。Gradio 和 Docker Space 要占用计算资源，所以创建时需要付费套餐：个人账号要 PRO，组织要 Team 或 Enterprise。

有一个例外，而且它决定了本课的做法。信誉良好的免费个人账号，可以在共享 GPU 服务 ZeroGPU 上托管最多 2 个 Gradio Space。信誉良好是指邮箱已验证，并且账号注册超过 30 天。

Gradio 的快速入门仍然说 Spaces 可以“免费”托管 Gradio 应用。规则由 Hub 的 Spaces 页面来定，而 2026 年 11 月 5 日它对 ZeroGPU 之外的 Gradio Space 说的正好相反。以 Hub 为准。

## 在你的机器上做一个 Gradio 应用

快速入门的第一个应用会向输入名字的人打招呼。把代码存成 `app.py`，运行 `python app.py`。应用会在 `http://localhost:7860` 打开；最后一行的 `share=True` 还会生成一个以 `gradio.live` 结尾的公开链接。改代码的时候，改用 `gradio app.py` 运行。这是**热重载**模式：每次保存，页面都会重新加载。

`gr.Interface` 类有三个核心参数。`fn` 是要包装的函数。`inputs` 为这个函数的每个参数各放一个**组件**，也就是文本框、图片上传框这类表单元素。`outputs` 为每个返回值各放一个组件，顺序一致。组件可以用 `"textbox"` 这样的字符串指定，也可以创建成 `gr.Textbox()` 这样的对象，Gradio 自带 30 多种组件。

想让别人看一眼演示，分享链接是最快的办法，但有限制。流量经过 Gradio 的分享服务器，它们只把流量转给你的电脑，不保存任何东西。计算都在你的机器上，所以你一停掉应用，链接就失效，而且每个链接一周后都会过期。拿到链接的人都能使用这个应用，所以别让函数接触隐私数据，也别让它做危险的操作。

想只给几个人看，就加一个登录。分享指南的示例把 `auth=("admin", "pass1234")` 传给 `launch()`，也就是一组用户名和密码；传多组的列表也行。

指南说这只是基础的访问控制，没有多因素登录、限流或锁定。它还需要第三方 Cookie，而 Safari 和 Chrome 无痕模式默认会拦截。

分享链接默认关闭，只有 Google Colab 笔记本会自动生成。想让特定的人看到本地应用又不留公开链接，指南建议改用 SSH 端口转发。

另外两个类适合别的形式。`gr.ChatInterface` 类围绕一个回复消息的函数搭出聊天窗口。`gr.Blocks` 类让你自己摆放组件、串联事件，仍然只用 Python。本课只用 `Interface`。

````python
import gradio as gr

def greet(name):
    return "Hello " + name + "!"

demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")

demo.launch(share=True)  # Share your demo with just 1 extra parameter 🚀
````

| 参数 | 接受什么 | 在热狗应用里 |
| --- | --- | --- |
| `fn` | 任意 Python 函数 | `predict`，负责运行分类器 |
| `inputs` | `fn` 的每个参数对应一个组件 | 一个图片框，可以上传图片或用摄像头拍照 |
| `outputs` | 每个返回值对应一个组件，顺序一致 | 先是原图，再是显示前 2 个类别的标签 |
| `examples` | 嵌套列表形式的示例输入，显示在表单下方 | 没有设置 |
| `title`、`description` | 显示在表单上方的文字 | 标题是“Hot Dog? Or Not?” |

## 发布到 Hugging Face Spaces

Spaces 文档用一个热狗分类器做示例，下面就是它发布的原样代码。它用[第 2 课](https://mindket.com/cn/learn/hugging-face/transformers-pipeline)的 Transformers pipeline 加载 `julien-c/hotdog-not-hotdog`，再包进一个 Interface。给它一张图，它会返回这张图，外加两个标签：是热狗或不是，各带一个分数。

文档在 `NimaBoscarino/hotdog-gradio` 保留了这个 Space 的完成版，你可以拿自己的文件对照。因为预装了 `huggingface_hub`，Space 也可以调用第 3 课的推理服务商，而不用自己加载模型。这条路在 Space 里占用的计算更少。

````python
import gradio as gr
from transformers import pipeline

pipeline = pipeline(task="image-classification", model="julien-c/hotdog-not-hotdog")

def predict(input_img):
    predictions = pipeline(input_img)
    return input_img, {p["label"]: p["score"] for p in predictions}

gradio_app = gr.Interface(
    predict,
    inputs=gr.Image(label="Select hot dog candidate", sources=['upload', 'webcam'], type="pil"),
    outputs=[gr.Image(label="Processed Image"), gr.Label(label="Result", num_top_classes=2)],
    title="Hot Dog? Or Not?",
)

if __name__ == "__main__":
    gradio_app.launch()
````

1. 在 [Spaces 页面](https://huggingface.co/spaces)点 **Create new Space**。起一个名字，可以选一个许可证，再选可见性，然后把 SDK 设为 **Gradio**。
2. 添加一个名为 `requirements.txt` 的文件，写两行：`transformers` 和 `torch`。每次构建时 Space 都会安装它们。`gradio`、`huggingface_hub`、`requests`、`datasets` 以及 `ffmpeg` 这类常见 Debian 软件包已经预装好了。缺少的系统软件包，可以写进 `packages.txt` 文件，每行一个，构建时会逐个用 `apt-get install` 安装。
3. 添加 `app.py`，内容就是上面的代码。有了最后两行，同一个文件在你的机器上也能用 `python app.py` 运行。
4. 推送文件。Spaces 都是 git 仓库，所以先用 `hf auth login` 登录，再克隆、提交、推送。也可以在应用文件夹里运行 `gradio deploy`：它会上传文件夹里除 `.gitignore` 所列之外的所有文件，然后启动 Space。
5. 等构建完成，打开 **App** 标签页。上传一张照片，看看它返回的两个标签。
6. 把 Space 的地址分享出去。之后每次推送都会重新构建应用，所以修复会随下一次构建上线。

## 设置、密钥，以及用 ZeroGPU 加上 GPU

Space 的 `README.md` 顶部那段 YAML 负责配置它，就像模型卡的元数据描述模型一样。`sdk` 写的是 `gradio`。`sdk_version` 记录 Gradio 的版本，创建 Space 时会设为最新版，想升级就改它。其他字段还能设置 `python_version`（默认 3.10）、`app_file`、`suggested_hardware` 和 `short_description`。如果应用启动要超过默认的半小时，就调大 `startup_duration_timeout`。

密钥和各种设置都放在 Space 的 **Settings** 里，作为变量或密钥保存，绝不写进 `app.py`。两者都会以环境变量的形式交给你的应用，表格列出了它们的区别。公开 Space 的代码谁都能看，Hub 会扫描 Spaces 里写死的密钥，并提醒所有者。

默认硬件 CPU Basic 提供 2 个 CPU 核心、16GB 内存和 50GB 磁盘，磁盘内容重启后不保留。跑热狗分类器足够了。CPU Basic 的 Space 连续 48 小时没有访客就会休眠，下一位访客会把它唤醒。付费硬件只在 Space 启动中或运行中计费，构建期间不收费，暂停 Space 就停止计费。运行中的 Space 如果开始出错，Hub 会把它挂起，计费也随之停止。

升级后的硬件默认不会休眠。你可以在设置里给它定一个休眠时间，休眠期间不收费。需要 GPU 却负担不起的 Space，可以在同一处休眠设置里申请社区 GPU 资助。

**ZeroGPU** 只在函数需要时才借给 Space 一块 GPU，来自一个由 NVIDIA RTX Pro 6000 Blackwell 显卡组成的共享池。它只支持 Gradio SDK。设置只要三步：在 Space 设置里选 ZeroGPU 硬件，加上 `import spaces`，再在每个需要 GPU 的函数上面加 `@spaces.GPU`。

在 ZeroGPU 之外，这个装饰器什么都不做，所以同一个文件在你的笔记本上照样能跑。

在文件顶部加载模型并把它移到 `cuda`，也就是第 2 课讲的 NVIDIA GPU 途径。真正的 GPU 只在被装饰的函数里才有，但文档说在启动时放好模型才是高效的做法，在函数里再移动模型要慢得多。

每次调用默认有 60 秒 GPU 时间。任务更长时，像下面的代码片段那样设定时长。时长设得越短，排队的位置越靠前。时长也可以是一个函数，接收同样的输入并返回秒数，这样步数多的任务就能申请更多时间。

装饰器默认申请 `large` 规格，也就是半块显卡、48GB 显存。传入 `size="xlarge"` 可以拿到整块显卡和 96GB 显存，但额度消耗翻倍，通常也要等更久。

ZeroGPU 支持 Gradio 4 及以上版本，以及 2.8.0 起的 PyTorch。

每位访客消耗的是自己每天的 GPU 额度，见图表，额度在他第一次使用 GPU 的 24 小时后重置。访客剩余的额度也决定了他在队列里的位置。ZeroGPU 不支持 `torch.compile`，文档建议改用提前编译。PRO 账号可以托管的 ZeroGPU Space 上限提高到 10 个。

第 1 课的 `hf` 命令行在终端里也能管理 secret 和额度。按[命令行参考](https://huggingface.co/docs/huggingface_hub/package_reference/cli)，`hf spaces secrets add username/my-space -s HF_TOKEN` 会添加一个 secret，`hf spaces zero-gpu quota` 以 GPU 秒为单位显示你的 ZeroGPU 额度。

````python
@spaces.GPU(duration=120)
def generate(prompt):
   return pipe(prompt).images
````

| 问题 | 变量 | 密钥 |
| --- | --- | --- |
| 用来存什么 | 不敏感的设置，比如模型 id | 访问令牌、API 密钥和密码 |
| 谁能看到值 | 所有人，它是公开的 | 谁都看不到，保存后设置页面也会把它隐藏 |
| 别人复制这个 Space 时会不会带过去 | 会，自动帮对方填好 | 不会，对方要自己添加 |
| 应用怎样读取 | 作为环境变量，比如用 `os.getenv` | 方式一样 |

**不同账号每天的 ZeroGPU 时间** 访客每天在所有 ZeroGPU Space 上可用的 GPU 分钟数。PRO、Team 和 Enterprise 的额度可以扩展。

- 未登录: 2分钟
- 免费账号: 5分钟
- PRO 账号: **40分钟**
- Team 成员: 40分钟
- Enterprise 成员: 60分钟

来源：[Hugging Face Hub: Spaces ZeroGPU](https://huggingface.co/docs/hub/spaces-zerogpu) (2026-11-05 查阅)

## Lucain Pouget 谈 Space 模板，Lysandre 谈 MCP Space

`huggingface_hub` 的维护者 Lucain Pouget 在 2026 年 7 月[在 X 上](https://x.com/Wauplin/status/2075242347760107797)介绍，1.23.0 版可以用一条命令从官方模板建出完整的 Space，比如 JupyterLab 或 Gradio 聊天机器人。[命令行参考](https://huggingface.co/docs/huggingface_hub/package_reference/cli)里的写法是 `hf repos create my-jupyterlab --type space --template SpacesExamples/jupyterlab`，`hf spaces templates` 会列出其他模板。想做聊天演示，就从 Gradio 聊天机器人模板起步，再换上你自己的函数。

Lysandre 是 Hugging Face 的首席开源官。他在 2025 年 6 月[在 X 上](https://x.com/LysandreJik/status/1931022549221056981)说，任何 MCP Space 都能通过 `hf.co/mcp` 选中，再拿到 MCP 客户端里用。他当时数到大约 900 个，涵盖图像、视频、音频和代码。

现在按 [HF MCP 服务器页面](https://huggingface.co/docs/hub/hf-mcp-server)的说明，在 [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp) 里添加它们，再重启客户端。Spaces 页面上的 **mcp-server** 筛选会列出提供 MCP 的 Space，自己动手做之前可以先试几个。

> 最快建出一个完整 Space 的办法。
>
> Lucain Pouget, huggingface_hub 维护者，引文为译文, [X](https://x.com/Wauplin/status/2075242347760107797) (2026-11-05 查阅)

[![Lucain Pouget（@Wauplin）2026 年 7 月 9 日在 X 上发帖：最快建出一个完整 Space 的办法。huggingface_hub v1.23.0 可以用一条命令从官方模板创建 Space，比如 JupyterLab 或 Gradio 聊天机器人：hf repos create my-lab --template jupyterlab。用 hf spaces templates 查看有哪些模板](https://mindket.com/blog/shots/x-wauplin-space-templates.webp?v=41dca60620f7)](https://x.com/Wauplin/status/2075242347760107797)

Lucain Pouget 在 X 上，2026 年 7 月 9 日

[![Lysandre（@LysandreJik）2025 年 6 月 6 日在 X 上发帖：现在可以通过 hf.co/mcp 选中任何 MCP Space，在 MCP 客户端里使用。我已经看到大约 900 个 MCP Space，有图像（flux）、视频（ltx）、音频、代码等等](https://mindket.com/blog/shots/x-lysandrejik-mcp-spaces.webp?v=5b7db37b2f3d)](https://x.com/LysandreJik/status/1931022549221056981)

Lysandre 在 X 上，2025 年 6 月 6 日

> X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。点击截图可到 X 上打开原帖。

## 常见错误

- 把令牌写进 `app.py`。在公开 Space 里谁都能读这个文件，所以要把令牌存成密钥。
- 忘了 `requirements.txt`。构建时就没有 `transformers` 和 `torch`，应用在第一个 import 处就会停下。
- 习惯性地申请 `xlarge` 规格的 GPU。它消耗的每日额度是默认 `large` 的两倍，只在需要整块显卡的任务上用。
- 在非常用端口上调用外部服务。Space 只能通过 80、443 和 8080 端口向外发请求。
- 以为付费 GPU 不用任何改动就能用。大多数 Space 确实可以，但有些需要在 `requirements.txt` 里装框架的 CUDA 版本，所以升级后要看看 Space 的日志。
- 没在本地跑过就直接推到 ZeroGPU。装饰器在你的机器上不起作用，所以先用 `gradio app.py` 检查页面，确认能用再推送。
- README 里的 `short_description` 留空。Space 的缩略图显示的就是这一行，人们打开演示之前读到的也是它。

## 自己试一试

下面两行来自 Spaces 概览，用来读取一个变量。先在 **Settings** 里创建这个变量，再把这两行加到 Space 的 `app.py` 里。

````python
import os
print(os.getenv('MODEL_REPO_ID'))
````

- 添加一个名为 `MODEL_REPO_ID` 的变量，值设为 `julien-c/hotdog-not-hotdog`。打印出来的值会出现在哪里？
- 把 pipeline 那一行改成从这个变量读取模型 id。别人复制你的 Space 后，能不能不改代码就换一个模型？
- 给 Interface 加上 `examples=`，放两张你提交到仓库里的图片。表单下方出现了什么？
- 在本地用 `gradio app.py` 运行应用，改一下标题再保存。打开的页面会自己更新吗？
- 打开一个你喜欢的[公开 Space](https://huggingface.co/spaces)，从三个点的菜单里选 **Duplicate this Space**，看看哪些变量已经自动填好。复制和创建 Space 遵循同样的套餐规则，复制出来的 Space 默认是私有的，跑在 CPU Basic 上。

## 下一门课：微调

到这里整个流程就闭合了：找到模型，运行它，调用更大的模型，再把演示摆到大家面前。下一门是微调课程。它的第一课[什么时候该微调](https://mindket.com/cn/learn/fine-tuning/when-to-fine-tune)讲清用自己的数据训练模型，什么时候比改提示词或用 RAG 更好，整门课最后会把你的模型放到 Hub 上。再往后是 MCP 课程。Gradio 自己也有捷径：在 `launch()` 里设置 `mcp_server=True`，应用的函数就会变成 MCP 工具，[用 Python 构建 MCP 服务器](https://mindket.com/cn/learn/mcp/build-mcp-server-python)讲了这类工具怎样工作。Space 让人们看到你的模型，MCP 服务器则让他们的助手用上你的代码。

## 自测一下

1. 个人账号要有哪种套餐，才能在 CPU 硬件上创建 Gradio Space？

   A. 免费账号就行
   B. PRO
   C. 任何邮箱已验证的账号
   D. 不需要，Gradio Space 一律免费

   答案：B。 个人账号创建 Gradio 和 Docker Space 需要 PRO，信誉良好的免费账号只能在 ZeroGPU 上托管最多 2 个。

2. Space 用到的 API 密钥应该放在哪里？

   A. 写在 app.py 里
   B. 写在 requirements.txt 里
   C. 存成 Space 的密钥，作为环境变量读取
   D. 写在 README 的 YAML 里

   答案：C。 密钥保持私有，别人复制 Space 时不会带走，并以环境变量的形式交给应用。

3. 在 ZeroGPU 上，应该在哪里把模型移到 cuda？

   A. 在文件顶部，应用启动时
   B. 在每个 @spaces.GPU 函数里面
   C. 在 requirements.txt 里
   D. 不用移，ZeroGPU 在 CPU 上运行

   答案：A。 文档要求在模块顶层把模型放到 cuda，在被装饰的函数里移动要低效得多。

4. Gradio 的分享链接能用多久？

   A. 一小时
   B. 24 小时
   C. 直到你删除 Space
   D. 最多一周，而且只在你的电脑运行应用时有效

   答案：D。 分享链接一周后过期，而且计算在你自己的机器上，应用一停，链接就失效。

## 常见问题

### 能把 Space 的代码设为私有吗？

可以。私有 Space 会把代码和应用都藏起来，只有你和协作者能看到。受保护的 Space 隐藏代码，但应用仍然在它的 hf.space 地址上公开，这需要 PRO、Team 或 Enterprise 套餐。

### 能用 Docker 或纯 HTML 代替 Gradio 吗？

可以，创建 Space 时这两种都是 SDK 选项。Docker Space 能运行任何可以装进容器的应用，付费规则和 Gradio 一样。静态 Space 提供 HTML、CSS 和 JavaScript，不收费。

### 怎样在自己的代码里调用我的 Space？

通过应用页脚的“Use via API”链接。几乎任何 Gradio 应用都能当作 API 使用，那个页面列出它的接口、参数和示例输入。请求由 Gradio 的 Python 客户端或 JavaScript 客户端发送。

### 能把 Space 嵌入我自己的网站吗？

可以。Gradio Space 可以用 Web Components 或 HTML iframe 嵌入。公开和受保护的 Space 还有自己的 hf.space 地址，可以直接链接过去。

## 资料来源

- [Gradio: Quickstart](https://www.gradio.app/guides/quickstart) (2026-11-05 查阅)
- [Gradio: The Interface class](https://www.gradio.app/guides/the-interface-class) (2026-11-05 查阅)
- [Gradio: Sharing your app](https://www.gradio.app/guides/sharing-your-app) (2026-11-05 查阅)
- [Hugging Face Hub: Spaces overview](https://huggingface.co/docs/hub/spaces-overview) (2026-11-05 查阅)
- [Hugging Face Hub: Gradio Spaces](https://huggingface.co/docs/hub/spaces-sdks-gradio) (2026-11-05 查阅)
- [Hugging Face Hub: Handling Spaces dependencies](https://huggingface.co/docs/hub/spaces-dependencies) (2026-11-05 查阅)
- [Hugging Face Hub: Spaces configuration reference](https://huggingface.co/docs/hub/spaces-config-reference) (2026-11-05 查阅)
- [Hugging Face Hub: Using GPU Spaces](https://huggingface.co/docs/hub/spaces-gpus) (2026-11-05 查阅)
- [Hugging Face Hub: Spaces ZeroGPU](https://huggingface.co/docs/hub/spaces-zerogpu) (2026-11-05 查阅)
- [huggingface_hub: CLI reference](https://huggingface.co/docs/huggingface_hub/package_reference/cli) (2026-11-05 查阅)
- [Hugging Face Hub: HF MCP Server](https://huggingface.co/docs/hub/hf-mcp-server) (2026-11-05 查阅)
- [Lucain Pouget on X: create a Space from a template in huggingface_hub v1.23.0](https://x.com/Wauplin/status/2075242347760107797) (2026-11-05 查阅)
- [Lysandre on X: MCP Spaces through hf.co/mcp](https://x.com/LysandreJik/status/1931022549221056981) (2026-11-05 查阅)

[浏览 MCP 服务器](https://mindket.com/cn/mcp-servers)