创建 Async Serverless Endpoint

首次操作时，请先完成账号的注册、实名认证和账户充值。详情请参见新手指引。本文以部署一个基于 PPIO SDK 的 ComfyUI worker 镜像 image.ppinfra.com/prod-gpucloudpublic/comfyui-worker:v0.0.1 为例，介绍如何创建一个 Async Serverless Endpoint。

1. 准备容器镜像

您需要提前将运行环境打包成 Docker 镜像，并上传至镜像仓库。支持指定公共镜像仓库地址和私有镜像仓库地址（需提供镜像仓库认证凭证）。

您可以将镜像上传至 Docker Hub，目前平台已针对该站点提供镜像预热服务。详情请参见使用镜像预热服务。

本示例使用 image.ppinfra.com/prod-gpucloudpublic/comfyui-worker:v0.0.1 模型镜像。该镜像内置 ComfyUI 与 PPIO worker SDK，任务输入为 ComfyUI workflow JSON，输出图片会通过 worker handler 返回。建议配置 BUCKET_ENDPOINT_URL 等对象存储相关环境变量，将 Async Serverless Endpoint 产生的图片、视频上传到对象存储 Bucket，并在任务结果中返回文件 URL。

2. 选择实例规格

目前Async Serverless Endpoint 支持以下两种 GPU 实例规格：

RTX 4090 24GB
H100 SXM 80GB

本示例中的 comfyui-worker 推荐选择 RTX 4090 24GB。如有更多需求，请联系我们。

3. 创建云存储（可选）

如果有共享存储和持久化存储的需求，可以在存储管理页面创建云存储，然后在创建实例时为容器挂载云存储。详情请参见管理云存储。

4.创建 Endpoint

进入 Serverless GPUs 页面，选择规格，单击「创建 Endpoint」。
完成 Endpoint 的参数配置。

Endpoint 名称：用于唯一标识 Endpoint，在创建job时是URL的一部分。系统会自动生成一个默认随机生产的名称，支持自定义，请优先用默认的名称。

Worker 配置

配置项	说明
最小 Worker 数	Endpoint 最少需要保留的实例数。设置最小实例数可以帮助减少冷启动时间。如果设置为0，则服务没有请求时不会保留任何实例，这可能会导致无法快速响应后续的请求，因此对于响应时间要求较高的场景，请谨慎设置为0。
最大 Worker 数	Endpoint 最大可以扩展的实例数。当服务请求增加，触发自动扩容机制时，会增加 Worker 数，因此限制最大 Worker 数可以帮助控制成本。
空闲超时（秒）	当触发自动缩容机制而准备释放 Worker 时，在指定的时间内（即空闲超时），平台会为您保留该 Worker ，以便快速应对后续可能上涨的请求量。请注意，平台会收取这段时间对应的 Worker 费用。
最大并发数	每个 Worker 能处理的请求最大并发数，当并发数超过最大值时，会将请求调度到其他 Worker 上。如果所有 Worker 并发都被打满，则会将请求存放到队列中等待被执行。
GPUs / Worker	每个 Worker 占用的 GPU 卡数。
CUDA 版本	支持指定 CUDA 版本。

本示例推荐选择 RTX 4090 24GB，GPUs / Worker 设置为 1。

Type
- Endpoint类型，请选择 异步（Async）；
弹性策略
- 策略类型请选择 队列请求数策略。
- 单 worker 目标并发请配置为 1。本示例中的 ComfyUI worker 每个 Worker 同一时间处理一个 job；当排队请求数超过当前 Worker 可处理能力时，平台会根据队列请求数自动扩容，直到达到最大 Worker 数。
镜像配置
- 镜像地址：要部署的镜像的地址。例如 image.ppinfra.com/prod-gpucloudpublic/comfyui-worker:v0.0.1。
- 镜像仓库凭证：如果指定的镜像为私有镜像，需要配置镜像仓库访问凭证才能拉取镜像。您可以在安全凭证管理页面创建凭证。
- HTTP 端口：Worker 对外开放的 HTTP 端口。
- 容器启动命令：容器启动时执行的命令。
存储配置
- 系统盘：每个 Worker 的系统盘容量大小。
- 云存储：如果要挂载云存储，请选择云存储。详情请参见管理云存储。
其他
- 健康检查路径：此参数暂未启用。
- 环境变量：设置服务所需的环境变量，以便在 Worker 启动时自动初始化。以腾讯云对象存储 COS 示例如下：
Bash
BUCKET_ENDPOINT_URL=https://<your-bucket-name>cos.<region>.myqcloud.com BUCKET_ACCESS_KEY_ID=AKIASVYYYN6L4S6TTTTTT BUCKET_SECRET_ACCESS_KEY=maVz2OwY98UUUUUUGjMsmR/Yo8/Zzw0qWMMMMMMM
在使用 comfyui-worker 这个镜像时，强烈推荐配置对象存储相关配置，将输出图片上传到对象存储的 Bucket 中；最终的图片上传效果取决于 worker handler 的实现。客户端调用使用的 API Key 不需要配置到 worker 环境变量中，worker 运行时鉴权信息由平台注入。

