La decisión está tomada: además del batch semanal para marketing, CineClick necesita un servicio online que, en el momento en que un cliente pulsa "cancelar suscripción", devuelva su probabilidad de abandono en menos de 300 ms para que producto decida si mostrar una oferta. En esta lección construimos ese servicio con FastAPI: definiremos contratos de entrada y salida con Pydantic, cargaremos al campeón desde el registry al arrancar, expondremos los endpoints /predecir, /salud y /version, y — cumpliendo el mandato de la lección 03-03 — importaremos construir_features del paquete instalable en lugar de reescribirla. Al final tendrás el servicio corriendo en tu máquina con uvicorn, probado desde la documentación interactiva y desde curl, y dejando en los logs la semilla de la monitorización que llegará en el módulo 6.

1. Por qué FastAPI para servir modelos
2. Estructura del servicio en el repo
3. Esquemas Pydantic: el contrato de entrada y salida
4. Cargar el modelo al arrancar: lifespan
5. El endpoint POST /predecir
6. Healthcheck y versión: GET /salud y GET /version
7. Probar el servicio: uvicorn, /docs y curl
8. Logging estructurado de cada predicción

Hay muchas formas de exponer un modelo por HTTP (Flask, Django, un servidor a mano). FastAPI se ha convertido en el estándar de facto para servir ML en Python por cuatro razones concretas:

• Tipado con Pydantic: defines la entrada y la salida como clases Python con tipos, y FastAPI valida automáticamente cada petición contra ese esquema. En un servicio de ML esto es oro: la causa número uno de predicciones absurdas en producción es una entrada malformada que el modelo traga sin quejarse (un plan inexistente, una antigüedad negativa). Con Pydantic, la petición inválida muere en la puerta con un error 422 explicativo, antes de tocar el modelo.
• Documentación OpenAPI automática: el servicio publica en /docs una interfaz interactiva generada a partir de los esquemas. El equipo de producto de CineClick puede ver y probar el contrato sin leer ni una línea de Python.
• Soporte async nativo: FastAPI corre sobre un servidor ASGI (uvicorn) y puede atender muchas conexiones concurrentes. Matiz importante para ML: predict de scikit-learn es código síncrono ligado a CPU, así que lo declararemos en un endpoint def normal (no async def) y FastAPI lo ejecutará en un threadpool sin bloquear el bucle de eventos.
• Rendimiento y ergonomía: es de lo más rápido del ecosistema Python y el código resultante es corto y legible — verás que el servicio completo cabe en dos ficheros.

Añadimos las dependencias al proyecto (y las congelamos en el lock, como manda el módulo 2):

El servicio vive dentro del paquete cineclick_churn, no en un repo aparte. Esta decisión es consecuencia directa de 03-03: el servicio debe importar construir_features del mismo paquete que usa el entrenamiento, y tenerlos juntos garantiza que ambos se instalan y versionan a la vez.

Dos ficheros: schemas.py define qué entra y sale; main.py define qué se hace con ello. Separarlos mantiene el contrato legible por sí solo.

El esquema de entrada replica las columnas crudas de clientes_churn.csv (menos id_cliente, que viaja aparte para trazabilidad, y abandono, que es lo que predecimos). Fíjate en que las validaciones codifican reglas de dominio, no solo tipos:

Desglose de las decisiones:

• ge=0 en antiguedad_meses y tickets_soporte corta en seco entradas negativas — que, recuerda, romperían silenciosamente la feature ratio_tickets (el clip(lower=1) protege contra divisiones raras, pero una antigüedad de -3 es un dato corrupto que no debe llegar tan lejos).
• le=168 en horas_semana: una semana tiene 168 horas; más que eso es un bug del emisor, no un cliente muy fan.
• Literal[...] en plan y metodo_pago restringe a los valores con los que el modelo se entrenó. Si mañana negocio lanza el plan "familiar", la API devolverá 422 en lugar de dejar que el modelo alucine sobre una categoría que nunca vio — y ese 422 es la alarma temprana de que hay que reentrenar y actualizar el contrato.
• PrediccionSalida devuelve no solo la probabilidad sino el umbral aplicado y la versión del modelo: cada respuesta es autoexplicativa y auditable. Cuando en el módulo 6 investiguemos una deriva, saber qué versión respondió cada petición será imprescindible.

Regla de oro del serving: el modelo se carga una vez, al arrancar el proceso — nunca dentro del endpoint. Cargar desde el registry cuesta segundos; hacerlo por petición destruiría cualquier presupuesto de latencia. FastAPI ofrece el patrón lifespan para ejecutar código en el arranque y la parada:

