huggingface-spaces
Build, deploy, and maintain applications on Hugging Face Spaces — Gradio / Docker / Static SDKs, ZeroGPU and dedicated hardware, model loading, debugging, buckets, inference providers, community grants. Use whenever the user asks to create or host an app on Hugging Face, port code onto...
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-22
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- huggingface-spaces
- risk
- unknown
- source
- https://github.com/huggingface/skills/tree/main/skills/huggingface-spaces
- license
- Apache-2.0
- date_added
- 1782864000000
- description
- Build, deploy, and maintain applications on Hugging Face Spaces — Gradio / Docker / Static SDKs, ZeroGPU and dedicated hardware, model loading, debugging, buckets, inference providers, community grants. Use whenever the user asks to create or host an app on Hugging Face, port code onto...
- source_repo
- huggingface/skills
- source_type
- official
- license_source
- https://github.com/huggingface/skills/blob/main/LICENSE
02 资源文件 8
- 参考文档references/buckets.md4.3 KB
- 参考文档references/debugging.md11.0 KB
- 参考文档references/gradio.md7.1 KB
- 参考文档references/grants.md2.6 KB
- 参考文档references/inference-providers.md3.2 KB
- 参考文档references/known-errors.md12.9 KB
- 参考文档references/requirements.md9.5 KB
- 参考文档references/zerogpu.md14.8 KB
03 SKILL.md 正文
Hugging Face Spaces
When to Use
Use this skill when you need build, deploy, and maintain applications on Hugging Face Spaces — Gradio / Docker / Static SDKs, ZeroGPU and dedicated hardware, model loading, debugging, buckets, inference providers, community grants. Use whenever the user asks to create or host an app on Hugging Face, port code onto...
Hugging Face Spaces host machine-learning applications. There are 1M+ today; each Space is a git repo. This skill covers creating, building, debugging, and maintaining them.
0. Getting ready
Before anything else:
- Check the
hfCLI is installed:which hf. If not,pip install -U huggingface_hub. - Check the user is logged in:
hf auth whoami. If not, ask them to run! hf auth loginin this session — they'll need a write-scoped token from https://huggingface.co/settings/tokens. - Note
whoami'scanPayandisProflags — they gate hardware choices below.
The hf-cli skill teaches an agent every hf command and is the recommended companion to this one. Install it with hf skills add hf-cli (add --claude --global to install for Claude Code as well, user-level).
1. What a Space is
A Space is a git repo with three possible SDKs:
- Gradio — most Spaces. Python, fast iteration, supports ZeroGPU.
- Docker — arbitrary container. Use when you need a non-Python stack or a pre-built template (Streamlit, Argilla, Shiny, etc. — full list at https://huggingface.co/docs/hub/spaces-sdks-docker). Does not support ZeroGPU.
- Static — plain HTML, or a React/Svelte/Vue project built at deploy time. Use for in-browser ML (transformers.js / WebGPU / WebAssembly / onnxruntime-web), project pages, interactive reports, or Spaces that orchestrate other Spaces. No hardware needed.
Hardware tiers
Free, no creator cost: cpu-basic and zero-a10g (ZeroGPU). Static Spaces are also free and don't need hardware.
cpu-basic — 2 vCPU / 16 GB. For data viz, API-proxy Spaces, small CPU-bound models.
ZeroGPU (zero-a10g) — dynamic, per-request GPU allocation on NVIDIA RTX PRO 6000 Blackwell (sm_120). Two sizes: large (half MIG, 48 GB, 1× quota) and xlarge (full, 96 GB, 2× quota). Free for the Space creator; Space visitors consume their own daily quota (~5 min free / 40 min Pro / 60 min Enterprise). Gradio-only, PyTorch-first. Requires the creator to be on a PRO / Team / Enterprise plan.
Dedicated GPU (T4, L4, A10G, L40S, A100, H200) — billed to the Space creator by the hour. List + pricing: hf spaces hardware. Only the creator can attach these, and only if canPay=True. Use when ZeroGPU genuinely doesn't fit — non-PyTorch main model with heavy init, very-large-model long-context inference, etc.
If a non-PRO user has a use case that wants ZeroGPU, you can still build it: create a cpu-basic Space, code the app for ZeroGPU, push, then request a community grant. See references/grants.md.
For the authoritative reference: https://huggingface.co/docs/hub/spaces-overview
2. Look for an existing demo first
Before deciding how to build anything, search for prior art:
hf spaces search "<model name or task>" --sdk gradio --limit 10
If someone has built a similar Space, read its app.py and requirements.txt — that gives you the working pattern. Saves a lot of blind iteration. Mention to the user what you found before committing to an approach.
3. Decide SDK and hardware
Follow the user's explicit request first. If they were vague:
- Default for a public ML demo: Gradio + ZeroGPU. Use this unless something below applies.
- The model's only inference path is non-PyTorch (ONNX / TF / JAX / vLLM as the MAIN model, with heavy init): dedicated GPU.
- But: marginal non-torch tools (a small ONNX preprocessor, a TF utility) inside a torch-main pipeline are fine on ZeroGPU. The hijack only patches torch; init the non-torch lib inside
@spaces.GPUand pay the short per-call init cost.
- But: marginal non-torch tools (a small ONNX preprocessor, a TF utility) inside a torch-main pipeline are fine on ZeroGPU. The hijack only patches torch; init the non-torch lib inside
- Tiny / CPU-bound model, or API-proxy Space:
cpu-basic(hardware-free isn't applicable to Gradio). - Browser-side ML or project page: Static.
- Container with non-Python stack: Docker.
Sourcing the model
- GitHub repo — clone locally to read structure. If it already has a Gradio demo, the minimal viable path is to adapt it onto ZeroGPU (see
references/zerogpu.md). Otherwise: read the README + inference code, prefer the PyTorch path, estimate VRAM (bf16 ≈params_B × 2GB; 48 GB fits ≤24B params at bf16, or much larger with quantization — seereferences/zerogpu.mdfor quantization on ZeroGPU). - HF model repo — read its README, follow any linked GitHub.
- Paper / blog post — look for an official or unofficial implementation. Don't reimplement unless trivial or the user explicitly asks.
- Vague request — search Spaces first; surface results.
If the model genuinely won't fit, check Inference Providers as an alternative: see references/inference-providers.md. This avoids hosting the model at all.
4. Create the 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-sdkis required.--flavorselects hardware.zero-a10gis the (legacy) identifier for ZeroGPU. Omit forcpu-basic. Runhf spaces hardwarefor the full paid list and pricing.- Visibility:
--public(anyone can view),--private(only you),--protected(app is reachable but git repo / Files tab is private). --secrets KEY=valbecomes an environment variable inside the Space and is not visible to visitors. Use for API keys, gated-repo tokens (HF_TOKEN=hf_…), etc. Can also be set later viahf spaces secrets set <id> KEY=val.--env KEY=valis visible to visitors — use only for non-sensitive config (GRADIO_SSR_MODE=false,PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True, etc.).
Note:
hardware:in the README YAML is silently ignored — hardware is only set via--flavorat creation, or later viahf spaces settings <id> --hardware <name>.
5. Build the app
The Space now exists at https://huggingface.co/spaces/<namespace>/<name> but is empty.
README.md frontmatter
Always required:
---
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
---
* Reasons to use an older Gradio: a custom component pins it, or you're adapting an existing demo and don't want to rewrite for 5.x→6.x breaking changes. If you need a 5.x, pick 5.50.0 (latest of the series; still supports custom components).
All frontmatter options: https://huggingface.co/docs/hub/spaces-config-reference
Minimal ZeroGPU Gradio app
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):
return pipe(prompt).images[0]
gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch()
Three rules — full treatment in references/zerogpu.md:
import spacesbefore torch / any CUDA-touching import. It monkey-patchestorch.cuda.*; once CUDA is initialized in the main process, it's too late.- Load the model at module scope,
.to("cuda")eagerly. ZeroGPU intercepts the call, packs weights to disk, and streams them into VRAM on the first@spaces.GPUentry. Lazy loading inside the decorator costs every user. - Decorate the function Gradio binds. Estimate
durationto the realistic worst case (smaller = higher queue priority and tighter quota check). For input-dependent runtime, pass a callable.
requirements.txt
Short version:
- Do NOT list:
gradio,spaces,huggingface_hub(preinstalled and platform-managed; pinning them causes resolution failures or silently breaks the ZeroGPU runtime). - Do list if you use them:
torchvision,torchaudio(not preinstalled), plus everything else (diffusers,transformers,accelerate,sentencepiece, …). - ZeroGPU only accepts torch
2.8.0,2.9.1,2.10.0,2.11.0. Default to leaving torch unpinned (the runtime preinstalls the latest). Only pin when a dep forces it. - For prebuilt CUDA-extension wheels (
flash_attn,xformers,pytorch3d,nvdiffrast,diff_gaussian_rasterization,torchmcubes): use the prebuilt Blackwell wheels athttps://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels. Full mapping + caveats inreferences/requirements.md.
Per-SDK depth
- Gradio patterns (themes,
gr.Examples, streaming, custom HTML components,gr.Server):references/gradio.md. - Docker: https://huggingface.co/docs/hub/spaces-sdks-docker. Examples:
hf spaces list --filter docker. - Static: https://huggingface.co/docs/hub/spaces-sdks-static. For built SPAs, set
app_build_command: npm run buildandapp_file: dist/index.htmlin frontmatter. - ZeroGPU specifics (decorator semantics, sizing, AoTI, generators, concurrency, pickle /
gr.Stateacross the worker boundary):references/zerogpu.md— read this whenever the Space targets ZeroGPU.
6. Iterate on the Space, not locally
Try to build a release candidate from the user quest locally and push it — then use the live URL as your test loop. The Space environment is the only one that matters; do not try to test locally. python3 -m py_compile app.py is the maximum local check worth doing before pushing.
Once pushed, pick the cheapest update mechanism for each change — hot-reload for pure Python edits, hf upload for code-only files hot-reload can't touch, full rebuild only when requirements.txt / Dockerfile / README frontmatter actually changed. Full ladder + footguns (hot-reload poisoning factory reboot, runtime.sha lag, etc.) in references/debugging.md.
7. Verify
Don't trust RUNNING alone — the app can be running but broken. Four steps, in order:
A. Alive? Stage + hardware:
hf spaces info <ns>/<name> --expand runtime
B. Logs clean post-boot? Read the run log to confirm startup finished without warnings or silent fallbacks:
hf spaces logs <ns>/<name> --tail 200
Look for model-load completion, no import warnings, no "falling back to CPU" / dtype downgrade messages, no RUNNING masking a half-broken app.
C. API actually responds. With logs still tailing in another terminal (hf spaces logs <ns>/<name> --follow), call the endpoint:
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. Sniff output AND logs. HTTP 200 ≠ correct output. Check both:
head = open(result, "rb").read(16)
# glTF / \x89PNG / RIFF…WEBP / RIFF…WAVE / [4:8]==b"ftyp" → png/jpg/webp/wav/mp4
And look at the run log emitted during the call — silent fallbacks (model snapping to a different size, missing optional dep, dtype downgrade) only show up there.
Full smoke-test patterns (streaming endpoints, OAuth-gated Spaces, gr.Server custom routes): references/debugging.md.
8. Permanent storage (buckets)
Spaces are stateless — /data is wiped on restart. If the Space needs to persist user uploads, generations, logs, or interact with a long-lived store, mount a bucket:
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
Buckets are paid storage; check canPay and confirm with the user. Full patterns (read-fast / write-durable, public bucket URLs, model-cache anti-pattern): references/buckets.md.
9. When things break
Order of operations:
- Read the logs:
hf spaces logs <id> --build --follow(build error) orhf spaces logs <id> --follow(runtime error). Find the first error, not the last. - Grep
references/known-errors.mdfor the error string. Check if this is a known issue before trying your own fix — most common ZeroGPU / Gradio / dependency errors have a 1–2 line fix there. - Iterate using the cheapest rung from
references/debugging.md. The vast majority of issues resolve with log-reading + smoke-test loops; interactive dev mode + SSH is a heavy-hammer last resort.
If you solve an error that wasn't in the known-errors list, suggest the user PR it back to this skill so future runs benefit.
Reference index
| When to read | File |
|---|---|
| How ZeroGPU works + correct patterns (decorator, sizing, pickle, generators, real-time, AoTI) | references/zerogpu.md |
| Iterate + debug: logs, rung ladder, smoke testing (and dev mode + SSH as a last resort) | references/debugging.md |
| Error-string lookup — the single place for all error symptoms (Spaces, ZeroGPU, Gradio, deps) | references/known-errors.md |
| Pinning deps, picking wheels, torch-family alignment | references/requirements.md |
gr.Examples caching, themes, custom HTML components, gr.Server |
references/gradio.md |
| Persistent storage, public bucket URLs | references/buckets.md |
| Community grant requests (non-PRO needing ZeroGPU) | references/grants.md |
| Provider proxy (zero-VRAM big LLM via Cerebras / Fireworks / Together / etc.) | references/inference-providers.md |
Limitations
- Use this skill only when the task clearly matches its upstream product or API scope.
- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
04 同仓库更多 Skills
testing-best-practices
Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.
tailwindcss-development
Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.
laravel-best-practices
Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.
infer-conventions
Use this skill to analyze how a Laravel application is actually written and record its conventions as shared rules. Trigger when the user wants to detect, infer, document, or standardize project conventions or coding style, set up or grow `.ai/rules`, resolve mixed or conflicting patterns (e.g. "are we using Form Requests or inline validation?"), or onboard agents and teammates to "how we do things here". Covers: a systematic sweep of ~49 Laravel convention dimensions (validation, models, architecture, testing, frontend, database, console), open-ended house-pattern discovery, conflict reporting, and recording rules scoped to the right paths via the Boost `record-rule` MCP tool. Only run this skill when the user explicitly asks for it; never start a sweep as part of another task. Do not use for one-off code review, enforcing formatting a linter already handles, or editing `.ai/rules` files by hand.
inertia-react-development
Develops Inertia.js v2 React client-side applications. Activates when creating React pages, forms, or navigation; using <Link>, <Form>, useForm, or router; working with deferred props, prefetching, or polling; or when user mentions React with Inertia, React pages, React forms, or React navigation.
deploying-to-cloud
Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to Cloud, create or manage applications, environments, databases, caches, object storage, queues, domains, instances, background processes, secrets, compute, scheduled tasks, or Laravel Cloud infrastructure; or check billing, usage, or spend. Triggers on deployment, shipping, Cloud management, environment setup, database provisioning, billing or usage queries, the `cloud` CLI, and Laravel Cloud deployment troubleshooting.