列队 Queue

利用我们的队列系统，您可以更精细地控制流量的意外激增。它还为您提供了在需要时取消请求的能力，并授予您可观察性以监控您在队列中的当前位置。除此之外，使用队列系统还可以让您免于长时间运行 https 请求的麻烦。

对于耗时超过几秒钟的请求（AI 应用程序通常如此），我们构建了一个队列系统。

队列端点

您可以通过队列子域添加到功能 URL 的一组端点与所有队列功能进行交互。端点如下：

端点	方法	描述
queue.fal.run/{appId}	POST	将请求添加到队列
queue.fal.run/{appId}/requests/{request_id}/status	GET	获取请求的状态
queue.fal.run/{appId}/requests/{request_id}	GET	获取请求的响应
queue.fal.run/{appId}/requests/{request_id}/cancel	PUT	取消请求

例如，如果您想使用 curl 命令向上述端点提交请求并将其添加到队列中，您的命令将显示如下：

以下是带有 request_id 的响应示例：

bash

curl -X POST https://queue.fal.run/fal-ai/fast-sdxl \
  -H "Authorization: Key $FAL_KEY" \
  -d '{"prompt": "a cat"}'

有效负载可帮助您使用 request_id 跟踪请求，并为您提供获取请求状态、取消请求或在响应准备就绪后获取响应所需的信息，因此您不必自己构建这些端点。

json

{
  "request_id": "80e732af-660e-45cd-bd63-580e4f2a94cc",
  "response_url": "https://queue.fal.run/fal-ai/fast-sdxl/requests/80e732af-660e-45cd-bd63-580e4f2a94cc",
  "status_url": "https://queue.fal.run/fal-ai/fast-sdxl/requests/80e732af-660e-45cd-bd63-580e4f2a94cc/status",
  "cancel_url": "https://queue.fal.run/fal-ai/fast-sdxl/requests/80e732af-660e-45cd-bd63-580e4f2a94cc/cancel"
}

请求状态

获得请求 ID 后，您可以使用此请求 ID 获取请求的状态。此端点将为您提供有关请求状态、请求在队列中的位置或响应本身（如果响应已准备就绪）的信息。

bash

curl -X GET https://queue.fal.run/fal-ai/fast-sdxl/requests/{request_id}/status

以下是具有 IN_QUEUE 状态的响应示例：

json

{
  "status": "IN_QUEUE",
  "queue_position": 0,
  "response_url": "https://queue.fal.run/fal-ai/fast-sdxl/requests/80e732af-660e-45cd-bd63-580e4f2a94cc"
}

状态类型

队列 status 可以具有以下类型之一及其各自的属性：

IN_QUEUE:

queue_position：任务在队列中的当前位置。
response_url：任务处理后响应可用的 URL。

IN_PROGRESS:

logs：与请求相关的日志数组。请注意，需要启用它，如上一节所述。
response_url：响应可用的 URL。

COMPLETED:

logs：与请求相关的日志数组。请注意，需要启用它，如上一节所述。
response_url：响应可用的 URL。

日志

默认情况下，日志处于禁用状态。为了为您的请求启用日志，您需要在获取请求状态时发送 logs=1 查询参数。例如：

bash

curl -X GET https://queue.fal.run/fal-ai/fast-sdxl/requests/{request_id}/status?logs=1

启用后，队列状态中的 logs 属性包含一个日志条目数组，每个条目都由 RequestLog 类型表示。RequestLog 对象具有以下属性：

message：包含日志消息的字符串。
level：日志的严重性，可以是以下之一：
STDERR | STDOUT | ERROR | INFO | WARN | DEBUG
source：表示日志的来源。
timestamp：表示生成日志的时间的字符串。

这些日志提供了有关排队任务的状态和进度的宝贵见解，有助于有效地监控和调试。

取消请求

如果您的请求仍在队列中且尚未处理，您仍可以取消它。

bash

curl -X PUT https://queue.fal.run/fal-ai/fast-sdxl/requests/{request_id}/cancel

获取响应

一旦您获得 COMPLETED 状态，response 将与其 logs 一起可用。

bash

curl -X GET https://queue.fal.run/fal-ai/fast-sdxl/requests/{request_id}

以下是具有 COMPLETED 状态的响应示例：

json

{
  "status": "COMPLETED",
  "logs": [
    {
      "message": "2020-05-04 14:00:00.000000",
      "level": "INFO",
      "source": "stdout",
      "timestamp": "2020-05-04T14:00:00.000000Z"
    }
  ],
  "response": {
    "message": "Hello World!"
  }
}

一个简单的队列配方

提交您的请求，让我们的客户端为您处理状态跟踪。下一节详细介绍了 fal 客户端如何使用 fal 函数简化应用程序的构建。

上次更新于 2024 年 6 月 21 日