Spaces:

ecotecds
/

Chatbot-RAG-v4

Running

App Files Files Community

Chatbot-RAG-v4 / README.md

NoeMartinezSanchez

Actualizacion del readme

7df5984 2 days ago

preview code

raw

history blame contribute delete

13.8 kB

metadata

title: Chatbot RAG PLS
emoji: 🤖
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

🤖 Prepa en Línea SEP - Asistente Educativo RAG

Asistente virtual con tecnología RAG (Retrieval-Augmented Generation) para estudiantes de Prepa en Línea SEP. Chatbot educativo que responde dudas sobre Convocatoria, Normativa, Protocolos y Guías del programa.

🎯 Características Principales

RAG con Groq API: Sistema de Retrieval-Augmented Generation usando LLaMA 3.3 70B Versatile vía Groq API
Sin GPU necesaria: Todo via APIs externas (Groq, embeddings); ejecución en CPU
Búsqueda Vectorial: FAISS con embeddings multilingües optimizados para español
Soporte Multi-formato: Procesa PDF, Word (docx), Excel (xlsx) y TXT
Re-ranking y Query Expansion: Calidad preservada con menos chunks (top_k=5)
Interfaz Web: Dashboard responsive tipo chat

🛠️ Tecnologías

Categoría	Tecnología
Framework API	FastAPI + Uvicorn
LLM	Groq API — LLaMA 3.3 70B Versatile
Embeddings	intfloat/multilingual-e5-small (local, 384 dims)
Vector Store	FAISS (cpu, FlatL2, top_k=5 optimizado)
Re-ranking	Activado con query expansion
Procesamiento Documentos	PyMuPDF (PDF), python-docx (Word), openpyxl (Excel)
Frontend	HTML/CSS/JS Vanilla (responsive)
Despliegue	Docker · Hugging Face Spaces
Orquestación	Ninguna (sin Celery/Redis, respuestas directas)
Evaluación Automática	Desactivada por defecto (ahorro de tokens)

⚡ Optimización de Tokens (Groq API)

Problema Identificado

Consumo excesivo de ~4,500 tokens por consulta que agotaba el límite gratuito de 100K tokens en menos de 25 interacciones.

Soluciones Implementadas

Optimización	Antes	Después	Reducción
Chunks de contexto	10 chunks	5 chunks	50% menos tokens
Prompt del sistema	~250 tokens	~60 tokens	76% menos
TOP_K_RESULTS	10	5	50% menos chunks

Resultados Clave

Métrica	Antes	Después	Mejora
Tokens por consulta	~4,500	~1,500	67% menos
Consultas diarias posibles	20-22	60-65	+200%
Margen de seguridad	0%	70%	✅

Mecanismos que Preservan la Calidad

Re-ranking activado: los 5 chunks finales son los más relevantes
Filtrado por metadata: elimina chunks no relacionados al contexto
Query expansion: expande la consulta para mejor recall sin añadir tokens al LLM

Configuración Final Optimizada

# optimized_retriever.py
self.config = {
    "top_k_initial": 10,
    "top_k_final": 5,
    "min_similarity": 0.2,
    "use_reranking": True,
    "use_query_expansion": True,
    "use_multi_query": True,
}

Prompt Optimizado

# gemma_generator.py → GroqWrapper
system_msg = "Eres asistente de [CLIENTE]. Respuestas claras en español."
user_prompt = f"Contexto oficial: {context}\n\nPregunta: {question}\n\nRespuesta:"

⚠️ El sistema está optimizado para consumir ~1,500 tokens por consulta, permitiendo ~65 interacciones diarias en la capa gratuita de Groq API. El margen de seguridad es del 70%.

📊 Dashboard de Métricas Avanzadas

Problemas resueltos

Problema	Solución
Confianza del 98.6% pero respuestas inútiles	Tasa de Éxito Real: detecta respuestas como "no encontré información"
No se veía distribución horaria de consumo	Gráfico ASCII por hora: muestra picos de consumo de tokens

Métricas implementadas

1. Tasa de Éxito Real (Calidad de respuestas)

Detecta patrones de respuestas no útiles: "no encontré información", "tuve un problema", "intenta de nuevo"
Diferencia entre confianza del sistema vs utilidad real

