全网最详细Gradio教程系列5——GradioClientpython

见贤思齐

全网最详细Gradio教程系列5——GradioClient:python前言本篇摘要5.GradioClient的三种使用方式5.1使用GradioPythonClient5.1.1安装gradio_client5.1.2连接Gradio应用程序1.通过URL连接2.通过SpaceID连接3.辅助：duplicate()和hf_token4.在线python环境：ColabNotebook5.1.3查看API1.函数调用view_api()2.页面查看API5.1.4使用API1.直接调用predict()2.异步调用job参考文献前言本系列文章主要介绍WEB界面工具Gradio。Gradio是HuggingFace发布的一个简易的webui开发框架，它基于FastAPI和svelte，便于部署人工智能模型，是当前热门的非常易于开发和展示机器大语言模型及扩散模型的UI框架。本系列文章不仅从概念上介绍Gradio的详细技术架构、历史、应用场景、与其他框架Gradio/NiceGui/StreamLit/Dash/PyWebIO的区别，还进行了大量实践讲解。实践部分先讲解了多种不同的安装、运行和部署方式，然后实践了基础类的Interfaces、Blocks和CustomComponents，最后对详解Gradio的多种高级特性，比如Gradio-Lite、GradioClient和TabularDataScienceAndPlots等。本系列文章目录如下：《全网最详细Gradio教程系列1——Gradio简介》《全网最详细Gradio教程系列2——Gradio的安装与运行》《全网最详细Gradio教程系列3——Gradio的3+1种部署方式实践》《全网最详细Gradio教程系列4——浏览器集成Gradio-Lite》《全网最详细Gradio教程系列5——GradioClient:python》《全网最详细Gradio教程系列5——GradioClient:javascript》《全网最详细Gradio教程系列5——GradioClient:curl》《全网最详细Gradio教程系列6——Interfaces》《全网最详细Gradio教程系列7——Blocks》《全网最详细Gradio教程系列8——CustomComponents》《全网最详细Gradio教程系列9——TabularDataScienceAndPlots》本篇摘要本章讲解访问API的GradioClient的三种使用方式：python、javascript和curl。受字数限制，所以分三篇博客发布。5.GradioClient的三种使用方式程序部署完成后，如何将GradioApp作为API访问使用呢，这就用到GradioClient。本章讲解GradioClient的三种使用方式：python、javascript和curl，以下分别讲解。5.1使用GradioPythonClient通过GradioPythonClient非常易于将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及以上：$pipinstall--upgradegradio_client15.1.2连接Gradio应用程序GradioClient可通过URL或SpaceID与任意托管的Gradio应用程序配合使用。1.通过URL连接因此尽管GradioClient主要用于HuggingFaceSpaces上托管的应用程序，但也可用于本地或网络上部署的Gradio应用程序，通过其URL连接。注意：在使用GradioClient之前，读者不需要非常详细地了解Gradio库，但有必要大致熟悉Gradio的输入和输出组件概念。比如还是以本地已部署的hello_name例程为例，代码如下：fromgradio_clientimportClientclient=Client("http://127.0.0.1:7860/")result=client.predict(name="Felix",api_name="/predict")print(result)>>LoadedasAPI:http://127.0.0.1:7860/✔>>HelloFelix!!!!1234567891011程序先从gradio_client中导入对象Client，然后利用URL创建其实例client，这里的URL即可是本地URL也可是互联网上任意Gradio程序的URL。最后使用client的内置函数predict执行预测结果，参数name为输入值，api_name指定接受参数的函数，尤其在多个路径时需要特别指定，后续会讲predict的使用方法。2.通过SpaceID连接当然也可用SpaceID创建Client对象。为增加对Gradio程序的了解，所以引入更多的例程。下面以huggingfaceSpaces的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的完整部署代码如下：importgradioasgrimportos#以下括号中的代码也可在对应环境的命令行下运行os.system('pipinstallspacy')os.system('python-mspacydownloaden_core_web_sm')importspacyfromspacyimportdisplacynlp=spacy.load("en_core_web_sm")deftext_analysis(text):doc=nlp(text)html=displacy.render(doc,style="dep",page=True)html=(""+html+"")pos_count={"char_count":len(text),"token_count":len(doc),}pos_tokens=[]fortokenindoc:pos_tokens.extend([(token.text,token.pos_),("",None)])returnpos_tokens,pos_count,htmldemo=gr.Interface(text_analysis,gr.Textbox(placeholder="Entersentencehere..."),["highlight","json","html"],examples=[["Whatabeautifulmorningforawalk!"],["Itwasthebestoftimes,itwastheworstoftimes."],],)demo.launch()12345678910111213141516171819202122232425262728293031323334353637383940程序运行截图如下：对应创建的Client及预测.predict()的代码如下：fromgradio_clientimportClientclient=Client("gradio/text_analysis")result=client.predict(text="FindtheAPIendpointbelowcorrespondingtoyourdesiredfunctionintheapp.",api_name="/predict")print(result)123456783.辅助：duplicate()和hf_token虽然可以通过HuggingFace的公共Space作为GradioClient的API，但当请求太多时会被HuggingFace限速。如果想无限次使用某个Space的Gradio程序，只需使用Client的类方法duplicate()，它将Space复制到本地并创建一个私人Space的Gradio应用。当访问HuggingFace上私有Space或复制Space时，需传入HF_TOKEN或使用登录后的HuggingFaceCLI。这里使用的例程是HuggingFace上的abidlabs/en2fr，它将英语翻译为法语，其源代码如下：importgradioasgrfromtransformersimportpipelinepipe=pipeline("translation",model="Helsinki-NLP/opus-mt-en-fr")defpredict(text):returnpipe(text)[0]["translation_text"]title="EnglishtoFrenchTranslation"iface=gr.Interface(fn=predict,inputs=[gr.Textbox(label="text",lines=3)],outputs='text',title=title,)iface.launch()12345678910111213141516171819例程可在本地启动，也可直接使用HuggingFace上的abidlabs/en2fr，这里采用第二种方式。使用HF_TOKEN方式连接，登录ColabNoteBook（详细用法见下）后在线运行，代码如下：importosfromgradio_clientimportClient,filefromgoogle.colabimportuserdata#设置系统变量的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')#输出如下UsingyourexistingSpace:https://hf.space/shao918516/en2fr🤗LoadedasAPI:https://shao918516-en2fr.hf.space✔Bonjour.12345678910111213141516注意：之前复制过Space，重新运行duplicate()将不会创建新的Space，相反，客户端将连接到先前创建的空间。因此，多次重新运行Client.duplicate()方法是安全的。如果在ColabNoteBook运行，获取HF_TOKEN方法如下：fromgoogle.colabimportuserdataHF_TOKEN=userdata.get('HF_TOKEN')123如果原始空间使用GPU，那么复制后的私人空间也会使用，这时你的HuggingFace账户将根据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.在线python环境：ColabNotebook由于国内都是通过代理访问HuggingFace，因此通过SpaceID或国外URL创建Client对象时可能会报错：JSONDecodeError:Expectingvalue:line1column1(char0)。报错原因：代理proxy出于“securityreasons”不允许queuing/streaming传输所需的websocket连接，这几乎肯定不是Gradio的问题，而是与代理相关的问题，详细解释请参考《GradioStreamingwithChatInterfacewithOpenAI:Expectingvalue:line1column1(char0)#5371》及《WebSocketsandaproxy》。上述问题在国内属实无法解决，但如果依然想通过SpaceID或外网URL运行此类程序，可通过代理使用Google的ColabNotebook，地址：https://colab.research.google.com/，注册google账号并设置HF_TOKEN即可使用。这时Client语句client=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连接时阐述。因为ColabNotebook是在线运行，数据在外网间传输，不需通过代理，因此可避免此类错误。Colab即Colaboratory（google合作实验室），是谷歌提供的一个在线工作平台，用户可以直接通过浏览器执行python代码并与他人分享合作，它还提供免费的GPU，同时它可以兼容jupyter的.ipynb文件。具体使用方法见参考文献1。我们在ColabNoteBook中运行截图如下：注意左侧的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，如下所示：fromgradio_clientimportClientclient=Client("http://127.0.0.1:7860/")client.view_api()#输出如下Client.predict()UsageInfo---------------------------NamedAPIendpoints:1-predict(text,api_name="/predict")->(output_0,output_1,output_2)Parameters:-[Textbox]text:str(required)Returns:-[Highlightedtext]output_0ist[Dict(token:str,class_or_confidence:str|float|None)]-[Json]output_1ict[Any,Any](anyvalidjson)-[Html]output_2:str1234567891011121314151617我们看到在这个空间中有1个APIEndpoint，并展示了如何使用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页面还包括一个“APIRecorder”，点击后可在页面底部看到被记录的调用（见本小节第一张图）。APIRecorder可以让您正常地与GradioUI交互，并将交互转换为相应的代码，以便与PythonClient配合一起运行。5.1.4使用API获取到可用的APIendpoint后，接下来讲如何使用。这里介绍两种使用API的方法：直接调用predict()和异步调用job。以下使用SpaceID的Client，均通过ColabNotebook运行。1.直接调用predict()使用API进行预测的最简单方法就是调用Client对象的predict()函数，如上文已使用的英转法abidlabs/en2fr：fromgradio_clientimportClientclient=Client("abidlabs/en2fr")client.predict("Hello",api_name='/predict')>>Bonjour123456下面看看predict()其它形式的参数设置：多个参数：当传递多个参数时，应将它们作为单独的参数传递给predict()，如提供计算器功能的Space"gradio/calculator"，它的地址为：https://huggingface.co/spaces/gradio/calculator，源代码如下：importgradioasgr#fromfooimportBAR#defcalculator(num1,operation,num2):ifoperation=="add":returnnum1+num2elifoperation=="subtract":returnnum1-num2elifoperation=="multiply":returnnum1*num2elifoperation=="divide":ifnum2==0:raisegr.Error("Cannotdividebyzero!")returnnum1/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="ToyCalculator",description="Here'sasampletoycalculator.Allowsyoutocalculatethingslike$2+2=4$",)if__name__=="__main__":demo.launch()1234567891011121314151617181920212223242526272829303132333435运行截图如下：多个参数的设置方法如下（建议提供关键字参数而不是位置参数）：fromgradio_clientimportClientclient=Client("gradio/calculator")#关键字参数：client.predict(num1=4,operation="add",num2=5)client.predict(4,"add",5)>>9.01234567默认参数：例如，Space"abidlabs/image_generator"中包括“滑块”组件steps的默认值，因此在使用客户端访问它时不需要提供该值，当然也可以进行指定，该程序的源代码为：importgradioasgrimportnumpyasnpimporttimedeffake_diffusion(text,steps):foriinrange(steps):time.sleep(1)image=np.random.random((600,600,3))yieldimageimage=np.ones((1000,1000,3),np.uint8)image[:]=[255,124,0]yieldimagedemo=gr.Interface(fake_diffusion,inputs=[gr.Textbox(),gr.Slider(1,10,3)],outputs="image")if__name__=="__main__":demo.launch()123456789101112131415161718默认参数设置方法如下所示：fromgradio_clientimportClientclient=Client("abidlabs/image_generator")client.predict(text="anastronautridingacamel",steps=25)1234文件或URL参数：我们可以将文件路径或URL以字符串形式传递给gradio_client.handle_file()，此函数负责将文件上传到Gradio服务器，并确保文件得到正确的预处理，如处理音频转录功能的"abidlabs/whisper"，源代码为：importgradioasgrwhisper=gr.load("models/openai/whisper-small")deftranscribe(audio):returnwhisper(audio)gr.Interface(transcribe,gr.Audio(type="filepath"),gr.Textbox()).launch()12345678其调用方法如下所示：fromgradio_clientimportClient,handle_fileclient=Client("abidlabs/whisper")client.predict(audio=handle_file("https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3"))##输出如下>>LoadedasAPI:https://abidlabs-whisper.hf.space✔AutomaticSpeechRecognitionOutput(text="MythoughtIhavenobodybyabeautyandwillasyoupoured.Mr.Rochesterissir,butthatsodon\'tfindsimpus,anddevotedabode,toatmightina",chunks=None)12345678910112.异步调用job我们应该注意到.predict()是一个阻塞操作，因为它在返回预测之前等待操作完成。在多数情况下，在需要预测结果之前，最好让作业在后台运行。这时我们可以通过创建Job实例并利用其.submit()提交操作，让作业在后台运行，稍后调用其.result()来获取结果。代码如下：fromgradio_clientimportClientclient=Client("abidlabs/en2fr")job=client.submit("Hello",api_name="/predict")#Thisisnotblocking#Dosomethingelsejob.result()#Thisisblocking>>Bonjour12345678910下面来看看job的其它功能：添加回调：可以通过参数result_callbacks添加一个或多个回调，以便在作业完成运行后执行操作，如下所示：fromgradio_clientimportClientdefprint_result(x):print("Thetranslatedresultis:{x}")client=Client(src="abidlabs/en2fr")job=client.submit("Hello",api_name="/predict",result_callbacks=[print_result])#Dosomethingelse>>Thetranslatedresultis:Bonjour123456789101112作者运行回调函数时，并未打印出结果且没有报错，或许这个函数还是有些问题，只能等官方改进。获取Status：Job对象可以通过调用其.status()方法来获取正在运行作业的状态。函数将返回一个StatusUpdate对象，它具有以下属性：code（状态代码，一组表示状态的字符串，请参阅utils.status类）、rank（此作业在队列中的当前位置）、queue_size（队列总大小）、eta（此作业将完成的估计时间）、success（表示作业是否成功完成）和time（生成状态的时间）等，如下：fromgradio_clientimportClientclient=Client(src="gradio/calculator")job=client.submit(5,"add",4,api_name="/predict")job.status()>>StatusUpdate(code=,rank=None,queue_size=None,eta=None,success=None,time=datetime.datetime(2024,7,10,10,3,21,689817),progress_data=None,log=None)1234567另外Job类还有一个.done()实例方法，它返回一个指示作业是否完成的布尔值。取消作业：Job类还有一个.cancel()实例方法，用于取消已排队但尚未启动的作业。例如运行：fromgradio_clientimportClient,handle_fileclient=Client("abidlabs/whisper")job1=client.submit(handle_file("audio_sample1.wav"))job2=client.submit(handle_file("audio_sample2.wav"))job1.cancel()#willreturnFalse,assumingthejobhasstartedjob2.cancel()#willreturnTrue,indicatingthatthejobhasbeencanceled1234567如果第一个作业已开始处理，则不会取消该作业。如果第二个作业尚未启动，它将被成功取消并从队列中删除。生成器端点：某些GradioAPI端点不返回单个值，而是返回一系列值。这时可以通过运行job.outputs()来获取此类生成器端点返回的所有系列值。数数程序gradio/count_generator的源代码如下，它每0.5秒返回一个递增的数字：importgradioasgrimporttimedefcount(n):foriinrange(int(n)):time.sleep(0.5)yieldidefshow(n):returnstr(list(range(int(n))))withgr.Blocks()asdemo:withgr.Column():num=gr.Number(value=10)withgr.Row():count_btn=gr.Button("Count")list_btn=gr.Button("List")withgr.Column()ut=gr.Textbox()count_btn.click(count,num,out)list_btn.click(show,num,out)demo.queue()if__name__=="__main__":demo.launch()123456789101112131415161718192021222324252627它的网址为：https://huggingface.co/spaces/gradio/count_generator。运行截图如下，点击“Count"会每隔0.5秒返回0到9的数字，点击"List"列出生成数字的列表：我们运行job.outputs()来获取此类生成器端点返回的所有系列值：fromgradio_clientimportClientimporttimeclient=Client(src="gradio/count_generator")job=client.submit(3,api_name="/count")whilenotjob.done():time.sleep(0.1)job.outputs()>>['0','1','2']12345678910注意：在生成器端点上运行job.result()时，只会返回端点生成的第一个值；Job对象也是可迭代的，这意味着您可以使用Job作为迭代器来显示从端点返回的结果。以下是使用Job作为迭代器的等效示例：fromgradio_clientimportClientclient=Client(src="gradio/count_generator")job=client.submit(3,api_name="/count")foroinjob:print(o)>>0>>1>>21234567891011我们还可以取消具有迭代输出的作业，在这种情况下，只要当前轮次的迭代完成，作业job就会结束，如下：fromgradio_clientimportClientimporttimeclient=Client("abidlabs/test-yield")job=client.submit("abcdef")time.sleep(3)job.cancel()#jobcancelsafter2iterations>>True123456789带有sessionstate的demos：最后看一下带有会话状态（seesionstate）的demo。Gradiodemos可以包括会话状态，这为demos提供了一种在页面会话中持久保存用户交互信息的方法。例如下面的demo，它使用gr.State()组件维护了用户提交的单词列表。当用户提交一个新词时，它会被添加到状态words中，并显示该词以前出现的次数：importgradioasgrdefcount(word,list_of_words):returnlist_of_words.count(word),list_of_words+[word]withgr.Blocks()asdemo:words=gr.State([])textbox=gr.Textbox()number=gr.Number()textbox.submit(count,inputs=[textbox,words],outputs=[number,words])demo.launch()123456789101112运行截图如下：如果我们使用PythonClient连接此Gradio应用程序，使用view_api()函数会发现API信息仅显示单个输入和输出：client=Client(src="http://127.0.0.1:7864")client.view_api()#输出如下LoadedasAPI:http://127.0.0.1:7862/✔Client.predict()UsageInfo---------------------------NamedAPIendpoints:1-predict(word,api_name="/count")->value_34Parameters:-[Textbox]word:str(required)Returns:-[Number]value_34:float1234567891011121314可以看到，输入输出参数自动忽略了gr.State()组件words，这是因为Python客户端会自动为我们处理状态——当我们发出一系列requests时，一个request返回的状态会存储在内部，并自动提供给后续request。如果想重置状态，可以通过调用Client.reset_session()来完成。参考文献Colab使用教程（超级详细版）及ColabPro/Pro+评测GettingStartedwiththeGradioPythonclient