Async Serverless Endpoint を作成する

Novita アカウントをお持ちでない場合は、まずサインアップしてください。詳細については、Quickstart guide を参照してください。この記事では、ComfyUI worker image novitalabs/comfyui-worker:v0.0.1 を例に、Async Serverless Endpoint の作成方法と呼び出し方法を説明します。

1. コンテナイメージを準備する

実行環境を Docker image としてパッケージ化し、事前に image registry へアップロードします。パブリックおよびプライベートの image registry の両方がサポートされています。プライベート registry では image pull credentials が必要です。

イメージは Docker Hub にアップロードできます。現在、プラットフォームは Docker Hub イメージ向けの image warm-up service を提供しています。

この例では novitalabs/comfyui-worker:v0.0.1 を使用します。このイメージには ComfyUI と Novita worker SDK が含まれています。タスク入力は ComfyUI workflow JSON で、worker handler は生成された画像結果を返します。生成された画像や動画を bucket にアップロードし、ジョブ出力で URL として返せるように、BUCKET_ENDPOINT_URL などの object storage 環境変数を設定することを推奨します。

2. インスタンス仕様を選択する

Async Serverless Endpoint は現在、次の GPU インスタンスタイプをサポートしています。

RTX 4090 24GB
H100 SXM 80GB

この comfyui-worker の例では、RTX 4090 24GB を推奨します。追加要件がある場合は、お問い合わせください。

3. Cloud Storage を作成する（任意）

共有ストレージまたは永続ストレージが必要な場合は、storage management page で cloud storage を作成し、Endpoint 作成時にそのストレージをマウントします。詳細については、Manage Cloud Storage を参照してください。

4. Endpoint を作成する

Async Serverless GPUs ページに移動し、インスタンスタイプを選択して “Create Endpoint” をクリックします。
Endpoint パラメーター設定を完了します。

Endpoint Name: Endpoint を一意に識別するために使用されます。ジョブ作成時の URL の一部になります。システムはランダムなデフォルト名を生成します。カスタマイズすることもできますが、デフォルト名の使用を推奨します。
Worker Configuration

設定項目	説明
Min Worker Count	Endpoint に保持する worker インスタンスの最小数です。最小数を大きく設定すると、コールドスタート時間の短縮に役立ちます。0 に設定すると、リクエストがない場合にアイドル worker は存在しないため、新しいリクエストの応答レイテンシが増加する可能性があります。レイテンシに敏感なシナリオで 0 を使用する場合は注意してください。
Max Worker Count	Endpoint がスケールアップできる worker インスタンスの最大数です。リクエスト量が増加すると、プラットフォームはこの最大値まで worker を自動的に増やします。この制限はコスト管理に役立ちます。
Idle Timeout (seconds)	スケールダウンによって worker が解放される直前に、プラットフォームは新しいリクエストへ素早く応答できるよう、設定された idle timeout の間 worker を保持します。この期間も worker の料金が発生します。
Max Concurrent Requests	1 つの worker が処理する同時リクエストの最大数です。これを超えた場合、リクエストは他の worker にルーティングされます。すべての worker が完全に使用中の場合、超過したリクエストは実行可能になるまでキューに入ります。
GPUs / Worker	各 worker に割り当てられる GPU カード数です。
CUDA Version	worker が使用する CUDA バージョンです。

この例では、RTX 4090 24GB を選択し、GPUs / Worker を 1 に設定します。

Type:
- Async を選択します。
Elastic Policy:
- Queue request policy を選択します。
- Single worker target concurrency を 1 に設定します。この例の ComfyUI worker は、一度に 1 つのジョブを処理します。キューに入ったリクエストが現在の worker キャパシティを超えると、プラットフォームは最大 worker 数に達するまで、キューリクエスト数に基づいて worker をスケールします。
Image Configuration:
- Image address: novitalabs/comfyui-worker:v0.0.1。
- Image repository credentials: イメージがプライベートの場合は、image pull credentials を指定します。security credentials management page で認証情報を作成できます。
- HTTP Port: Worker の HTTP ポートです。
- Container start command: コンテナ起動時に実行されるコマンドです。
Storage Configuration:
- System disk: worker インスタンスごとのシステムディスクサイズです。
- Cloud storage: マウントが必要な場合は cloud storage を選択します。詳細については、Manage Cloud Storage を参照してください。
Other:
- Health check path: このパラメーターは現在有効化されていません。
- Environment variables: サービスに必要な環境変数を設定します。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>

