Runpod показал, как поднять собственный API на Serverless за четыре шага

Runpod опубликовал пошаговое руководство по созданию собственного API на платформе Serverless. Путь от пустой папки до рабочего HTTP-эндпоинта занимает четыре шага: написать воркер, проверить его локально, собрать Docker-образ и создать эндпоинт в консоли. Платформа сама добавляет пять служебных маршрутов, очередь запросов и автомасштабирование, а платить нужно только за секунды, пока воркер обрабатывает задачу.

Материал вводный, новых функций в нём нет. Но для команд, которые хотят вынести инференс модели в отдельный сервис и не поднимать для этого кластер, это удобная точка входа.

Как устроен воркер

Ядро всего решения — функция-обработчик (handler). Она принимает словарь с описанием задачи, а входные данные лежат в ключе input. Внутри можно делать что угодно: загрузить модель в видеопамять при старте контейнера, сгенерировать текст, обработать изображение или просто сложить два числа для проверки. Результат функция возвращает как обычный Python-объект, платформа сериализует его в JSON.

Чтобы функция стала воркером, её передают в runpod.serverless.start({"handler": handler}). Это единственная точка интеграции с SDK. Тяжёлые объекты, например веса модели, разумно инициализировать вне handler, на уровне модуля. Тогда они загружаются один раз при старте воркера, а не при каждом запросе.

Проверять код можно до деплоя. Если положить рядом файл test_input.json и запустить скрипт, SDK прогонит обработчик на тестовом входе и выведет результат в консоль. Есть и режим локального сервера с теми же маршрутами, что и в облаке: к нему можно обращаться через curl или Postman.

Эндпоинты и режимы вызова

После создания эндпоинта Runpod выдаёт идентификатор и публичный адрес вида api.runpod.ai/v2/{id}. Запросы авторизуются API-ключом в заголовке Bearer. Набор маршрутов фиксирован:

• /run: асинхронный запуск, в ответ приходит id задачи;
• /runsync: синхронный вызов, соединение держится до готовности результата;
• /status/{job_id}: статус и результат асинхронной задачи;
• /cancel/{job_id}: отмена задачи в очереди или в работе;
• /health: состояние воркеров и очереди.

Выбор между /run и /runsync определяется длительностью задачи. Короткие операции удобнее вызывать синхронно. Генерацию изображений, транскрибацию длинного аудио и всё, что может занять минуты, лучше отправлять асинхронно и опрашивать статус. Для потоковых ответов, например токен за токеном из языковой модели, handler можно сделать генератором.

Деплой и стоимость

Код и зависимости упаковываются в Docker-образ, который публикуется в реестре. При создании эндпоинта в консоли указывают образ, тип GPU или CPU, лимит воркеров и таймауты. Дальше платформа сама запускает и останавливает контейнеры в зависимости от длины очереди.

Здесь есть два режима. Flex-воркеры стартуют по требованию и при простое гасятся, так что за простой платить не приходится, но первый запрос после паузы ждёт холодного старта. Для моделей с большими весами это может быть заметно. Active-воркеры работают постоянно: задержка ниже, цена за секунду тоже ниже, зато они считаются как занятые даже без трафика. Оплата идёт посекундно.

С чего начать

Для первого эксперимента хватит минимального набора действий:

1. Установить пакет runpod и написать handler, возвращающий простой результат. 2. Прогнать его локально через test_input.json и убедиться, что формат входа и выхода устраивает клиента. 3. Собрать образ, запушить его в реестр и создать эндпоинт с одним воркером и коротким таймаутом. 4. Вызвать /runsync через curl, затем перейти на /run и /status. 5. Только после этого подставлять реальную модель и измерять холодный старт.

Лучше сразу замерить время первого ответа после простоя и сравнить его с требованиями продукта. От этого числа зависит выбор между flex- и active-воркерами. Размер образа тоже влияет на холодный старт, поэтому веса крупных моделей стоит держать в сетевом хранилище или кэшировать, а не вшивать в образ без необходимости.