全网最详细Gradio教程系列5——Gradio Client: curl_gradio 去掉底部通过api使用

前言

本系列文章主要介绍WEB界面工具Gradio。Gradio是Hugging Face发布的一个简易的webui开发框架，它基于FastAPI和svelte，便于部署人工智能模型，是当前热门的非常易于开发和展示机器大语言模型及扩散模型的UI框架。本系列文章不仅从概念上介绍Gradio的详细技术架构、历史、应用场景、与其他框架Gradio/NiceGui/StreamLit/Dash/PyWebIO的区别，还进行了大量实践讲解。实践部分先讲解了多种不同的安装、运行和部署方式，然后实践了基础类的Interfaces、Blocks和Custom Components，最后对详解Gradio的多种高级特性，比如Gradio-Lite、Gradio Client和Tabular Data Science And Plots等。

本系列文章目录如下：

1. 《全网最详细Gradio教程系列1——Gradio简介》
2. 《全网最详细Gradio教程系列2——Gradio的安装与运行》
3. 《全网最详细Gradio教程系列3——Gradio的3+1种部署方式实践》
4. 《全网最详细Gradio教程系列4——浏览器集成Gradio-Lite》
5. 《全网最详细Gradio教程系列5——Gradio Client: python》
6. 《全网最详细Gradio教程系列5——Gradio Client: javascript》
7. 《全网最详细Gradio教程系列5——Gradio Client: curl》
8. 《全网最详细Gradio教程系列6——Interfaces》
9. 《全网最详细Gradio教程系列7——Blocks》
10. 《全网最详细Gradio教程系列8——Custom Components》
11. 《全网最详细Gradio教程系列9——Tabular Data Science And Plots 》

本篇摘要

本章讲解访问API的Gradio Client的三种使用方式：python、javascript和curl。受字数限制，所以分三篇博客发布。本篇讲解curl方式。

5. Gradio Client的三种使用方式

程序部署完成后，如何将Gradio App作为API访问使用呢，这就用到Gradio Client。本章讲解Gradio Client的三种使用方式：python、javascript和curl，以下分别讲解。

5.3 Curl查询Gradio Apps

当我们试图从Python或Javascript以外的环境查询Gradio应用程序，cURL就派上用场了。cURL是多数操作系统上预安装的命令行工具，它可以将任意Gradio程序作为API使用。本节将详细讲述curl的用法，包括curl的安装、获取Gradio程序的curl方式URL的两种途径：通过API使用和定位源码关键字、POST/GET示例及awk/red整合命令等。

5.3.1 安装

在多数操作系统中已预安装curl，只需要用以下命令查验版本即可：

$ curl --version
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libpsl/0.21.0 (+libidn2/2.3.2) libssh/0.9.6/openssl/zlib nghttp2/1.43.0 librtmp/2.3 OpenLDAP/2.5.17
Release-Date: 2022-01-05
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM NTLM_WB PSL SPNEGO SSL TLS-SRP UnixSockets zstd
1
2
3
4
5

当版本需要更新或确认需要安装时，可参考curl官网安装教程：https://curl.se/download.html。

5.3.2 获取Gradio程序的URL

为了查询相应的Gradio程序，需要获得其完整URL。Gradio的URL有两种形式：对于托管在Gradio官网的应用程序，其形式通常为：https://bec81a83-5b5c-471e.gradio.live；而托管在Hugging Face Spaces中的Gradio程序，则需使用Gradio嵌入式的URL，而不是Space网页的URL，如下所示：

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

而Gradio嵌入式URL的获取也有两种途径，以2024年5月发布的OpenGPT-4o为例，其Hugging Face地址为：https://huggingface.co/spaces/KingNish/OpenGPT-4o。

• 第一种途径，通过API使用。我们可以点击Gradio程序页面底部的“通过API使用->Bash”，查看可用的URL及其API，如下图所示：
  
• 第二种途径，查看页面源码。可以右键单击程序页面，然后选择“View Frame Source”或“查看页面源代码”或其等效项，通过定位类似关键字如embedSrc来查看嵌入式Gradio应用程序的URL，但这种方式的缺点是无法查看可用API。通过查找，其嵌入式URL为https://kingnish-opengpt-4o.hf.space，如下所示：

{"embedSrc":"https://kingnish-opengpt-4o.hf.space","src":"https://kingnish-opengpt-4o.hf.space"}
1

5.3.3 HF_TOKEN和身份认证

本小节先通过一个简单例子演示POST/GET两类curl请求的使用方法，然后加入HF_TOKEN和帐密授权。在下一小节详细讲解POST/GET的细节。

1. POST/GET示例

获取到Gradio程序的URL后，我们就可以使用curl进行预测。还是以英转法翻译程序为例，先执行第一个POST请求，Gradio程序会返回一个EVENT_ID并将其打印到控制台，然后在第二个GET请求中使用EVENT_ID获取结果，如下所示：

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

$ curl -N https://abidlabs-en2fr.hf.space/call/predict/5e847ae0816844acaa7b0ecc956aec4d
>> event: complete
>> data: ["Bonjour, mon ami."]
1
2
3
4
5
6
7
8

