Criar Endpoint Serverless Assíncrono

Se você não tiver uma conta Novita, cadastre-se primeiro. Para detalhes, consulte o guia de início rápido. Este artigo usa a imagem de worker do ComfyUI novitalabs/comfyui-worker:v0.0.1 como exemplo para mostrar como criar e chamar um Endpoint Serverless Assíncrono.

1. Preparar a imagem do contêiner

Empacote seu ambiente de execução em uma imagem Docker e faça o upload para um registro de imagens com antecedência. Registros de imagens públicos e privados são compatíveis. Registros privados exigem credenciais para pull da imagem.

Você pode fazer upload da sua imagem para o Docker Hub. Atualmente, a plataforma fornece um serviço de aquecimento de imagem para imagens do Docker Hub.

Este exemplo usa novitalabs/comfyui-worker:v0.0.1. A imagem inclui o ComfyUI e o SDK de worker da Novita. A entrada da tarefa é um JSON de workflow do ComfyUI, e o handler do worker retorna os resultados das imagens geradas. Recomendamos configurar variáveis de ambiente de armazenamento de objetos, como BUCKET_ENDPOINT_URL, para que imagens e vídeos gerados possam ser enviados para seu bucket e retornados como URLs na saída do job.

2. Selecionar especificação da instância

Atualmente, o Endpoint Serverless Assíncrono oferece suporte aos seguintes tipos de instância de GPU:

RTX 4090 24GB
H100 SXM 80GB

Para este exemplo comfyui-worker, recomendamos RTX 4090 24GB. Para requisitos adicionais, entre em contato conosco.

3. Criar armazenamento em nuvem (opcional)

Se você precisar de armazenamento compartilhado ou persistente, crie um armazenamento em nuvem na página de gerenciamento de armazenamento e, em seguida, monte o armazenamento ao criar o endpoint. Para detalhes, consulte Gerenciar armazenamento em nuvem.

4. Criar Endpoint

Acesse a página GPUs Serverless Assíncronas, selecione um tipo de instância e clique em “Criar Endpoint”.
Conclua a configuração dos parâmetros do Endpoint.

Nome do Endpoint: usado para identificar exclusivamente o Endpoint. Ele faz parte da URL ao criar jobs. O sistema gera um nome padrão aleatório. Você pode personalizá-lo, mas é recomendado usar o nome padrão.
Configuração do worker

Item de configuração	Descrição
Número mínimo de workers	O número mínimo de instâncias de worker a serem mantidas para o Endpoint. Definir um mínimo mais alto ajuda a reduzir o tempo de cold start. Se definido como 0, não haverá workers ociosos quando não houver solicitações, o que pode aumentar a latência de resposta para novas solicitações. Use 0 com cautela em cenários sensíveis à latência.
Número máximo de workers	O número máximo de instâncias de worker para o qual o Endpoint pode escalar. Quando o volume de solicitações aumenta, a plataforma aumenta automaticamente o número de workers até esse máximo. Esse limite ajuda a controlar custos.
Tempo limite de ociosidade (segundos)	Quando um worker está prestes a ser liberado devido à redução de escala, a plataforma o mantém pelo tempo limite de ociosidade configurado para que ele possa responder rapidamente a novas solicitações. Você é cobrado pelo worker durante esse período.
Máximo de solicitações simultâneas	O número máximo de solicitações simultâneas tratadas por um worker. Se esse número for excedido, as solicitações serão roteadas para outros workers. Se todos os workers estiverem totalmente ocupados, as solicitações excedentes serão enfileiradas até que a execução seja possível.
GPUs / worker	Número de placas de GPU alocadas para cada worker.
Versão do CUDA	Versão do CUDA usada pelo worker.

Para este exemplo, selecione RTX 4090 24GB e defina GPUs / Worker como 1.

Tipo:
- Selecione Assíncrono.
Política elástica:
- Selecione Política de enfileiramento de solicitações.
- Defina Concorrência-alvo de um único worker como 1. O worker do ComfyUI neste exemplo processa um job por vez. Quando as solicitações enfileiradas excedem a capacidade atual dos workers, a plataforma escala os workers com base na contagem de solicitações na fila até atingir o número máximo de workers.
Configuração da imagem:
- Endereço da imagem: novitalabs/comfyui-worker:v0.0.1.
- Credenciais do repositório de imagens: se a imagem for privada, forneça credenciais para pull da imagem. Você pode criar credenciais na página de gerenciamento de credenciais de segurança.
- Porta HTTP: porta HTTP do worker.
- Comando de inicialização do contêiner: comando executado quando o contêiner é iniciado.
Configuração de armazenamento:
- Disco do sistema: tamanho do disco do sistema por instância de worker.
- Armazenamento em nuvem: selecione o armazenamento em nuvem se precisar montá-lo. Para detalhes, consulte Gerenciar armazenamento em nuvem.
Outros:
- Caminho de verificação de integridade: este parâmetro não está habilitado no momento.
- Variáveis de ambiente: defina as variáveis de ambiente exigidas pelo serviço. Exemplo de configuração S3:

