前言

本系列文章主要介绍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。受字数限制，所以分三篇博客发布。

5. Gradio Client的三种使用方式

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

5.1 使用Gradio Python Client

通过Gradio Python Client非常易于将Gradio应用程序作为API使用，本节讲述gradio_client安装、连接Gradio应用程序、查看可用API及其使用方式、job和session等用法。在使用前先安装gradio_client。

5.1.1 安装gradio_client

如果已安装gradio的最新版本（4.39.0)，那么gradio_client将作为依赖项包含在内。但请注意，此文档使用了gradio_client的最新版本，如果不确定，请使用以下命令升级，并确保python版本在3.9及以上：

$ pip install --upgrade gradio_client

5.1.2 连接Gradio应用程序

Gradio Client可通过URL或SpaceID与任意托管的Gradio应用程序配合使用。

1. 通过URL连接

因此尽管Gradio Client主要用于Hugging Face Spaces上托管的应用程序，但也可用于本地或网络上部署的Gradio应用程序，通过其URL连接。

注意：在使用Gradio Client之前，读者不需要非常详细地了解Gradio库，但有必要大致熟悉Gradio的输入和输出组件概念。

比如还是以本地已部署的hello_name例程为例，代码如下：

from gradio_client import Clientclient = Client("http://127.0.0.1:7860/")
result = client.predict(name="Felix",api_name="/predict"
)
print(result)>> Loaded as API: http://127.0.0.1:7860/ ✔
>> Hello Felix!!!!

程序先从gradio_client中导入对象Client，然后利用URL创建其实例client，这里的URL即可是本地URL也可是互联网上任意Gradio程序的URL。最后使用client的内置函数predict执行预测结果，参数name为输入值，api_name指定接受参数的函数，尤其在多个路径时需要特别指定，后续会讲predict的使用方法。

2. 通过SpaceID连接

当然也可用SpaceID创建Client对象。为增加对Gradio程序的了解，所以引入更多的例程。下面以huggingface Spaces的gradio/text_analysis为例，它对一句话进行语法分析，并输出highlight、json和html三种格式的分析结果，完整地址为：https://huggingface.co/spaces/gradio/text_analysis。那么创建Client对象语句为：client = Client(“gradio/text_analysis”)或client = Client(“https://huggingface.co/spaces/gradio/text_analysis”)。gradio/text_analysis的完整部署代码如下：

import gradio as gr
import os
# 以下括号中的代码也可在对应环境的命令行下运行
os.system('pip install spacy')
os.system('python -m spacy download en_core_web_sm')
import spacy
from spacy import displacynlp = spacy.load("en_core_web_sm")def text_analysis(text):doc = nlp(text)html = displacy.render(doc, style="dep", page=True)html = ("<div style='max-width:100%; max-height:360px; overflow:auto'>"+ html+ "</div>")pos_count = {"char_count": len(text),"token_count": len(doc),}pos_tokens = []for token in doc:pos_tokens.extend([(token.text, token.pos_), (" ", None)])return pos_tokens, pos_count, htmldemo = gr.Interface(text_analysis,gr.Textbox(placeholder="Enter sentence here..."),["highlight", "json", "html"],examples=[["What a beautiful morning for a walk!"],["It was the best of times, it was the worst of times."],],
)demo.launch()

程序运行截图如下：

对应创建的Client及预测.predict()的代码如下：

from gradio_client import Clientclient = Client("gradio/text_analysis")
result = client.predict(text="Find the API endpoint below corresponding to your desired function in the app.",api_name="/predict"
)
print(result)

3. 辅助：duplicate()和hf_token

虽然可以通过Hugging Face的公共Space作为Gradio Client的API，但当请求太多时会被Hugging Face限速。如果想无限次使用某个Space的Gradio程序，只需使用Client的类方法duplicate()，它将Space复制到本地并创建一个私人Space的Gradio应用。

当访问Hugging Face上私有Space或复制Space时，需传入HF_TOKEN或使用登录后的Hugging Face CLI。

