Demo Serving

Proyecto de demostración de diferentes arquitecturas de despliegue de modelos de Machine Learning usando Ray Serve y NVIDIA Triton Inference Server en Kubernetes.

📋 Descripción General

Este repositorio contiene múltiples implementaciones de servicios de ML, cada una demostrando diferentes patrones arquitectónicos para servir modelos ONNX a escala. Desde servicios simples de Ray Serve hasta arquitecturas híbridas que combinan Ray y Triton.

📖 Navegación: Para una visión completa de toda la documentación disponible, consulta STRUCTURE.md

🏗️ Arquitecturas Disponibles

El proyecto está organizado en tres grandes categorías:

🎓 Módulo de Entrenamiento (training/)

Código para entrenar el modelo de predicción de ganancias usando Ray Train:

Módulo	Descripción	Características
training	Entrenamiento distribuido con Ray Train	Escalable, GPU support, exportación ONNX

Ver: training/README.md para guía completa de entrenamiento.

📂 Módulos de Serving (serving/)

Implementaciones completas de un servicio de predicción de ganancias usando diferentes arquitecturas:

Módulo	Descripción	Casos de Uso
1-ray-serve	Ray Serve puro con preprocesamiento local	Proyectos que requieren flexibilidad en el preprocesamiento
2-triton-server	Triton Server con ensemble Python+ONNX	Alta performance con GPU, preprocesamiento en Triton
3-ray-triton-microservices	Ray como API Gateway + Triton como motor de inferencia	Máxima flexibilidad y seguridad, escalado independiente
4-ray-triton-single	Ray y Triton en el mismo contenedor	Despliegue simplificado, menor latencia de red

📚 Ejemplos de Aprendizaje (examples/)

Ejemplos progresivos para aprender Ray Serve desde cero:

• app1.py: Servicio simple con generador de emails falsos
• app2.py: Múltiples deployments comunicándose (mercado de frutas)
• app3.py: Versión mejorada con FastAPI y validación

🎯 Comparación de Arquitecturas

Tabla Comparativa

Característica	Ray Serve	Triton Server	Ray + Triton Microservices	Ray + Triton Single
Preprocesamiento	Python/Scikit-learn	Python en Triton	Python/Scikit-learn	Python/Scikit-learn
Inferencia	ONNX Runtime	Triton Server	Triton Server	Triton Server
Flexibilidad	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Performance	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Complejidad	Baja	Media	Media-Alta	Media
Escalado	Horizontal	Horizontal	Independiente	Conjunta
Seguridad	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Latencia	Baja	Muy Baja	Baja-Media	Muy Baja

¿Cuál Elegir?

Ray Serve (serving/1-ray-serve/)

✅ Elige esto si:

• Necesitas máxima flexibilidad en el preprocesamiento
• Tu equipo domina Python/Scikit-learn
• El modelo es CPU-only
• Requieres iteración rápida en el código de preprocesamiento

❌ Evita si:

• Necesitas máximo rendimiento con GPU
• Tienes alto volumen de requests (>1000 req/s)

Triton Server (serving/2-triton-server/)

✅ Elige esto si:

• Necesitas máximo rendimiento
• Tienes GPUs disponibles
• El preprocesamiento es estable y no cambia frecuentemente
• Requieres servir múltiples modelos (ensembles)

❌ Evita si:

• El preprocesamiento cambia constantemente
• No tienes experiencia con Triton

Ray + Triton Microservices (serving/3-ray-triton-microservices/)

✅ Elige esto si:

• Necesitas máxima seguridad (Triton no expuesto públicamente)
• Quieres escalar preprocesamiento e inferencia independientemente
• Requieres un API Gateway robusto
• Necesitas flexibilidad en Ray + performance de Triton

❌ Evita si:

• La latencia de red es crítica (<10ms)
• Quieres minimizar la complejidad operacional

Ray + Triton Single (serving/4-ray-triton-single/)

✅ Elige esto si:

