Spaces:

MalcomNavarro
/

hf-gaia-agents-course-MN

Sleeping

App Files Files Community

hf-gaia-agents-course-MN / DEPLOY_QUICKSTART.md

Mahynlo

Final Version

82c91df 12 days ago

preview code

raw

history blame contribute delete

8.56 kB

📦 Guía de Deploy Exitoso a Hugging Face Spaces

🎉 RESULTADO: Deploy Exitoso - Meta Alcanzada (30%)

Space URL: https://huggingface.co/spaces/MalcomNavarro/hf-gaia-agents-course-MN Score Final: 30.0% (6/20 correctas) ✅ Modelo: Gemini 2.5 Flash Fecha: Octubre 2025

🚀 Pasos para Deploy (Verificados)

1. Pre-Deploy Checklist ✅

✅ Variable GEMINI_API_KEY unificada en código
✅ Todas las dependencias en requirements.txt (37 paquetes)
✅ Dependencias de sistema en packages.txt (ffmpeg, tesseract)
✅ Modelo actualizado a gemini/gemini-2.5-flash
✅ Rate limiting implementado (20s entre preguntas)
✅ Logging mejorado con timestamps y emojis
✅ App corregido para pasar archivos al agent
✅ Límite de 2 preguntas eliminado
✅ Test suite creado (test_agent.py)
✅ 15 herramientas configuradas y funcionando

2. Configurar Secret en HF Spaces ✅

