第3章（3）——使用cURL查询Gradio应用-平芜编程栈

第3章（3）——使用cURL查询Gradio应用

- 3.3 使用cURL查询Gradio应用
- - 3.3.1 获取Spaces的嵌入式URL
  - 3.3.2 POST请求的语法与使用
  - 3.3.3 GET获取的语法与使用
  - 3.3.4 POST/GET组合示例与身份认证
- 3.4 社区客户端与MCP客户端

3.3 使用cURL查询Gradio应用

cURL是多数操作系统上预安装的命令行工具，它可以将任意Gradio应用作为API使用，本节将详述cURL查询Gradio应用的用法。关于安装cURL，cURL是利用URL语法在命令行方式下工作的开源文件传输工具，在多数操作系统中已预安装cURL，只需要用以下命令查验版本即可：curl --version。当版本需要更新或确认需要安装时，可参考cURL官网安装教程：🖇️链接3-5。

3.3.1 获取Spaces的嵌入式URL

为了查询相应的Gradio程序，需要获得其完整URL。Gradio的URL有两种形式：对于托管在Gradio官网的应用程序，其形式通常为：https://xxxx.gradio.live；而托管在Spaces中的Gradio程序，其在cURL的有效访问格式为嵌入式URL，而不是网页访问的URL，错误与正确格式的对比如下所示：

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

有两种获取Gradio应用的嵌入式URL的途径，以GPT-OSS为例描述如下：
(1)页脚按钮“通过API使用”。单击Gradio应用页脚的“通过API使用”，选择cURL，可查看API使用方法中包含的嵌入式URL。GPT-OSS的Space部署（🖇️链接3-6）中API/generate为例，其嵌入式URL如图3-10所示：

图3-10

(2)查看应用页面源码。可以右键单击程序页面，然后选择“View Frame Source”或“查看网页源代码”或其等效项，通过定位类似关键字如embedSrc或src来查看嵌入式Gradio应用程序的URL，一般有几个可用API就有几个embedSrc或src关键字。这种方式的缺点是无法查看可用API。查找结果如下：
{"embedSrc":"https://openai-gpt-oss-safeguard-20b.hf.space","src":"https://openai-gpt-oss-safeguard-20b.hf.space"}

3.3.2 POST请求的语法与使用

curl命令中的起始请求类型是POST，它将输入的有效载荷提交给Gradio应用，以便Gradio应用进行后续处理。POST请求的语法如下所示：

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

下面对命令中各字段进行解读：

$URL：Gradio应用的嵌入式URL。
$API_NAME：正在运行的API端点。
$PAYLOAD：是一个包含输入的有效载荷的可用JSON数据列表，每个输入组件对应一个元素。

当成功发出此POST请求后，将获得一个事件ID，它以下面格式打印到终端：{“event_id”: $EVENT_ID}，用于在后续的GET请求中获取预测结果。
POST请求通过传递不同的数据和参数调用Gradio API，基本用法如下所述：
(1)多输入组件。例如API接受三个输入：字符串、布尔值和数值，添加数据命令：-d ‘{“data”: [“Hello”, true, 5]}’。
(2)文件。当curl查询需要文件输入的Gradio应用程序时，需将输入文件转为URL，并在data字段以字典形式呈现：-d ‘{“data”: [{“path”: “$URL”}]}’。
(3)有状态会话。当聊天机器人应用需要在多次交互中保持用户状态时，可以在数据后传递session_hash：-d ‘{“data”: [], “session_hash”: “123”}’。具有相同session_hash的会话会被当作相同用户的session。

3.3.3 GET获取的语法与使用

一旦Gradio应用收到客户端GET请求中与POST请求相对应的EVENT_ID，就可以向客户端流式传输预测结果。Gradio应用将这些结果存储在LRU（Least Recently Used，最近最少使用）缓存中，缓存默认可存储2000个跨用户和端点的结果。
基本语法。客户端需使用以下语法发出GET请求：

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

此GET请求会产生响应流：event: … data: […]，其中event分为以下四类：

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

响应流中data字段的格式与输入的有效载荷相同，它是包含输出结果的有效JSON数据列表，其每个输出组件代表一个结果元素。
常见示例。GET请求的除了返回简单字符串，也会返回复杂结果，例如：
(1)多个输出。如果端点返回多个值，它们将显示为数据列表中的元素（由于curl命令相同，这里不再重复）：

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

(2)流式传输系列值。当Gradio应用产生一系列值时，它们将通过事件generating流式传输到终端显示，如下所示：

event: generating data:["Hello, w"]... event: complete data:["Hello, world!"]

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

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

3.3.4 POST/GET组合示例与身份认证

POST/GET组合示例：获取到Gradio应用的URL后，就可以使用curl进行预测。以英转法翻译应用为例，先执行POST请求，Gradio应用会返回一个EVENT_ID并将其打印到控制台，然后在GET请求中使用EVENT_ID获取结果。当查询私有Space时，需要用到HF_TOKEN，这时需在两个curl调用中都包含一个额外的标头：-H "Authorization: Bearer $HF_TOKEN"。如代码3-22所示：

代码3-22

$curl-XPOST https://abidlabs-en2fr.hf.space/call/predict-H"Content-Type: application/json"-H"Authorization: Bearer$HF_TOKEN"-d'{ "data": ["Hello, my friend."] }'>{"event_id":"5e847ae0816844acaa7b0ecc956aec4d"}$curl-Nhttps://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID-H"Authorization: Bearer$HF_TOKEN">event: complete>data:["Bonjour, mon ami."]

通过awk和read将这些命令组合成一个命令，awk通过双引号分割命令结果，然后由read将解析值写入EVENT_ID，最后将其传入GET命令。如代码3-23所示：

代码3-23

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

身份认证：除了HF_TOKEN认证，当Gradio应用程序启用了身份验证时，在查询之前需要发出额外的POST请求以进行身份验证。完整步骤如下：
（1）使用携带有效用户名和密码的POST请求进行登录，命令如代码3-24所示：

代码3-24

curl-XPOST$URL/login\-d"username=$USERNAME&password=$PASSWORD"\-ccookies.txt

登录成功将收到响应{“success”：true}，登录授权Cookie保存在cookies.txt中。
（2）在发出起始POST请求时，需通过命令-b cookies.txt将Cookie添加到命令中。使用GET请求获取结果时，同样需要cookies.txt。

3.4 社区客户端与MCP客户端

此外，还有两种由第三方社区构建客户端，以及新加入的MCP客户端：
Rust客户端：由@JacobLinCool开发的gradio-rs🖇️链接3-7。
Powershell客户端：由@rrg92开发的powershai🖇️链接3-8。
MCP客户端：Gradio在5.26.0还加入了MCP Client，请参考MCP章节。