• Quieres balance entre flexibilidad y performance
• Prefieres un solo contenedor para simplificar despliegue
• La latencia de red entre servicios es un concern
• Tienes recursos limitados (menos pods)

❌ Evita si:

• Necesitas escalar preprocesamiento e inferencia de forma independiente
• Quieres aislar completamente Triton del acceso externo

🚀 Inicio Rápido

Prerrequisitos

• Docker (20.10+)
• Kubernetes (cluster local con kind/minikube o GKE)
• kubectl configurado
• Python 3.11+ (para desarrollo local)
• Helm (para instalar KubeRay operator)

Entrenar tu Propio Modelo (Opcional)

Si quieres entrenar el modelo desde cero:

# 1. Descargar datos de ventas
mkdir -p data
cd data
wget https://excelbianalytics.com/wp/wp-content/uploads/2017/07/1500000%20Sales%20Records.zip
unzip "1500000 Sales Records.zip"
mv "1500000 Sales Records.csv" ventas.csv
cd ..

# 2. Entrenar con Ray Train
cd training
python ray_trainer.py --data-path ../data/ventas.csv --num-workers 2 --epochs 50

# 3. Copiar modelos entrenados a módulos de despliegue
cp models/model.onnx* ../serving/1-ray-serve/models/
cp models/preprocessing_info.pkl ../serving/1-ray-serve/models/

Ver documentación completa: training/README.md

Instalación del Entorno

# 1. Clonar el repositorio
git clone <repo-url>
cd demo-ray-serving

# 2. Crear cluster de Kubernetes local (si usas kind)
kind create cluster --name ray-cluster

# 3. Instalar KubeRay operator
helm repo add kuberay https://ray-project.github.io/kuberay-helm/
helm repo update
helm install kuberay-operator kuberay/kuberay-operator --version 1.4.2

# 4. Crear entorno virtual Python (opcional, para desarrollo)
python3 -m venv env
source env/bin/activate  # En Windows: env\Scripts\activate
pip install -r examples/requirements.txt

Desplegar un Servicio

Opción 1: Ray Serve (Más Simple)

cd profit/ray

# Construir imagen
docker build -t ray-serving-model:latest .

# Cargar en kind
kind load docker-image ray-serving-model:latest --name ray-cluster

# Desplegar
kubectl apply -f config-serve-docker.yaml

# Port-forward
kubectl port-forward service/rayservice-volumen-serve-svc 8000:8000

# Probar
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"Region": "Sub-Saharan Africa", "Country": "South Africa", ...}'

Opción 2: Ray + Triton Microservices (Recomendado para Producción)

cd profit/ray-triton-separados

# Desplegar con Docker Compose
docker-compose up --build

# Probar
curl http://localhost:8080/health
curl -X POST http://localhost:8080/predict -H "Content-Type: application/json" -d '{...}'

Ver documentación detallada en cada módulo para más opciones.

📚 Documentación por Módulo

Módulo de Entrenamiento

0. training/README.md
   • Entrenamiento distribuido con Ray Train
   • Descarga de datasets de ventas
   • Exportación a ONNX
   • Uso en cluster Ray

Módulos de Serving

1. serving/1-ray-serve/README.md

   • Servicio completo de Ray Serve con preprocesamiento
   • Validación con Pydantic
   • Despliegue en Kubernetes
   • Publicación en GCP Artifact Registry

2. serving/2-triton-server/README.md

   • Triton Server con ensemble de modelos
   • Preprocesamiento Python + inferencia ONNX
   • Configuración de batching dinámico
   • Monitoreo con métricas de Triton

3. serving/3-ray-triton-microservices/README.md

   • Arquitectura de microservicios
   • Ray como API Gateway con seguridad
   • Triton Server interno (no expuesto)
   • Docker Compose para desarrollo

4. serving/4-ray-triton-single/README.md

   • Triton Server embebido en Ray
   • Contenedor único
   • Latencia mínima
   • Despliegue simplificado

Ejemplos de Aprendizaje