Ve a tu Space: https://huggingface.co/spaces/[TU_USERNAME]/[TU_SPACE]
Click en Settings
Scroll a Repository secrets
Click Add a secret
Configurar:
- Name: GEMINI_API_KEY (EXACTO, case-sensitive)
- Value: Tu API key de Google AI Studio (https://aistudio.google.com/apikey)
- Click Add

✅ Verificado funcionando: La key se inyecta automáticamente como variable de entorno.

3. Estructura de Archivos Final ✅

hf-gaia-agents-course-MN/
├── app.py                      # Gradio UI con logging mejorado
├── agents.py                   # Agent wrapper de smolagents
├── model.py                    # Gemini model wrapper con retry
├── tool.py                     # Registry de 15 herramientas
├── tools/
│   ├── __init__.py            # Package init
│   └── tools.py               # Custom tools (vision, YouTube, OCR, etc.)
├── utils/
│   └── logger.py              # Logger configuration
├── api.py                     # API client (opcional)
├── requirements.txt           # 37 dependencias Python
├── packages.txt               # 2 dependencias sistema (ffmpeg, tesseract)
├── test_agent.py              # Test suite
├── README.md                  # Con metadata OAuth
└── *.md                       # Documentación

Archivos de documentación:
├── DIAGNOSTIC_REPORT.md
├── CORRECCIONES_APLICADAS.md
├── DEPLOY_QUICKSTART.md (este archivo)
├── RATE_LIMIT_FIX.md
├── READY_TO_DEPLOY.md
└── RESUMEN_IMPLEMENTACION.md

4. Push a HF Spaces ✅

# Ver estado
git status

# Agregar todos los cambios
git add .

# Commit con mensaje descriptivo
git commit -m "Improve logging with timestamps, emojis, and progress tracking"

# Push a HF Spaces (origin apunta a huggingface.co)
git push

# Ver logs del build en HF Spaces
# https://huggingface.co/spaces/[USERNAME]/[SPACE]/logs

5. Monitorear Build ✅

Build exitoso muestra:

Installing dependencies from requirements.txt...
✓ gradio==5.49.1
✓ smolagents>=0.1.0
✓ litellm>=1.0.0
✓ google-generativeai>=0.8.0
... (33 más)

Installing system packages from packages.txt...
✓ ffmpeg
✓ tesseract-ocr

Starting Gradio app...
Running on http://0.0.0.0:7860

Errores comunes resueltos:

✅ youtube-transcript-api==0.6.0 (versión específica, no 3.0.0)
✅ ddgs>=0.0.1 (DuckDuckGo search dependency)
✅ wikipedia-api>=0.5.0 (Wikipedia tool dependency)
✅ markdownify y requests (VisitWebpageTool dependencies)

6. Ejemplo de Logs de Ejecución Exitosa ✅

================================================================================
[07:27:28] ℹ️  🚀 GAIA BENCHMARK EVALUATION STARTED
================================================================================

[07:27:28] ✅ User authenticated: MalcomNavarro
[07:27:28] ℹ️  Initializing agent...
[07:27:28] ✅ Agent initialized with model: gemini/gemini-2.5-flash
[07:27:28] ℹ️  Tools loaded: 15 tools available

[07:27:28] ℹ️  Fetching questions from scoring server...
[07:27:28] ✅ Fetched 20 questions from server
[07:27:28] ℹ️  Questions include: 5 with files

================================================================================
[07:27:28] ℹ️  🤖 STARTING AGENT EVALUATION
================================================================================

[07:27:28] 🔄 [1/20] Starting question 1
[07:27:28] ℹ️  Processing task abc123
[07:27:28] ℹ️  Question: How many studio albums were published...
[07:27:28] ℹ️  Building context...
[07:27:28] ℹ️  🤖 Running agent reasoning...
[07:27:40] ℹ️  🧹 Cleaning answer...
[07:27:40] ℹ️  ✨ Final answer: 3
[07:27:40] ✅ Task abc123 completed: 3

[07:27:40] ℹ️  ⏳ Waiting 20 seconds before next question (Rate limit: 10 req/min)
[07:27:40] ℹ️  📊 Progress: 1/20 completed | 19 remaining (~6 min left)
======================================================================

... (18 preguntas más con mismo formato) ...

[07:33:20] ✅ All 20 questions processed!

================================================================================
[07:33:20] ℹ️  📤 PREPARING SUBMISSION
================================================================================

[07:33:20] ℹ️  Submitting to scoring server...
[07:33:28] ✅ 🎉 SUBMISSION SUCCESSFUL!
[07:33:28] ✅ 📊 Score: 30.0% (6/20 correct)
[07:33:28] ℹ️  Message: Score calculated successfully
================================================================================

📊 Métricas de Rendimiento

Tiempo de Ejecución

Build time: ~3-5 minutos
Evaluation time: ~8-10 minutos (20 preguntas)
Total: ~15 minutos desde push hasta score

Rate Limits (Free Tier)

Modelo: Gemini 2.5 Flash
Límite: 10 requests/minuto
Delay: 20 segundos entre preguntas
Retry: 5 intentos con exponential backoff

Recursos Utilizados

Memoria: ~2-3 GB (Whisper, Transformers, etc.)
CPU: Suficiente para Gradio + LLM calls
Disk: ~500 MB (dependencias)

🎯 Score Final y Meta del Curso

Resultado Alcanzado ✅

📊 Score: 30.0%
✓ Correct: 6/20
� User: MalcomNavarro
📅 Date: Octubre 2025
🤖 Model: Gemini 2.5 Flash

Meta del Curso

✅ Meta mínima: 30% (ALCANZADO)
📈 Meta buena: 40-50%
🏆 Meta excelente: >50%

Breakdown de Preguntas

Total intentadas: 20
Correctas: 6
Incorrectas: 14
Con archivos: 5
Solo texto: 15

💡 Lecciones Aprendidas

✅ Lo que funcionó:

smolagents framework - Excelente manejo de herramientas
Gemini 2.5 Flash - Buen balance costo/rendimiento
Logging detallado - Facilita debugging enormemente
Rate limiting - Previene errores 429
Múltiples tools - Cubren diversos tipos de preguntas

⚠️ Desafíos:

Free tier restrictivo - 10 req/min vs 250 req/min (paid)
Tiempo de evaluación - ~10 minutos por rate limits
Dependencias ocultas - Algunos packages no documentados

🚀 Recomendaciones futuras:

Usar API key paga para 25x más velocidad
Implementar caching de respuestas
Mejorar prompts con más ejemplos GAIA
Fine-tuning específico para benchmark GAIA

📝 Comandos Útiles

# Ver logs en tiempo real
git log --oneline -10

# Ver cambios pendientes
git status

# Ver diferencias
git diff app.py

# Ver branches
git branch

# Crear nuevo branch
git checkout -b feature/mejora

# Push a branch específico
git push origin main

# Ver remote URLs
git remote -v

🔗 Enlaces Importantes

Space URL: https://huggingface.co/spaces/MalcomNavarro/hf-gaia-agents-course-MN
Repo URL: https://huggingface.co/spaces/MalcomNavarro/hf-gaia-agents-course-MN/tree/main
Logs: https://huggingface.co/spaces/MalcomNavarro/hf-gaia-agents-course-MN/logs
Settings: https://huggingface.co/spaces/MalcomNavarro/hf-gaia-agents-course-MN/settings
Gemini API: https://aistudio.google.com/apikey
Rate Limits: https://ai.google.dev/gemini-api/docs/rate-limits
GAIA Benchmark: https://huggingface.co/gaia-benchmark
Curso HF: https://huggingface.co/learn/agents-course/unit4/hands-on

✅ Deploy Exitoso - Meta Alcanzada (30%) 🎉

Stack Final: Python 3.10+, Gradio 5.x, Gemini 2.5 Flash, LiteLLM, smolagents
Fecha: Octubre 2025
Malcom Navarro Licencia: MIT