使用 Curl 查询 Gradio 应用

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

例如，考虑这个将文本从英语翻译成法语的 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 并将其打印到控制台，第二个 GET 请求使用该 EVENT_ID 来获取结果。您可以使用 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 调用中都包含一个额外的标头

-H "Authorization: Bearer $HF_TOKEN"

现在，我们准备好进行两个 curl 请求。

步骤 1：发起预测 (POST)

两个 curl 请求中的第一个是 POST 请求，它将输入负载提交到 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 数据列表，其中包含输入负载，每个输入组件一个元素。

当您成功发出此 POST 请求时，您将获得一个事件 ID，该 ID 以以下格式打印到终端

>> {"event_id": $EVENT_ID}

后续的 curl 请求将需要此 EVENT_ID 来获取预测结果。

以下是一些关于如何发起 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/main/test/test_files/bus.png"}] 
}'

有状态演示

如果您的 Gradio 演示在多次交互中保持用户状态（例如，是一个聊天机器人），您可以将 session_hash 与数据一起传入。具有相同 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

提示： 如果您正在从私有 Space 获取结果，请在 GET 请求中包含带有您的 HF token 的 header，如下所示：-H "Authorization: Bearer $HF_TOKEN"。

这应该生成此格式的响应流

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

此处：event 可以是以下之一

generating：表示中间结果
complete：表示预测已完成以及最终结果
error：表示预测未成功完成
heartbeat：每 15 秒发送一次，以保持请求处于活动状态

data 的格式与输入有效负载相同：有效的 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