5. examples/README.md
   • Tutoriales paso a paso
   • Desde servicios simples hasta deployments complejos
   • Ejemplos con FastAPI
   • Comunicación entre deployments

🔧 Herramientas de Desarrollo

Scripts Útiles

Cada módulo incluye scripts y herramientas para desarrollo:

• Dockerfiles: Construcción de imágenes optimizadas
• docker-compose.yaml: Desarrollo local (ray-triton-separados)
• config-serve-*.yaml: Configuraciones de Kubernetes
• requirements.txt: Dependencias Python

Testing

# Ejecutar ejemplos localmente
cd examples
ray start --head
serve run app1:deployment

# En otra terminal
curl http://localhost:8000/fake-email

🐛 Troubleshooting

Problemas Comunes

1. Pods no inician

# Ver logs
kubectl get pods
kubectl logs <pod-name> -c ray-head

# Ver eventos
kubectl describe pod <pod-name>

2. Imagen Docker no encontrada

# Verificar imágenes cargadas en kind
docker exec -it ray-cluster-control-plane crictl images

# Recargar imagen
kind load docker-image <image-name>:latest --name ray-cluster

3. Error de preprocesamiento

# Verificar que preprocessing_info.pkl existe
# Debe contener: encoders, scaler, feature_columns, categorical_columns

4. Triton Server no responde

# Verificar health
curl http://localhost:8000/v2/health/ready

# Ver modelos cargados
curl http://localhost:8000/v2/models

Limpiar Recursos

# Eliminar deployments
kubectl delete -f <config-file>.yaml

# Eliminar cluster de kind
kind delete cluster --name ray-cluster

# Limpiar imágenes Docker
docker system prune -a --volumes -f

📖 Conceptos Clave

Ray Serve

Framework de Anyscale para servir modelos de ML a escala:

• Escalado automático horizontal
• Batching inteligente de requests
• Deployments distribuidos
• Integración nativa con Kubernetes

NVIDIA Triton Inference Server

Servidor de inferencia de alto rendimiento:

• Soporte para múltiples frameworks (ONNX, TensorFlow, PyTorch)
• Optimización de GPU/CPU
• Batching dinámico
• Ensembles de modelos

ONNX (Open Neural Network Exchange)

Formato estándar para modelos de ML:

• Interoperabilidad entre frameworks
• Optimización de inferencia
• Portabilidad multiplataforma

KubeRay

Operador de Kubernetes para Ray:

• Gestión automática de clusters Ray
• Escalado automático
• Alta disponibilidad

📊 Métricas y Monitoreo

Ray Serve Metrics

# Ray Dashboard (port-forward del head node)
kubectl port-forward <head-pod> 8265:8265
# Abrir http://localhost:8265

Triton Metrics

# Prometheus metrics
curl http://localhost:8002/metrics

# Métricas clave:
# - nv_inference_request_success
# - nv_inference_request_failure
# - nv_inference_queue_duration_us
# - nv_inference_exec_count

🔗 Referencias

Documentación Oficial

• Ray Serve Documentation
• Triton Inference Server
• KubeRay Documentation
• ONNX Documentation

Tutoriales y Recursos

• Ray Serve Examples
• Triton Tutorials
• ONNX Runtime Python API

🤝 Contribuir

Este es un proyecto de demostración. Para contribuir:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/nueva-caracteristica)
3. Commit tus cambios (git commit -am 'Agregar nueva característica')
4. Push a la rama (git push origin feature/nueva-caracteristica)
5. Crea un Pull Request

📝 Notas Importantes

• Los modelos ONNX deben estar pre-entrenados y exportados
• El archivo preprocessing_info.pkl debe coincidir con el entrenamiento
• Para producción, usar un registry de imágenes (GCP Artifact Registry, Docker Hub)
• Ajustar recursos (CPU/memoria/GPU) según las necesidades
• Considerar usar GPU en producción para modelos grandes

📄 Licencia

Este proyecto es de código abierto y está disponible bajo la licencia MIT.

---

Última actualización: Diciembre 2025
Mantenedor: [@camigomezdev]