La nota de resiliencia merece pararse: si el registry no responde al arrancar, hay dos filosofías. La equivocada es capturar la excepción, arrancar "de todos modos" y devolver errores en cada /predecir — un servicio que parece sano pero no puede hacer su trabajo (un zombi). La correcta, y la que implementamos, es fallar rápido y claro: el raise mata el proceso con un mensaje inequívoco en el log, y el orquestador (Docker en 04-03, Kubernetes en 04-04) lo detectará y reintentará o alertará. Un proceso que muere ruidosamente se diagnostica en minutos; un zombi silencioso, en días.

Paso a paso:

1. cliente.model_dump() convierte el objeto Pydantic (ya validado) en un diccionario, y pd.DataFrame([...]) lo envuelve en un DataFrame de una fila — el formato que construir_features espera, idéntico al de entrenamiento.
2. construir_features importada del paquete. Este es el momento en que la decisión de 03-03 paga: ratio_tickets = tickets_soporte / antiguedad_meses.clip(lower=1) se calcula con la implementación canónica. Si alguien la mejora mañana en features.py, entrenamiento y serving cambian a la vez — el training/serving skew es estructuralmente imposible.
3. predict_proba(X)[0, 1]: fila 0 (solo hay una), columna 1 (probabilidad de la clase positiva). Devolvemos la probabilidad, no solo el booleano, porque el consumidor puede querer graduar la oferta.
4. El umbral es configurable (variable de entorno UMBRAL_ABANDONO, sobreescribible por petición con el query param umbral). El 0.5 por defecto es solo el punto de partida matemático: el umbral real es una decisión de negocio. Con el campeón actual (precision 0.55, recall 0.68), bajar el umbral captura más futuros abandonos a costa de ofrecer descuentos a clientes que no se iban a ir; subirlo hace lo contrario. Producto y finanzas deben elegir ese punto con una cuenta de costes — la API solo tiene que permitir cambiarlo sin redesplegar.

• /salud no responde "estoy vivo" sin más: comprueba que el modelo está en memoria. Este matiz importa porque es el endpoint que Docker (04-03) y las probes de Kubernetes (04-04) llamarán para decidir si el contenedor recibe tráfico o se reinicia. Un healthcheck que miente es peor que no tener healthcheck.
• /version responde a la pregunta operativa por excelencia: "¿qué modelo está sirviendo esto AHORA?". Cuando en 03-02 movimos el alias @champion, dijimos que el rollback era "mover un alias"; /version es cómo verificas, tras reiniciar el servicio, que el cambio surtió efecto.

Con el servidor de MLflow corriendo (el de sqlite del módulo 3), arrancamos:

En el log verás Cargando modelo desde models:/churn-cineclick@champion ... y después Modelo churn-cineclick v2 cargado. — el lifespan en acción. Abre ahora http://localhost:8000/docs: FastAPI ha generado la documentación interactiva con los tres endpoints, los esquemas con sus restricciones (antiguedad_meses >= 0, los valores permitidos de plan) y un botón Try it out para lanzar peticiones desde el navegador. Este /docs es el contrato que le pasas al equipo de producto.

Probemos con curl y un cliente ficticio de perfil arriesgado (poca antigüedad, poco uso, tickets):

Respuesta:

Y la validación en acción — un plan que no existe:

El modelo ni se enteró. Eso es Pydantic haciendo de portero.

Una nota sobre seguridad, sin desviarnos: este servicio correrá en la red interna de CineClick, pero aun así el mínimo exigible es una API key simple (una cabecera X-API-Key verificada con una dependencia de FastAPI contra un secreto en variable de entorno). La autenticación empresarial seria — OAuth2, mTLS, gateway — es terreno de la plataforma de la empresa, no de esta lección; lo importante es que el endpoint no quede abierto a cualquiera ni siquiera "temporalmente".

Ya lo has visto en el endpoint: cada predicción emite una línea de log con campos estructurados, no una frase libre. Configuramos la salida como JSON para que sea procesable por máquinas:

Cada línea de log de predicción contiene: hash del input (con hash_entrada sobre el payload — trazable sin volcar datos del cliente en texto plano), probabilidad, predicción, versión del modelo y latencia en ms. Parece poco, pero es exactamente la semilla de la monitorización del módulo 6: con estos logs acumulados podremos pintar la distribución de probabilidades a lo largo del tiempo (deriva, 06-02), la latencia p95 (06-01) y el volumen de peticiones. La regla: si no lo registras desde el día uno, no existirá cuando lo necesites.

