Gradio Python 客户端入门

Gradio Python 客户端使将任何 Gradio 应用用作 API 变得非常容易。例如，考虑这个 Hugging Face Space，它可以转录从麦克风录制的音频文件。

使用 gradio_client 库，我们可以轻松地使用 Gradio 作为 API 以编程方式转录音频文件。

这是执行此操作的完整代码

from gradio_client import Client, handle_file

client = Client("abidlabs/whisper")

client.predict(
    audio=handle_file("audio_sample.wav")
)

>> "This is a test of the whisper speech recognition model."

Gradio 客户端适用于任何托管的 Gradio 应用！虽然客户端主要与托管在 Hugging Face Spaces 上的应用一起使用，但你的应用可以托管在任何地方，例如你自己的服务器。

先决条件：要使用 Gradio 客户端，你不需要非常详细地了解 gradio 库。但是，对 Gradio 的输入和输出组件的概念有所了解会很有帮助。

安装

如果你已经安装了最新版本的 gradio，则 gradio_client 作为依赖项包含在内。但请注意，本文档反映了最新版本的 gradio_client，因此如果不确定，请升级！

轻量级的 gradio_client 包可以从 pip（或 pip3）安装，并经过测试，可在 Python 3.10 或更高版本 中使用

$ pip install --upgrade gradio_client

连接到 Hugging Face Spaces 上的 Gradio 应用

首先实例化一个 Client 对象，并将其连接到 Hugging Face Spaces 上运行的 Gradio 应用。

from gradio_client import Client

client = Client("abidlabs/en2fr")  # a Space that translates from English to French

你还可以通过传入带有 hf_token 参数的 HF 令牌来连接到私有 Space。你可以在此处获取你的 HF 令牌：https://hugging-face.cn/settings/tokens

from gradio_client import Client

client = Client("abidlabs/my-private-space", hf_token="...")

复制 Space 以供私人使用

虽然你可以使用任何公共 Space 作为 API，但如果你发出太多请求，你可能会受到 Hugging Face 的速率限制。为了无限制地使用 Space，只需复制 Space 以创建一个私有 Space，然后使用它发出任意数量的请求！

gradio_client 包括一个类方法：Client.duplicate()，使此过程变得简单（你需要传入你的 Hugging Face 令牌或使用 Hugging Face CLI 登录）

import os
from gradio_client import Client, handle_file

HF_TOKEN = os.environ.get("HF_TOKEN")

client = Client.duplicate("abidlabs/whisper", hf_token=HF_TOKEN)
client.predict(handle_file("audio_sample.wav"))

>> "This is a test of the whisper speech recognition model."

如果你之前复制过 Space，则重新运行 duplicate() 不会创建新的 Space。相反，客户端将连接到先前创建的 Space。因此，可以安全地多次重新运行 Client.duplicate() 方法。

注意： 如果原始 Space 使用 GPU，你的私有 Space 也将使用 GPU，并且你的 Hugging Face 帐户将根据 GPU 的价格收费。为了最大限度地减少费用，你的 Space 将在不活动 1 小时后自动进入休眠状态。你还可以使用 duplicate() 的 hardware 参数设置硬件。

连接通用 Gradio 应用

如果你的应用在其他地方运行，只需提供完整的 URL，包括“http://”或“https://”。这是一个向在共享 URL 上运行的 Gradio 应用进行预测的示例

from gradio_client import Client

client = Client("https://bec81a83-5b5c-471e.gradio.live")

连接到带有身份验证的 Gradio 应用

如果您连接的 Gradio 应用程序需要用户名和密码，请将它们作为元组提供给 Client 类的 auth 参数。

from gradio_client import Client

Client(
  space_name,
  auth=[username, password]
)

检查 API 端点

连接到 Gradio 应用后，您可以通过调用 Client.view_api() 方法来查看可用的 API。对于 Whisper Space，我们看到以下内容：

Client.predict() Usage Info
---------------------------
Named API endpoints: 1

 - predict(audio, api_name="/predict") -> output
    Parameters:
     - [Audio] audio: filepath (required)  
    Returns:
     - [Textbox] output: str

