Hugging Face ZeroGPU

要解决什么问题

在 Hugging Face Spaces 上把 ML 演示跑在 ZeroGPU 上时，Gradio 进程在启动阶段并没有真正挂载 GPU，而 @spaces.GPU 内的推理又运行在独立 worker 里。若仍按「本地 CUDA 脚本」或「专用 GPU Space」的习惯写代码，容易出现 quota exceeded、illegal duration、PicklingError，或在并发下静默覆盖全局状态与固定文件路径。

技能如何组织答案

本技能把 ZeroGPU 当成一套明确的运行时契约来读：

• 模块级加载模型并 model.to("cuda")，由平台注册张量并在请求时流式载入 VRAM；实际算子只放在 @spaces.GPU 装饰的函数里。
• duration 与 size 按声明值做档位上限与配额预检查（不是按真实耗时）；可变负载可用可调用对象动态估计；xlarge 配额成本为 2×。
• 进程边界走 pickle：勿返回 CUDA 张量（先 .cpu()）；gr.State 在 ZeroGPU 上不是引用语义，生成器里要显式 yield 状态。
• 并发默认开启：只读全局（模型、分词器）安全；可变全局与固定输出路径是反模式。
• 构建与依赖：镜像构建阶段无 nvcc，CUDA 包需预编译 wheel；README 中应固定 python_version，且不要在 requirements.txt 里 pin spaces。

更细的机制见技能内 references/（并发、配额、冷启动与 wheel 标签）。

适用边界

仅适用于 Gradio SDK + ZeroGPU 的 Space。Docker / Static Spaces 无法调度 ZeroGPU；Streamlit 目前走 Docker，不在本技能范围。通用 Gradio 组件与布局请对照同系列的 huggingface-gradio 技能。后台 GPU 型号与档位阈值会变更，以 ZeroGPU 官方文档 为准；不支持 torch.compile，需用 PyTorch AoTI（torch 2.8+）。