2. Consumo de tokens por hora

Gráfico ASCII mostrando consumo en últimas 24 horas
Identifica horas pico (ejemplo: 04:00 AM con 2,777 tokens)

Ejemplo del dashboard

┌──────────────────────────────────────────────────────────────────┐
│ 📊 Tasa de Éxito: 94%                                           │
│ útiles: 135 | no útiles: 8                                      │
│ ████████████████████████████████████████░░░░░░░░ 94%            │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ 📈 Consumo de Tokens por Hora                                   │
│                                                                  │
│ 04:00 │ ████████████████████ 2777 tokens                        │
│ 20:00 │ ████████████████ 2345 tokens                            │
│ 23:00 │ ████████ 1234 tokens                                    │
│                                                                  │
│ 🔵 Pico máximo: 2777 tokens/hora | 📊 Promedio: 1850 tokens/hora │
└──────────────────────────────────────────────────────────────────┘

Beneficios

Antes: "El sistema tiene 98.6% de confianza" (métrica engañosa)
Ahora: "94% de respuestas RAG son útiles, 6% son 'no encontré información'"
Permite identificar consultas problemáticas y horas de mayor carga

Acceso

El dashboard está disponible en: /user-dashboard

🔄 CI/CD Pipeline

¿Qué es y por qué lo necesitamos?

CI/CD automatiza pruebas y despliegues. Cada cambio en el código se valida automáticamente antes de llegar a producción.

Beneficio	Antes	Después
Detección de errores	En producción (usuarios afectados)	Antes del despliegue (2-3 minutos)
Tiempo de recuperación	15-30 minutos manual	0 minutos (no se despliega código roto)
Confianza en despliegues	Baja	Alta (pruebas automáticas)
Despliegue a HF Spaces	Manual con git push --force	Automático al hacer push a main

Arquitectura del Pipeline

git push → GitHub Actions → Pruebas automáticas → ¿OK? → Despliegue a HF Spaces
                                                          ↓
                                             [Fallo] → Notificar (pendiente)

Pruebas implementadas

Prueba	Qué verifica	Tiempo
Conexión Groq	API key válida, modelo responde	2 seg
Importación API	Sin errores de sintaxis o imports	1 seg
GroqWrapper	Inicialización correcta	1 seg
RAGSystem	Carga de índices FAISS (108 vectores)	2 seg

Tiempo total del pipeline: ~1 min 38 seg

Flujo de trabajo

name: CI/CD - Test & Deploy
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - Checkout código
      - Setup Python 3.11
      - Instalar dependencias
      - Verificar archivos críticos
      - Test conexión Groq (real)
      - Test importación API
      - Test RAG system

  deploy:
    needs: test
    if: success()
    - Despliegue automático a Hugging Face Spaces

Variables de entorno requeridas (GitHub Secrets)

Secret	Propósito
`GROQ_API_KEY`	Autenticación con Groq para pruebas reales
`HF_TOKEN`	Autenticación para desplegar a Hugging Face Spaces

Resultados obtenidos

✅ Tasa de éxito de pruebas: 100%
✅ Tiempo de detección de errores: 2 minutos
✅ Impacto en usuarios por errores: 0 (nunca se despliega código roto)
✅ Despliegues automáticos: Funcionando

Compatibilidad con otros destinos

El pipeline es portable. Para migrar a VPS, AWS o Docker Hub solo se necesita agregar un step adicional:

# Ejemplo: despliegue a VPS con Docker
- name: Deploy to VPS
  uses: appleboy/ssh-action@v1.0.0
  with:
    host: ${{ secrets.VPS_HOST }}
    script: docker-compose up -d

Próximas mejoras

Prioridad	Acción	Impacto
1	Cache de pip en workflow	Reduce tiempo 90s → 30s
2	Notificaciones a Telegram/Slack	Visibilidad inmediata de fallos
3	Pruebas unitarias por módulo	Mayor cobertura
4	Smoke test post-despliegue	Verifica que HF reconstruyó bien

📁 Estructura del Proyecto

