Skip to content

README.md

Latest commit

 

History

History
406 lines (299 loc) · 12.5 KB

README.md

File metadata and controls

406 lines (299 loc) · 12.5 KB

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

  1. 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

  1. 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

Tutoriales y Recursos

🤝 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]