Hugging Face Spaces 与 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。

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 🚀

发布到 Hugging Face Spaces

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

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

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 页面点 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 和额度。按命令行参考，hf spaces secrets add username/my-space -s HF_TOKEN 会添加一个 secret，hf spaces zero-gpu quota 以 GPU 秒为单位显示你的 ZeroGPU 额度。

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

Lucain Pouget 谈 Space 模板，Lysandre 谈 MCP Space

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

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

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

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 里。

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，从三个点的菜单里选 Duplicate this Space，看看哪些变量已经自动填好。复制和创建 Space 遵循同样的套餐规则，复制出来的 Space 默认是私有的，跑在 CPU Basic 上。

下一门课：微调

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

常见问题

资料来源

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