前言¶
在 Hugging Face Spaces 上挂一个带 GPU 的 Gradio 演示，成本往往是拦路虎：专用 GPU Space 要付费或排队，本地写完再迁上去又容易踩平台特有的坑——PicklingError、声明 duration 和实际配额对不上、flash-attn 在构建阶段找不到 nvcc，或者把 torch.compile 写进 Space 直接跑不起来。官方 ZeroGPU 文档会随硬件代次和配额策略更新，单靠记忆很难写对。
huggingface-zerogpu 是 Hugging Face 在 skills 仓库 里维护的一条 Agent Skill，把 ZeroGPU 上的编码约定、运行时模型和常见错误对照写进 SKILL.md，供 Cursor、Codex、Claude Code 等客户端在写码或排错时自动遵循。下面介绍它解决什么问题、覆盖哪些能力，以及如何安装与对照使用。
这是什么¶
huggingface-zerogpu 面向「在 Hugging Face Spaces 上使用 ZeroGPU 构建 Gradio AI 演示与 GPU 计算」这一场景。Skill 的 YAML 描述写明：在用户编写或审查使用 @spaces.GPU 的代码、配置 ZeroGPU Space 的 python_version 或 requirements.txt、或处理 ZeroGPU 特有约束（基于 pickle 的进程隔离、gr.State 跨 worker 边界语义、不支持 torch.compile、CUDA 仅 wheel 构建、large / xlarge 规格、动态 duration 等）时应启用。
适用范围有硬边界：仅 Gradio SDK + ZeroGPU 硬件 的 Space。Docker Space、Static Space 无法调度到 ZeroGPU；Streamlit 现以 Docker Space 运行，因此不在本 Skill 范围内。通用 Gradio 组件与布局应配合同仓库的 huggingface-gradio Skill。权威运行时参数（当前 backing GPU、运行时版本列表、档位阈值）以 ZeroGPU 官方文档 为准，会随平台变更而更新。
核心功能¶
Skill 正文与配套 reference 主要覆盖以下方面（均来自官方 SKILL.md 与引用说明）。
硬件规格与配额¶
ZeroGPU 通过 size 映射物理卡的一部分：
size |
占用 | 配额消耗 |
|---|---|---|
large（默认） |
半卡 | 1x |
xlarge |
整卡 | 2x |
默认 large 的显存带宽与算力显著低于整卡规格；仅在确实需要额外显存或算力时使用 xlarge。文档强调 backing GPU 可能无预告更换，旧文章里写的具体型号可能已过时， sizing 前应先查官方文档。
基本编码模式¶
典型写法：在模块作用域加载模型并指向 cuda，用 @spaces.GPU 包裹真正做推理的函数：
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"]
关键规则包括：
- 在模块作用域实例化模型并
.to("cuda")或device="cuda"，ZeroGPU 负责后续设备迁移。 - GPU 计算只放在
@spaces.GPU装饰的函数内；装饰器在非 ZeroGPU 环境是 no-op，可保留在代码里。 duration按最坏情况声明（默认 60 秒）。平台按「请求的 duration」与用户剩余配额做预检，而非按实际运行时长；短任务若仍用 60 秒默认值，在用户剩余配额低于 60 秒时会直接quota exceeded。更小的duration在节点队列里通常排序更靠前。- 不支持
torch.compile；需改用 PyTorch 2.8+ 的 ahead-of-time compilation（AoTI），官方博客有 ZeroGPU 相关说明。 size="xlarge"慎用：占满整卡、配额 2 倍、排队往往更长。
长任务可显式声明时长，例如：
@spaces.GPU(duration=120)
def generate_image(prompt: str):
return pipe(prompt).images[0]
CUDA 可用性模型¶
真实 GPU 仅在 @spaces.GPU 函数执行期间挂到进程；模块作用域外没有 GPU。但 import spaces 会 monkey-patch torch，使 torch.cuda.is_available() 全局为 True，模块级的 .to("cuda") 不报错——这是为了把权重注册到 ZeroGPU 后端，经启动阶段的 pack/offload，再在 GPU worker 里流式载入 VRAM。
因此：不要在模块作用域跑推理或 CUDA kernel；应继续用 device = torch.device("cuda" if torch.cuda.is_available() else "cpu") 这类写法，避免硬编码 device="cuda" 导致 CPU Space 或本地 CPU 环境失效。模型应在模块作用域 eager 加载，而不是把首次加载推迟到第一个用户请求（lazy / lru_cache 会把冷启动成本转给首个访问者）。
本地开发与 spaces 包¶
本地只需安装 spaces。不要用 try/except 自建 no-op 的 spaces.GPU：非 ZeroGPU 时 heavyweight 行为由环境变量 SPACES_ZERO_GPU 门控，@spaces.GPU 已是透传。Gradio SDK 基础镜像各硬件档都会装 spaces，复制到专用 GPU 或 CPU Space 通常无需改 import。
配套 reference（Skill 内）¶
| 文件 | 何时查阅 |
|---|---|
references/concurrency.md |
写 ZeroGPU 代码时必读；handler 默认并行 |
references/how-zerogpu-works.md |
冷启动、worker 复用、模块级 warmup 不跨请求、返回 CUDA tensor 卡住等 |
references/how-quota-works.md |
选 duration、illegal duration 与 quota exceeded |
references/cuda-and-deps.md |
flash-attn 等 CUDA 依赖、torch 侧车版本、wheel 标签 |
Skill 描述还列出触发场景：用户提到 ZeroGPU、@spaces.GPU、spaces 包，或出现跨 worker 的 PicklingError、illegal duration、flash-attn wheel 构建失败等，即使未明确要求 ZeroGPU 指南也应启用。
安装与启用¶
Hugging Face Skills 遵循 Agent Skills 格式，仓库为 huggingface/skills。huggingface-zerogpu 路径：
https://github.com/huggingface/skills/tree/main/skills/huggingface-zerogpu
各客户端安装方式（摘自仓库 README，以你当前环境为准）：
Claude Code
- 注册插件市场：
/plugin marketplace add huggingface/skills - 可先装 CLI Skill：
/plugin install hf-cli@huggingface/skills - 安装本 Skill：
hf skills add huggingface-zerogpu（或仓库约定的 skill 名称；与hf skills add <skill-name>用法一致）
Codex
将 skills/huggingface-zerogpu 复制或符号链接到 Codex 的 .agents/skills 标准位置（如 $REPO_ROOT/.agents/skills 或 $HOME/.agents/skills），由客户端按 Agent Skills 标准发现 SKILL.md。
Cursor
仓库提供 .cursor-plugin/plugin.json 与 MCP 配置；市场入口侧重 hf-cli。安装额外 workflow Skill 时，文档建议使用：
hf skills add <skill-name>
将 <skill-name> 换为 huggingface-zerogpu（或与 Hub CLI 列出的名称一致）。
Gemini CLI
可通过仓库扩展安装，例如：
gemini extensions install https://github.com/huggingface/skills.git --consent
若 Agent 不支持 Skills，仓库提供 agentsmd/AGENTS.md 作为兜底说明 bundle。
典型用法（Agent 侧）¶
启用 Skill 后，Agent 在以下任务中应对照 Skill 与 ZeroGPU 文档 行动，而不是按普通 PyTorch/CUDA 习惯臆造：
- 新建或审查 Gradio Space，硬件选 ZeroGPU，在
requirements.txt/python_version中满足 CUDA wheel 约束（无nvcc构建）。 - 为推理入口添加
@spaces.GPU，并按真实最坏耗时设置duration与必要的size。 - 处理并发与
gr.State时阅读references/concurrency.md与进程隔离说明，避免跨 worker 传递不可 pickle 的对象。 - 遇到
quota exceeded/illegal duration时对照references/how-quota-works.md调整声明时长与配额理解。 - 需要编译优化时避开
torch.compile，改用 AoTI 路径。
开发者仍在本仓库 app.py（或等价入口）中维护业务代码；Skill 不改变 Hub 部署流程，而是约束 Agent 生成的补丁与审查意见。
适用场景与注意¶
适合谁
- 要在 Spaces 上做 免费档 GPU 演示、原型验证的 Gradio 作者。
- 使用 AI 编码助手写 ZeroGPU Space，希望减少平台特有 bug 的团队。
- 需要把
@spaces.GPU、配额、PicklingError等关键词与正确修复模式绑定的维护者。
限制与坑
- 仅 Gradio + ZeroGPU；Docker / Static / Streamlit 路径不适用本 Skill 主文档。
- backing GPU 与文档阈值会变，文章或 Skill 里的硬件名可能过期，必须以官方文档为准。
- 默认
duration=60对短任务不友好，且与配额预检强相关。 torch.compile不可用；CUDA 扩展依赖需预编译 wheel。- Handler 默认并行，必须结合 concurrency reference 设计共享状态。
同仓库的 huggingface-spaces Skill 覆盖更广的 Spaces 生命周期（多 SDK、专用硬件、调试等）；ZeroGPU 细节以 huggingface-zerogpu 为专精补充。
结尾¶
ZeroGPU 降低了在 Hub 上展示 GPU 推理 demo 的门槛，但执行模型、配额和构建链路与普通 CUDA 开发并不相同。huggingface-zerogpu 把这些规则固化成 Agent 可执行的 Skill，与官方文档和仓库内 reference 对齐，适合在写 Space 或排错时一并启用。
- Skill 目录：huggingface/skills — huggingface-zerogpu
- ZeroGPU 运行时文档：Spaces ZeroGPU