这里使用的例程是Hugging Face上的abidlabs/en2fr，它将英语翻译为法语，其源代码如下：

import gradio as grfrom transformers import pipelinepipe = pipeline("translation", model="Helsinki-NLP/opus-mt-en-fr")def predict(text):return pipe(text)[0]["translation_text"]title = "English to French Translation"iface = gr.Interface(fn=predict, inputs=[gr.Textbox(label="text", lines=3)],outputs='text',title=title,
)iface.launch()

例程可在本地启动，也可直接使用Hugging Face上的abidlabs/en2fr，这里采用第二种方式。
使用HF_TOKEN方式连接，登录Colab NoteBook（详细用法见下）后在线运行，代码如下：

import os
from gradio_client import Client, file
from google.colab import userdata# 设置系统变量的hf_token，hf_token需在HuggingFace官网申请
HF_TOKEN = userdata.get('HF_TOKEN')client = Client.duplicate("abidlabs/en2fr", hf_token=HF_TOKEN, hardware = 'cpu-basic')
client.predict("Hello", api_name='/predict')# 输出如下
Using your existing Space: https://hf.space/shao918516/en2fr 🤗Loaded as API: https://shao918516-en2fr.hf.space ✔Bonjour.

注意：

1. 之前复制过Space，重新运行duplicate()将不会创建新的Space，相反，客户端将连接到先前创建的空间。因此，多次重新运行Client.duplicate()方法是安全的。
2. 如果在Colab NoteBook运行，获取HF_TOKEN方法如下：

from google.colab import userdataHF_TOKEN = userdata.get('HF_TOKEN')

3. 如果原始空间使用GPU，那么复制后的私人空间也会使用，这时你的Hugging Face账户将根据GPU的价格进行计费。为了最大限度地减少花费，共享空间会在不活动1小时后自动进入睡眠状态。如果不想扩大开销，我们也可以使用duplicate()的hardware参数来设置免费硬件：hardware= “cpu-basic”，其它可选参数包括[cpu-basic, zero-a10g, cpu-upgrade, cpu-xl, t4-small, t4-medium, l4x1, l4x4, a10g-small, a10g-large, a10g-largex2, a10g-largex4, a100-large, h100, h100x8, v5e-1x1, v5e-2x2, v5e-2x4]。
4. 这里程序生成的Space地址https://hf.space/shao918516/en2fr有时不可用，进行替换即可：https://huggingface.co/spaces/shao918516/en2fr，即将hf.space替换为huggingface.co/spaces。

4. Colab Notebook

由于国内都是通过代理访问Hugging Face，因此通过SpaceID或国外URL创建Client对象时可能会报错：JSONDecodeError: Expecting value: line 1 column 1 (char 0)。报错原因：代理proxy出于“security reasons”不允许queuing/streaming传输所需的websocket连接，这几乎肯定不是Gradio的问题，而是与代理相关的问题，详细解释请参考《Gradio Streaming with Chat Interface with OpenAI: Expecting value: line 1 column 1 (char 0) #5371》及《WebSockets and a proxy》。

上述问题在国内属实无法解决，但如果依然想通过SpaceID或外网URL运行此类程序，可通过代理使用Google的Colab Notebook，地址：https://colab.research.google.com/，注册google账号并设置HF_TOKEN即可使用。这时Client语句clien t= Client(“http://127.0.0.1:7860/”)改为client = Client(“gradio/text_analysis”)或client = Client(“https://gradio-text-analysis.hf.space”)，注意此处的URL并不是访问的"https://huggingface.co/spaces/gradio/text_analysis"，原因将在curl连接时阐述。因为Colab Notebook是在线运行，数据在外网间传输，不需通过代理，因此可避免此类错误。Colab即Colaboratory（google合作实验室），是谷歌提供的一个在线工作平台，用户可以直接通过浏览器执行python代码并与他人分享合作，它还提供免费的GPU，同时它可以兼容jupyter的.ipynb文件。具体使用方法见参考文献1。

