huggingface-zerogpu-huggingface-skills

1. 基本信息

项目	内容
名称	huggingface-zerogpu-huggingface-skills
作者/维护者	Hugging Face（官方）
来源链接	https://github.com/huggingface/skills/tree/main/skills/huggingface-zerogpu
许可证	Apache-2.0（来自 GitHub API，仓库根 LICENSE）
所属合集仓库 Stars/Forks	10,909 / 724（`huggingface/skills` 整体合集数据，来自 GitHub API；不代表本技能个体热度，见第 7 章说明）
该技能自身活跃度	该目录自 2026-05-20 创建以来仅 1 次提交（新增即完整版本），仓库整体近一天内仍有提交，非弃置
最新版本	无独立版本号（随仓库整体迭代，未使用 GitHub Releases 机制）
安装方式	见第十章

2. 功能介绍与亮点

huggingface-zerogpu 教会编程 Agent 正确编写运行在 Hugging Face Spaces ZeroGPU（按请求动态分配的免费 GPU 硬件）上的 Gradio 应用代码。它不是“如何部署”的入门引导，而是聚焦这套特殊运行时违反直觉的执行语义，覆盖官方文档也容易被开发者忽略的细节：

进程隔离与 Pickle 边界：@spaces.GPU 装饰的函数运行在独立子进程，参数与返回值经 pickle 序列化传递——直接返回 CUDA 张量、闭包、文件句柄会触发 PicklingError，技能给出具体规避写法（如 .cpu() 转换）
gr.State 跨进程语义：State 值在每次 yield 时被 pickle 复制而非按引用共享，生成器内的原地修改对其他 handler 不可见——这是一个极易踩、且报错信息不直观的陷阱
CUDA 可用性模型：解释 import spaces 会 monkey-patch torch.cuda.is_available() 恒为 True，模型应在模块作用域 .to("cuda")、真正的推理必须在装饰函数内执行，否则静默跑在 CPU 上或直接报错
配额与排队机制：拆解 duration 参数如何同时影响硬性上限检查、剩余配额预检查与队列优先级，给出为什么“就近声明真实所需时长”比默认值更划算的具体逻辑
构建期约束：ZeroGPU 构建阶段没有 nvcc，纯 sdist 分发的 CUDA 依赖包（如裸 flash-attn）无法安装，只能用预编译 wheel——并给出识别 wheel 版本标签的方法
并发正确性三原则：无可变全局状态、不用固定文件路径、只读全局变量安全——直接对应生产环境下静默数据错乱的常见根因

技能自带 4 份专题参考文档（并发、运行原理、配额机制、CUDA 依赖），SKILL.md 正文本身即含大量可直接复制的代码示例与反模式对照。

3. 适用场景

所属分类：DevOps 与基础设施（技能内容是在 ZeroGPU 这一云硬件运行时上构建自己的应用、处理其资源调度与执行环境约束，不涉及调用外部 SaaS API，判据见第 7 步审计记录）。

已经用 Gradio 在 Hugging Face Spaces 上部署 AI/ML 演示应用、想申请免费 ZeroGPU 硬件的开发者
遇到 PicklingError、illegal duration、quota exceeded、flash-attn 编译失败等 ZeroGPU 特有报错、需要定位根因的开发者
需要处理多用户并发请求、避免生产环境下状态错乱或文件冲突的 Gradio 应用开发者

4. 跨 Agent 兼容性

Claude Code：✅ 原生支持——仓库自带 .claude-plugin 插件市场配置，/plugin marketplace add huggingface/skills 后可直接安装
Codex：✅ 原生支持——官方文档说明可将技能目录复制或软链接到 Codex 标准的 .agents/skills 位置，由 Codex 按 Agent Skills 标准自动发现
OpenClaw：未验证——抓取到的官方材料未提及
Hermes Agent：未验证，同上

5. 推荐理由