• Error: cargar el modelo dentro del endpoint. Cada petición pagaría segundos de carga desde el registry. El modelo se carga una vez en el lifespan y vive en memoria.
• Error: reimplementar las features en la API. "Es solo una división" — hasta que alguien cambia el clip en features.py y el serving se queda con la versión vieja: training/serving skew silencioso, el bug más caro de detectar. En CineClick está prohibido por decisión de 03-03: siempre from cineclick_churn.features import construir_features.
• Error: arrancar sin modelo y devolver errores por petición. El servicio zombi. Falla rápido en el arranque (raise en el lifespan) y deja que el orquestador haga su trabajo.
• Error: usar async def en el endpoint de predicción. predict_proba es CPU síncrono: dentro de async def bloquearía el bucle de eventos y hundiría la concurrencia. Con def, FastAPI lo lleva al threadpool automáticamente.
• Error: aceptar cualquier string en los campos categóricos. Sin Literal, un plan="Básico" (con mayúscula y tilde) llegaría al modelo como categoría desconocida. El esquema debe reflejar el vocabulario exacto del entrenamiento.
• Consejo: devuelve siempre la versión del modelo en la respuesta. Cuesta un campo y convierte cada respuesta en evidencia auditable.
• Consejo: trata el umbral como configuración de negocio, no como constante del código. Cambiar de 0.5 a 0.4 no debería requerir un despliegue.

Producto pide un endpoint POST /predecir-lote que reciba una lista de clientes (máximo 100) y devuelva una lista de predicciones, para puntuar de una vez a todos los asistentes a un webinar de retención. Impleméntalo reutilizando los esquemas existentes. Pista: predict_proba acepta un DataFrame de N filas.

Escribe un test con TestClient de FastAPI (en tests/test_api.py) que verifique que una petición con antiguedad_meses: -5 recibe un 422 sin llegar a invocar el modelo. Pista: puedes monkeypatchear estado para no depender del registry en los tests.

Ahora mismo, si MLflow está caído cuando arranca el servicio, el proceso muere (correcto). Pero ¿qué pasa si MLflow cae después, con el servicio ya arrancado? Razona: (a) ¿sigue funcionando /predecir?, (b) ¿qué devuelve /salud?, (c) ¿es este comportamiento aceptable?

Solución 1

Lo esencial: una sola llamada a construir_features y a predict_proba para las N filas, no un bucle de N predicciones — la diferencia de rendimiento la cuantificaremos en 04-05. El max_length=100 protege al servicio de que alguien le envíe la base entera por HTTP (para eso está el batch de 04-01).

Solución 2

Si Pydantic dejara pasar la entrada, ModeloProhibido.predict_proba lanzaría el AssertionError y el test fallaría con un mensaje claro. Este test entrará en el CI de la lección 05-01.

Solución 3

(a) Sí. El modelo ya está en memoria; /predecir no toca MLflow en el camino de la petición. Que el registry esté caído no afecta al tráfico en curso — es una virtud del patrón "cargar al arrancar". (b) /salud devuelve 200 ok, porque solo comprueba que el modelo está en memoria, no la conectividad con MLflow — y eso es correcto: el healthcheck debe medir la capacidad de hacer el trabajo (predecir), no la salud de dependencias que ya no necesita. (c) Aceptable con un matiz: los nuevos arranques (un reinicio, una réplica nueva al escalar) sí fallarán mientras MLflow esté caído. Es un riesgo conocido que apuntamos para 04-03: allí discutiremos la alternativa de hornear el modelo en la imagen justamente para eliminar esta dependencia en el arranque, y por qué CineClick aun así elige el registry.

El modelo de Laura ya atiende peticiones. El servicio tiene contrato explícito (Pydantic valida dominio, no solo tipos), carga al campeón una única vez desde models:/churn-cineclick@champion con política de fallar rápido, predice importando construir_features de la fuente única — cero lógica duplicada —, expone /salud y /version para que las máquinas y los humanos sepan qué corre, y registra cada predicción en logs JSON que el módulo 6 convertirá en monitorización. Todo esto funciona... en tu máquina, con tu Python 3.11.9, tu requirements.lock instalado y tu variable de entorno apuntando a tu MLflow. El servidor de producción no tiene nada de eso, y "instálalo a mano y cruza los dedos" es exactamente la clase de proceso que este curso vino a eliminar. La siguiente lección congela el servicio completo — sistema operativo, Python, dependencias y código — en una imagen Docker que corre idéntica en cualquier parte: el "funciona en mi máquina" está a punto de dejar de ser una excusa.