使用 Curl 查询 Gradio 应用

可以使用 cURL 将任何 Gradio 应用作为 API 使用，cURL 是预装在许多操作系统上的命令行工具。如果您尝试从 Python 或 Javascript 之外的环境查询 Gradio 应用，这将特别有用（因为 Gradio 为 Python 和 Javascript 都提供了专门的客户端）。

例如，考虑这个将文本从英语翻译成法语的 Gradio 演示：https://abidlabs-en2fr.hf.space/。

使用 curl，我们可以通过编程方式翻译文本。

这是实现此目的的代码

$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello, my friend."] 
}'

>> {"event_id": $EVENT_ID}

$ curl -N https://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID

>> event: complete
>> data: ["Bonjour, mon ami."]

注意：进行预测和获取结果需要两次 curl 请求：一次 POST 和一次 GET。POST 请求返回一个 EVENT_ID 并将其打印到控制台，该 EVENT_ID 用于第二次 GET 请求以获取结果。您可以使用 awk 和 read 将这些命令合并为单个命令，以解析第一个命令的结果并将其传递给第二个命令，如下所示

$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello, my friend."] 
}' \
  | awk -F'"' '{ print $4}'  \
  | read EVENT_ID; curl -N https://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID

>> event: complete
>> data: ["Bonjour, mon ami."]

在本指南的其余部分，我们将更详细地解释这两个步骤，并提供使用 curl 查询 Gradio 应用的更多示例。

先决条件：对于本指南，您不需要详细了解如何构建 Gradio 应用。但是，熟悉 Gradio 的输入和输出组件概念会有所帮助。

安装

通常不需要安装 cURL，因为它预装在许多操作系统上。运行

curl --version

以确认 curl 已安装。如果尚未安装，您可以访问 https://curl.se/download.html 进行安装。

步骤 0：获取 Gradio 应用的 URL

要查询 Gradio 应用，您需要其完整的 URL。这通常就是 Gradio 应用托管的 URL，例如：https://bec81a83-5b5c-471e.gradio.live

Hugging Face Spaces

但是，如果您要查询 Hugging Face Spaces 上的 Gradio 应用，您需要使用嵌入的 Gradio 应用的 URL，而不是 Space 网页的 URL。例如

❌ Space URL: https://hugging-face.cn/spaces/abidlabs/en2fr
✅ Gradio app URL: https://abidlabs-en2fr.hf.space/

您可以通过单击页面底部的“view API”链接获取 Gradio 应用 URL。或者，您可以右键单击页面，然后单击“查看框架源代码”或浏览器中的等效选项，以查看嵌入的 Gradio 应用的 URL。

虽然您可以将任何公共 Space 用作 API，但如果您发出过多请求，Hugging Face 可能会对您进行速率限制。为了无限使用 Space，只需复制 Space 创建一个私有 Space，然后您就可以根据需要发出任意数量的请求！

注意：要查询私有 Space，您需要传入您的 Hugging Face (HF) 令牌。您可以在此处获取您的 HF 令牌：https://hugging-face.cn/settings/tokens。在这种情况下，您需要在下面讨论的两次 curl 调用中都包含一个额外的 header

-H "Authorization: Bearer $HF_TOKEN"

现在，我们准备发出两次 curl 请求。

步骤 1：进行预测 (POST)

两次 curl 请求中的第一次是 POST 请求，它将输入 payload 提交给 Gradio 应用。

POST 请求的语法如下

$ curl -X POST $URL/call/$API_NAME -H "Content-Type: application/json" -d '{
  "data": $PAYLOAD
}'

其中

$URL 是在步骤 0 中获取的 Gradio 应用的 URL
$API_NAME 是您正在运行的事件的 API 端点名称。您可以通过点击页面底部的“view API”链接获取 API 端点名称。
$PAYLOAD 是一个有效的 JSON 数据列表，其中包含输入 payload，每个输入组件一个元素。

成功发出此 POST 请求后，您将收到一个事件 ID，其格式如下所示，并打印到终端

>> {"event_id": $EVENT_ID}

此 EVENT_ID 将在随后的 curl 请求中用于获取预测结果。

以下是一些如何发出 POST 请求的示例

基本示例

回到页面开头的示例，以下是如何为接受单个输入文本组件的简单 Gradio 应用程序发出 POST 请求

$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello, my friend."] 
}'

多个输入组件

此 Gradio 演示接受三个输入：一个对应 gr.Textbox 的字符串，一个对应 gr.Checkbox 的布尔值，以及一个对应 gr.Slider 的数值。以下是 POST 请求

curl -X POST https://gradio-hello-world-3.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello", true, 5]
}'

私有 Space

如前所述，如果您要向私有 Space 发出请求，则需要传入一个对该 Space 具有读取权限的 Hugging Face 令牌。请求将如下所示