我们在Colab NoteBook中运行截图如下：
注意左侧的Secret，在这里设置HF_TOKEN等环境变量。

5.1.3 查看API

如何获取已部署Gradio的API以便编程时使用呢？有两种方法可以实现：函数调用view_api()和页面查看API，使用时用Clilent内置predict方法的参数api_name指定相应API即可。

1. 函数调用view_api()

当使用Client连接到Gradio程序后，可以通过Client内置的函数view_api()查看可用的API接口，以gradio/text_analysis为例，在本地启动后得到URL：http://127.0.0.1:7860，然后创建Client并使用view_api()查看可用的API，如下所示：

from gradio_client import Clientclient = Client("http://127.0.0.1:7860/")
client.view_api()# 输出如下
Client.predict() Usage Info
---------------------------
Named API endpoints: 1- predict(text, api_name="/predict") -> (output_0, output_1, output_2)Parameters:- [Textbox] text: str (required)  Returns:- [Highlightedtext] output_0: List[Dict(token: str, class_or_confidence: str | float | None)] - [Json] output_1: Dict[Any, Any] (any valid json) - [Html] output_2: str 

我们看到在这个空间中有1个API Endpoint，并展示了如何使用API端点进行预测：我们应该调用.predict()方法（将在下面探讨），提供str类型的参数text，这是需要分析的语句，我们还应该为predict()方法提供参数api_name=‘/predict’。虽然这里只有一个命名端点predict，它是非必要的，但当Gradio程序中有多个端点时，就需要用这个参数指定要使用的endpoint。最后返回对应类型Highlightedtext、Json及Html的分析结果。

2. 页面查看API

在demo.launch()中的设置参数show_api：是否在app脚页显示api帮助文档，默认为True，启动后在WEB页面底部会显示“通过API使用”，如下图右侧黑框所示：

点击“通过API使用”，出现可用API页面，如图：
关于页面参数的解释参考上一小节。注意：API页面还包括一个“API Recorder”，点击后可在页面底部看到被记录的调用（见本小节第一张图）。API Recorder可以让您正常地与Gradio UI交互，并将交互转换为相应的代码，以便与Python Client配合一起运行。

5.1.4 使用API

获取到可用的API endpoint后，接下来讲如何使用。这里介绍两种使用API的方法：直接调用predict()和异步调用job。以下使用SpaceID的Client，均通过Colab Notebook运行。

1. 直接调用predict()

使用API进行预测的最简单方法就是调用Client对象的predict()函数，如上文已使用的英转法abidlabs/en2fr：

from gradio_client import Clientclient = Client("abidlabs/en2fr")
client.predict("Hello", api_name='/predict')>> Bonjour

下面看看predict()其它形式的参数设置：

1. 多个参数：当传递多个参数时，应将它们作为单独的参数传递给predict()，如提供计算器功能的Space"gradio/calculator"，它的地址为：https://huggingface.co/spaces/gradio/calculator，源代码如下：

import gradio as gr
#from foo import BAR
#
def calculator(num1, operation, num2):if operation == "add":return num1 + num2elif operation == "subtract":return num1 - num2elif operation == "multiply":return num1 * num2elif operation == "divide":if num2 == 0:raise gr.Error("Cannot divide by zero!")return num1 / num2demo = gr.Interface(calculator,["number", gr.Radio(["add", "subtract", "multiply", "divide"]),"number"],"number",examples=[[45, "add", 3],[3.14, "divide", 2],[144, "multiply", 2.5],[0, "subtract", 1.2],],title="Toy Calculator",description="Here's a sample toy calculator. Allows you to calculate things like $2+2=4$",
)if __name__ == "__main__":demo.launch()

运行截图如下：
多个参数的设置方法如下（建议提供关键字参数而不是位置参数）：

from gradio_client import Clientclient = Client("gradio/calculator")
# 关键字参数：client.predict(num1=4, operation="add", num2=5)
client.predict(4, "add", 5)>> 9.0

