Skip to main content

Spaces 概览

Hugging Face Spaces 让你可以在几分钟内创建并部署由机器学习驱动的 Demo 应用。你可以先观看下面这个视频，快速了解 Spaces 的基础用法：

在接下来的内容中，你会依次学到：如何创建一个 Space、如何进行配置，以及如何把自己的代码部署到 Space 中。

创建一个新的 Space​

要创建一个新的 Space，先访问 Spaces 主页面，然后点击 Create new Space。在这个过程中，你需要为 Space 选择一个名称、可选地指定许可证、设置 Space 的可见性，同时还会被要求选择该 Space 使用的 SDK。Hub 当前提供三种 SDK 选项：Gradio、Docker 和静态 HTML。如果你选择了 “Gradio” 作为 SDK，系统会为你创建一个新的仓库，并展示如下页面：

Spaces 空白空间页面Spaces 空白空间页面

在底层实现上，Spaces 会像模型仓库和数据集仓库一样，把你的代码存储在一个 Git 仓库中。正因为如此，我们在 Hub 上管理 其它类型仓库 时使用的那些工具（git 和 git-lfs），同样也适用于 Spaces。你可以参考 Getting Started with Repositories 中的流程，将文件添加到你的 Space。每当你向仓库推送新的 commit 时，这个 Space 都会自动重新构建并重启。

如果你希望通过一步一步的教程来创建自己的第一个 Space，可以参考下面这些指南：

硬件资源​

默认情况下，每个 Spaces 运行环境都可以免费使用最多 16GB 内存、2 个 CPU 核心以及 50GB（非持久化）的磁盘空间。如果你需要更强的硬件资源，包括多种 GPU 加速卡以及持久化存储，可以以一个具有竞争力的价格进行升级。要发起升级请求，只需要在 Space 中点击 Settings 按钮，然后选择你想要的硬件环境即可。

硬件类型GPU 显存CPU内存磁盘每小时价格
CPU Basic-2 vCPU16 GB50 GBFree!
CPU Upgrade-8 vCPU32 GB50 GB$0.03
Nvidia T4 - small16GB4 vCPU15 GB50 GB$0.60
Nvidia T4 - medium16GB8 vCPU30 GB100 GB$0.90
Nvidia A10G - small24GB4 vCPU15 GB110 GB$1.05
Nvidia A10G - large24GB12 vCPU46 GB200 GB$3.15
2x Nvidia A10G - large48GB24 vCPU92 GB1000 GB$5.70
4x Nvidia A10G - large96GB48 vCPU184 GB2000 GB$10.80
Nvidia A100 - large40GB12 vCPU142 GB1000 GB$4.13
存储档位容量是否持久化按月价格
Ephemeral (default)50GBNoFree!
SmallEphemeral + 20GBYes$5
MediumEphemeral + 150GBYes$25
LargeEphemeral + 1TByes$100

注意：更完整、最新的价格信息，请参考 定价页面。

如果你已经有一个非常优秀的 Space，但暂时无力承担硬件升级的费用，我们也非常乐意支持有创新想法的项目。你可以在 Space 的 Settings 标签页中找到申请社区 GPU 资助（community GPU grant）的入口，提交申请，看一看你的 Space 是否能入选。

关于硬件升级和存储升级，可以参考专门的小节：Spaces GPU 升级 和 Spaces 存储升级。

Spaces GPU SettingsSpaces GPU Settings

管理 Secrets 和环境变量​

如果你的应用需要使用环境变量（例如密钥或访问令牌），千万不要把这些值直接写死在应用代码里！正确的做法是：进入该 Space 仓库的 Settings 页面，在其中添加新的 variable 或 secret。一般来说：

  • 需要存储非敏感的配置类信息时，可以使用 variables。
  • 需要存储访问令牌、API key 或其它敏感凭据时，应当使用 secrets。
Secrets and VariablesSecrets and Variables

你可以按下面的方式来理解和使用它们：

  • Variables：适合存储非敏感的配置值。它们是公开可见的，并且当别人在 Hub 上复制你的 Space 时，这些 variables 会自动一并复制过去。
  • Secrets：适合存储访问令牌、API key 或任何敏感的凭据。它们是私有的，一旦设置之后，就无法在 Space 的设置页面中查看其值；同时，当别人复制你的 Space 仓库时，这些 secrets 也不会被自动带过去。

根据 Space 所使用的 SDK 不同，访问 secrets 和 variables 的方式也有所差异：

  • 对于 Static Spaces，可以在客户端 JavaScript 中通过 window.huggingface.variables 访问它们。
  • 对于 Docker Spaces，可以参考文档 environment management with Docker。

对于其它类型的 Spaces，这两类信息都会以环境变量的形式暴露给你的应用。下面是一个非常简单的 Python 示例，展示如何访问前面已经声明好的 MODEL_REPO_ID 变量（对于 secrets 也是同样的用法）：

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

