Gradio教程系列终极篇5:Python中Gradio Client的全方位指南

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

  • 前言
  • 本篇摘要
  • 5. Gradio Client的三种使用方式
  • 5.1 使用Gradio Python Client
  • 5.1.1 安装gradio_client
  • 5.1.2 连接Gradio应用程序
  • 1. 通过URL连接
  • 2. 通过SpaceID连接
  • 3. 辅助:duplicate()和hf_token
  • 4. 在线python环境:Colab Notebook
  • 5.1.3 查看API
  • 1. 函数调用view_api()
  • 2. 页面查看API
  • 5.1.4 使用API
  • 1. 直接调用predict()
  • 2. 异步调用job
  • 参考文献
  • 前言

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

    注意

    1. 之前复制过Space,重新运行duplicate()将不会创建新的Space,相反,客户端将连接到先前创建的空间。因此,多次重新运行Client.duplicate()方法是安全的。
    2. 如果在Colab NoteBook运行,获取HF_TOKEN方法如下:
    from google.colab import userdata
    
    HF_TOKEN = userdata.get('HF_TOKEN')
    
    1. 如果原始空间使用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-1×1, v5e-2×2, v5e-2×4]。
    2. 这里程序生成的Space地址https://hf.space/shao918516/en2fr有时不可用,进行替换即可:https://huggingface.co/spaces/shao918516/en2fr,即将hf.space替换为huggingface.co/spaces。
    4. 在线python环境: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()其它形式的参数设置:

    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 + 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
    
    1. 默认参数:例如,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)
    
    1. 文件或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的其它功能:

    1. 添加回调:可以通过参数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
    

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

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

    1. 取消作业: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
    

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

    1. 生成器端点:某些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
    
    1. 带有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()来完成。

    参考文献

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

    作者:shao918516

    物联沃分享整理
    物联沃-IOTWORD物联网 » Gradio教程系列终极篇5:Python中Gradio Client的全方位指南

    发表回复