2. 默认参数：例如，Space"abidlabs/image_generator"中包括“滑块”组件steps的默认值，因此在使用客户端访问它时不需要提供该值，当然也可以进行指定，该程序的源代码为：

import gradio as gr
import numpy as np
import timedef fake_diffusion(text, steps):for i in range(steps):time.sleep(1)image = np.random.random((600, 600, 3))yield imageimage = np.ones((1000,1000,3), np.uint8)image[:] = [255, 124, 0]yield imagedemo = gr.Interface(fake_diffusion, inputs=[gr.Textbox(), gr.Slider(1, 10, 3)], outputs="image")if __name__ == "__main__":demo.launch()

默认参数设置方法如下所示：

from gradio_client import Clientclient = Client("abidlabs/image_generator")
client.predict(text="an astronaut riding a camel", steps=25)

3. 文件或URL参数：我们可以将文件路径或URL以字符串形式传递给gradio_client.handle_file()，此函数负责将文件上传到Gradio服务器，并确保文件得到正确的预处理，如处理音频转录功能的"abidlabs/whisper"，源代码为：

import gradio as grwhisper = gr.load("models/openai/whisper-small")def transcribe(audio):return whisper(audio)gr.Interface(transcribe, gr.Audio(type="filepath"), gr.Textbox()).launch()

其调用方法如下所示：

from gradio_client import Client, handle_fileclient = Client("abidlabs/whisper")
client.predict(audio=handle_file("https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3")
)## 输出如下
>> Loaded as API: https://abidlabs-whisper.hf.space ✔AutomaticSpeechRecognitionOutput(text=" My thought I have nobody by a beauty and will as you poured. Mr. Rochester is sir, but that so don\'t find simpus, and devoted abode, to at might in a", chunks=None)

2. 异步调用job

我们应该注意到.predict()是一个阻塞操作，因为它在返回预测之前等待操作完成。在多数情况下，在需要预测结果之前，最好让作业在后台运行。这时我们可以通过创建Job实例并利用其.submit()提交操作，让作业在后台运行，稍后调用其.result()来获取结果。代码如下：

from gradio_client import Clientclient = Client("abidlabs/en2fr")
job = client.submit("Hello", api_name="/predict")  # This is not blocking# Do something elsejob.result()  # This is blocking>> Bonjour

下面来看看job的其它功能：

1. 添加回调：可以通过参数result_callbacks添加一个或多个回调，以便在作业完成运行后执行操作，如下所示：

from gradio_client import Clientdef print_result(x):print("The translated result is: {x}")client = Client(src="abidlabs/en2fr")job = client.submit("Hello", api_name="/predict", result_callbacks=[print_result])# Do something else>> The translated result is: Bonjour

作者运行回调函数时，并未打印出结果且没有报错，或许这个函数还是有些问题，只能等官方改进。

2. 获取Status：Job对象可以通过调用其.status()方法来获取正在运行作业的状态。函数将返回一个StatusUpdate对象，它具有以下属性：code（状态代码，一组表示状态的字符串，请参阅utils.status类）、rank（此作业在队列中的当前位置）、queue_size（队列总大小）、eta（此作业将完成的估计时间）、success（表示作业是否成功完成）和time（生成状态的时间）等，如下：

from gradio_client import Clientclient = Client(src="gradio/calculator")
job = client.submit(5, "add", 4, api_name="/predict")
job.status()>> StatusUpdate(code=<Status.STARTING: 'STARTING'>, rank=None, queue_size=None, eta=None, success=None, time=datetime.datetime(2024, 7, 10, 10, 3, 21, 689817), progress_data=None, log=None)

另外Job类还有一个.done()实例方法，它返回一个指示作业是否完成的布尔值。

3. 取消作业：Job类还有一个.cancel()实例方法，用于取消已排队但尚未启动的作业。例如运行：

