huggingface-spaces

Hugging Face Spaces

Hugging Face Spaces 托管机器学习应用。目前已有 100 多万个，每个 Space 都是一个 git 仓库。本技能涵盖创建、构建、调试和维护 Space。

0. 准备工作

开始之前：

1. 检查是否已安装 hf CLI：which hf。如果没有，请运行 pip install -U huggingface_hub。
2. 检查用户是否已登录：hf auth whoami。如果没有，请运行 hf auth login——它会显示一个 URL 和一次性验证码；请用户打开该 URL 并输入验证码，随后即可自动完成登录（使用 OAuth，无需令牌）。或者，传入来自 https://huggingface.co/settings/tokens 的写入权限令牌，并使用 --token。
3. 记下 whoami 的 canPay 和 isPro 标志——它们决定了下文可选的硬件。免费（isPro=False）账户只能托管 Static Space，以及最多 2 个 ZeroGPU Space。

hf-cli 技能会向 Agent 介绍每个 hf 命令，建议与本技能配合使用。运行 hf skills add hf-cli 安装（添加 --claude --global 也可为 Claude Code 安装，适用于用户级别）。

1. 什么是 Space

Space 是一个 git 仓库，支持以下三种 SDK：

• Gradio — 大多数 Space 都使用它。基于 Python，迭代速度快，支持 ZeroGPU。
• Docker — 任意容器。需要非 Python 技术栈或预构建模板（Streamlit、Argilla、Shiny 等——完整列表见 https://huggingface.co/docs/hub/spaces-sdks-docker）时使用。不支持 ZeroGPU。
• Static — 纯 HTML，或在部署时构建的 React/Svelte/Vue 项目。适用于浏览器内机器学习（transformers.js / WebGPU / WebAssembly / onnxruntime-web）、项目页面、交互式报告，或用于编排其他 Space 的 Space。无需硬件。

硬件等级

Static Space 对所有人免费，且无需硬件。Gradio 和 Docker Space 在计算资源上运行，创建时需要付费方案——个人账户需要 PRO，组织需要 Team 或 Enterprise——但有一个例外：状态良好的免费个人账户（邮箱已验证且账户注册时间超过 30 天）最多可托管 2 个 ZeroGPU Space。

因此，对于免费账户，ZeroGPU 是托管 Gradio Space 的唯一方式。cpu-basic 不再是过去那种稳妥的备用选项——它也受到限制。

ZeroGPU（zero-a10g） — 在 NVIDIA RTX PRO 6000 Blackwell（sm_120）上按请求动态分配 GPU。提供两种规格：large（半个 MIG，48 GB，1× 配额）和 xlarge（完整 MIG，96 GB，2× 配额）。Space 创建者免费；Space 访客消耗各自的每日配额（免费用户约 5 分钟 / Pro 用户 40 分钟 / Enterprise 用户 60 分钟）。仅支持 Gradio，以 PyTorch 为主。每个账户的托管上限：免费个人账户 2 个，PRO 账户 10 个，Team / Enterprise 组织 50 个。

cpu-basic — 2 个 vCPU / 16 GB，无小时费用，但需要付费方案。适用于数据可视化、API 代理 Space 和小型 CPU 密集型模型。

专用 GPU（T4、L4、A10G、L40S、A100、H200）— 按小时向 Space 创建者收费。型号列表和价格：hf spaces hardware。只有创建者可以添加这些 GPU，且必须满足 canPay=True。仅当 ZeroGPU 确实不适用时使用，例如主模型并非基于 PyTorch 且初始化开销很大、超大型模型长上下文推理等。

如果用户需要自己无力支付的硬件——专用 GPU，或超出免费 2 个 ZeroGPU 上限的 Gradio Space——仍可创建 Static Space（所有人均可免费使用），将应用推送到其中，然后申请社区资助。请参阅 references/grants.md。

权威参考文档：https://huggingface.co/docs/hub/spaces-overview

2. 先查找现有演示

在决定如何构建之前，先搜索已有的实现：

hf spaces search "<model name or task>" --sdk gradio --limit 10

如果有人构建过类似的 Space，请查看其 app.py 和 requirements.txt——这能提供可行的实现范例，省去大量盲目尝试。在确定方案之前，向用户说明你找到的内容。

3. 选择 SDK 和硬件

优先遵循用户的明确要求。如果用户没有说清楚：