它把 ZeroGPU 这套免费 GPU 运行时里最容易踩、报错信息又最不直观的几类坑（进程隔离序列化、State 跨进程语义、配额预检查逻辑、CUDA 构建期限制）一次性讲透，且每条规则都配可运行代码示例与反模式对照，官方持续维护，能显著减少 Agent 帮用户调试 ZeroGPU 报错时的试错轮次。

6. 评分

维度	分数	说明
受欢迎程度	7	Hugging Face 为发布方且是 ZeroGPU/Spaces 产品本身的所有者，属第一方官方出品；合集仓库万级 star 数据不代表单个子技能的独立热度，也未检索到该技能条目自身可具名归因的独立第三方评价
可用性	9	SKILL.md 正文约 18KB 外加 4 份专题参考文档，规则均配可运行代码示例与反模式对照；该目录 2026-05-20 创建后仓库仍在近一天内持续提交，维护活跃；单条插件市场命令即可安装，无付费依赖
安全性	9	纯代码规范与运行时语义讲解，技能自身不执行任何 shell 命令、不联网外发数据、不要求任何凭据；官方出品、完全开源可审计（Apache-2.0）；未发现可疑指令

安全检查清单：①无 shell 执行 ②无网络外发（仅引用官方文档 URL，不发起请求） ③无凭据要求 ④未发现可疑指令或提示词注入迹象 ⑤作者为 Hugging Face，信誉良好 ⑥License 明确（Apache-2.0） ⑦该目录创建于 2026-05-20，仓库整体近一天内仍有提交，维护活跃。

综合评分：8.3（三项均值）

7. 跟同类 Skills 相比的优势

同一合集仓库内还有两个紧密相关但定位不同的技能：

技能	定位	与 huggingface-zerogpu 的差异
huggingface-spaces	创建、部署、调试 Space 本身（`hf` CLI 登录、推送、查日志、硬件选型）	解决“怎么把应用发布上去”，覆盖 Gradio/Docker/Static 全形态；不深入 ZeroGPU 内部的进程隔离、pickle 语义等代码级细节
huggingface-gradio	用 Python 搭建 Gradio 界面本身（组件、布局、事件监听）	解决“界面怎么写”，与硬件运行时无关；同一应用若跑在 ZeroGPU 上，仍需搭配本技能处理执行环境约束

三者组合覆盖“搭界面 → 发布应用 → 正确使用免费 GPU”的完整链路，huggingface-zerogpu 的差异化在于：唯一深入到 ZeroGPU 执行模型内部（进程隔离、序列化边界、配额预检查算法）的技能，其余两者都停在“怎么用”的操作层面。

8. 用户评价

该技能已被 truefoundry.com、mcpservers.org 等第三方 Agent Skills 索引站点收录镜像，但这些页面均为技能自述内容的转载，不含独立评价文字；目前尚未检索到针对该技能的具名第三方用户评论。

9. 安装使用方式

Claude Code：

/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface/skills
hf skills add huggingface-zerogpu --claude --global

Codex： 将仓库 skills/huggingface-zerogpu 目录复制或软链接到 Codex 标准位置（如 $REPO_ROOT/.agents/skills 或 $HOME/.agents/skills），Codex 会按 Agent Skills 标准自动发现并加载。

安装后无需重启 Agent；触发条件是对话中出现 ZeroGPU、@spaces.GPU、spaces 包相关代码或上述报错关键词时自动加载。

10. 注意事项

仅适用于 Gradio SDK 的 Space——Docker 与 Static Space 无法调度到 ZeroGPU 硬件，Streamlit 应用现以 Docker Space 形式运行，同样不适用
技能明确提示 ZeroGPU 背后实际挂载的 GPU 型号会不定期迁移，具体显存与算力规格需查官方文档实时确认，不建议依赖技能正文里的历史型号描述
免费 ZeroGPU 存在访客侧每日配额限制，个人创建者可用但非无限资源，重度使用场景仍需评估专用 GPU 或付费额度