comfyui-worker を使用する場合、出力画像が bucket にアップロードされ、URL として返されるように object storage を設定することを強く推奨します。

料金を確認し、“Deploy with One Click” をクリックします。

5. サービスにアクセスする

Async Serverless GPUs ページで、新しく作成した Endpoint を見つけ、ステータスが “Running” であることを確認します。
Endpoint 内の少なくとも 1 つの Worker が実行中であることを確認します。
認証用の API Key があることを確認します。Endpoint 作成者と API Key 所有者は、同じチームに所属している必要があります。

Async Serverless Endpoint を呼び出すには、次の情報が必要です。

パラメーター	説明
Public base URL	`https://async-public.serverless.novita.ai/v1`
Endpoint Name	Endpoint 作成後に生成される名前です。例: `0f43a6867e05fddd`。この名前はジョブ URL の一部です。
API Key	API Key / Key Management ページから API Key を作成またはコピーします。`Authorization: Bearer <API_KEY>` リクエストヘッダーで渡します。

API Key を取得する:

Novita コンソールにログインします。
API Key / Key Management ページに移動します。
API Key を作成し、生成された sk_... 値をコピーします。
API Key 所有者と Endpoint 所有者が同じチームに所属していることを確認します。

5.1 Curl でジョブを作成し、出力を取得する

次のリクエストは、実行可能な comfyui-worker の例であり、テスト済みケースに一致しています。URL 内の 0f43a6867e05fddd を実際の Endpoint 名に置き換え、sk_xxxx を実際の API Key に置き換えてください。

Async Serverless Endpoint が受け付ける最大ジョブサイズは 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"
    }
}'

レスポンス例。ここで id は job_id です。

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

ジョブステータスを確認し、結果を取得する

Async Serverless Endpoint の status API が返す最大出力サイズは 4 MiB です。この制限を回避するには、object storage 環境変数を設定し、アップロード済みファイルの URL を出力で返してください。ジョブ結果は、完了後最大 6 時間 Async Serverless Endpoint に保持されます。

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

ジョブをキャンセルする

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

Endpoint のジョブキューステータスを確認する

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

レスポンス例:

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

5.2 Novita SDK でジョブを作成し、結果を取得する

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)

novita-gpus SDK のデフォルトリクエスト URL は https://async-public.serverless.novita.ai/v1 です。

6. Async Serverless Endpoint を管理する

Manage Serverless Endpoint を参照してください。

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Async Serverless Endpoint を作成する

1. コンテナイメージを準備する

2. インスタンス仕様を選択する

3. Cloud Storage を作成する（任意）

4. Endpoint を作成する

5. サービスにアクセスする

5.1 Curl でジョブを作成し、出力を取得する

5.2 Novita SDK でジョブを作成し、結果を取得する

6. Async Serverless Endpoint を管理する

​1. コンテナイメージを準備する

​2. インスタンス仕様を選択する

​3. Cloud Storage を作成する（任意）

​4. Endpoint を作成する

​5. サービスにアクセスする

​5.1 Curl でジョブを作成し、出力を取得する

​5.2 Novita SDK でジョブを作成し、結果を取得する

​6. Async Serverless Endpoint を管理する

1. コンテナイメージを準備する

2. インスタンス仕様を選択する

3. Cloud Storage を作成する（任意）

4. Endpoint を作成する

5. サービスにアクセスする

5.1 Curl でジョブを作成し、出力を取得する

5.2 Novita SDK でジョブを作成し、結果を取得する

6. Async Serverless Endpoint を管理する