• 公开 ML 演示的默认选择：Gradio + ZeroGPU。除非符合以下情况，否则使用此方案。
• 模型唯一的推理路径不是 PyTorch（将 ONNX / TF / JAX / vLLM 作为主模型，且初始化开销较大）：专用 GPU。
  • 但是：在以 torch 为主的流程中使用少量非 torch 工具（小型 ONNX 预处理器、TF 实用工具）没有问题，可以使用 ZeroGPU。在 @spaces.GPU 内初始化非 torch 库，并承担每次调用时短暂的初始化开销。劫持机制只会修补 torch。
• 小型 / 受 CPU 限制的模型，或 API 代理 Space：cpu-basic——但需要付费计划。免费账户可将其部署到 zero-a10g，并使用空操作装饰函数（ZeroGPU 至少需要一个这样的函数），将实际工作放在函数外部——没有任何操作会请求 GPU，因此不会消耗配额。参见 references/inference-providers.md。
• 浏览器端 ML 或项目页面：Static。
• 包含非 Python 技术栈的容器：Docker。

获取模型

• GitHub 仓库——克隆到本地以查看结构。如果仓库已有 Gradio 演示，最精简可行的方案是将其改为使用 ZeroGPU（参见 references/zerogpu.md）。否则：阅读 README 和推理代码，优先选择 PyTorch 路径，估算 VRAM（bf16 ≈ params_B × 2 GB；48 GB 可容纳 ≤24B 参数的 bf16 模型，量化后可容纳更大的模型——关于 ZeroGPU 上的量化，参见 references/zerogpu.md）。
• HF 模型仓库——阅读其 README，并查看其中链接的 GitHub 仓库。
• 论文 / 博客文章——查找官方或非官方实现。除非实现非常简单，或用户明确提出要求，否则不要重新实现。
• 模糊的请求——先搜索 Spaces，并展示搜索结果。

如果模型确实无法放入硬件，请考虑 Inference Providers 作为替代方案：参见 references/inference-providers.md。这样就无需自行托管模型。

4. 创建 Space

hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> \
    [--flavor zero-a10g|cpu-basic|<paid-flavor>] \
    [--secrets KEY=val] [--env KEY=val] \
    --public|--private|--protected \
    --exist-ok

• 必须指定 --space-sdk。
• --flavor 用于选择硬件。zero-a10g 是 ZeroGPU 的旧标识符。省略该参数时会使用 cpu-basic——而它本身也需要付费计划，因此免费账户请明确传入 --flavor zero-a10g。运行 hf spaces hardware 可查看完整的付费硬件列表及价格。
• 可见性：--public（任何人都可查看）、--private（仅你可查看）、--protected（应用可访问，但 git 仓库 / Files 标签页为私有）。
• --secrets KEY=val 会变成 Space 内的环境变量，且访客不可见。用于 API 密钥、受限仓库令牌（HF_TOKEN=hf_…）等。之后也可通过 hf spaces secrets set <id> KEY=val 设置。
• --env KEY=val 访客可见——仅用于非敏感配置（GRADIO_SSR_MODE=false、PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True 等）。

注意：README YAML 中的 hardware: 会被静默忽略——只能在创建时通过 --flavor 设置硬件，或之后通过 hf spaces settings <id> --hardware <name> 设置。

5. 构建应用

Space 现已创建，地址为 https://huggingface.co/spaces/<namespace>/<name>，但内容为空。

README.md frontmatter

始终需要：

---
title: ...
emoji: 🚀                # pick something representative
colorFrom: blue          # red|yellow|green|blue|indigo|purple|pink|gray (only these)
colorTo: indigo
sdk: gradio              # gradio | docker | static
sdk_version: 6.15.1      # latest stable unless you have a reason*
app_file: app.py         # gradio only (docker / static use Dockerfile / index.html)
short_description: ...   # ≤ 60 chars (server rejects longer)
python_version: "3.12"   # ZeroGPU officially supports 3.10.13 and 3.12.12
startup_duration_timeout: 30m   # default; bump to 1h for big LLMs / heavy downloads
---

* 默认使用当前最新稳定版本，并且查明具体版本（运行 pip index versions gradio，或查看新建 Space 默认使用的版本）——上方的版本号只是占位符，之后会过时，不要直接复用。只有当最新版本确实无法用于此 Space 时才指定旧版本：例如自定义组件要求固定版本，或你正在改造现有演示，不想处理 5.x→6.x 的重大变更。如果需要使用 5.x，请选择 5.50.0（该系列的最新版本；仍支持自定义组件）。

