前言¶
在 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