2. 整合命令：awk和read

我们也可以使用awk和read将这些命令组合成一个命令，awk解析第一个POST命令的结果，并使用read将解析的$4写入EVENT_ID，然后将其传入第二个GET命令，整个命令如下所示：

$ 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
1
2
3
4
5

3. HF_TOKEN

当查询私有Spaces，需要用到Hugging Face (HF) token，这时需在两个curl调用中都包含一个额外的标头，其命令如下：

-H "Authorization: Bearer $HF_TOKEN"
1

完整命令如下：

$ 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 -N https://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID -H "Authorization: Bearer $HF_TOKEN"
1
2
3
4

4. 身份认证

当Gradio应用程序启用了身份验证时，我们在进行任何查询之前，需要使用cURL发出额外的POST请求以进行身份验证。完整步骤如下：

首先，使用有效用户名和密码的POST请求进行登录：

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

如果凭据正确，我们将收到响应{“success”：true}，Cookie将保存在cookies.txt中。

接下来，在发出原始POST请求时，需要将cookies.txt添加到命令中，如下所示：

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

最后，使用GET获取结果，同样需要cookies.txt提供Cookie，如下：

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

在获取Gradio程序的URL和连接方法后，接下来我们详细介绍curl的两个请求POST和GET，以实现更复杂的参数和命令。

5.3.4 POST：请求预测

两个curl请求中的第一个是POST请求，它将输入的有效载荷提交给Gradio应用程序，以便Gradio应用程序进行后续处理。

1. 基本语法

POST请求的语法如下：

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

各字段解释如下：

• $URL：第5.3.2节获得的Gradio应用程序的URL；
• $API_NAME：正在运行的事件的API端点，可通过页面底部“view API”获取；
• $PAYLOAD：是一个包含输入的有效载荷的可用JSON数据列表，每个输入组件对应一个元素。

当我们成功发出此POST请求时，将获得一个事件id，该id以下面格式打印到终端：{"event_id": $EVENT_ID} ，在后续的curl请求GET中需要此EVENT_ID来获取预测结果。

2. 常用示例

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

• 基本示例：与节5.3.3的示例类似，以下是如何向只接受一个输入文本组件的简单Gradio应用程序发出的POST请求：

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

• 多输入组件：此Gradio演示接受三个输入：与gr.Textbox对应的字符串、与gr.Coheckbox对应的布尔值和与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]
}'
1
2
3

• 文件：当curl查询需要文件输入的Gradio应用程序，需要以URL形式提供文件，并且URL需要以下面格式包含在字典中：{"path": $URL}，示例如下：

$ 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"}] 
}'
1
2
3

• 有状态会话：在聊天机器人等需要在多次交互保持用户状态的查询中，可以在数据后传递session_hash，具有相同session_hash的会话会被当作相同用户的session，示例如下：

# 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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

5.3.5 GET：获取结果

一旦我们收到与预测相对应的EVENT_ID，就可以stream流式传输结果。Gradio应用程序将这些结果存储在最近最少使用缓存（least-recently-used cache）中，缓存默认可以存储2000个跨用户和端点的结果。

1. 基本语法

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

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

字段解释请参考POST。这条会产生以下格式的响应流：event: ... data: [...]，其中event有以下几种分类：

• generating：表示数据是生成的中间结果；
• complete：表示预测完成，产生最终结果；
• error：错误，表示预测失败；
• heartbeat：每15秒发送一次，以保持请求有效。

响应流中data的格式与输入的有效载荷相同，是包含输出结果的有效JSON数据列表，每个输出组件代表一个结果元素。

2. 常用示例

以下是一些示例，说明如果请求成功应该得到什么结果：

• 基本示例：回顾5.3.3中的示例，我们发出GET请求，得到结果如下：

$ curl -N https://abidlabs-en2fr.hf.space/call/predict/5e847ae0816844acaa7b0ecc956aec4d
event: complete
data: ["Bonjour, mon ami."]
1
2
3

• 多个输出：如果端点返回多个值，它们将显示为数据列表的元素（由于curl命令相同，这里不再重复）：

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

• 流式传输系列值：当Gradio应用程序stream传输一系列值时，它们将直接流式传输到终端显示，如下所示：

event: generating
data: ["Hello, w"]
event: generating
data: ["Hello, wo"]
...
event: complete
data: ["Hello, world!"] 
1
2
3
4
5
6
7

• 文件传输：如果Gradio应用程序返回一个文件，该文件将表示为下面的字典格式（可能包括一些额外的键）：

{
    "orig_name": "example.jpg",
    "path": "/path/in/server.jpg",
    "url": "https:/example.com/example.jpg",
    "meta": {"_type": "gradio.FileData"}
}
1
2
3
4
5
6

在终端可能显示如下：

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"}}]
1
2

至此，Gradio Client的三种使用方式：python、javascript和curl已讲解完毕，后续我们将讲解gradio-tools工具包，请继续关注博主龙焰。

参考文献

1. Querying Gradio Apps with Curl