所有 frontmatter 选项：https://huggingface.co/docs/hub/spaces-config-reference

最简 ZeroGPU Gradio 应用

import spaces           # MUST come before torch / diffusers / transformers
import torch
import gradio as gr
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained("<repo>", torch_dtype=torch.bfloat16).to("cuda")

@spaces.GPU(duration=60)
def generate(prompt: str):
    """Generate an image from a text prompt."""   # docstring → API / MCP tool description
    return pipe(prompt).images[0]

gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch(mcp_server=True)

三条规则——完整说明见 references/zerogpu.md：

1. 在导入 torch / 任何会触及 CUDA 的模块之前 import spaces。 它会对 torch.cuda.* 进行猴子补丁；一旦主进程初始化了 CUDA，就来不及了。
2. 在模块作用域加载模型，并立即调用 .to("cuda")。 ZeroGPU 会拦截该调用，将权重打包到磁盘，并在首次进入 @spaces.GPU 时将其流式传输到 VRAM。在装饰器内部延迟加载会影响每位用户。
3. 装饰 Gradio 绑定的函数。 将 duration 估算为实际最坏情况（值越小，队列优先级越高，配额检查也越严格）。对于运行时间取决于输入的情况，传入一个可调用对象。

示例、文档字符串和 MCP

• 只要适用，就添加 gr.Examples（应用接受输入，且存在有代表性的输入）——优先使用模型/仓库自带的官方示例。示例行只保留用户实际会更改的少数输入（提示词、图像），其余参数（步数、种子、引导系数）设为处理函数默认值，这样一行就是 ["a prompt"]，而不是一大串选项。使用 cache_examples=True, cache_mode="lazy"。参见 references/gradio.md。
• 为每个由 API 调用的函数添加文档字符串和类型提示。 每个 Gradio 事件处理函数都会通过 API 暴露；调用方以及 MCP 工具架构看到的就是文档字符串和函数签名。
• 使用 demo.launch(mcp_server=True) 启动（Gradio 5+），使 Space 同时作为 MCP 服务：每个 API 函数都会成为一个 MCP 工具，其描述来自文档字符串和类型提示。

requirements.txt

简要说明：

• 不要列出：gradio、spaces、huggingface_hub（已预装并由平台管理；固定这些依赖的版本会导致解析失败，或悄无声息地破坏 ZeroGPU 运行时）。
• 如果使用则列出：torchvision、torchaudio（未预装），以及其他所有依赖（diffusers、transformers、accelerate、sentencepiece……）。
• ZeroGPU 仅接受 torch 2.8.0、2.9.1、2.10.0、2.11.0。默认不要固定 torch 版本（运行时会预装最新版本）。仅在依赖强制要求时才固定版本。
• 对于预构建的 CUDA 扩展 wheel（flash_attn、xformers、pytorch3d、nvdiffrast、diff_gaussian_rasterization、torchmcubes）：使用 https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels 上预构建的 Blackwell wheel。完整映射和注意事项见 references/requirements.md。

各 SDK 的详细说明

• Gradio 模式（主题、gr.Examples、流式传输、自定义 HTML 组件、gr.Server）：references/gradio.md。
• Docker：https://huggingface.co/docs/hub/spaces-sdks-docker。示例：`hf spaces list --filter docker`。
• Static：https://huggingface.co/docs/hub/spaces-sdks-static。对于构建好的 SPA，在 frontmatter 中设置 app_build_command: npm run build 和 app_file: dist/index.html。
• ZeroGPU 特定说明（装饰器语义、资源规格、AoTI、生成器、并发、跨 worker 边界的 pickle / gr.State）：references/zerogpu.md — 只要 Space 面向 ZeroGPU，就请阅读此文档。

6. 在 Space 上迭代，而不是在本地

尝试根据用户的任务在本地构建一个候选发布版本并推送，然后使用线上 URL 作为测试循环。Space 环境才是唯一重要的环境；不要尝试在本地测试。推送前，python3 -m py_compile app.py 是值得做的唯一一次本地检查。

使用 hf upload <namespace>/<name> . --repo-type space 推送文件。必须使用 --repo-type space——hf upload 默认使用 model 仓库，否则会上传到同名的 model 仓库（并静默创建该仓库）。添加 --exclude "**/__pycache__/**"，避免将本地字节码缓存提交到 Space。

