Runpod muestra cómo levantar tu propia API en Serverless en cuatro pasos

Runpod ha publicado una guía paso a paso para crear una API propia en la plataforma Serverless. Ir de una carpeta vacía a un endpoint HTTP funcional lleva cuatro pasos: escribir el worker, probarlo en local, construir una imagen Docker y crear el endpoint en la consola. La plataforma añade por sí sola cinco rutas de servicio, una cola de solicitudes y autoescalado, y solo se paga por los segundos en que el worker procesa una tarea.

El material es introductorio y no presenta funciones nuevas. Aun así, para los equipos que quieren sacar la inferencia de un modelo a un servicio independiente sin montar un clúster, es un punto de entrada cómodo.

Cómo funciona el worker

El núcleo de la solución es la función manejadora (handler). Recibe un diccionario con la descripción de la tarea, y los datos de entrada están en la clave input. Dentro se puede hacer lo que se quiera: cargar el modelo en la memoria de vídeo al arrancar el contenedor, generar texto, procesar una imagen o simplemente sumar dos números para comprobar que todo funciona. La función devuelve el resultado como un objeto normal de Python y la plataforma lo serializa a JSON.

Para convertir la función en un worker, se pasa a runpod.serverless.start({"handler": handler}). Es el único punto de integración con el SDK. Los objetos pesados, como los pesos del modelo, conviene inicializarlos fuera del handler, a nivel de módulo. Así se cargan una sola vez al arrancar el worker y no en cada solicitud.

El código se puede probar antes del despliegue. Si se coloca al lado un archivo test_input.json y se ejecuta el script, el SDK lanza el manejador con esa entrada de prueba y muestra el resultado en la consola. También hay un modo de servidor local con las mismas rutas que en la nube, al que se puede acceder con curl o Postman.

Endpoints y modos de llamada

Tras crear el endpoint, Runpod entrega un identificador y una dirección pública con el formato api.runpod.ai/v2/{id}. Las solicitudes se autorizan con una clave de API en la cabecera Bearer. El conjunto de rutas es fijo:

• /run: lanzamiento asíncrono; la respuesta devuelve el id de la tarea;
• /runsync: llamada síncrona; la conexión se mantiene hasta que el resultado está listo;
• /status/{job_id}: estado y resultado de una tarea asíncrona;
• /cancel/{job_id}: cancelación de una tarea en cola o en ejecución;
• /health: estado de los workers y de la cola.

La elección entre /run y /runsync depende de la duración de la tarea. Las operaciones cortas es mejor llamarlas de forma síncrona. La generación de imágenes, la transcripción de audios largos y cualquier cosa que pueda tardar minutos conviene enviarlas de forma asíncrona y consultar el estado. Para las respuestas en streaming, por ejemplo token a token desde un modelo de lenguaje, el handler puede implementarse como generador.

Despliegue y coste

El código y las dependencias se empaquetan en una imagen Docker que se publica en un registro. Al crear el endpoint en la consola se indican la imagen, el tipo de GPU o CPU, el límite de workers y los timeouts. A partir de ahí, la plataforma arranca y detiene contenedores según la longitud de la cola.

Hay dos modos. Los workers flex arrancan bajo demanda y se apagan cuando están inactivos, así que no se paga por el tiempo de inactividad, pero la primera solicitud tras una pausa tiene que esperar un arranque en frío. Con modelos de pesos grandes, esa espera puede notarse. Los workers active funcionan de forma permanente: la latencia es menor y el precio por segundo también, pero se contabilizan como ocupados incluso sin tráfico. El pago es por segundo.

Por dónde empezar

Para un primer experimento basta con un conjunto mínimo de acciones:

1. Instalar el paquete runpod y escribir un handler que devuelva un resultado sencillo. 2. Ejecutarlo en local con test_input.json y comprobar que el formato de entrada y salida satisface al cliente. 3. Construir la imagen, subirla al registro y crear un endpoint con un worker y un timeout corto. 4. Llamar a /runsync con curl y después pasar a /run y /status. 5. Solo entonces incorporar el modelo real y medir el arranque en frío.

Lo mejor es medir desde el principio el tiempo de la primera respuesta tras un periodo de inactividad y compararlo con los requisitos del producto. De esa cifra depende la elección entre workers flex y active. El tamaño de la imagen también influye en el arranque en frío, por lo que los pesos de los modelos grandes conviene mantenerlos en almacenamiento de red o cachearlos, en lugar de incluirlos en la imagen sin necesidad.