Write and review ZeroGPU code for Hugging Face Spaces

This skill covers the rules and patterns for building ML demos on Hugging Face Spaces with ZeroGPU hardware, scoped specifically to Gradio SDK Spaces - Docker and Static Spaces cannot schedule onto ZeroGPU, and Streamlit now runs as Docker Spaces, so this doesn't apply to those. ZeroGPU exposes two sizes mapping to a fraction of the backing card - large (default, half the GPU, 1x quota cost) and xlarge (full GPU, 2x quota cost, and it doubles the requested duration in both the tier-max and quota checks) - and the backing GPU generation changes over time, so the skill points to the live docs rather than naming a fixed card. The basic pattern instantiates models at module scope with .to("cuda") called eagerly, decorates the actual inference function with @spaces.GPU (a no-op outside ZeroGPU, safe everywhere), and sets duration to the realistic worst case rather than leaving the 60s default - since the platform pre-checks requested duration against remaining quota, not actual run time, so even a fast task can fail with quota exceeded once remaining quota drops below the declared duration, and shorter declared durations also rank higher in the node-level queue. torch.compile isn't supported; PyTorch ahead-of-time compilation (AoTI, torch 2.8+) is the replacement. The CUDA availability model is central: real GPU access exists only inside @spaces.GPU-decorated calls, but import spaces monkey-patches torch.cuda.is_available() to always return True so that module-scope .to("cuda") calls succeed - ZeroGPU registers those tensors, offloads them to disk at a startup "pack" step, and streams them into VRAM via a pinned-memory pipeline when a decorated call actually runs, with warm workers skipping that step. The standard device = torch.device("cuda" if torch.cuda.is_available() else "cpu") idiom still works correctly across ZeroGPU, dedicated GPU, and CPU-only environments. Locally, the spaces package is already a genuine no-op gated on the SPACES_ZERO_GPU env var - wrapping import spaces in try/except with a hand-rolled fallback is called out as an anti-pattern that drifts from the real API and hides the dependency from requirements.txt. Process isolation matters: @spaces.GPU functions run in a separate scheduler-managed process, with arguments and return values crossing via pickle - only picklable objects survive, CUDA tensors must be moved to CPU before returning (tensor.cpu()) since unpickling a CUDA tensor in the main process triggers a blocked torch.cuda._lazy_init(), and gr.State values are pickled on every yield rather than shared by reference, so in-place mutations are invisible to other handlers until explicitly yielded back. Handlers run concurrently by default, so mutable global state and fixed output file paths (use tempfile instead) will corrupt or leak data under concurrent load; read-only globals loaded once at startup are safe. Call granularity matters too - decorate the outer function that owns a loop rather than a per-iteration worker, since each GPU entry costs a pickle round-trip, worker warm-up, and a fresh queue pass. Build-time constraints: ZeroGPU's build phase has no nvcc (the base image is plain python:3.13), so CUDA-dependent sdist-only packages like bare flash-attn can't install via requirements.txt - only pre-built wheels work, though the runtime does mount nvcc for AoTI support. gr.Examples defaults to cache_examples=True with cache_mode="lazy" on ZeroGPU specifically, since eager caching would fail with no GPU attached at startup. Dependency management requires pinning python_version in the README frontmatter (runtime defaults to 3.10), never pinning spaces itself in requirements.txt (the platform pins its own version), and pinning torch to match any CUDA wheel's encoded version tag.

Use it when writing or reviewing code that uses @spaces.GPU, configuring python_version/requirements.txt for a ZeroGPU Space, or handling ZeroGPU-specific constraints like pickle-based process isolation, duration/quota tuning, or CUDA build limits. Do NOT apply it to Docker or Static Spaces, which cannot schedule onto ZeroGPU at all - and for general Gradio coding unrelated to ZeroGPU (components, layouts, event listeners), use the separate huggingface-gradio skill instead.

Inputs: a model/pipeline to serve, its expected worst-case inference duration, and any CUDA-dependent dependencies. Outputs: a @spaces.GPU-decorated Gradio Space with module-scope model loading, correctly tuned duration/size, pickle-safe function signatures (CPU tensors/arrays/paths, not raw CUDA tensors or unpicklable objects), concurrency-safe state handling, and a requirements.txt/README frontmatter pinned for ZeroGPU's Python version and wheel constraints.

import spaces
import torch
from transformers import pipeline

pipe = pipeline("text-generation", model="...", device="cuda")

@spaces.GPU
def generate(prompt: str) -> str:
    return pipe(prompt, max_new_tokens=100)[0]["generated_text"]

Built on the spaces Python package and its @spaces.GPU decorator, Gradio's SDK (gr.State, gr.Examples, GRADIO_CACHE_EXAMPLES/GRADIO_CACHE_MODE), PyTorch's AoTI export path as the torch.compile replacement, and pre-built CUDA wheels (e.g. for flash-attn) since the build environment lacks nvcc. Points to companion reference files (concurrency.md, how-zerogpu-works.md, how-quota-works.md, cuda-and-deps.md) and the authoritative live docs at huggingface.co/docs/hub/spaces-zerogpu for values that change over time.

ML engineers building or debugging Gradio demos on Hugging Face ZeroGPU Spaces who need to get device placement, quota/duration, process isolation, and dependency pinning right on a hardware model that only attaches a real GPU inside decorated calls.