推送后，针对每项更改选择成本最低的更新方式：纯 Python 编辑使用热重载；热重载无法处理的纯代码文件使用 hf upload；只有在 requirements.txt / Dockerfile / README 前置元数据实际发生更改时，才进行完整重建。完整步骤及常见陷阱（热重载导致工厂重启出错、runtime.sha 延迟等）请参阅 references/debugging.md。

7. 验证

不要只凭 RUNNING 就认定一切正常——应用可能正在运行，但已经损坏。按顺序执行以下四个步骤：

A. 是否正常启动？ 检查阶段和硬件：

hf spaces info <ns>/<name> --expand runtime

B. 启动后日志是否干净？ 查看运行日志，确认启动已完成，且没有警告或静默回退：

hf spaces logs <ns>/<name> --tail 200

检查模型加载是否完成、是否没有导入警告、是否没有“回退到 CPU” / dtype 降级消息，以及是否没有 RUNNING 掩盖应用部分故障的情况。

C. API 是否确实有响应。 在另一个终端中继续跟踪日志（hf spaces logs <ns>/<name> --follow），同时调用端点：

from gradio_client import Client, handle_file
import os
c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"], httpx_kwargs={"timeout": 600})
print(c.view_api())                    # discover endpoints — don't guess
result = c.predict(..., api_name="/generate")

D. 检查输出和日志。 HTTP 200 ≠ 输出正确。两者都要检查：

head = open(result, "rb").read(16)
# glTF / \x89PNG / RIFF…WEBP / RIFF…WAVE / [4:8]==b"ftyp" → png/jpg/webp/wav/mp4

同时查看调用期间生成的运行日志——静默回退（模型自动切换到其他大小、缺少可选依赖、dtype 降级）只会出现在日志中。

完整的冒烟测试模式（流式端点、OAuth 保护的 Spaces、gr.Server 自定义路由）：references/debugging.md。

8. 永久存储（存储桶）

Spaces 是无状态的——重启时会清除 /data。如果 Space 需要持久保存用户上传内容、生成内容、日志，或与长期存储交互，请挂载一个存储桶：

hf buckets create <ns>/<bucket-name>                                          # --private optional
hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data   # read-write at /data

存储桶是付费存储；请检查 canPay 并向用户确认。完整模式（快速读取 / 持久写入、公共存储桶 URL、模型缓存反模式）：references/buckets.md。

9. 出错时的处理方法

操作顺序：

1. 查看日志：hf spaces logs <id> --build --follow（构建错误）或 hf spaces logs <id> --follow（运行时错误）。找出第一个错误，而不是最后一个。
2. 在 references/known-errors.md 中搜索错误字符串。尝试自行修复前，先确认这是否是已知问题——大多数常见的 ZeroGPU / Gradio / 依赖项错误都有 1–2 行修复方法。
3. 使用 references/debugging.md 中成本最低的方法进行迭代。绝大多数问题都能通过查看日志 + 冒烟测试循环解决；交互式开发模式 + SSH 是最后才使用的重型手段。

如果你解决了已知错误列表中没有的问题，请建议用户将其修复以 PR 的形式提交回此技能，让后续运行也能受益。

---

参考索引

何时阅读	文件
ZeroGPU 的工作原理 + 正确模式（装饰器、资源规格、pickle、生成器、实时处理、AoTI）	references/zerogpu.md
迭代 + 调试：日志、阶梯式排查、冒烟测试（以及开发模式 + SSH 作为最后手段）	references/debugging.md
错误字符串查询——所有错误症状的统一查阅处（Spaces、ZeroGPU、Gradio、依赖项）	references/known-errors.md
固定依赖项版本、选择 wheel、对齐 torch 系列	references/requirements.md
gr.Examples（适用时添加）、主题、自定义 HTML 组件、gr.Server、MCP 服务（mcp_server=True）	references/gradio.md
持久化存储、公共存储桶 URL	references/buckets.md
社区资助申请（用户无力承担的硬件）	references/grants.md
提供商代理（通过 Cerebras / Fireworks / Together / 等实现零显存占用的大型 LLM）	references/inference-providers.md
3D Spaces：生成、CUDA 扩展、输出格式和模型配方（包括高斯溅射）	references/3d-generation.md