🤖 Cleo AI Backend - RunPod Deployment

Backend optimizado para GPU A40 en RunPod con PokeeAI/pokee_research_7b (7B parámetros).

---

🚀 Quick Start (RunPod)

1. Conectar a tu Pod RunPod

ssh root@<POD_IP> -p <SSH_PORT>

2. Clonar el repositorio

cd /workspace
git clone https://github.com/LuisNSantana/ai-backend-cleo-model.git backend_ai_local
cd backend_ai_local

3. Configurar y ejecutar

# Copiar configuración del servidor
cp .env.server .env

# Hacer ejecutables los scripts
chmod +x start_server.sh finetune_server.sh

# Iniciar servidor
./start_server.sh

¡Listo! El servidor estará corriendo en el puerto 8000.

---

📋 Características

• 🤖 Modelo: PokeeAI/pokee_research_7b (7B parámetros, Apache 2.0)
• ⚡ GPU: NVIDIA A40 (40GB VRAM)
• 🔥 Optimizado: CUDA + FP16 para máxima velocidad
• 🎯 Fine-tuning: LoRA adapters para personalización
• 🌐 API: Compatible con OpenAI API
• 💬 Cleo: Personalidad de Huminary Labs (Madrid)

---

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                     RUNPOD SERVER (A40)                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  FastAPI Backend (Port 8000)                        │   │
│  │  ├── /v1/chat/completions (OpenAI compatible)      │   │
│  │  ├── /health (Health check)                        │   │
│  │  └── /docs (Swagger UI)                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                          ↓                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  PokeeAI/pokee_research_7b                          │   │
│  │  └── LoRA Adapter (Fine-tuned - Cleo)             │   │
│  └─────────────────────────────────────────────────────┘   │
│                          ↓                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  NVIDIA A40 GPU (40GB VRAM)                        │   │
│  │  └── CUDA 11.8 + FP16                              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

📖 Documentación

Archivos de configuración

• .env.server - Configuración optimizada para RunPod A40
• requirements.txt - Dependencias Python con CUDA support
• start_server.sh - Script automatizado de inicio
• finetune_server.sh - Script de fine-tuning

Scripts

• scripts/finetune_cleo_gpu.py - Fine-tuning con LoRA (optimizado para A40)
• scripts/combine_datasets.py - Utilidad para combinar datasets

Dataset

• datasets/cleo_combined_training.jsonl - 40 ejemplos bilingües (EN/ES)
  • Identidad de Huminary Labs (Madrid)
  • Personalidad de Cleo
  • Filosofía de compañero incondicional

---

🔧 Configuración

Variables de entorno principales

# Modelo
HF_DEFAULT_MODEL=PokeeAI/pokee_research_7b

# GPU
HF_DEVICE=cuda
HF_TORCH_DTYPE=float16

# Servidor
HOST=0.0.0.0
PORT=8000

# Fine-tuning
LORA_R=16
LORA_ALPHA=32
BATCH_SIZE=4
NUM_EPOCHS=3

Ver .env.server para todas las opciones.

---

🎯 Fine-Tuning

Ejecutar fine-tuning en RunPod

./finetune_server.sh

Tiempo estimado: ~15-20 minutos en A40 (vs 89 min en Mac M4)

Usar modelo fine-tuned

# 1. Editar .env
nano .env

# 2. Actualizar modelo
HF_DEFAULT_MODEL=/workspace/backend_ai_local/models/cleo_finetuned_7b

# 3. Reiniciar servidor
pkill -f uvicorn
./start_server.sh

---

📡 API Usage

Health Check

curl https://your-pod-url:8000/health

Chat Completion

curl -X POST "https://your-pod-url:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PokeeAI/pokee_research_7b",
    "messages": [
      {"role": "user", "content": "¿Quién eres y qué haces?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Swagger UI

Accede a la documentación interactiva:

https://your-pod-url:8000/docs

---

📊 Performance

---

🔍 Monitoreo

Ver logs en tiempo real

tail -f logs/server.log

Verificar GPU

nvidia-smi
watch -n 1 nvidia-smi  # Actualización cada segundo

Health endpoint

curl http://localhost:8000/health

---

🐛 Troubleshooting

CUDA out of memory

Reducir batch size:

# En .env
BATCH_SIZE=2

O activar cuantización 4-bit:

# En scripts/finetune_cleo_gpu.py
USE_4BIT = True

Puerto 8000 ocupado

# Ver proceso
lsof -i :8000

# Matar proceso
pkill -f uvicorn

# O cambiar puerto en .env
PORT=8001

Modelo no descarga

Verificar token de HuggingFace:

# En .env (si es necesario)
HF_TOKEN=tu_token_aqui

# O login manual
huggingface-cli login

---

📁 Estructura del Proyecto

backend_ai_local/
├── app/                              # FastAPI application
│   ├── main.py                       # Entry point
│   ├── routers/                      # API routes
│   │   ├── chat.py                   # Chat endpoints
│   │   └── health.py                 # Health checks
│   └── services/                     # Business logic
│       └── huggingface_service.py    # Model inference
├── datasets/                         # Training datasets
│   └── cleo_combined_training.jsonl  # 40 bilingual examples
├── scripts/                          # Utility scripts
│   ├── finetune_cleo_gpu.py         # GPU fine-tuning
│   └── combine_datasets.py          # Dataset tools
├── models/                           # Fine-tuned models (gitignored)
│   └── cleo_finetuned_7b/           # Output after fine-tuning
├── .env.server                       # Server config template
├── requirements.txt                  # Python dependencies
├── start_server.sh                  # Server startup
├── finetune_server.sh               # Fine-tuning script
└── README.md                        # This file

---

🔐 Seguridad

Para producción, configura:

1. Autenticación API

# En .env
API_KEY=tu_api_key_secreta

2. CORS específicos

# En .env
CORS_ORIGINS=["https://tu-frontend.com"]

3. HTTPS

Usa reverse proxy (nginx) o SSL de RunPod.

---

🤝 Contribuir

Este es un proyecto de Huminary Labs (Madrid, España).

Equipo

• Cleo Team - Desarrollo y entrenamiento
• Huminary Labs - Investigación y producto

---

📝 Licencia

Este proyecto usa:

• PokeeAI/pokee_research_7b - Apache 2.0 License
• Backend code - MIT License

---

📞 Soporte

Documentación adicional

• README_DEPLOYMENT_DETAILED.md - Guía detallada de deployment
• FINE_TUNING_GUIDE.md - Guía de fine-tuning
• HUMINARY_TRAINING_GUIDE.md - Dataset y personalidad

Issues

Reporta bugs o solicita features en:

• GitHub Issues: ai-backend-cleo-model/issues

---

🎉 ¡Empezar ahora!

# 1. Clonar
git clone https://github.com/LuisNSantana/ai-backend-cleo-model.git
cd ai-backend-cleo-model

# 2. Configurar
cp .env.server .env
chmod +x start_server.sh

# 3. Ejecutar
./start_server.sh

¡Disfruta de Cleo! 🚀

---

Hecho con ❤️ por Huminary Labs en Madrid, España