Skip to content

GROQ_SETUP.md

Latest commit

 

History

History
184 lines (127 loc) · 5.35 KB

GROQ_SETUP.md

File metadata and controls

184 lines (127 loc) · 5.35 KB

🤖 Configuración de Groq AI para Análisis de Métricas

📋 Requisitos

  • Cuenta en Groq Cloud (gratuita)
  • API Key de Groq

🚀 Pasos de Configuración

1. Obtener API Key

  1. Visita console.groq.com
  2. Crea una cuenta o inicia sesión
  3. Ve a API Keys en el menú lateral
  4. Haz clic en Create API Key
  5. Dale un nombre descriptivo (ej: "Learning Analytics")
  6. Copia la API key (solo se muestra una vez)

2. Configurar la Variable de Entorno

Abre el archivo .env.local en la raíz del proyecto y reemplaza:

GROQ_API_KEY=tu-api-key-aqui

Por tu API key real:

GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Reiniciar el Servidor de Desarrollo

pnpm dev

🎯 Modelos Disponibles

La integración utiliza los siguientes modelos de Groq:

Modelo por Defecto: llama-3.3-70b-versatile

Características:

  • ✅ Mejor opción para análisis educativo
  • 🧠 Excelente razonamiento y comprensión de contexto
  • 📊 Ideal para generar insights pedagógicos detallados
  • ⚡ Velocidad: ~300 tokens/segundo
  • 💰 Gratis con límites generosos

Límites del Plan Gratuito:

  • 30 requests/minuto
  • 14,400 tokens/minuto

Modelos Alternativos

Si necesitas ajustar el modelo, edita lib/actions/ai-analysis.ts:

const MODEL = 'llama-3.3-70b-versatile'; // Modelo actual

Opciones:

Modelo Pros Contras Uso Recomendado
llama-3.3-70b-versatile Mejor razonamiento, análisis profundo Ligeramente más lento ✅ Producción
llama-3.1-70b-versatile Muy estable y confiable Versión anterior Backup confiable
llama-3.1-8b-instant Ultra rápido (~800 tok/s) Menos detallado Pruebas rápidas
mixtral-8x7b-32768 Ventana de contexto grande Menos actualizado Documentos largos

🧪 Probar la Integración

  1. Inicia sesión como profesor
  2. Ve al dashboard de estudiantes
  3. Selecciona un estudiante con métricas
  4. Haz clic en "Generar Análisis"
  5. Espera 3-5 segundos
  6. Revisa el análisis generado

📊 Estructura del Análisis Generado

El LLM generará un reporte en Markdown con:

  1. 📊 Resumen Ejecutivo
  2. 🎯 Patrones de Aprendizaje Identificados
  3. 💪 Fortalezas Detectadas
  4. 🔍 Áreas de Oportunidad
  5. 📝 Recomendaciones Pedagógicas
  6. 🎓 Conclusión

⚙️ Configuración Avanzada

Ajustar Parámetros del Modelo

En lib/actions/ai-analysis.ts, puedes modificar:

const chatCompletion = await groq.chat.completions.create({
  model: MODEL,
  temperature: 0.7,      // Creatividad (0.0 = determinista, 1.0 = creativo)
  max_tokens: 2048,      // Longitud máxima de la respuesta
  top_p: 1,              // Diversidad de vocabulario
});

Recomendaciones:

  • temperature: 0.7: Balance perfecto para análisis educativo

    • Usa 0.5 para respuestas más conservadoras
    • Usa 0.9 para análisis más creativos

  • max_tokens: 2048: Suficiente para un reporte completo

    • Reducir a 1024 para respuestas más concisas
    • Aumentar a 4096 para análisis muy detallados

🔒 Seguridad

  • ✅ La API key está en .env.local (no se sube a Git)
  • ✅ Las llamadas se hacen desde el servidor ('use server')
  • ✅ Los datos del estudiante NO se almacenan en Groq
  • ✅ Groq usa el modelo en tiempo real sin guardar conversaciones

🐛 Solución de Problemas

Error: "API key no configurada"

Causa: La API key no está en .env.local o aún dice tu-api-key-aqui

Solución:

  1. Verifica que .env.local tenga la API key real
  2. Reinicia el servidor de desarrollo (Ctrl+C y pnpm dev)

Error: "Rate limit exceeded"

Causa: Excediste los límites del plan gratuito

Solución:

  • Espera 1 minuto antes de intentar otro análisis
  • Considera actualizar al plan pago de Groq si necesitas más requests

El análisis tarda mucho

Causa: El modelo 70B es más lento que los modelos pequeños

Solución:

  • Normal: 3-8 segundos para respuestas completas
  • Si tarda >15 segundos, verifica tu conexión a internet
  • Para pruebas rápidas, usa llama-3.1-8b-instant

El análisis está incompleto

Causa: max_tokens muy bajo o respuesta cortada

Solución:

  • Aumenta max_tokens a 3000 o 4096
  • Verifica que el prompt no sea excesivamente largo

📈 Mejores Prácticas

  1. Espera datos suficientes: El análisis es más útil cuando el estudiante tiene al menos 3-5 videos vistos
  2. No abuses del botón: Genera análisis solo cuando realmente lo necesites (límites de API)
  3. Revisa el contexto: El LLM analiza basándose en los datos disponibles
  4. Personaliza el prompt: Edita buildAnalysisPrompt() para ajustar el estilo del análisis

💡 Próximas Mejoras

  • Generación de PDF del reporte
  • Comparación entre estudiantes del mismo grupo
  • Análisis de tendencias temporales
  • Recomendaciones de contenido específico
  • Exportación a diferentes formatos

📚 Recursos

¿Problemas? Revisa los logs del servidor o abre un issue en el repositorio.