El modelo de churn de MercaFresh vive hasta ahora en un notebook: pipeline de preprocesamiento del módulo 3, algoritmo optimizado en el módulo 7, umbral de decisión elegido por costes en el módulo 6. Pero un notebook no puede recibir la llamada del sistema de campañas a las 3 de la madrugada preguntando "¿qué probabilidad de abandono tiene el cliente 48210?". Llevar un modelo a producción significa convertirlo en un servicio fiable que otros sistemas puedan usar. En esta lección recorremos ese camino completo: serializar el pipeline con joblib, elegir entre servir en batch o en tiempo real, construir una API con FastAPI, empaquetarla con Docker y desplegarla de forma gradual y segura.

1. Del notebook a producción: qué cambia
2. Serializar el pipeline con joblib
3. Versionado del artefacto y sus riesgos
4. Patrones de servicio: batch vs. online
5. Una API REST con FastAPI
6. Empaquetado con Docker
7. Despliegue gradual: shadow mode y test A/B
8. Checklist de puesta en producción

Un notebook y un servicio en producción son objetos de naturaleza distinta, aunque contengan el mismo modelo:

La consecuencia práctica: en producción no se despliega "el notebook", se despliega un artefacto (el pipeline serializado) envuelto en código de servicio (API o proceso batch) dentro de un entorno reproducible (contenedor). Vamos pieza a pieza.

Serializar es convertir el objeto Python entrenado —con todos sus parámetros aprendidos— en un fichero que puede guardarse, copiarse a un servidor y volver a cargarse. En el ecosistema scikit-learn el estándar es joblib, eficiente con los arrays grandes de NumPy que viven dentro de los modelos.

El punto crítico, que justifica todo el trabajo del módulo 3: se serializa el pipeline completo, no solo el modelo. El Pipeline con su ColumnTransformer guarda también lo aprendido por los preprocesadores (medias del escalador, categorías del codificador). Así, producción aplica exactamente las mismas transformaciones que el entrenamiento, y eliminamos de raíz la familia de errores "entrené con datos escalados pero predigo con datos sin escalar".

Fíjate en que en producción usamos predict_proba y no predict: como viste en 06-04, la decisión final se toma comparando la probabilidad con el umbral elegido por costes de negocio, y ese umbral conviene mantenerlo como configuración explícita del servicio, no enterrado en el modelo.

Dos advertencias importantes antes de seguir:

1. Versiona el artefacto como versionas el código. Un nombre como modelo.joblib que se sobrescribe es una bomba de relojería: cuando algo falle no sabrás qué modelo estaba sirviendo. Prácticas mínimas:

• Nombre con versión y fecha: modelo_churn_v3_2026-08-24.joblib.
• Junto al artefacto, un fichero de metadatos: fecha de entrenamiento, rango de datos usado, métricas de validación, versiones de las bibliotecas (pip freeze), y el umbral de decisión.
• Nunca borres la versión anterior al desplegar la nueva: es tu plan de rollback (lo retomaremos en 08-03, junto con los registros de modelos tipo MLflow).

2. Dos riesgos de seguridad y compatibilidad que debes conocer:

• Deserializar es ejecutar código. Un fichero joblib/pickle puede contener código arbitrario que se ejecuta al cargarlo. Regla de oro: joblib.load solo sobre ficheros cuyo origen controlas (tus propios entrenamientos, tu almacenamiento interno). Jamás cargues un modelo descargado de una fuente no confiable.
• Sensibilidad a versiones. Un pipeline guardado con scikit-learn 1.5 puede fallar —o peor, comportarse sutilmente distinto sin error— al cargarse con la 1.2 o la 1.7. Por eso el requirements.txt con versiones fijadas de la lección anterior viaja siempre con el artefacto: entrenar y servir deben usar las mismas versiones.

Antes de escribir una API, una decisión de arquitectura: ¿cómo van a consumirse las predicciones? Hay dos patrones fundamentales.

El caso natural del churn de MercaFresh es batch: el equipo de retención planifica campañas semanales; no necesita saber la probabilidad de abandono en este milisegundo, sino una tabla fresca cada mañana. Un scoring nocturno es más simple, más barato y más fácil de operar:

El patrón online se justifica cuando la predicción depende de información que solo existe en el momento (el contenido del carrito actual) o cuando otro sistema necesita respuesta inmediata. Como muchos sistemas acaban necesitando ambas cosas —y porque es el patrón técnicamente más rico— construimos ahora la versión online.

FastAPI es el framework Python más usado hoy para servir modelos: rápido, con validación automática de datos vía pydantic y documentación interactiva generada sola. La idea: el modelo se carga una vez al arrancar el servicio, y cada petición HTTP a /predict devuelve una predicción.

Puntos que conviene entender línea a línea:

• DatosCliente(BaseModel) define el contrato de entrada. Si llega una petición con recencia_dias: "muchos" o sin el campo ciudad, FastAPI la rechaza con un error 422 claro antes de tocar el modelo. En producción, la mitad de los incidentes son datos malformados; la validación en la puerta los convierte en errores explícitos en lugar de predicciones absurdas.
• Field(ge=0) añade restricciones (aquí: mayor o igual que cero) — validación de negocio, no solo de tipos.
• La respuesta incluye "modelo": "churn_v3": identificar qué versión respondió cada petición es oro para el monitoreo (08-03).

Se levanta y se prueba así:

Con esto, cualquier sistema de MercaFresh —el backend web, el sistema de campañas— puede pedir predicciones con una llamada HTTP, sin saber nada de Python ni de scikit-learn.

Queda un problema: la API funciona en tu máquina, con tu Python y tus versiones. Docker resuelve el "en mi máquina funcionaba" empaquetando la aplicación con su entorno completo (sistema base, Python, bibliotecas exactas, código y artefacto) en una imagen inmutable. Esa imagen se ejecuta como contenedor de forma idéntica en tu portátil, en el servidor de MercaFresh o en la nube.

La receta de la imagen es el Dockerfile:

Explicación de las decisiones:

1. FROM python:3.12-slim: se parte de una imagen oficial con Python ya instalado; slim recorta lo innecesario (imagen más pequeña, menos superficie de ataque).
2. WORKDIR /app: todas las rutas siguientes son relativas a /app dentro del contenedor.
3. El orden COPY requirements.txt → RUN pip install → COPY app.py aprovecha la caché por capas: en el ciclo habitual (cambias código, no dependencias) reconstruir la imagen tarda segundos.
4. El artefacto del modelo viaja dentro de la imagen: imagen y modelo se versionan juntos, y desplegar una versión es desplegar un binario cerrado. (En sistemas grandes el modelo puede descargarse de un registro al arrancar; empezar con él dentro es más simple.)
5. EXPOSE documenta el puerto; 6. CMD define qué ejecuta el contenedor al arrancar.

Por qué contenedores, en una frase por motivo: reproducibilidad (el entorno viaja con la app), aislamiento (no interfiere con nada más del servidor), portabilidad (la misma imagen corre en cualquier sitio) y escalado (¿más tráfico? se arrancan más contenedores idénticos, a mano o con un orquestador como Kubernetes — que queda fuera de este curso).

Tienes la imagen v3 lista. Error clásico: reemplazar de golpe la versión anterior. Si v3 tiene un problema que la validación no detectó —y el mundo real siempre encuentra alguno—, lo descubrirás con todos los clientes afectados. El despliegue profesional es gradual:

Fase 1 — Shadow mode (modo sombra). La v3 se despliega junto a la v2 y recibe copia de todas las peticiones, pero sus predicciones no se usan: solo se registran. Durante una o dos semanas comparas: ¿responde con la latencia esperada? ¿falla con algún tipo de entrada? ¿sus probabilidades tienen una distribución razonable frente a las de v2? Todo el riesgo de un despliegue, sin ningún impacto en clientes.

Fase 2 — Test A/B del modelo. Superada la sombra, la v3 empieza a decidir para una fracción aleatoria de clientes (p. ej. el 10 %), y la v2 para el resto. Es exactamente el test A/B de la lección 02-04, con el modelo como tratamiento: se compara la métrica de negocio (tasa de retención tras campaña, coste por cliente retenido) entre grupos, y se exige significancia estadística antes de concluir que v3 es mejor en el mundo real — no solo en el conjunto de test. Nota importante: la métrica offline (AUC, F1) y la de negocio no siempre se mueven juntas; el A/B es el juez final.

Fase 3 — Rollout completo. v3 pasa al 100 % del tráfico. La v2 no se borra: queda lista para rollback inmediato si algo va mal.

Antes de dar por desplegado el modelo de churn, repasa:

• [ ] El artefacto es el pipeline completo (preprocesamiento incluido) y acepta datos crudos.
• [ ] Artefacto versionado, con metadatos (datos, métricas, umbral, pip freeze) y versión anterior conservada.
• [ ] Versiones de bibliotecas idénticas entre entrenamiento y servicio (requirements fijado, 08-01).
• [ ] Patrón de servicio elegido conscientemente (batch vs. online) según la necesidad real.
• [ ] Validación de entradas en la puerta (pydantic): tipos, rangos, campos obligatorios.
• [ ] El umbral de decisión es configuración explícita, justificada por costes (06-04).
• [ ] Imagen Docker construida y probada en local; puerto y comando de arranque correctos.
• [ ] Cada respuesta registra qué versión del modelo la generó.
• [ ] Plan de despliegue gradual: shadow → A/B → rollout, con rollback preparado.
• [ ] Logs de peticiones y predicciones activados — son la materia prima del monitoreo (08-03).