from gradio_client import Client, handle_fileclient = Client("abidlabs/whisper")
job1 = client.submit(handle_file("audio_sample1.wav"))
job2 = client.submit(handle_file("audio_sample2.wav"))
job1.cancel()  # will return False, assuming the job has started
job2.cancel()  # will return True, indicating that the job has been canceled

如果第一个作业已开始处理，则不会取消该作业。如果第二个作业尚未启动，它将被成功取消并从队列中删除。

4. 生成器端点：某些Gradio API端点不返回单个值，而是返回一系列值。这时可以通过运行job.outputs()来获取此类生成器端点返回的所有系列值。数数程序gradio/count_generator的源代码如下，它每0.5秒返回一个递增的数字：

import gradio as gr
import timedef count(n):for i in range(int(n)):time.sleep(0.5)yield idef show(n):return str(list(range(int(n))))with gr.Blocks() as demo:with gr.Column():num = gr.Number(value=10)with gr.Row():count_btn = gr.Button("Count")list_btn = gr.Button("List")with gr.Column():out = gr.Textbox()count_btn.click(count, num, out)list_btn.click(show, num, out)demo.queue()if __name__ == "__main__":demo.launch()

它的网址为：https://huggingface.co/spaces/gradio/count_generator。运行截图如下，点击“Count"会每隔0.5秒返回0到9的数字，点击"List"列出生成数字的列表：

我们运行job.outputs()来获取此类生成器端点返回的所有系列值：

from gradio_client import Client
import timeclient = Client(src="gradio/count_generator")
job = client.submit(3, api_name="/count")
while not job.done():time.sleep(0.1)
job.outputs()>> ['0', '1', '2']

注意：

• 在生成器端点上运行job.result()时，只会返回端点生成的第一个值；
• Job对象也是可迭代的，这意味着您可以使用Job作为迭代器来显示从端点返回的结果。以下是使用Job作为迭代器的等效示例：

from gradio_client import Clientclient = Client(src="gradio/count_generator")
job = client.submit(3, api_name="/count")for o in job:print(o)>> 0
>> 1
>> 2

• 我们还可以取消具有迭代输出的作业，在这种情况下，只要当前轮次的迭代完成，作业job就会结束，如下：

from gradio_client import Client
import timeclient = Client("abidlabs/test-yield")
job = client.submit("abcdef")
time.sleep(3)
job.cancel()  # job cancels after 2 iterations>>True

5. 带有session state的demos：最后看一下带有会话状态（seesion state）的demo。Gradio demos可以包括会话状态，这为demos提供了一种在页面会话中持久保存用户交互信息的方法。

例如下面的demo，它使用gr.State()组件维护了用户提交的单词列表。当用户提交一个新词时，它会被添加到状态words中，并显示该词以前出现的次数：

import gradio as grdef count(word, list_of_words):return list_of_words.count(word), list_of_words + [word]with gr.Blocks() as demo:words = gr.State([])textbox = gr.Textbox()number = gr.Number()textbox.submit(count, inputs=[textbox, words], outputs=[number, words])demo.launch()

运行截图如下：

如果我们使用Python Client连接此Gradio应用程序，使用view_api()函数会发现API信息仅显示单个输入和输出：

client = Client(src="http://127.0.0.1:7864")
client.view_api()# 输出如下
Loaded as API: http://127.0.0.1:7862/ ✔
Client.predict() Usage Info
---------------------------
Named API endpoints: 1- predict(word, api_name="/count") -> value_34Parameters:- [Textbox] word: str (required)  Returns:- [Number] value_34: float 

可以看到，输入输出参数自动忽略了gr.State()组件words，这是因为Python客户端会自动为我们处理状态——当我们发出一系列requests时，一个request返回的状态会存储在内部，并自动提供给后续request。如果想重置状态，可以通过调用Client.reset_session()来完成。

参考文献

1. Colab使用教程（超级详细版）及Colab Pro/Pro+评测
2. Getting Started with the Gradio Python client