在 Hugging Face Spaces 上选…

需要在 Hugging Face Spaces 上托管 Gradio/Docker/Static 应用、使用 ZeroGPU 或专用硬件、排查构建/运行故障时使用。

适用场景

解决思路

1. 准备：检查 `hf` CLI 是否安装，运行 `which hf`；未安装则 `pip install -U huggingface_hub`。
2. 准备：检查登录状态，运行 `hf auth whoami`；未登录则运行 `hf auth login`，让用户打开打印出的 URL 并输入一次性 code，OAuth 会自动完成；也可从 https://huggingface.co/settings/tokens 获取 write 权限 token 并用 `--token` 传入。
3. 准备：记录 `whoami` 的 `canPay` 和 `isPro` 标志，它们决定可用硬件；免费账号只能托管 Static Spaces 和最多 2 个 ZeroGPU Spaces。
4. 准备：推荐安装配套 `hf-cli` skill，运行 `hf skills add hf-cli`；加 `--claude --global` 可同时为用户级 Claude Code 安装。
5. 理解 Space：Space 是 git repo，有三种 SDK：Gradio（多数 Space，Python，快速迭代，支持 ZeroGPU）、Docker（任意容器，非 Python 栈或预建模板，不支持 ZeroGPU）、Static（纯 HTML 或部署时构建的 React/Svelte/Vue，用于浏览器端 ML、项目页、交互报告、编排其他 Space，无需硬件）。
6. 理解硬件：Static Spaces 对所有人免费且无需硬件；Gradio 和 Docker Spaces 运行在计算资源上，创建需要付费计划（个人 PRO，组织 Team 或 Enterprise），例外是状态良好的免费个人账号可托管最多 2 个 ZeroGPU Spaces；因此免费账号上 ZeroGPU 是托管 Gradio Space 的唯一方式，`cpu-basic` 也不是安全回退，它同样受付费计划限制。
7. 理解 ZeroGPU：标识为 `zero-a10g`，在 NVIDIA RTX PRO 6000 Blackwell（sm_120）上按请求动态分配 GPU；两种大小：`large`（半 MIG，48 GB，1× quota）和 `xlarge`（全卡，96 GB，2× quota）；对 Space 创建者免费，访客消耗自己的每日 quota（免费约 5 分钟 / Pro 约 40 分钟 / Enterprise 约 60 分钟）；仅 Gradio、PyTorch 优先；账号托管上限为免费个人 2、PRO 10、Team/Enterprise 组织 50。
8. 理解 `cpu-basic`：2 vCPU / 16 GB，无小时费用但需要付费计划；适合数据可视化、API 代理 Space、小型 CPU 绑定模型。
9. 理解专用 GPU：T4、L4、A10G、L40S、A100、H200，按小时向 Space 创建者计费；用 `hf spaces hardware` 查看列表和价格；只有创建者且 `canPay=True` 才能附加；当 ZeroGPU 确实不适合时使用，例如非 PyTorch 主模型且初始化很重、超大模型长上下文推理等。
10. 如果用户需要自己付不起的硬件（专用 GPU，或超过免费 2 个 ZeroGPU 上限的 Gradio Space），仍可创建 Static Space（对所有人免费），把应用推上去，并申请社区 grant；见 `references/grants.md`。
11. 权威参考：https://huggingface.co/docs/hub/spaces-overview。
12. 先找现有 demo：构建前搜索先例，运行 `hf spaces search "<model name or task>" --sdk gradio --limit 10`。
13. 先找现有 demo：如果有人做过类似 Space，读它的 `app.py` 和 `requirements.txt` 获取可工作的模式；先告知用户你发现了什么，再决定方案。
14. 决定 SDK 和硬件：优先遵循用户明确请求；如果用户说得模糊，按下面规则选择。
15. 决定 SDK 和硬件：公开 ML demo 默认用 Gradio + ZeroGPU。
16. 决定 SDK 和硬件：如果模型唯一推理路径是非 PyTorch（ONNX / TF / JAX / vLLM 作为主模型且初始化很重），用专用 GPU；但在 torch 主流程中的边缘非 torch 工具（小 ONNX 预处理器、TF 工具）可以留在 ZeroGPU，因为 hijack 只 patch torch，在 `@spaces.GPU` 内初始化非 torch 库并支付短的 per-call 初始化成本即可。
17. 决定 SDK 和硬件：极小或 CPU 绑定模型、API 代理 Space 可用 `cpu-basic`，但它需要付费计划；免费账号可放到 `zero-a10g` 并加一个 no-op 装饰函数（ZeroGPU 至少需要一个），把真实工作放在它外面，这样永远不会请求 GPU，也就不消耗 quota；见 `references/inference-providers.md`。
18. 决定 SDK 和硬件：浏览器端 ML 或项目页用 Static。
19. 决定 SDK 和硬件：非 Python 栈容器用 Docker。
20. 模型来源：GitHub repo 可克隆到本地读结构；如果它已有 Gradio demo，最小可行路径是改到 ZeroGPU（见 `references/zerogpu.md`）；否则读 README 和推理代码，优先 PyTorch 路径，估算 VRAM（bf16 约 `params_B × 2` GB；48 GB 在 bf16 下可容纳 ≤24B 参数，量化后可更大，见 `references/zerogpu.md`）。
21. 模型来源：HF model repo 读它的 README，并跟进其中链接的 GitHub。
22. 模型来源：论文/博客寻找官方或非官方实现；除非实现很简单或用户明确要求，否则不要重新实现。
23. 模型来源：请求模糊时先搜索 Spaces 并展示结果。
24. 模型来源：如果模型确实放不下，检查 Inference Providers 作为替代方案，见 `references/inference-providers.md`，这样可以完全避免托管模型。
25. 创建 Space：运行 `hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> [--flavor zero-a10g|cpu-basic|<paid-flavor>] [--secrets KEY=val] [--env KEY=val] --public|--private|--protected --exist-ok`。
26. 创建 Space：`--space-sdk` 必填。
27. 创建 Space：`--flavor` 选择硬件；`zero-a10g` 是 ZeroGPU 的旧标识；省略会给 `cpu-basic`，而它本身受付费计划限制，所以免费账号要显式传 `--flavor zero-a10g`；运行 `hf spaces hardware` 查看完整付费列表和价格。
28. 创建 Space：可见性用 `--public`（任何人可查看）、`--private`（仅自己）、`--protected`（应用可达但 git repo / Files tab 私有）。
29. 创建 Space：`--secrets KEY=val` 会成为 Space 内环境变量且访客不可见；用于 API keys、gated repo token（`HF_TOKEN=hf_…`）等；之后也可用 `hf spaces secrets set <id> KEY=val` 设置。
30. 创建 Space：`--env KEY=val` 对访客可见；仅用于非敏感配置，例如 `GRADIO_SSR_MODE=false`、`PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True` 等。
31. 创建 Space：注意 README YAML 中的 `hardware:` 会被静默忽略；硬件只能在创建时通过 `--flavor` 设置，或之后通过 `hf spaces settings <id> --hardware <name>` 设置。
32. 构建应用：Space 创建后位于 `https://huggingface.co/spaces/<namespace>/<name>`，但内容是空的。
33. 构建应用：README.md frontmatter 始终必需，包含 `title`、`emoji`、`colorFrom`（仅 red|yellow|green|blue|indigo|purple|pink|gray）、`colorTo`、`sdk`（gradio|docker|static）、`sdk_version`（除非有理由，否则用最新稳定版）、`app_file`（仅 gradio；docker/static 分别用 Dockerfile/index.html）、`short_description`（≤60 字符，服务器拒绝更长）、`python_version`（ZeroGPU 官方支持 3.10.13 和 3.12.12）、`startup_duration_timeout`（默认 30m；大 LLM 或重下载调至 1h）。
34. 构建应用：SDK 版本默认当前最新稳定版，并查实际版本（`pip index versions gradio`，或看新创建 Space 默认版本）；仅当最新版确实不适用时才 pin 旧版：自定义组件已 pin，或改造已有 demo 不想重写 5.x→6.x breaking changes；需要 5.x 时选 `5.50.0`（该系列最新，仍支持自定义组件）。
35. 构建应用：所有 frontmatter 选项见 https://huggingface.co/docs/hub/spaces-config-reference。
36. 构建应用：最小 ZeroGPU Gradio 应用应包含：`import spaces` 必须在 torch / diffusers / transformers 之前；`import torch`、`import gradio as gr`、从 diffusers 加载 pipeline、用 `@spaces.GPU(duration=60)` 装饰函数、docstring 作为 API / MCP tool 描述、`gr.Interface(...).launch(mcp_server=True)`。
37. 构建应用：ZeroGPU 三条规则之一：`import spaces` 必须在 torch / 任何触碰 CUDA 的 import 之前；它 monkey-patch `torch.cuda.*`，一旦主进程初始化 CUDA 就太晚。
38. 构建应用：ZeroGPU 三条规则之二：在模块作用域加载模型并 eager `.to('cuda')`；ZeroGPU 会拦截调用，把权重打包到磁盘，并在首次进入 `@spaces.GPU` 时流入 VRAM；在装饰器内懒加载会让每个用户都付出成本。
39. 构建应用：ZeroGPU 三条规则之三：装饰 Gradio 绑定的函数；`duration` 估计为现实最坏情况（更小 = 更高队列优先级和更严格 quota 检查）；若运行时间依赖输入，传一个 callable。
40. 构建应用：在合理时添加 `gr.Examples`（应用有输入且存在代表性输入），优先用模型/repo 自己的官方示例；示例行只保留用户实际会变的少数输入（prompt、image），其余（steps、seed、guidance）给 handler 默认值，使一行是 `["a prompt"]` 而不是一堆旋钮；使用 `cache_examples=True, cache_mode="lazy"`；见 `references/gradio.md`。
41. 构建应用：给每个 API 触发的函数加 docstring 和类型提示；每个 Gradio event handler 都会通过 API 暴露，docstring + 签名是调用者和 MCP tool schema 看到的内容。
42. 构建应用：用 `demo.launch(mcp_server=True)` 启动（Gradio 5+），让 Space 兼作 MCP server：每个 API 函数按其 docstring 和 hints 变成一个 MCP tool。
43. 构建应用：requirements.txt 不要列出 `gradio`、`spaces`、`huggingface_hub`（预安装且由平台管理；pin 它们会导致解析失败或静默破坏 ZeroGPU runtime）。
44. 构建应用：如果使用则列出 `torchvision`、`torchaudio`（不预装），以及其他所有依赖（`diffusers`、`transformers`、`accelerate`、`sentencepiece` 等）。
45. 构建应用：ZeroGPU 只接受 torch `2.8.0`、`2.9.1`、`2.10.0`、`2.11.0`；默认不 pin torch（runtime 预装最新）；仅当依赖强制时才 pin。
46. 构建应用：对于预建 CUDA 扩展 wheel（`flash_attn`、`xformers`、`pytorch3d`、`nvdiffrast`、`diff_gaussian_rasterization`、`torchmcubes`），使用 `https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels` 的预建 Blackwell wheels；完整映射和注意事项见 `references/requirements.md`。
47. 构建应用：Gradio 模式（主题、`gr.Examples`、流式、自定义 HTML 组件、`gr.Server`）见 `references/gradio.md`。
48. 构建应用：Docker 见 https://huggingface.co/docs/hub/spaces-sdks-docker；示例用 `hf spaces list --filter docker`。
49. 构建应用：Static 见 https://huggingface.co/docs/hub/spaces-sdks-static；构建 SPA 时在 frontmatter 设 `app_build_command: npm run build` 和 `app_file: dist/index.html`。
50. 构建应用：ZeroGPU 具体内容（装饰器语义、sizing、AoTI、generators、concurrency、pickle / `gr.State` 跨 worker 边界）见 `references/zerogpu.md`；只要 Space 目标是 ZeroGPU 就要读。
51. 在 Space 上迭代而不是在本地：尽量在本地构建 release candidate 并推送，然后用 live URL 作为测试循环；Space 环境是唯一重要的环境，不要尝试本地测试；推送前最多做 `python3 -m py_compile app.py` 本地检查。
52. 在 Space 上迭代而不是在本地：用 `hf upload <namespace>/<name> . --repo-type space` 推送文件；`--repo-type space` 必填，因为 `hf upload` 默认到 model repo，否则会传到并静默创建同名 model repo；加 `--exclude "**/__pycache__/**"` 避免提交本地字节码缓存。
53. 在 Space 上迭代而不是在本地：推送后对每次改动选择最便宜的更新机制：纯 Python 编辑用 hot-reload，hot-reload 碰不了的文件用 `hf upload`，仅当 `requirements.txt` / `Dockerfile` / README frontmatter 实际改变时 full rebuild；完整阶梯和坑（hot-reload 毒化 factory reboot、runtime.sha 滞后等）见 `references/debugging.md`。
54. 验证：不要只信 `RUNNING`，应用可能正在运行但已损坏；按顺序执行四步。
55. 验证 A：存活？Stage + hardware 用 `hf spaces info <ns>/<name> --expand runtime`。
56. 验证 B：启动后日志是否干净？读运行日志确认启动完成且无警告或静默回退：`hf spaces logs <ns>/<name> --tail 200`；检查 model-load 完成、无 import 警告、无 “falling back to CPU” / dtype downgrade 消息、无 `RUNNING` 掩盖半坏应用。
57. 验证 C：API 是否实际响应？在另一个终端继续 tail 日志（`hf spaces logs <ns>/<name> --follow`）时调用端点：用 `gradio_client.Client`，`Client('<ns>/<name>', token=os.environ['HF_TOKEN'], httpx_kwargs={'timeout': 600})`，`print(c.view_api())` 发现端点不要猜，`result = c.predict(..., api_name='/generate')`。
58. 验证 D：嗅探输出和日志。HTTP 200 ≠ 正确输出；两者都检查：`head = open(result, 'rb').read(16)`，根据 magic bytes 判断 glTF / PNG / WebP / WAV / MP4（`\x89PNG`、`RIFF…WEBP`、`RIFF…WAVE`、`[4:8]==b'ftyp'`）；并查看调用期间发出的运行日志——静默回退（模型 snap 到不同 size、缺可选依赖、dtype downgrade）只在日志里显示。
59. 验证：完整 smoke-test 模式（流式端点、OAuth 门控 Space、`gr.Server` 自定义路由）见 `references/debugging.md`。
60. 持久存储：Space 无状态，`/data` 重启即擦除；若需要持久化用户上传、生成结果、日志，或与长期存储交互，挂载 bucket：`hf buckets create <ns>/<bucket-name>`（`--private` 可选）；`hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data`（读写挂到 `/data`）。
61. 持久存储：Buckets 是付费存储；检查 `canPay` 并与用户确认；完整模式（读快/写持久、公开 bucket URL、model-cache 反模式）见 `references/buckets.md`。
62. 出问题时：按顺序读日志：`hf spaces logs <id> --build --follow`（构建错误）或 `hf spaces logs <id> --follow`（运行时错误）；找第一个错误，不是最后一个。
63. 出问题时：在 `references/known-errors.md` 中 grep 错误字符串；先检查是否已知问题再自己修——多数常见 ZeroGPU / Gradio / 依赖错误都有 1–2 行修复。
64. 出问题时：使用 `references/debugging.md` 中最便宜的 rung 迭代；绝大多数问题通过读日志 + smoke-test 循环解决；交互式 dev mode + SSH 是重型最后手段。
65. 出问题时：如果解决了不在 known-errors 列表中的错误，建议用户 PR 回该 skill，让未来运行受益。
66. 参考索引：需要了解 ZeroGPU 工作原理和正确模式（装饰器、sizing、pickle、generators、real-time、AoTI）时读 `references/zerogpu.md`。
67. 参考索引：需要迭代 + 调试：日志、rung ladder、smoke testing（以及最后手段 dev mode + SSH）时读 `references/debugging.md`。
68. 参考索引：需要按错误字符串查找——所有错误症状（Spaces、ZeroGPU、Gradio、依赖）的唯一位置——时读 `references/known-errors.md`。
69. 参考索引：需要 pin 依赖、选 wheels、对齐 torch family 时读 `references/requirements.md`。
70. 参考索引：需要 `gr.Examples`（合理时添加）、主题、自定义 HTML 组件、`gr.Server`、MCP server（`mcp_server=True`）时读 `references/gradio.md`。
71. 参考索引：需要持久存储、公开 bucket URL 时读 `references/buckets.md`。
72. 参考索引：需要社区 grant 请求（用户付不起的硬件）时读 `references/grants.md`。
73. 参考索引：需要 provider proxy（通过 Cerebras / Fireworks / Together 等零 VRAM 跑大 LLM）时读 `references/inference-providers.md`。
74. 参考索引：需要 3D Spaces：生成、CUDA 扩展、输出格式、模型配方（含 gaussian splatting）时读 `references/3d-generation.md`。

适用边界 · 注意事项

• 不适用于非 Hugging Face Spaces 的部署场景，例如其他云、自托管、Kubernetes 或纯本地应用。
• 不适用于没有 Hugging Face 账号、无法安装或使用 `hf` CLI、或无法完成登录/授权的环境。
• 不适用于必须完全本地/离线开发且不能把 Space 作为测试循环的场景；也不适用于需要付费硬件但用户无 `canPay` 且无法申请社区 grant 的场景。