hf-spaces-expert

prof-ramos's avatarfrom prof-ramos

This skill should be used when creating or configuring Hugging Face Spaces, including ZeroGPU hardware, secrets/env variables, persistent storage, repo-based deploys, and build/memory troubleshooting.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026⬇️1downloads
[Cloud Infrastructure]

When & Why to Use This Skill

This Claude skill serves as a specialized assistant for architecting, deploying, and optimizing machine learning applications on Hugging Face Spaces. It provides expert guidance on configuring ZeroGPU hardware, managing persistent storage, and resolving complex build or memory-related bottlenecks to ensure seamless application performance.

Use Cases

  • Case 1: Configuring ZeroGPU for heavy workloads, including implementing dynamic GPU duration logic to optimize queue priority and resource usage.
  • Case 2: Setting up persistent storage and environment secrets to securely handle model weights, API keys, and cached data at /data.
  • Case 3: Troubleshooting deployment issues such as build failures, startup timeouts, and Out-of-Memory (OOM) errors through dependency and concurrency optimization.
  • Case 4: Automating the creation of repository-based deployment configurations, including precise YAML metadata for SDK versions and hardware requirements.
namehf-spaces-expert
descriptionThis skill should be used when creating or configuring Hugging Face Spaces, including ZeroGPU hardware, secrets/env variables, persistent storage, repo-based deploys, and build/memory troubleshooting.

Hf Spaces Expert

Overview

Criar e ajustar Spaces do Hugging Face com foco em operacoes praticas (arquivos de app, dependencias, README) e otimizacao para workloads pesados em ZeroGPU.

Fluxo principal (workflow)

1) Coletar contexto minimo

  • Confirmar SDK (preferir Gradio para ZeroGPU) e nome do Space/repo.
  • Confirmar necessidade de ZeroGPU, Storage persistente e Secrets/Env.
  • Confirmar entradas/saidas principais do app e tamanho tipico dos PDFs.
  • Identificar limites de tempo de execucao por job e requisitos de concorrencia.

2) Configurar README.md (YAML)

  • Escrever o bloco YAML do README.md com sdk, app_file, python_version, sdk_version e title.
  • Definir suggested_hardware e suggested_storage quando quiser orientar duplicacoes.
  • Ajustar startup_duration_timeout quando o boot inicial for pesado.
  • Usar preload_from_hub quando modelos/arquivos grandes precisarem baixar no build.

Exemplo minimo (adaptar):

---
title: Docling Space
emoji: ":page_facing_up:"
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
python_version: 3.10
sdk_version: 4.44.1
suggested_hardware: "cpu-basic"
suggested_storage: "small"
startup_duration_timeout: 45m
---

3) Configurar dependencias

  • Declarar pacotes Python em requirements.txt.
  • Usar pre-requirements.txt se precisar atualizar pip/compiladores antes.
  • Usar packages.txt para dependencias Debian (ex.: libs de imagem/PDF).

4) Implementar/ajustar app.py

  • Estruturar processamento de PDF em etapas curtas e isoladas.
  • Reduzir uso de memoria com:
    • Processamento por paginas/lotes.
    • Liberacao explicita de objetos grandes.
    • Escrita de artefatos intermediarios em /data quando houver storage persistente.
  • Controlar concorrencia para evitar OOM:
    • Limitar workers e tamanho de fila no Gradio.
    • Evitar processar multiplos PDFs longos em paralelo.

5) ZeroGPU e gestao de filas

  • Usar @spaces.GPU para funcoes GPU-bound.
  • Definir duration para otimizar prioridade de fila.
  • Implementar duracao dinamica baseada no tamanho do PDF (paginas, MB, etc.).
  • Evitar torch.compile; preferir AOT se necessario.

Exemplo de duracao dinamica (adaptar ao fluxo real):

import spaces

def duration_from_pages(pages_count: int) -> int:
    base = 30
    per_page = 2
    return base + per_page * pages_count

@spaces.GPU(duration=duration_from_pages)
def process_pdf(file_path: str, pages_count: int):
    ...

6) Secrets/Env e Storage persistente

  • Criar variaveis e secrets no Settings do Space; evitar hard-code.
  • Ler variaveis com os.getenv (Gradio/Spaces padrao).
  • Quando houver storage persistente:
    • Usar /data para cache e outputs.
    • Definir HF_HOME=/data/.huggingface para evitar downloads repetidos.

7) Deploy por repositorio

  • Manter app.py, requirements.txt, README.md na raiz do repo.
  • Lembrar que cada git push dispara rebuild.
  • Documentar no README instrucoes de uso e limites conhecidos (ex.: tamanho maximo de PDF).

8) Troubleshooting (build/memoria)

  • Build falhando: validar requirements.txt, pre-requirements.txt, packages.txt.
  • Timeouts de startup: ampliar startup_duration_timeout no YAML.
  • OOM: reduzir concorrencia, baixar batch size, usar /data para evitar memoria RAM.
  • ZeroGPU lento: diminuir duration quando possivel e reduzir cargas GPU por job.

Recursos

  • Referencia oficial local: references/hf_spaces_docs.md
    • Usar para checar fatos especificos sobre ZeroGPU, Storage, Secrets/Env e YAML do README.