BUCKET_ENDPOINT_URL=https://s3.<aws-region>.amazonaws.com
BUCKET_ACCESS_KEY_ID=<your-access-key-id>
BUCKET_SECRET_ACCESS_KEY=<your-secret-access-key>
BUCKET_NAME=<your-bucket-name>

Ao usar comfyui-worker, recomendamos fortemente configurar o armazenamento de objetos para que as imagens de saída sejam enviadas para um bucket e retornadas como URLs.

Revise os preços e clique em “Implantar com um clique”.

5. Acessar o serviço

Na página GPUs Serverless Assíncronas, encontre o Endpoint recém-criado e verifique se seu status é “Em execução”.
Certifique-se de que pelo menos um Worker no Endpoint esteja em execução.
Certifique-se de ter uma Chave de API para autenticação. O criador do Endpoint e o proprietário da Chave de API devem pertencer à mesma equipe.

Você precisa das seguintes informações para chamar um Endpoint Serverless Assíncrono:

Parâmetro	Descrição
URL base pública	`https://async-public.serverless.novita.ai/v1`
Nome do Endpoint	O nome gerado após a criação do Endpoint, por exemplo `0f43a6867e05fddd`. Esse nome faz parte da URL do job.
Chave de API	Crie ou copie uma Chave de API na página API Key / Gerenciamento de chaves. Passe-a no cabeçalho de solicitação `Authorization: Bearer <API_KEY>`.

Obter uma Chave de API:

Faça login no console da Novita.
Acesse a página API Key / Gerenciamento de chaves.
Crie uma Chave de API e copie o valor sk_... gerado.
Certifique-se de que o proprietário da Chave de API e o proprietário do Endpoint estejam na mesma equipe.

5.1 Criar um job e recuperar a saída via Curl

A solicitação a seguir é um exemplo executável de comfyui-worker e corresponde ao caso testado. Substitua 0f43a6867e05fddd na URL pelo nome real do seu Endpoint e substitua sk_xxxx pela sua Chave de API real.

O tamanho máximo de job aceito pelo Endpoint Serverless Assíncrono é 4 MiB.

curl -X POST https://async-public.serverless.novita.ai/v1/0f43a6867e05fddd/run \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_xxxx' \
  -d '{
    "input": {
      "workflow": {
        "4": {
          "class_type": "CheckpointLoaderSimple",
          "inputs": {
            "ckpt_name": "flux1-dev-fp8.safetensors"
          }
        },
        "5": {
          "class_type": "EmptyLatentImage",
          "inputs": {
            "width": 512,
            "height": 512,
            "batch_size": 1
          }
        },
        "6": {
          "class_type": "CLIPTextEncode",
          "inputs": {
            "clip": ["4", 1],
            "text": "a red apple on a table"
          }
        },
        "7": {
          "class_type": "CLIPTextEncode",
          "inputs": {
            "clip": ["4", 1],
            "text": "blurry, low quality"
          }
        },
        "3": {
          "class_type": "KSampler",
          "inputs": {
            "model": ["4", 0],
            "positive": ["6", 0],
            "negative": ["7", 0],
            "latent_image": ["5", 0],
            "seed": 42,
            "steps": 10,
            "cfg": 7,
            "sampler_name": "euler",
            "scheduler": "normal",
            "denoise": 1
          }
        },
        "8": {
          "class_type": "VAEDecode",
          "inputs": {
            "samples": ["3", 0],
            "vae": ["4", 2]
          }
        },
        "9": {
          "class_type": "SaveImage",
          "inputs": {
            "filename_prefix": "test",
            "images": ["8", 0]
          }
        }
      },
      "output_node_id": "9"
    }
}'

Exemplo de resposta, em que id é o job_id:

{"id":"8cb6a77c-62aa-4eb4-9226-1ca5724fd9dd","status":"PENDING"}