当我们的 Spaces Secrets Scanner 检测到硬编码的敏感信息 时，Space 的拥有者会收到告警。

复制一个 Space​

当你希望基于现有 Demo 作为模板，快速搭建一个新的 Demo 时，复制（Duplicate）一个 Space 会非常方便。如果你想拥有一个只属于自己的、已升级硬件的 Space 来做快速推理，复制也是一个常见做法。

如果你想复制某个 Space，可以点击 Space 页面右上角的三个点，然后选择 Duplicate this Space。在发起复制之后，你可以修改以下属性：

  • Owner：复制出来的 Space 可以归属于你的个人账号，也可以归属于你拥有写权限的任意组织。
  • Space name：新 Space 的名称。
  • Visibility：新 Space 默认是私有的。关于私有仓库的更多说明，可以查看这里。
  • Hardware：你可以选择新 Space 运行时使用的硬件配置。关于硬件升级的详细说明，见这里。
  • Storage：如果原始仓库使用了持久化存储，复制流程会提示你选择存储档位。关于持久化存储，可以查看这里。
  • Secrets 和 variables：如果原始仓库配置了一些 secrets 和 variables，在复制仓库的过程中你也可以为它们设置新值。

有些 Spaces 可能依赖特定的环境变量，这些变量也需要在新 Space 中重新配置。在这种情况下，复制流程会自动从源 Space 中带入公开的 Variables，并对需要配置的 Secrets 给出提示。复制出来的 Space 默认会使用免费的 CPU 硬件，如果有需要，你可以后续再进行升级。

网络访问​

如果你的 Space 需要发起网络请求，它可以使用标准的 HTTP 与 HTTPS 端口（80 和 443），以及端口 8080。发往其它端口的请求都会被阻止。

生命周期管理​

在使用免费硬件时，如果 Space 在一段时间内没有被访问，它会自动“休眠”，也就是停止运行。如果你希望 Space 一直保持运行状态，可以考虑升级到付费硬件。你也可以在 Settings 标签页中手动暂停一个 Space，被暂停的 Space 会停止执行，直到它的拥有者手动重新启动。 被暂停的时间不会计入费用。

辅助环境变量​

有时你可能希望在代码里以编程方式获取 Space 的作者或仓库名称等信息，尤其是在你期望别人复制你的 Space 时，这会非常有用。为此，Spaces 在运行时会暴露出一组辅助环境变量。以 Space osanseviero/i-like-flan 为例：

  • CPU_CORES: 4
  • MEMORY: 15Gi
  • SPACE_AUTHOR_NAME: osanseviero
  • SPACE_REPO_NAME: i-like-flan
  • SPACE_TITLE: I Like Flan（在 README 文件中指定的标题）
  • SPACE_ID: osanseviero/i-like-flan
  • SPACE_HOST: osanseviero-i-like-flan.hf.space
  • SPACE_CREATOR_USER_ID: 6032802e1f993496bc14d9e3 —— 这是最初创建该 Space 的用户 ID，尤其在 Space 归属于某个组织时，这个信息非常有用。你可以通过调用 https://huggingface.co/api/users/{SPACE_CREATOR_USER_ID}/overview API 获取该用户的详细信息。

如果你的 Space 启用了 OAuth，还会额外提供下面这些环境变量：

  • OAUTH_CLIENT_ID：你的 OAuth 应用的 client ID（公开信息）。
  • OAUTH_CLIENT_SECRET：你的 OAuth 应用的 client secret。
  • OAUTH_SCOPES：你的 OAuth 应用可以访问的 scope。目前这里总是 "openid profile"。
  • OPENID_PROVIDER_URL：OpenID 提供方的 URL。该提供方的元数据可以通过 {OPENID_PROVIDER_URL}/.well-known/openid-configuration 获取。

克隆仓库​

你可以非常方便地把 Space 仓库克隆到本地。首先，在 Space 页面右上角点击下拉菜单：

Spaces Clone RepositorySpaces Clone Repository

选择 “Clone repository”，然后根据提示，使用 HTTPS 或 SSH 将 Space 仓库克隆到本地。

Https Clone RepositoryHttps Clone Repository
SSH Clone RepositorySSH Clone Repository

在 Hub 上关联模型和数据集​

你可以在 Space 的 README 元数据中添加模型和数据集的标识符，从而在页面上展示该 Space 所关联的所有模型和数据集。具体来说，可以在元数据中的 models 和 datasets 字段下进行配置。除了在 README 文件中列出这些 artefacts，你也可以在任意 .py、.ini 或 .html 文件中记录这些信息，我们会自动解析它们。

下面是一个示例，展示了如何从一个 Space 关联两个模型：

title: My lovely space
emoji: 🤗
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
models:
- reach-vb/musicgen-large-fp16-endpoint
- reach-vb/wav2vec2-large-xls-r-1B-common_voice7-lt-ft
Last updated on