使用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并将其打印到控制台，该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 空间

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

❌ Space URL: https://huggingface.co/spaces/abidlabs/en2fr
✅ Gradio app URL: https://abidlabs-en2fr.hf.space/

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

虽然您可以使用任何公共空间作为API，但如果请求过多，可能会被Hugging Face限速。要无限制地使用空间，只需复制该空间以创建私有空间，然后使用它进行任意数量的请求！

注意：要查询私有空间，您需要传入您的Hugging Face (HF) 令牌。您可以在此处获取您的HF令牌：https://huggingface.co/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端点名称。您可以通过点击页面底部的“查看API”链接来获取API端点名称。
$PAYLOAD 是一个包含输入有效载荷的有效 JSON 数据列表，每个输入组件对应一个元素。

当你成功发出这个POST请求时，你将获得一个事件ID，该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]
}'

私人空间

如前所述，如果您正在向一个私有空间发出请求，您将需要传递一个具有该空间读取权限的Hugging Face token。请求将如下所示：

$ 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演示在多次交互中保持用户状态（例如是一个聊天机器人），你可以在data旁边传入一个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：获取结果

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

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

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

提示： 如果您从私有Space获取结果，请在`GET`请求中包含一个带有您的HF令牌的头部，例如：`-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}作为响应，并且cookies将被保存在cookies.txt中。

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

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

最后，你需要再次从文件中提供cookies来GET结果：

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