Verificar o status do job e recuperar resultados

O tamanho máximo de saída retornado pela API status do Endpoint Serverless Assíncrono é 4 MiB. Para evitar essa limitação, configure variáveis de ambiente de armazenamento de objetos e retorne URLs dos arquivos enviados na saída.Os resultados do job são mantidos no Endpoint Serverless Assíncrono por até 6 horas após a conclusão.

curl -X GET https://async-public.serverless.novita.ai/v1/0f43a6867e05fddd/status/33a0bc4b-7312-41f6-ad15-eb9016bd68f9 \
  -H 'Authorization: Bearer sk_xxxx'

Cancelar job

curl -X POST https://async-public.serverless.novita.ai/v1/0f43a6867e05fddd/cancel/e5f3c3c0-c3b1-49c2-9452-bb96eaa34ce6 \
  -H 'Authorization: Bearer sk_xxxx'

Verificar status da fila de jobs do Endpoint

curl -X GET https://async-public.serverless.novita.ai/v1/0f43a6867e05fddd/health \
  -H 'Authorization: Bearer sk_xxxx'

Exemplo de resposta:

{
  "workers": {
    "idle": 0,
    "running": 0,
    "throttled": 0,
    "total": 0
  },
  "jobs": {
    "completed": 0,
    "failed": 0,
    "inProgress": 0,
    "inQueue": 0,
    "retried": 0
  }
}

5.2 Criar job e obter resultados via SDK da Novita

Instale o SDK:

pip install novita-gpus

import novita_gpus

novita_gpus.api_key = "sk_xxxx"

input_payload = {
    "workflow": {
        "4": {
            "class_type": "CheckpointLoaderSimple",
            "inputs": {"ckpt_name": "flux1-dev-fp8.safetensors"},
        },
        "5": {
            "class_type": "EmptyLatentImage",
            "inputs": {"width": 512, "height": 512, "batch_size": 1},
        },
        "6": {
            "class_type": "CLIPTextEncode",
            "inputs": {"clip": ["4", 1], "text": "a red apple on a table"},
        },
        "7": {
            "class_type": "CLIPTextEncode",
            "inputs": {"clip": ["4", 1], "text": "blurry, low quality"},
        },
        "3": {
            "class_type": "KSampler",
            "inputs": {
                "model": ["4", 0],
                "positive": ["6", 0],
                "negative": ["7", 0],
                "latent_image": ["5", 0],
                "seed": 42,
                "steps": 10,
                "cfg": 7,
                "sampler_name": "euler",
                "scheduler": "normal",
                "denoise": 1,
            },
        },
        "8": {
            "class_type": "VAEDecode",
            "inputs": {"samples": ["3", 0], "vae": ["4", 2]},
        },
        "9": {
            "class_type": "SaveImage",
            "inputs": {"filename_prefix": "test", "images": ["8", 0]},
        },
    },
    "output_node_id": "9",
}

endpoint = novita_gpus.Endpoint("0f43a6867e05fddd")
job = endpoint.run(input_payload)

print(job.status())
output = job.output(timeout=300)
print(output)

A URL de solicitação padrão do SDK novita-gpus é https://async-public.serverless.novita.ai/v1.

6. Gerenciar Endpoint Serverless Assíncrono

Consulte Gerenciar Endpoint Serverless.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Criar Endpoint Serverless Assíncrono

1. Preparar a imagem do contêiner

2. Selecionar especificação da instância

3. Criar armazenamento em nuvem (opcional)

4. Criar Endpoint

5. Acessar o serviço

5.1 Criar um job e recuperar a saída via Curl

5.2 Criar job e obter resultados via SDK da Novita

6. Gerenciar Endpoint Serverless Assíncrono

​1. Preparar a imagem do contêiner

​2. Selecionar especificação da instância

​3. Criar armazenamento em nuvem (opcional)

​4. Criar Endpoint

​5. Acessar o serviço

​5.1 Criar um job e recuperar a saída via Curl

​5.2 Criar job e obter resultados via SDK da Novita

​6. Gerenciar Endpoint Serverless Assíncrono

1. Preparar a imagem do contêiner

2. Selecionar especificação da instância

3. Criar armazenamento em nuvem (opcional)

4. Criar Endpoint

5. Acessar o serviço

5.1 Criar um job e recuperar a saída via Curl

5.2 Criar job e obter resultados via SDK da Novita

6. Gerenciar Endpoint Serverless Assíncrono