Hugging Face's logo

Spaces:
guifav
/
rag_template
Sleeping

App Files Community
rag_template / docs /SPACES_LIMITATIONS.md
Guilherme Favaron
Sync: Complete project update (Phase 6) - API, Metadata, Eval, Docs
a686b1b
preview code
|
raw
history blame contribute delete
7.46 kB

A newer version of the Gradio SDK is available: 6.6.0

Upgrade

Limitacoes do Hugging Face Spaces

Guia completo sobre limitacoes ao usar o RAG Template no Hugging Face Spaces.

Hardware Spaces (Free Tier)

CPU Basic

Recursos:

  • 2 vCPU
  • 16 GB RAM
  • 50 GB disco

Limitacoes:

  • Sem GPU (embeddings e inference via CPU)
  • Cold start: 30-60 segundos
  • Timeout: 60 segundos por request

Limitacoes de Performance

Embeddings

Modelo: sentence-transformers/all-MiniLM-L6-v2

Performance:

  • Geracao: ~100-200ms por documento (CPU)
  • Batch de 10 docs: ~1-2 segundos
  • Upload de 100 docs: ~10-20 segundos

Recomendacoes:

  • Limite uploads a 50-100 documentos por vez
  • Use documentos menores (<10 paginas)
  • Evite PDFs muito grandes (>5MB)

Busca Vetorial

Performance:

  • Query simples: 50-150ms
  • Hybrid search: 100-300ms
  • Com reranking: 200-500ms

Recomendacoes:

  • Limite top_k a 10 ou menos
  • Use reranking apenas quando necessario
  • Considere indices otimizados (IVFFLAT)

Geracao de Respostas

HuggingFace Inference API (Free)

Limites:

  • ~30,000 tokens/hora
  • Queue em horarios de pico
  • Timeout de 60 segundos
  • Modelos limitados

Performance:

  • Geracao: 2-10 segundos
  • Pode ter espera na queue
  • Tokens/segundo: variavel

Recomendacoes:

  • Use modelos menores (7B parameters)
  • Limite max_tokens a 512
  • Evite uso intensivo em pico

OpenAI / Anthropic

Limites:

  • Baseado em creditos da conta
  • Rate limits por tier
  • Custos por token

Performance:

  • GPT-3.5: ~1-3 segundos
  • GPT-4: ~3-10 segundos
  • Claude: ~2-5 segundos

Limitacoes de Database

Espaco de Armazenamento

O Space em si nao armazena dados persistentes. Voce precisa de banco externo:

Supabase Free

  • Storage: 500MB
  • Documentos: ~300,000 chunks pequenos
  • Embeddings (384d): ~1.5KB por documento
  • Estimativa: 500MB = ~330k documentos

Calculo:

Documento medio: 1000 chars = 1 chunk
Embedding: 384 floats * 4 bytes = 1536 bytes
Metadata: ~100 bytes
Total: ~1.6KB por documento

500MB / 1.6KB = ~312,500 documentos

Neon Free

  • Storage: 10GB
  • Documentos: ~6M chunks pequenos
  • Compute: 100 horas/mes

Connection Limits

Supabase Free

  • Conexoes simultaneas: ~50
  • Pooling: Sim (pgBouncer)

Neon Free

  • Conexoes simultaneas: 1000
  • Pooling: Sim (integrado)

Recomendacao: Configure connection pooling no app.

Cold Start

O que e Cold Start?

Quando seu Space nao recebe requests por algum tempo, ele "dorme". No proximo acesso:

  1. Container reinicia
  2. Dependencias carregam
  3. Modelos baixam
  4. Banco conecta

Tempo total: 30-60 segundos

Como Mitigar

  1. Keep-alive simples:

    # Ping a cada 10 minutos (externamente)
curl https://seu-space.hf.space

  2. Upgrade para persistente:

    • Spaces Pro: Sem cold start
    • Custo: $5-20/mes

Timeouts

Request Timeout

Limite: 60 segundos

Impacto:

  • Uploads muito grandes podem falhar
  • Geracao longa pode timeout
  • Processos pesados podem ser interrompidos

Solucoes:

  1. Divida uploads grandes em batches
  2. Limite max_tokens
  3. Use modelos mais rapidos
  4. Otimize queries

Idle Timeout

Free Tier: Space pausa apos ~15 minutos sem uso

Pro: Sem pause

Limites de Rede

