teste / docs /huggingface_spaces_troubleshooting.md
torxyton's picture
fix: Correções de importação e atualização da documentação v2.3.1
c579d54

A newer version of the Gradio SDK is available: 6.13.0

Upgrade

🚀 Guia de Troubleshooting - Hugging Face Spaces

Este guia aborda problemas comuns ao executar aplicações Gradio no Hugging Face Spaces e suas soluções.

🔥 Problemas Mais Comuns

1. Erro 500 - Internal Server Error

Sintomas:

  • Aplicação retorna erro 500 ao carregar
  • Interface não carrega completamente
  • Erro "Application startup failed"

Causa Principal: O Gradio 5.x usa Server-Side Rendering (SSR) por padrão no Hugging Face Spaces, o que pode causar conflitos e erros 500.

Solução:

# No seu app.py, adicione ssr_mode=False
demo.launch(ssr_mode=False)

# Ou configure via variável de ambiente
import os
os.environ['GRADIO_SSR_MODE'] = 'false'

Implementação no Projeto: O projeto já inclui configurações automáticas em hf_spaces_config.py que resolvem este problema.

2. Problemas de Autenticação

Sintomas:

  • Erro ao usar auth parameter
  • Login não funciona no HF Spaces

Causa: Problemas de compatibilidade entre Gradio 5.x e sistema de autenticação do HF Spaces.

Solução:

# Evite usar auth no HF Spaces
demo.launch(auth=None)  # Remover autenticação customizada

3. Problemas de Performance

Sintomas:

  • Aplicação lenta para carregar
  • Timeouts frequentes
  • Interface não responsiva

Soluções:

# Configurações otimizadas
demo.launch(
    max_threads=10,
    enable_queue=True,
    show_error=True
)

4. Problemas de Tema/CSS

Sintomas:

  • CSS customizado não carrega
  • Temas não aplicam corretamente

Solução:

# Use temas padrão para melhor compatibilidade
with gr.Blocks(theme='default') as demo:
    # Seu código aqui
    pass

🛠️ Configurações Recomendadas

README.md do HF Space

---
title: Seu App
emoji: 📈
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.44.0
app_file: app.py
pinned: false
license: mit
---

requirements.txt

gradio==5.44.0
# Suas outras dependências...

Configuração de Launch Otimizada

from hf_spaces_config import HuggingFaceSpacesConfig

# Aplicar configurações automáticas
HuggingFaceSpacesConfig.apply_hf_spaces_fixes()

# Usar configurações otimizadas
launch_config = HuggingFaceSpacesConfig.get_launch_config()
demo.launch(**launch_config)

🔍 Diagnóstico de Problemas

Verificar Logs do HF Spaces

  1. Acesse seu Space no HF
  2. Clique em "Logs" no canto superior direito
  3. Procure por mensagens de erro específicas

Testar Localmente

# Simular ambiente HF Spaces
export GRADIO_SSR_MODE=false
export GRADIO_ANALYTICS_ENABLED=false
python app.py

Verificar Compatibilidade

# Adicione no início do seu app.py
import gradio as gr
print(f"Gradio version: {gr.__version__}")

# Verificar se está no HF Spaces
import os
if os.getenv('SPACE_ID'):
    print(f"Running on HF Space: {os.getenv('SPACE_ID')}")
else:
    print("Running locally")

📋 Checklist de Compatibilidade

  • ssr_mode=False configurado
  • ✅ Gradio versão 5.44.0 ou superior
  • auth=None (sem autenticação customizada)
  • server_name='0.0.0.0' para acesso externo
  • enable_queue=True para melhor performance
  • ✅ Tema padrão ou compatível
  • ✅ CSS customizado testado
  • ✅ Dependências no requirements.txt
  • ✅ README.md com sdk_version correto

🚨 Problemas Conhecidos

Gradio 5.x + HF Spaces

  • SSR Mode: Causa erro 500 → Solução: ssr_mode=False
  • Node.js: SSR requer Node.js → Solução: Desabilitar SSR
  • Auth: Conflitos com auth customizada → Solução: Usar auth do HF

Erros de Importação de Módulos

2.1. AdvancedMarketProcessor não definido

# Adicionar no início do arquivo market_analysis.py
from src.core.advanced_market_processing import AdvancedMarketProcessor

2.2. TECHNICAL_CONFIG não definido

# Substituir TECHNICAL_CONFIG por TechnicalAnalysisConfig
# Em market_analysis.py
self.config = TechnicalAnalysisConfig  # ao invés de TECHNICAL_CONFIG

2.3. VotingStrategy não definido

# Criar arquivo __init__.py no diretório src/ai/
# Conteúdo do arquivo:
from .voting_system import VotingStrategy, intelligent_vote
from .ensemble_ai import ensemble_ai, EnsembleResult

__all__ = ['VotingStrategy', 'intelligent_vote', 'ensemble_ai', 'EnsembleResult']

Workarounds Temporários

# Se ainda tiver problemas, tente downgrade
# requirements.txt:
# gradio==4.44.1  # Versão estável anterior

📞 Suporte Adicional

Recursos Úteis

Reportar Problemas

  1. Verifique logs do HF Spaces
  2. Teste localmente com configurações similares
  3. Documente passos para reproduzir
  4. Inclua versões de dependências

💡 Dica: Este projeto já inclui todas as configurações necessárias em hf_spaces_config.py. Basta importar e usar!