Runpod explique comment monter sa propre API sur Serverless en quatre étapes

Runpod a publié un guide pas à pas pour créer sa propre API sur la plateforme Serverless. Pour passer d'un dossier vide à un endpoint HTTP fonctionnel, il faut quatre étapes : écrire un worker, le tester en local, construire une image Docker et créer l'endpoint dans la console. La plateforme ajoute elle-même cinq routes de service, une file d'attente de requêtes et l'autoscaling. Seules les secondes pendant lesquelles le worker traite une tâche sont facturées.

Le contenu est introductif et ne présente aucune nouvelle fonctionnalité. Mais pour les équipes qui veulent isoler l'inférence d'un modèle dans un service dédié sans monter de cluster, c'est un point d'entrée pratique.

Comment fonctionne un worker

Le cœur de la solution est la fonction handler. Elle reçoit un dictionnaire décrivant la tâche, et les données d'entrée se trouvent sous la clé input. À l'intérieur, on peut faire ce qu'on veut : charger un modèle en mémoire vidéo au démarrage du conteneur, générer du texte, traiter une image, ou simplement additionner deux nombres pour un test. La fonction renvoie son résultat sous forme d'objet Python ordinaire, que la plateforme sérialise en JSON.

Pour que la fonction devienne un worker, on la passe à runpod.serverless.start({"handler": handler}). C'est l'unique point d'intégration avec le SDK. Mieux vaut initialiser les objets lourds, comme les poids d'un modèle, en dehors du handler, au niveau du module. Ils sont alors chargés une seule fois au démarrage du worker, et non à chaque requête.

Le code peut être vérifié avant le déploiement. Si l'on place à côté un fichier test_input.json et que l'on lance le script, le SDK exécute le handler sur cette entrée de test et affiche le résultat dans la console. Il existe aussi un mode serveur local, avec les mêmes routes que dans le cloud : on peut l'interroger avec curl ou Postman.

Endpoints et modes d'appel

Une fois l'endpoint créé, Runpod fournit un identifiant et une adresse publique de la forme api.runpod.ai/v2/{id}. Les requêtes sont authentifiées par une clé d'API placée dans l'en-tête Bearer. Le jeu de routes est fixe :

• /run : lancement asynchrone, la réponse contient l'id de la tâche ;
• /runsync : appel synchrone, la connexion reste ouverte jusqu'à ce que le résultat soit prêt ;
• /status/{job_id} : statut et résultat d'une tâche asynchrone ;
• /cancel/{job_id} : annulation d'une tâche en file d'attente ou en cours ;
• /health : état des workers et de la file d'attente.

Le choix entre /run et /runsync dépend de la durée de la tâche. Les opérations courtes s'appellent plus commodément en mode synchrone. La génération d'images, la transcription d'un long fichier audio et tout ce qui peut prendre plusieurs minutes gagnent à être envoyés en asynchrone, avec une interrogation régulière du statut. Pour les réponses en streaming, par exemple token par token depuis un modèle de langage, le handler peut être écrit comme un générateur.

Déploiement et coût

Le code et les dépendances sont empaquetés dans une image Docker publiée dans un registre. À la création de l'endpoint dans la console, on indique l'image, le type de GPU ou de CPU, la limite de workers et les timeouts. Ensuite, la plateforme démarre et arrête elle-même les conteneurs en fonction de la longueur de la file d'attente.

Deux modes existent. Les workers flex démarrent à la demande et s'éteignent en cas d'inactivité : l'inactivité n'est donc pas facturée, mais la première requête après une pause subit un démarrage à froid. Pour les modèles aux poids volumineux, cela peut se remarquer. Les workers active tournent en permanence : la latence est plus faible, le prix à la seconde l'est aussi, mais ils sont comptés comme occupés même sans trafic. La facturation se fait à la seconde.

Par où commencer

Pour une première expérience, un ensemble minimal d'actions suffit :

1. Installer le paquet runpod et écrire un handler qui renvoie un résultat simple. 2. L'exécuter en local via test_input.json et vérifier que le format d'entrée et de sortie convient au client. 3. Construire l'image, la pousser dans le registre et créer un endpoint avec un seul worker et un timeout court. 4. Appeler /runsync avec curl, puis passer à /run et /status. 5. N'intégrer le vrai modèle et ne mesurer le démarrage à froid qu'après ces étapes.

Il vaut mieux mesurer d'emblée le délai de la première réponse après une période d'inactivité et le comparer aux exigences du produit. Ce chiffre détermine le choix entre workers flex et active. La taille de l'image influe aussi sur le démarrage à froid : les poids des gros modèles gagnent donc à être conservés sur un stockage réseau ou mis en cache, plutôt que d'être intégrés à l'image sans nécessité.