Chatbot-RAG-Fuente-Base/
├── api/
│   ├── main.py              # FastAPI + diagnóstico FAISS
│   └── endpoints.py         # Endpoints /upload, /search
├── rag/
│   ├── core.py              # RAGSystem principal
│   ├── gemma_generator.py   # Generador → GroqWrapper
│   ├── generator.py         # Generator legacy (TinyLlama, no usado)
│   ├── optimized_retriever.py  # Retrieval con expansión de queries
│   ├── retriever.py         # VectorStoreFAISS
│   └── embeddings.py        # EmbeddingModel (e5-small)
├── models/
│   ├── groq_wrapper.py      # Groq API wrapper (LLaMA 3.3 70B)
│   ├── gemini_wrapper.py    # Gemini API wrapper (alternativa)
│   ├── ollama_wrapper.py    # Legacy (no usado)
│   └── tinyllama_wrapper.py # Legacy (no usado)
├── evaluation/
│   ├── automated_evaluator.py  # Tests automáticos
│   ├── generate_dashboard.py   # Visualización de resultados
│   └── test_set.json           # 20 preguntas de evaluación
├── scripts/
│   └── load_chunks_to_rag.py   # Carga de documentos al vector store
├── config/
│   └── settings.py          # Configuración centralizada
├── static/
│   └── index.html           # Frontend web responsive
├── data/
│   └── vector_store/        # Índice FAISS + metadatos
├── Dockerfile               # Imagen Docker para HF Spaces
└── requirements.txt         # Dependencias Python

🚀 Instalación Local

# 1. Clonar repositorio
git clone https://github.com/tu-usuario/Chatbot-RAG-Fuente-Base.git
cd Chatbot-RAG-Fuente-Base

# 2. Crear entorno virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 3. Instalar dependencias
pip install -r requirements.txt

# 4. Configurar variables de entorno (crear archivo .env)
# Obtén tu API Key en https://console.groq.com/keys
echo "GROQ_API_KEY=tu_api_key_aqui" > .env

# 5. Cargar documentos al vector store
python scripts/load_chunks_to_rag.py

# 6. Iniciar API
uvicorn api.main:app --reload

📖 Uso de la API

Endpoint Principal

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "¿El módulo propedéutico es obligatorio?"}'

Respuesta

{
  "response": "Sí, el módulo propedéutico es obligatorio.",
  "sources": ["bases_convocatoria_g85.pdf"],
  "is_rag_response": true,
  "confidence": 0.85
}

Documentación API

Swagger UI: http://localhost:8000/api/docs
ReDoc: http://localhost:8000/api/redoc

🧪 Validación del Sistema

4 preguntas críticas para verificar que el RAG funciona correctamente:

Pregunta	Respuesta Esperada
¿El módulo propedéutico es obligatorio?	Sí
¿Qué significa escribir en mayúsculas?	Gritar
¿Cuánto dura la prepa?	2 años 6 meses
¿La prepa es gratuita?	Sí, completamente gratis

# Probar validación
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "¿El módulo propedéutico es obligatorio?"}'

🌐 Despliegue

Hugging Face Spaces (Docker)

El proyecto incluye un Dockerfile listo para usar. El Space debe configurarse con sdk: docker (ya incluido en la cabecera YAML).

Configurar GROQ_API_KEY en los Secrets del Space
El hardware CPU (8 vCPU, 32GB RAM) es suficiente (no requiere GPU)
Hacer push al repositorio de Hugging Face

📊 Métricas del Sistema

Métrica	Valor
Chunks Indexados	108
Dimensión Embedding	384
Tokens por Consulta	~1,500 (optimizado)
Consultas Diarias (free tier)	~65
Tiempo de Respuesta	< 2s

👨‍💻 Habilidades Demostradas

Machine Learning: RAG, embeddings, vector search
Deep Learning: LLMs (LLaMA 3.3 vía Groq API), prompt engineering
APIs: FastAPI, RESTful design
DevOps: Docker, Hugging Face Spaces
Logging: Diagnóstico avanzado, monitoreo, métricas de latencia
Testing: Evaluación automática con 20 casos de prueba
Database: FAISS, vector stores, NumPy

📝 Licencia

MIT License - feel free to use for learning and personal projects.