我们看到此 space 中有 1 个 API 端点，并向我们展示了如何使用 API 端点进行预测：我们应该调用 .predict() 方法（我们将在下面探讨），提供类型为 str 的参数 input_audio，它是一个 filepath or URL。

我们还应该为 predict() 方法提供 api_name='/predict' 参数。虽然如果 Gradio 应用程序只有一个命名端点，则这不是必需的，但如果单个应用程序中存在多个端点，则它允许我们调用不同的端点。

“查看 API”页面

作为运行 .view_api() 方法的替代方法，您可以单击 Gradio 应用程序页脚中的“通过 API 使用”链接，该链接向我们显示相同的信息以及示例用法。

“查看 API”页面还包括一个“API 记录器”，可让您正常与 Gradio UI 交互，并将您的交互转换为使用 Python Client 运行的相应代码。

进行预测

进行预测的最简单方法是直接使用适当的参数调用 .predict() 函数

from gradio_client import Client

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

>> Bonjour

如果有多个参数，则应将它们作为单独的参数传递给 .predict()，如下所示：

from gradio_client import Client

client = Client("gradio/calculator")
client.predict(4, "add", 5)

>> 9.0

建议提供关键字参数而不是位置参数。

from gradio_client import Client

client = Client("gradio/calculator")
client.predict(num1=4, operation="add", num2=5)

>> 9.0

这使您可以利用默认参数。例如，此 Space 包括 Slider 组件的默认值，因此您在使用客户端访问它时无需提供它。

from gradio_client import Client

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

默认值是相应 Gradio 组件的初始值。如果组件没有初始值，但 predict 函数中的相应参数的默认值为 None，则该参数在客户端中也是可选的。当然，如果您想覆盖它，也可以包含它。

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 服务器，并确保文件得到正确预处理。

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")
)

>> "My thought I have nobody by a beauty and will as you poured. Mr. Rochester is serve in that so don't find simpus, and devoted abode, to at might in a r—"

异步运行作业

应该注意的是，.predict() 是一个阻塞操作，因为它会等待操作完成，然后才返回预测结果。

在许多情况下，您最好让作业在后台运行，直到您需要预测结果。您可以使用 .submit() 方法创建一个 Job 实例，然后在稍后调用作业的 .result() 以获取结果。例如：

from gradio_client import Client

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

# Do something else

job.result()  # This is blocking

>> Bonjour

添加回调

或者，您可以添加一个或多个回调，以在作业完成后执行操作，如下所示：

from gradio_client import Client

def print_result(x):
    print("The translated result is: {x}")

client = Client(space="abidlabs/en2fr")

job = client.submit("Hello", api_name="/predict", result_callbacks=[print_result])

# Do something else

>> The translated result is: Bonjour

状态

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()

>> <Status.STARTING: 'STARTING'>

注意：Job 类还有一个 .done() 实例方法，该方法返回一个布尔值，指示作业是否已完成。

取消作业

Job 类还具有 .cancel() 实例方法，用于取消已排队但尚未开始的作业。例如，如果您运行：

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() 从此类生成器端点获取任何时候返回的一系列值。

from gradio_client import Client

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 作为生成器的等效示例：

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

您还可以取消具有迭代输出的作业，在这种情况下，作业将在当前迭代完成运行时立即完成。

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

具有会话状态的演示

Gradio 演示可以包含会话状态，这为演示提供了一种在页面会话中持久保存用户交互信息的方法。

例如，考虑以下演示，该演示维护用户在 gr.State 组件中提交的单词列表。当用户提交一个新单词时，它会被添加到状态中，并显示该单词先前出现的次数。

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 应用程序，您会注意到 API 信息仅显示单个输入和输出。

Client.predict() Usage Info
---------------------------
Named API endpoints: 1

 - predict(word, api_name="/count") -> value_31
    Parameters:
     - [Textbox] word: str (required)  
    Returns:
     - [Number] value_31: float

这是因为 Python 客户端会自动为您处理状态 - 当您发出一系列请求时，来自一个请求的返回状态会在内部存储，并自动提供给后续请求。如果您想重置状态，可以通过调用 Client.reset_session() 来完成。