确认费用信息，单击「一键部署」。

5.访问服务

Serverless GPUs 页面，找到新创建的 Endpoint，确认状态已变为运行中。
确认 Endpoint 中至少有一个 Worker 处于运行中。
确认拥有对应的 API Key 用于调用鉴权，创建 Endpoint 的用户与 API Key 对应的用户应处于同一团队中。

调用 Async Serverless Endpoint 需要准备以下信息：

参数	说明
公网调用地址	`https://async-public.serverless.ppinfra.com/v1`
Endpoint 名称	创建 Endpoint 后得到的名称，例如 `0f43a6867e05fddd`。该名称是任务提交 URL 的一部分。
API Key	进入控制台的 API Key / 密钥管理页面创建或复制 API Key。调用时放在 `Authorization: Bearer <API_KEY>` 请求头中。

获取 API Key：

登录 PPIO 控制台。
进入 API Key / 密钥管理页面。
单击创建 API Key，复制生成的 sk_... 字符串。
确认该 API Key 所属用户与 Endpoint 所属用户在同一团队中。

5.1 通过Curl的方式来创建job 以及获取执行结果

创建Job 这里给出一个 comfyui-worker worker 中实际可执行的例子。该请求地址和 payload 与测试用例保持一致。请将 URL 中的 0f43a6867e05fddd 替换为您的真实 Endpoint 名称，并将 sk_xxxx 替换为您的真实 API Key。请注意：Async Serverless Endpoint 所能接受最大的 job size 大小为 4MiB；

Bash

curl -X POST https://async-public.serverless.ppinfra.com/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"
    }
}'

创建成功得到的 response 如下，其中的 id 为 job_id：

JSON

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

查看job状态及获取执行结果： 请注意：您能通过 Async Service Endpoint 的 status 接口能获取到的最大 output size 为 4MiB；所以请通过配置 S3 环境变量的方式在 handler.py 中将输出的图片或视频上传到 S3 对象存储，这种情况下 output 的大小不受限制；请注意：Job执行结束后，执行结果在Async serverless Endpoint中最多保存 6 小时；

Bash

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

Cancel（取消） Job ：

Bash

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

查看Endpoint Job队列状态：

Bash

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

得到的 response 如下：

JSON

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

5.2 通过 PPIO SDK 来创建 Job 及获取执行结果

安装 SDK：

Bash

pip install ppio-gpus

Python

import ppio_gpus

ppio_gpus.api_key = "sk_xxx"

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 = ppio_gpus.Endpoint("0f43a6867e05fddd")
run_request = endpoint.run(input_payload)

status = run_request.status()
print(f"Initial job status: {status}")

if status != "COMPLETED":
    # Polling with timeout for long-running tasks
    output = run_request.output(timeout=60)
else:
    output = run_request.output()
print(f"Job output: {output}")

ppio-gpus SDK 默认请求地址已经是 https://async-public.serverless.ppinfra.com/v1。这里设置的 ppio_gpus.api_key 只用于客户端提交、查询、取消任务，不用于 worker 拉取任务或回传结果。如需使用 ppio-gpus SDK 编写自定义 worker handler、上报进度或上传图片/文件，请参见《PPIO GPUs SDK 使用指南》。

6. 管理 Async Serverless Endpoint

参考管理 serverless Endpoint 文档；

产品简介

计费说明

操作指南

常见问题

最佳实践

1. 准备容器镜像

2. 选择实例规格

3. 创建云存储（可选）

4.创建 Endpoint

5.访问服务

5.1 通过Curl的方式来创建job 以及获取执行结果

5.2 通过 PPIO SDK 来创建 Job 及获取执行结果

6. 管理 Async Serverless Endpoint

​1. 准备容器镜像

​2. 选择实例规格

​3. 创建云存储（可选）

​4.创建 Endpoint

​5.访问服务

​5.1 通过Curl的方式来创建job 以及获取执行结果

​5.2 通过 PPIO SDK 来创建 Job 及获取执行结果

​6. 管理 Async Serverless Endpoint

1. 准备容器镜像

2. 选择实例规格

3. 创建云存储（可选）

4.创建 Endpoint

5.访问服务

5.1 通过Curl的方式来创建job 以及获取执行结果

5.2 通过 PPIO SDK 来创建 Job 及获取执行结果

6. 管理 Async Serverless Endpoint