README.md

metadata

title: PERI BERT Classifier
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
app_file: app.py
pinned: false
license: apache-2.0

PERI BERT Classifier

API REST para clasificación de arquetipos éticos en reflexiones sobre IA usando BERT fine-tuneado.

📋 Descripción

Este espacio proporciona una API FastAPI para clasificar reflexiones éticas sobre IA en 5 arquetipos PERI:

1. Tecnócrata Optimizador - Confía en la eficiencia de sistemas automatizados
2. Humanista Crítico - Prioriza el bienestar humano y cuestiona sesgos
3. Pragmático Equilibrado - Busca balance entre innovación y humanidad
4. Visionario Adaptativo - Abraza la transformación tecnológica
5. Escéptico Conservador - Postura cautelosa hacia la IA

🚀 Características

• MC Dropout: Uncertainty quantification para cada predicción
• Batch Processing: Clasificación de múltiples textos simultáneamente
• FastAPI Docs: Documentación interactiva automática
• CORS Enabled: Listo para integración desde cualquier frontend
• Métricas detalladas: Confidence, uncertainty, top-3 predictions

🔧 Endpoints

GET /

Documentación interactiva Swagger UI

GET /health

Health check del servicio

{
  "status": "healthy",
  "model_loaded": true,
  "device": "cuda",
  "timestamp": 1234567890.123
}

GET /info

Información del modelo

{
  "model_name": "bert-base-multilingual-cased (fine-tuned)",
  "num_classes": 5,
  "max_length": 512,
  "device": "cuda",
  "mc_dropout_samples": 10,
  "archetypes": [...]
}

POST /predict

Clasificar una reflexión individual

Request:

{
  "text": "La automatización mediante IA representa...",
  "use_mc_dropout": true
}

Response:

{
  "archetype": {
    "id": "TECNOCRATA_OPTIMIZADOR",
    "name": "Tecnócrata Optimizador",
    "description": "Confía en la eficiencia y objetividad..."
  },
  "confidence": 0.87,
  "uncertainty": 0.23,
  "top3_predictions": [
    {
      "archetype_id": "TECNOCRATA_OPTIMIZADOR",
      "archetype_name": "Tecnócrata Optimizador",
      "probability": 0.87
    },
    {
      "archetype_id": "PRAGMATICO_EQUILIBRADO",
      "archetype_name": "Pragmático Equilibrado",
      "probability": 0.08
    },
    {
      "archetype_id": "VISIONARIO_ADAPTATIVO",
      "archetype_name": "Visionario Adaptativo",
      "probability": 0.03
    }
  ],
  "inference_time_ms": 245.6,
  "method": "bert-mc-dropout"
}

POST /predict-batch

Clasificar múltiples reflexiones (máx 50)

Request:

{
  "texts": ["Reflexión 1...", "Reflexión 2...", "..."],
  "use_mc_dropout": true
}

Response:

{
  "predictions": [...],
  "total_inference_time_ms": 1234.5
}

🛠️ Uso desde JavaScript/TypeScript

// Clasificar una reflexión
async function classifyReflection(text: string) {
  const response = await fetch('https://your-space.hf.space/predict', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: text,
      use_mc_dropout: true
    })
  });

  const result = await response.json();
  console.log('Arquetipo:', result.archetype.name);
  console.log('Confianza:', result.confidence);
  console.log('Incertidumbre:', result.uncertainty);
  return result;
}

📦 Deployment en HuggingFace Space

Paso 1: Crear Space

1. Ir a https://huggingface.co/spaces
2. Click "Create new Space"
3. Configurar:
   • Name: peri-bert-classifier
   • License: MIT
   • Space SDK: Docker
   • Hardware: CPU basic (o T4 small para GPU)

Paso 2: Subir archivos

Estructura del repositorio:

peri-bert-classifier/
├── app.py                    # API FastAPI
├── requirements.txt          # Dependencias Python
├── Dockerfile               # Configuración Docker
├── README.md                # Esta documentación
└── model/                   # Modelo BERT fine-tuneado
    ├── config.json
    ├── pytorch_model.bin
    ├── tokenizer_config.json
    └── vocab.txt

Paso 3: Dockerfile

FROM python:3.10-slim

WORKDIR /app

# Copiar archivos
COPY requirements.txt .
COPY app.py .
COPY model/ ./model/

# Instalar dependencias
RUN pip install --no-cache-dir -r requirements.txt

# Exponer puerto
EXPOSE 7860

# Comando de inicio
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

Paso 4: Git push

# Clonar el space
git clone https://huggingface.co/spaces/YOUR_USERNAME/peri-bert-classifier
cd peri-bert-classifier

# Copiar archivos
cp app.py requirements.txt Dockerfile README.md .
cp -r ../../../models/peri-bert/best_model ./model

# Push
git add .
git commit -m "Initial deployment"
git push

🧪 Testing Local

# Instalar dependencias
pip install -r requirements.txt

# Ejecutar servidor
python app.py

# Acceder a:
# - Docs: http://localhost:7860
# - Health: http://localhost:7860/health

📊 Performance

• Latencia (sin GPU): ~200-300ms por reflexión
• Latencia (con GPU T4): ~50-100ms por reflexión
• Throughput batch: ~10 reflexiones/segundo (GPU)
• Memoria: ~2GB RAM + ~1GB VRAM (GPU)

🔒 Seguridad

• Input validation con Pydantic
• CORS configurado (ajustar origins en producción)
• Rate limiting recomendado para producción
• Longitud máxima de texto: 5000 caracteres

📈 Métricas del Modelo

• Test Accuracy: ~84%
• MC Dropout Accuracy: ~86%
• Mean Uncertainty: 0.32
• F1-Score (macro avg): 0.84

📞 Soporte

Para issues o preguntas sobre el modelo:

• GitHub: PERI Project
• Paper: [Ver documentación científica]

---

Generado con ❤️ para el proyecto PERI Deep Learning Conference 2025