Bandwidth

Free Tier: Ilimitado (com fair use)

Upload:

  • Limite pratico: ~100MB por arquivo
  • Multiple uploads: OK

Download:

  • Responses: Sem limite oficial
  • Fair use aplicado

Limitacoes de Features

Nao Disponivel no Spaces Free

  1. GPU: Apenas CPU (ou upgrade)
  2. Persistencia de dados: Precisa banco externo
  3. Scheduled jobs: Nao suportado
  4. WebSockets persistentes: Limitado
  5. Custom domains: Apenas em Pro

Disponivel

  1. Gradio interface: Totalmente suportado
  2. PostgreSQL externo: Supabase/Neon/Railway
  3. API calls: OpenAI, Anthropic, HF
  4. File uploads: Temporarios (perdidos no restart)
  5. Secrets management: Sim

Comparacao: Free vs Pro

Feature Free Pro ($5/mes)
CPU 2 vCPU 4 vCPU
RAM 16 GB 32 GB
Disco 50 GB 100 GB
Cold start Sim Nao
Timeout 60s 120s
Priority queue Nao Sim
Custom domain Nao Sim

Recomendacoes de Uso

Para Demo/Portfolio

Configuracao ideal:

  • Supabase Free (500MB)
  • HuggingFace Inference API
  • ~100-1000 documentos
  • Top_k: 3-5
  • Max_tokens: 256-512

Usuarios simultaneos: 5-10

Para Desenvolvimento

Configuracao ideal:

  • Neon Free (10GB)
  • Qualquer LLM provider
  • ~1000-5000 documentos
  • Testes de features

Usuarios simultaneos: 1-2 (voce)

Para Producao

Nao recomendado Free Tier

Upgrade necessario:

  • Spaces Pro ($5-20/mes)
  • Supabase Pro ($25/mes)
  • LLM provider pago

Ou:

  • Deploy proprio (Railway, Render, VPS)
  • Mais controle e recursos

Otimizacoes Recomendadas

1. Cache Embeddings

Ja implementado no template:

# Embeddings sao cacheados automaticamente
# Evita reprocessar mesmos documentos

2. Batch Processing 

# Processe multiplos documentos de uma vez
# Mais eficiente que um por um

3. Lazy Loading 

# Modelos carregam apenas quando necessario
# Reduz cold start

4. Connection Pooling 

# Reusa conexoes de banco
# Evita overhead de novas conexoes

Monitoramento

Metricas Disponiveis

  1. Logs: Via interface do Space
  2. Usage: Dashboard do HF
  3. Database: Dashboard do provider

O que Monitorar

  • Cold starts: Frequencia
  • Timeouts: Quantas requests falham
  • Database size: Proximo do limite?
  • API usage: LLM provider credits

Troubleshooting

"Application startup timeout"

Causa: Modelos muito grandes ou muitas dependencias

Solucao:

  1. Reduza dependencias
  2. Use modelos menores
  3. Upgrade para Pro

"Request timeout"

Causa: Operacao demora >60s

Solucao:

  1. Divida em batches menores
  2. Reduza max_tokens
  3. Use modelo mais rapido

"Out of memory"

Causa: Modelos ou dados muito grandes

Solucao:

  1. Use modelo de embedding menor (384d)
  2. Limite batch size
  3. Upgrade para Pro

"Database connection failed"

Causa: Banco pausado ou limites excedidos

Solucao:

  1. Verifique se banco esta ativo
  2. Verifique connection string
  3. Verifique limites de conexao

Alternativas ao Spaces

Se limitacoes sao problematicas:

Railway

  • $5/mes credito
  • Mais controle
  • Deployment completo

Render

  • Free tier generoso
  • 750h/mes compute
  • Hibernacao apos 15min

VPS (DigitalOcean, Linode)

  • $5-10/mes
  • Controle total
  • Requer setup manual

Local

  • Gratuito
  • Sem limitacoes
  • Apenas para voce

Conclusao

Hugging Face Spaces Free e excelente para:

  • Demos e portfolios
  • Prototipos e MVPs
  • Aprendizado e testes
  • Projetos pessoais pequenos

Nao recomendado para:

  • Producao em escala
  • Aplicacoes criticas
  • Multiplos usuarios simultaneos
  • Processamento pesado continuo

Para producao, considere upgrade ou deploy proprio.

Recursos Adicionais

Feito com muito cafe