全网最详细Gradio教程系列5——Gradio Client: python

shao918516

已于 2024-07-26 18:06:53 修改

阅读量412

点赞数 15

文章标签： Colab Notebook Gradio Client Python view_api job session

于 2024-07-26 17:36:26 首次发布

本文链接：https://blog.csdn.net/shao918516/article/details/140710253

版权

全网最详细Gradio教程系列5——Gradio Client: python

前言
本篇摘要
5. Gradio Client的三种使用方式
- 5.1 使用Gradio Python Client
参考文献

前言

本系列文章主要介绍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等。

本系列文章目录如下：

《全网最详细Gradio教程系列1——Gradio简介》
《全网最详细Gradio教程系列2——Gradio的安装与运行》
《全网最详细Gradio教程系列3——Gradio的3+1种部署方式实践》
《全网最详细Gradio教程系列4——浏览器集成Gradio-Lite》
《全网最详细Gradio教程系列5——Gradio Client: python》
《全网最详细Gradio教程系列5——Gradio Client: javascript》
《全网最详细Gradio教程系列5——Gradio Client: curl》
《全网最详细Gradio教程系列6——Interfaces》
《全网最详细Gradio教程系列7——Blocks》
《全网最详细Gradio教程系列8——Custom Components》
《全网最详细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 Client

client = 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 displacy

nlp = 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, html

demo = 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 Client

client = 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 gr

from transformers import pipeline

pipe = 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.

注意：

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

from google.colab import userdata

HF_TOKEN = userdata.get('HF_TOKEN')

如果原始空间使用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]。
这里程序生成的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 Client

client = 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 Client

client = Client("abidlabs/en2fr")
client.predict("Hello", api_name='/predict')

>> Bonjour

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

多个参数：当传递多个参数时，应将它们作为单独的参数传递给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 + num2
    elif operation == "subtract":
        return num1 - num2
    elif operation == "multiply":
        return num1 * num2
    elif operation == "divide":
        if num2 == 0:
            raise gr.Error("Cannot divide by zero!")
        return num1 / num2

demo = 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 Client

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

>> 9.0

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

import gradio as gr
import numpy as np
import time

def fake_diffusion(text, steps):
    for i in range(steps):
        time.sleep(1)
        image = np.random.random((600, 600, 3))
        yield image
    image = np.ones((1000,1000,3), np.uint8)
    image[:] = [255, 124, 0]
    yield image


demo = gr.Interface(fake_diffusion, inputs=[gr.Textbox(), gr.Slider(1, 10, 3)], outputs="image")

if __name__ == "__main__":
    demo.launch()

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

from gradio_client import Client

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

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

import gradio as gr

whisper = 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_file

client = 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 Client

client = Client("abidlabs/en2fr")
job = client.submit("Hello", api_name="/predict")  # This is not blocking

# Do something else

job.result()  # This is blocking

>> Bonjour

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

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

from gradio_client import Client

def 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

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

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

from gradio_client import Client

client = 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()实例方法，它返回一个指示作业是否完成的布尔值。

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

from gradio_client import Client, handle_file

client = 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

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

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

import gradio as gr
import time

def count(n):
    for i in range(int(n)):
        time.sleep(0.5)
        yield i

def 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 time

client = 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 Client

client = 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 time

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

>>True

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

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

import gradio as gr

def 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_34
    Parameters:
     - [Textbox] word: str (required)  
    Returns:
     - [Number] value_34: float

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

参考文献

shao918516

关注

15
点赞
踩
7

收藏

觉得还不错? 一键收藏
0
评论
全网最详细Gradio教程系列5——Gradio Client: python

程序部署完成后，如何将Gradio App作为API访问使用呢，这就用到Gradio Client。本章讲解Gradio Client的三种使用方式：python、javascript和curl，受字数限制，所以分三篇博客发布。使用Gradio Python Client非常易于将Gradio应用程序作为API使用，本节讲述gradio_client安装、如何连接Gradio应用程序、查看可用API及其使用方式、job及session等用法。通过Gradio Python Cli
复制链接

扫一扫