GPUs SDK-Nutzungsleitfaden

Dieser Leitfaden erklärt, wie Sie das novita-gpus SDK verwenden, um einen Async Serverless Endpoint aufzurufen, und wie Sie einen Worker-Handler anpassen.

1. SDK installieren

Installieren Sie das SDK in Ihrer Client-Umgebung oder Worker-Laufzeitumgebung:

pip install novita-gpus

2. Jobs mit dem SDK übermitteln

Die Standard-Anfrage-URL des novita-gpus SDK ist https://async-public.serverless.novita.ai/v1. Um einen Endpoint aufzurufen, legen Sie Ihren API-Schlüssel fest und erstellen Sie einen Client mit dem Endpoint-Namen.

import novita_gpus

novita_gpus.api_key = "sk_xxxx"

endpoint = novita_gpus.Endpoint("0f43a6867e05fddd")
job = endpoint.run({
    "prompt": "a red apple on a table"
})

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

3. ComfyUI-Jobbeispiel

Für novitalabs/comfyui-worker:v0.0.1 muss die Job-Eingabe einen ComfyUI-Workflow enthalten. Das folgende minimale Beispiel entspricht dem getesteten Fall:

import novita_gpus

novita_gpus.api_key = "sk_xxxx"

endpoint = novita_gpus.Endpoint("0f43a6867e05fddd")

job = endpoint.run({
    "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",
})

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

4. Benutzerdefinierter Handler

Rufen Sie auf der Worker-Seite novita_gpus.start({"handler": handler}) auf, um die Task-Schleife zu starten. Die Plattform übergibt Task-Daten an handler(job):

job["id"]: aktuelle Job-ID
job["input"]: vom Client übermittelter Eingabeinhalt
Der Rückgabewert des Handlers wird als Job-Ausgabe verwendet
Wenn das zurückgegebene dict ein error-Feld enthält, wird der Job als fehlgeschlagen markiert

Minimales Handler-Beispiel:

import time
import novita_gpus


def handler(job: dict) -> dict:
    job_id = job["id"]
    job_input = job.get("input", {})
    prompt = job_input.get("prompt", "hello")

    novita_gpus.progress_update(job, {
        "status": "running",
        "message": "job accepted",
    })

    time.sleep(1)

    return {
        "job_id": job_id,
        "prompt": prompt,
        "result": "ok",
    }


if __name__ == "__main__":
    novita_gpus.start({"handler": handler})

5. Vollständige Worker-Beispiele

Vollständigen Worker-Quellcode, Anweisungen zum Erstellen von Docker-Images und Skripte zur Task-Übermittlung finden Sie in den Novita GPUs Python-Beispielen. Das Repository enthält zwei Beispiele:

comfyui-worker: führt ComfyUI aus handler.py aus und gibt generierte Bilder zurück.
sleep-worker: ein minimales handler.py, das für eine angeforderte Dauer wartet und ein JSON-Ergebnis zurückgibt.

Jedes Beispielverzeichnis enthält:

handler.py: definiert handler(job) und startet den Worker mit novita_gpus.start({"handler": handler}).
Dockerfile: erstellt das Worker-Image.
requirements.txt: installiert novita-gpus.
submit_task.py: übermittelt eine Task mit dem novita-gpus Client-SDK.

Erstellen Sie Ihr Worker-Image und pushen Sie es in Ihre eigene Registry:

IMAGE=<your-registry>/comfyui-worker:v0.0.1

docker buildx build --platform linux/amd64 \
  -t "$IMAGE" \
  --push .

Die Task-Übermittlung verwendet das Endpoint-Namensformat <endpoint-id>-<app-name>. Beispielsweise ergeben Endpoint-ID o8UJWkag5WTn und App-Name async Folgendes:

o8UJWkag5WTn-async

Die submit_task.py-Beispiele akzeptieren die Endpoint-ID und den App-Namen separat und setzen dann den endgültigen Endpoint-Namen zusammen:

export NOVITA_API_KEY="sk_xxxx"
export NOVITA_ENDPOINT_ID="o8UJWkag5WTn"
export NOVITA_APP_NAME="async"

python submit_task.py \
  --endpoint "$NOVITA_ENDPOINT_ID" \
  --app-name "$NOVITA_APP_NAME" \
  --api-key "$NOVITA_API_KEY"

Im Skript wird der SDK-Client mit dem zusammengesetzten Endpoint-Namen erstellt:

endpoint_name = f"{args.endpoint}-{args.app_name}"
endpoint = novita_gpus.Endpoint(endpoint_name, api_key=args.api_key)

6. Bilder oder Dateien zurückgeben

Die Async Serverless Endpoint status API hat eine Größenbeschränkung für Ausgaben. Laden Sie große Dateien wie Bilder und Videos zuerst in einen Objektspeicher hoch und geben Sie URLs in der Ausgabe zurück. Konfigurieren Sie Umgebungsvariablen für den Objektspeicher im Endpoint:

BUCKET_ENDPOINT_URL=https://<your-bucket-endpoint>
BUCKET_ACCESS_KEY_ID=<your-access-key-id>
BUCKET_SECRET_ACCESS_KEY=<your-secret-access-key>
BUCKET_NAME=<your-bucket-name>

Laden Sie ein Bild im Handler hoch:

import novita_gpus


def handler(job: dict) -> dict:
    image_url = novita_gpus.upload_image(job["id"], "/tmp/output.png")

    return {
        "images": [
            {
                "filename": "output.png",
                "url": image_url,
            }
        ]
    }


if __name__ == "__main__":
    novita_gpus.start({"handler": handler})

Sie können auch reguläre Dateien oder Bytes hochladen:

import novita_gpus

file_url = novita_gpus.upload_file("result.json", "/tmp/result.json")
bytes_url = novita_gpus.upload_bytes("result.txt", b"hello")

7. FAQ

Muss ich im Worker einen API-Schlüssel konfigurieren?

Normalerweise nicht. API-Schlüssel werden hauptsächlich von Clients verwendet, um Jobs zu übermitteln, abzufragen und abzubrechen.

Welcher Handler-Rückgabewert markiert einen Job als fehlgeschlagen?

Wenn der Handler ein dict zurückgibt, das ein error-Feld enthält, wird der Job als fehlgeschlagen markiert:

return {"error": "invalid input"}

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

GPUs SDK-Nutzungsleitfaden

1. SDK installieren

2. Jobs mit dem SDK übermitteln

3. ComfyUI-Jobbeispiel

4. Benutzerdefinierter Handler

5. Vollständige Worker-Beispiele

6. Bilder oder Dateien zurückgeben

7. FAQ

Muss ich im Worker einen API-Schlüssel konfigurieren?

Welcher Handler-Rückgabewert markiert einen Job als fehlgeschlagen?

​1. SDK installieren

​2. Jobs mit dem SDK übermitteln

​3. ComfyUI-Jobbeispiel

​4. Benutzerdefinierter Handler

​5. Vollständige Worker-Beispiele

​6. Bilder oder Dateien zurückgeben

​7. FAQ

​Muss ich im Worker einen API-Schlüssel konfigurieren?

​Welcher Handler-Rückgabewert markiert einen Job als fehlgeschlagen?

1. SDK installieren

2. Jobs mit dem SDK übermitteln

3. ComfyUI-Jobbeispiel

4. Benutzerdefinierter Handler

5. Vollständige Worker-Beispiele

6. Bilder oder Dateien zurückgeben

7. FAQ

Muss ich im Worker einen API-Schlüssel konfigurieren?

Welcher Handler-Rückgabewert markiert einen Job als fehlgeschlagen?