EPP-Detector API

API para detección de Equipos de Protección Personal (EPP) en imágenes y videos, y para responder preguntas frecuentes mediante un modelo transformer y recuperación semántica avanzada.

---

Tabla de Contenidos

• Descripción
• Características
• Estructura del Proyecto
• Requisitos
• Instalación
• Uso
  • Levantando el servidor
  • Detección de EPP en Imagen
  • Detección de EPP en Video
  • WebSocket para Webcam
  • Chat Transformer (FAQ)
  • Diagnóstico de preguntas
  • Análisis completo (detección + chat)
• Endpoints
• Notas
• Licencia

---

Descripción

Este backend proporciona una API REST y WebSocket para:

• Detectar EPP en imágenes y videos usando modelos de visión por computadora.
• Responder preguntas frecuentes sobre EPP usando un modelo transformer y recuperación semántica robusta (RAG).
• Integrar ambos procesos para análisis y explicación automática.

---

Características

• FastAPI para endpoints REST y WebSocket.
• Detección de EPP en imágenes y videos.
• Respuestas automáticas a preguntas frecuentes usando un modelo LLM y embeddings.
• Recuperación semántica ponderada por elementos EPP y categorías.
• Diagnóstico detallado del procesamiento de preguntas.
• Endpoint combinado de análisis y explicación.
• CORS habilitado para cualquier origen.
• Logging avanzado para auditoría y debugging.

---

Estructura del Proyecto

app/
  __init__.py
  detector.py
  main.py
  requirements.txt
  chat/
    __init__.py
    build_index.py
    qa_transformer.py
    data/
      epp_faq.csv
    vectors/
      answers.json
      epp_faq.json
      epp.index
weights/
  best_v1.pt

• app/main.py: Entrypoint de la API y definición de endpoints.
• app/detector.py: Lógica de detección de EPP.
• app/chat/qa_transformer.py: Lógica de preguntas y respuestas, recuperación semántica y diagnóstico.
• app/chat/build_index.py: Construcción de índices FAISS y metadatos para RAG.
• app/chat/data/epp_faq.csv: Preguntas frecuentes y respuestas normativas.
• app/chat/vectors/: Índices y metadatos para recuperación semántica.
• weights/best_v1.pt: Pesos del modelo de detección.

---

Requisitos

Hardware Recomendado

• CPU: 4+ núcleos (Intel i5/i7 o AMD Ryzen 5/7)
• RAM: 16 GB mínimo (32 GB recomendado para procesamiento de video)
• GPU: NVIDIA con 6+ GB VRAM (para inferencia del modelo de detección y LLM)
• Almacenamiento: 10 GB de espacio libre (SSD recomendado)

Software

• Python 3.11+
• FastAPI
• Uvicorn
• PyTorch con soporte CUDA
• FAISS para búsqueda vectorial
• OpenCV, NumPy, Transformers, SentenceTransformers
• Otras dependencias en requirements.txt o environment.yml

---

Instalación

Hay dos formas de instalar las dependencias necesarias:

Opción 1: Con pip (básico)

1. Clona el repositorio:

   git clone <repo-url>
   cd epp_project/epp_api

2. Instala las dependencias:

   pip install -r app/requirements.txt

Opción 2: Con conda/mamba (recomendado)

Esta opción proporciona un entorno aislado con todas las dependencias, incluidas las bibliotecas para aceleración GPU:

1. Clona el repositorio:

   git clone <repo-url>
   cd epp_project/epp_api

2. Crea y activa el entorno usando el script de configuración:

   # Da permisos de ejecución (solo la primera vez)
   chmod +x setup_env.sh
   
   # Ejecuta el script de configuración
   ./setup_env.sh
   
   # Activa el entorno
   conda activate epp_detector

3. (Opcional) Si prefieres hacerlo manualmente:

   # Con mamba (más rápido)
   mamba env create -f environment.yml
   
   # O con conda
   conda env create -f environment.yml

4. Importante: Asegúrate de tener el modelo de detección en app/weights/best_v1.pt.

---

Uso

Levantando el servidor

uvicorn app.main:app --reload

El servidor estará disponible en http://localhost:8000.

---

Detección de EPP en Imagen

POST /detect/image

• Body: Form-data con archivo de imagen (file)
• Respuesta: JSON con resultado de detección, elementos faltantes, veredicto y la imagen anotada en base64.

---

Detección de EPP en Video

POST /detect/video

• Body: Form-data con archivo de video (file)
• Respuesta: JSON con resultados por frames (cada 5 frames), elementos faltantes globales y muestra de resultados.

---

WebSocket para Webcam

WS /ws

• Envío: Frames en formato de bytes.
• Recepción: JSON con resultados de detección en tiempo real.

  {
    "boxes": [[x1, y1, x2, y2], ...],
    "ok": false,
    "missing": ["casco"]
  }

Chat Transformer (FAQ)

POST /chat/transformer

• Body: JSON

{
  "question": "¿Qué EPP es obligatorio?",
  "missing": ["casco"],
  "k": 7,
  "diagnostics": false
}

