Runpod mostra como subir uma API própria no Serverless em quatro passos

A Runpod publicou um guia passo a passo para criar uma API própria na plataforma Serverless. Ir de uma pasta vazia a um endpoint HTTP funcional leva quatro passos: escrever o worker, testá-lo localmente, montar a imagem Docker e criar o endpoint no console. A plataforma adiciona por conta própria cinco rotas de serviço, uma fila de requisições e autoescalonamento, e só é preciso pagar pelos segundos em que o worker está processando uma tarefa.

O material é introdutório e não traz funcionalidades novas. Ainda assim, para equipes que querem isolar a inferência de um modelo em um serviço separado sem montar um cluster, é um ponto de partida conveniente.

Como funciona o worker

O núcleo da solução é a função de tratamento (handler). Ela recebe um dicionário com a descrição da tarefa, e os dados de entrada ficam na chave input. Dentro dela é possível fazer qualquer coisa: carregar o modelo na memória de vídeo quando o contêiner inicia, gerar texto, processar uma imagem ou simplesmente somar dois números para testar. A função devolve o resultado como um objeto Python comum, e a plataforma o serializa em JSON.

Para que a função vire um worker, ela é passada a runpod.serverless.start({"handler": handler}). Esse é o único ponto de integração com o SDK. Objetos pesados, como os pesos de um modelo, convém inicializar fora do handler, no nível do módulo. Assim, eles são carregados uma vez, quando o worker inicia, e não a cada requisição.

É possível testar o código antes do deploy. Se você colocar um arquivo test_input.json ao lado do script e executá-lo, o SDK roda o handler com essa entrada de teste e mostra o resultado no console. Há também um modo de servidor local com as mesmas rotas da nuvem: ele pode ser acessado via curl ou Postman.

Endpoints e modos de chamada

Depois que o endpoint é criado, a Runpod fornece um identificador e um endereço público no formato api.runpod.ai/v2/{id}. As requisições são autorizadas por uma chave de API no cabeçalho Bearer. O conjunto de rotas é fixo:

• /run: execução assíncrona, que devolve o id da tarefa;
• /runsync: chamada síncrona, em que a conexão fica aberta até o resultado ficar pronto;
• /status/{job_id}: status e resultado de uma tarefa assíncrona;
• /cancel/{job_id}: cancelamento de uma tarefa na fila ou em execução;
• /health: estado dos workers e da fila.

A escolha entre /run e /runsync depende da duração da tarefa. Operações curtas são mais convenientes de chamar de forma síncrona. Geração de imagens, transcrição de áudios longos e tudo o que pode levar minutos é melhor enviar de forma assíncrona e consultar o status. Para respostas em streaming, como token por token de um modelo de linguagem, o handler pode ser feito como um gerador.

Deploy e custo

O código e as dependências são empacotados em uma imagem Docker, que é publicada em um registro. Ao criar o endpoint no console, você informa a imagem, o tipo de GPU ou CPU, o limite de workers e os timeouts. A partir daí, a plataforma inicia e para os contêineres por conta própria, de acordo com o tamanho da fila.

Há dois modos. Os workers flex iniciam sob demanda e são desligados quando ficam ociosos, então não se paga pelo tempo ocioso, mas a primeira requisição depois de uma pausa espera por um cold start. Em modelos com pesos grandes, isso pode ser perceptível. Os workers active ficam ligados o tempo todo: a latência é menor, o preço por segundo também, mas eles são contabilizados como ocupados mesmo sem tráfego. A cobrança é por segundo.

Por onde começar

Para um primeiro experimento, basta um conjunto mínimo de ações:

1. Instalar o pacote runpod e escrever um handler que devolva um resultado simples. 2. Executá-lo localmente com o test_input.json e conferir se o formato de entrada e de saída atende ao cliente. 3. Montar a imagem, enviá-la ao registro e criar um endpoint com um worker e um timeout curto. 4. Chamar /runsync via curl e, depois, passar para /run e /status. 5. Só então plugar o modelo real e medir o cold start.

O ideal é medir logo o tempo da primeira resposta após um período de ociosidade e compará-lo com os requisitos do produto. Essa medição define a escolha entre workers flex e active. O tamanho da imagem também afeta o cold start, por isso os pesos de modelos grandes devem ficar em armazenamento de rede ou em cache, em vez de embutidos na imagem sem necessidade.