• Serializar solo el modelo y reimplementar el preprocesamiento "a mano" en producción. Tarde o temprano las dos implementaciones divergen y las predicciones se corrompen en silencio. Siempre el pipeline completo.
• Cargar el modelo dentro del endpoint. joblib.load en cada petición multiplica la latencia por cien. Se carga una vez, al arrancar el proceso.
• Ignorar los avisos de versión de scikit-learn al cargar un artefacto. Ese warning de "unpickling from a different version" no es ruido: es el síntoma exacto del riesgo de incompatibilidad. Alinea versiones.
• Montar una API online cuando un batch nocturno bastaba. Es el error de arquitectura más caro: pagas disponibilidad 24/7, escalado y guardias para una necesidad que era una tabla diaria.
• Desplegar al 100 % sin fase de sombra. El conjunto de test no contiene las sorpresas del tráfico real (campos nuevos, valores extremos, picos de carga). La sombra las encuentra gratis.
• Consejo: añade a la API un endpoint /health que devuelva la versión del modelo y un "ok". Los sistemas de despliegue lo usan para saber si el servicio está vivo, y a ti te ahorra el clásico "¿qué versión hay en producción?".

Ejercicio 1. Para cada escenario de MercaFresh, decide batch u online y justifica en una frase: (a) lista diaria de clientes en riesgo para el equipo de retención por email; (b) decidir, mientras el cliente navega, si mostrarle un banner con descuento de retención; (c) informe mensual de evolución del riesgo medio de churn por ciudad.

Ejercicio 2. La API del ejemplo recibe esta petición: {"recencia_dias": -5, "frecuencia_90d": 2, "gasto_medio": 38.5, "antiguedad_meses": 14, "incidencias_entrega": 3, "ciudad": "Valencia", "canal_captacion": "app"}. ¿Qué ocurre y por qué es preferible ese comportamiento a que el pipeline predijera sin más?

Ejercicio 3. Escribe (sin ejecutarlo) el plan de despliegue gradual de la versión v4 del modelo de churn, indicando: qué se compara en shadow mode, qué métrica decide el test A/B y qué condición dispararía un rollback tras el rollout.

Solución 1. (a) Batch: la lista se necesita una vez al día; un scoring nocturno programado es suficiente y mucho más simple. (b) Online: la decisión depende del momento de la visita y alguien (el frontend) espera la respuesta en milisegundos; requiere la API. (c) Batch: es agregación mensual sobre scores ya calculados; ni siquiera necesita predicciones nuevas, solo los resultados del batch diario.

Solución 2. Pydantic rechaza la petición con un error 422 antes de llegar al modelo, porque recencia_dias tiene la restricción Field(ge=0) y llega -5. Es preferible porque una recencia negativa es imposible: casi seguro hay un bug en el sistema que llama (o en la integración). Si el pipeline predijera de todos modos, devolvería un número con apariencia legítima calculado sobre datos corruptos — un fallo silencioso que nadie detectaría. Un error explícito en la puerta convierte el problema en visible y atribuible.

Solución 3. Plan tipo: (1) Shadow, 2 semanas: v4 recibe copia del tráfico real; se comparan con v3 la tasa de errores, la latencia (p. ej. percentil 95) y la distribución de probabilidades predichas (si v4 predice sistemáticamente más alto/bajo, investigar antes de seguir). (2) A/B, 4-6 semanas al 10 %: métrica de decisión de negocio — por ejemplo, tasa de retención de los clientes contactados (o coste por cliente retenido) en el grupo v4 frente al grupo v3, con test de significancia como en 02-04; si no hay mejora significativa, v4 no avanza. (3) Rollout 100 % conservando la imagen v3; rollback si se dispara la tasa de errores del servicio, la latencia supera el umbral acordado, o la distribución de predicciones/métrica de negocio se desvía bruscamente de lo visto en el A/B.

El modelo de churn de MercaFresh ya no vive en un notebook: es un pipeline serializado y versionado con joblib, servido cada noche en batch para las campañas y disponible en tiempo real tras una API FastAPI que valida cada entrada, todo empaquetado en una imagen Docker que se ejecuta igual en cualquier máquina, y desplegado con red de seguridad — sombra, test A/B como el de 02-04 y rollback preparado. Pero poner el modelo en producción no es el final del trabajo, sino el principio de una etapa nueva: el mundo cambia, los clientes cambian, y un modelo entrenado con el pasado se degrada en silencio. Detectar esa degradación y decidir cuándo y cómo reentrenar es el tema de la próxima lección: mantenimiento y monitoreo de modelos.