• Respuesta: JSON con la respuesta generada por el modelo transformer

{
  "answer": "El casco es obligatorio según la normativa...",
  "missing_used": ["casco"],
  "sources": ["Resolución 1409 de 2012", "..."],
  "processing_time_ms": 235
}

---

Diagnóstico de preguntas

POST /diagnose

• Body: JSON con la pregunta.
• Respuesta: Diagnóstico detallado del procesamiento semántico, elementos EPP detectados, categorías, resultados de búsqueda y recomendaciones.

---

Análisis completo (detección + chat)

POST /analyse/complete

• Body: Form-data con archivo de imagen (file)
• Respuesta: Resultado de detección, imagen anotada, veredicto, pregunta automática generada y respuesta del modelo transformer con fuentes normativas.

---

Endpoints

Método	Endpoint	Descripción
POST	/detect/image	Detección de EPP en imagen
POST	/detect/video	Detección de EPP en video
WS	/ws	Detección en tiempo real (webcam)
POST	/chat/transformer	Preguntas frecuentes (modelo transformer + RAG)
POST	/diagnose	Diagnóstico del procesamiento de preguntas
POST	/analyse/complete	Detección y respuesta automática combinada
GET	/	Mensaje de bienvenida y descripción de endpoints
GET	/health	Estado de la API

---

Integración con Frontend

A continuación se presentan ejemplos de cómo integrar esta API en aplicaciones frontend:

Procesando imágenes

// Ejemplo con Fetch API
async function uploadImage(imageFile) {
  const formData = new FormData();
  formData.append('file', imageFile);

  const response = await fetch('http://localhost:8000/detect/image', {
    method: 'POST',
    body: formData,
  });

  const result = await response.json();

  // Mostrar la imagen procesada
  document.getElementById('result-image').src = result.image_b64;

  // Mostrar el veredicto
  document.getElementById('verdict').textContent = result.verdict;
}

Procesando videos

async function analyzeVideo(videoFile) {
  const formData = new FormData();
  formData.append('file', videoFile);

  const response = await fetch('http://localhost:8000/detect/video', {
    method: 'POST',
    body: formData,
  });

  const data = await response.json();

  // Procesar los resultados por frame
  const video = document.getElementById('video');
  const canvas = document.getElementById('canvas');
  const ctx = canvas.getContext('2d');

  // Al cambiar el tiempo de reproducción
  video.addEventListener('timeupdate', () => {
    const currentFrame = Math.floor(video.currentTime * 30); // Asumiendo 30fps

    // Buscar el frame más cercano en los resultados
    const frameResult = data.sample_results.find(
      (r) => Math.abs(r.frame - currentFrame) < 3
    );

    if (frameResult) {
      // Dibujar los cuadros de detección
      ctx.drawImage(video, 0, 0, canvas.width, canvas.height);

      frameResult.boxes.forEach(([x1, y1, x2, y2]) => {
        ctx.strokeStyle = frameResult.ok ? 'green' : 'red';
        ctx.lineWidth = 2;
        ctx.strokeRect(x1, y1, x2 - x1, y2 - y1);
      });

      // Mostrar el veredicto
      const verdict = frameResult.ok
        ? '✅ Cumple'
        : `❌ Falta: ${frameResult.missing.join(', ')}`;

      document.getElementById('verdict').textContent = verdict;
    }
  });
}

Arquitectura

La API está construida sobre dos componentes principales:

1. Sistema de detección visual: Utiliza un modelo entrenado para detectar la presencia o ausencia de 5 elementos de protección personal críticos.

2. Sistema de preguntas y respuestas: Implementa una arquitectura RAG (Retrieval Augmented Generation) con:

   • Embedding multilingüe para codificar preguntas y documentos
   • Índice FAISS para búsqueda semántica eficiente
   • Ponderación contextual basada en EPP detectados
   • Generación de respuestas con un modelo LLM optimizado (Microsoft Phi-3)

Notas

• El sistema de preguntas y respuestas usa embeddings multilingües (paraphrase-multilingual-MiniLM-L12-v2) y el modelo Phi-3 Mini para generar respuestas precisas y normativas.
• La búsqueda semántica pondera resultados según elementos EPP y categorías detectadas en la pregunta.
• Para un rendimiento óptimo en videos, se procesan solo frames seleccionados (cada 5).
• El endpoint /diagnose permite depurar y entender el razonamiento del sistema ante cada consulta.
• El endpoint /analyse/complete integra visión y lenguaje para una experiencia explicativa completa.
• Para producción, configura correctamente CORS y seguridad.
• El logging se almacena en epp_api.log y en consola.

---

🔗 Repositorios del Proyecto

Este proyecto es parte del sistema EPP Detector:

• Backend / API: epp-detector-api
• Frontend / Client: epp-detector-client
• Entrenamiento del Modelo (IA): epp-detector-train

---

Licencia

MIT License

ByteCrafters - 2025

• GitHub
• LinkedIn

@JLosada-Dev - ByteCrafters

• GitHub
• LinkedIn