$ curl -X POST https://private-space.hf.space/call/predict -H "Content-Type: application/json" -H "Authorization: Bearer $HF_TOKEN" -d '{
  "data": ["Hello, my friend."] 
}'

文件

如果您使用 curl 查询需要文件输入的 Gradio 应用程序，则文件必须以 URL 形式提供，并且 URL 必须以以下格式包含在字典中

{"path": $URL}

以下是一个 POST 请求示例

$ curl -X POST https://gradio-image-mod.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": [{"path": "https://raw.githubusercontent.com/gradio-app/gradio/test/test_files/bus.png"}] 
}'

有状态演示

如果您的 Gradio 演示在多次交互中保留用户状态（例如，是一个聊天机器人），您可以传递一个 session_hash 以及 data。具有相同 session_hash 的请求被视为同一用户会话的一部分。这可能看起来像这样

# These two requests will share a session

curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{
  "data": ["Are you sentient?"],
  "session_hash": "randomsequence1234"
}'

curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{
  "data": ["Really?"],
  "session_hash": "randomsequence1234"
}'

# This request will be treated as a new session

curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{
  "data": ["Are you sentient?"],
  "session_hash": "newsequence5678"
}'

步骤 2：获取结果 (GET)

一旦您收到对应于您的预测的 EVENT_ID，您就可以流式传输结果。Gradio 将这些结果存储在 Gradio 应用程序的最近最少使用缓存中。默认情况下，缓存可以存储 2,000 个结果（跨应用程序的所有用户和端点）。

要流式传输您的预测结果，请使用以下语法发出 GET 请求

$ curl -N $URL/call/$API_NAME/$EVENT_ID

提示： 如果您从私人空间获取结果，请在 GET 请求中包含带有您的 HF 令牌的 header，如下所示：`-H "Authorization: Bearer $HF_TOKEN"`。

这应该会产生以下格式的响应流

event: ... 
data: ...
event: ... 
data: ...
...

这里：event 可以是以下之一

generating：表示一个中间结果
complete：表示预测已完成并返回最终结果
error：表示预测未成功完成
heartbeat：每 15 秒发送一次以保持请求活动

data 的格式与输入 payload 相同：包含输出结果的有效 JSON 数据列表，每个输出组件一个元素。

以下是一些如果请求成功完成，您应该期望得到的结果示例

基本示例

回到页面开头的示例，我们期望结果如下所示

event: complete
data: ["Bonjour, mon ami."]

多个输出

如果您的端点返回多个值，它们将作为 data 列表的元素出现

event: complete
data: ["Good morning Hello. It is 5 degrees today", -15.0]

流式传输示例

如果您的 Gradio 应用流式传输一系列值，那么它们将直接流式传输到您的终端，如下所示

event: generating
data: ["Hello, w!"]
event: generating
data: ["Hello, wo!"]
event: generating
data: ["Hello, wor!"]
event: generating
data: ["Hello, worl!"]
event: generating
data: ["Hello, world!"]
event: complete
data: ["Hello, world!"]

文件示例

如果您的 Gradio 应用返回一个文件，该文件将以这种格式表示为字典（可能包括一些附加键）

{
    "orig_name": "example.jpg",
    "path": "/path/in/server.jpg",
    "url": "https:/example.com/example.jpg",
    "meta": {"_type": "gradio.FileData"}
}

在您的终端中，它可能显示如下

event: complete
data: [{"path": "/tmp/gradio/359933dc8d6cfe1b022f35e2c639e6e42c97a003/image.webp", "url": "https://gradio-image-mod.hf.space/c/file=/tmp/gradio/359933dc8d6cfe1b022f35e2c639e6e42c97a003/image.webp", "size": null, "orig_name": "image.webp", "mime_type": null, "is_stream": false, "meta": {"_type": "gradio.FileData"}}]

身份验证

如果您的 Gradio 应用程序启用了身份验证怎么办？在这种情况下，您需要使用 cURL 发出额外的 POST 请求以进行身份验证，然后才能进行任何查询。以下是完整的步骤

首先，使用 POST 请求登录，提供有效的用户名和密码

curl -X POST $URL/login \
     -d "username=$USERNAME&password=$PASSWORD" \
     -c cookies.txt

如果凭据正确，您将收到 {"success":true} 响应，并且 cookie 将保存到 cookies.txt 中。

接下来，您需要在发出原始 POST 请求时包含这些 cookie，如下所示

$ curl -X POST $URL/call/$API_NAME -b cookies.txt -H "Content-Type: application/json" -d '{
  "data": $PAYLOAD
}'

最后，您需要 GET 结果，再次提供文件中的 cookie

curl -N $URL/call/$API_NAME/$EVENT_ID -b cookies.txt