Gradio JavaScript 客户端入门

标签：客户端，API，空间

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

The Gradio JavaScript client makes it very easy to use any Gradio app as an API. As an example, consider this Hugging Face Space that transcribes audio files that are recorded from the microphone.

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

Using the @gradio/client library, we can easily use the Gradio as an API to transcribe audio files programmatically.

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

Here's the entire code to do it:

import { client } from "@gradio/client";

const response = await fetch(
  "https://github.com/audio-samples/audio-samples.github.io/raw/master/samples/wav/ted_speakers/SalmanKhan/sample-1.wav"
);
const audio_file = await response.blob();

const app = await client("abidlabs/whisper");
const transcription = await app.predict("/predict", [audio_file]);

console.log(transcription.data);
// [ "I said the same phrase 30 times." ]

Gradio 客户端适用于任何托管的 Gradio 应用程序，无论是图像生成器、文本摘要器、状态聊天机器人、税务计算器还是其他任何东西！ Gradio 客户端主要用于托管在Hugging Face Spaces上的应用程序，但你的应用程序可以托管在任何地方，例如你自己的服务器。

The Gradio client works with any hosted Gradio app, whether it be an image generator, a text summarizer, a stateful chatbot, a tax calculator, or anything else! The Gradio Client is mostly used with apps hosted on Hugging Face Spaces, but your app can be hosted anywhere, such as your own server.

前提条件：使用 Gradio 客户端 _ 不需要 _ 对 gradio 库有很详细的了解。 但是，大体熟悉 Gradio 的输入和输出组件概念会很有帮助。

Prequisites: To use the Gradio client, you do not need to know the gradio library in great detail. However, it is helpful to have general familiarity with Gradio's concepts of input and output components.

安装

轻量级的 @gradio/client 包可以使用你选择的包管理器从 npm 注册表安装，并支持节点版本 18 及更高版本：

The lightweight @gradio/client package can be installed from the npm registry with a package manager of your choice and support node version 18 and above:

npm i @gradio/client

连接到正在运行的 Gradio 应用程序

首先连接实例化一个 client 实例，并将其连接到在 Hugging Face Spaces 上或通常在 Web 上的任何地方运行的 Gradio 应用程序。

Start by connecting instantiating a client instance and connecting it to a Gradio app that is running on Hugging Face Spaces or generally anywhere on the web.

连接到拥抱面空间

import { client } from "@gradio/client";

const app = client("abidlabs/en2fr"); // a Space that translates from English to French

你还可以通过使用选项参数的 hf_token 属性传入你的 HF 令牌来连接到私有空间。 你可以在这里获取你的 HF 代币： https ://huggingface.co/settings/tokens

You can also connect to private Spaces by passing in your HF token with the hf_token property of the options parameter. You can get your HF token here: https://huggingface.co/settings/tokens

import { client } from "@gradio/client";

const app = client("abidlabs/my-private-space", { hf_token="hf_..." })

复制空间供私人使用

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

While you can use any public Space as an API, you may get rate limited by Hugging Face if you make too many requests. For unlimited usage of a Space, simply duplicate the Space to create a private Space, and then use it to make as many requests as you'd like!

@gradio/client 导出另一个函数 duplicate 来简化这个过程（你需要传入你的Hugging Face token ）。

The @gradio/client exports another function, duplicate, to make this process simple (you'll need to pass in your Hugging Face token).

duplicate 几乎与 client 相同，唯一的区别是在引擎盖下：

duplicate is almost identical to client, the only difference is under the hood:

import { client } from "@gradio/client";

const response = await fetch(
  "https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3"
);
const audio_file = await response.blob();

const app = await duplicate("abidlabs/whisper", { hf_token: "hf_..." });
const transcription = app.predict("/predict", [audio_file]);

如果你之前复制过一个空间，重新运行 duplicate 将 _ 不会 _ 创建一个新的空间。 相反，客户端将附加到先前创建的空间。 所以用相同的空间多次重新运行 duplicate 方法是安全的。

If you have previously duplicated a Space, re-running duplicate will not create a new Space. Instead, the client will attach to the previously-created Space. So it is safe to re-run the duplicate method multiple times with the same space.

注意：如果原始 Space 使用 GPU，你的私人空间也会使用 GPU，并且你的 Hugging Face 帐户将根据 GPU 的价格进行计费。 为最大限度地减少费用，你的 Space 将在闲置 5 分钟后自动进入休眠状态。 你还可以使用 duplicate 的选项对象的 hardware 和 timeout 属性来设置硬件，如下所示：

Note: if the original Space uses GPUs, your private Space will as well, and your Hugging Face account will get billed based on the price of the GPU. To minimize charges, your Space will automatically go to sleep after 5 minutes of inactivity. You can also set the hardware using the hardware and timeout properties of duplicate's options object like this:

import { client } from "@gradio/client";

const app = await duplicate("abidlabs/whisper", {
  hf_token: "hf_...",
  timeout: 60,
  hardware: "a10g-small",
});

连接通用的 Gradio 应用程序

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

If your app is running somewhere else, just provide the full URL instead, including the "http://" or "https://". Here's an example of making predictions to a Gradio app that is running on a share URL:

import { client } from "@gradio/client";

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

检查 API 端点

连接到 Gradio 应用程序后，你可以通过调用 client 的 view_api 方法来查看可用的 API。

Once you have connected to a Gradio app, you can view the APIs that are available to you by calling the client's view_api method.

对于耳语空间，我们可以这样做：

For the Whisper Space, we can do this:

import { client } from "@gradio/client";

const app = await client("abidlabs/whisper");

const app_info = await app.view_info();

console.log(app_info);

我们将看到以下内容：

And we will see the following:

{
  "named_endpoints": {
    "/predict": {
      "parameters": [
        {
          "label": "text",
          "component": "Textbox",
          "type": "string"
        }
      ],
      "returns": [
        {
          "label": "output",
          "component": "Textbox",
          "type": "string"
        }
      ]
    }
  },
  "unnamed_endpoints": {}
}

这向我们展示了我们在此空间中有 1 个 API 端点，并向我们展示了如何使用 API 端点进行预测：我们应该调用 .predict() 方法（我们将在下面探讨），提供类型为 input_audio 的参数 string ，这是文件的 url。

This shows us that we have 1 API endpoint in this space, and shows us how to use the API endpoint to make a prediction: we should call the .predict() method (which we will explore below), providing a parameter input_audio of type string, which is a url to a file.

我们还应该为 predict() 方法提供 api_name='/predict' 参数。 虽然如果 Gradio 应用程序只有 1 个命名端点，这不是必需的，但它确实允许我们在单个应用程序中调用不同的端点（如果它们可用）。 如果应用程序具有未命名的 API 端点，也可以通过运行 .view_api(all_endpoints=True) 来显示这些端点。

We should also provide the api_name='/predict' argument to the predict() method. Although this isn't necessary if a Gradio app has only 1 named endpoint, it does allow us to call different endpoints in a single app if they are available. If an app has unnamed API endpoints, these can also be displayed by running .view_api(all_endpoints=True).

做出预测

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

The simplest way to make a prediction is simply to call the .predict() method with the appropriate arguments:

import { client } from "@gradio/client";

const app = await client("abidlabs/en2fr");
const result = await app.predict("/predict", ["Hello"]);

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

If there are multiple parameters, then you should pass them as an array to .predict(), like this:

import { client } from "@gradio/client";

const app = await client("gradio/calculator");
const result = await app.predict("/predict", [4, "add", 5]);

对于某些输入，例如图像，你应该根据最方便的方式传入 Buffer 、 Blob 或 File 。 在节点中，这将是一个 Buffer 或 Blob ； 在浏览器环境中，这将是 Blob 或 File 。

For certain inputs, such as images, you should pass in a Buffer, Blob or File depending on what is most convenient. In node, this would be a Buffer or Blob; in a browser environment, this would be a Blob or File.

import { client } from "@gradio/client";

const response = await fetch(
  "https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3"
);
const audio_file = await response.blob();

const app = await client("abidlabs/whisper");
const result = await client.predict("/predict", [audio_file]);

使用事件

如果你正在使用的 API 可以随时间返回结果，或者你希望访问有关作业状态的信息，则可以使用事件界面以获得更大的灵活性。 这对于迭代端点或生成器端点特别有用，它们将随着时间的推移产生一系列值作为谨慎的响应。

If the API you are working with can return results over time, or you wish to access information about the status of a job, you can use the event interface for more flexibility. This is especially useful for iterative endpoints or generator endpoints that will produce a series of values over time as discreet responses.

import { client } from "@gradio/client";

function log_result(payload) {
  const {
    data: [translation],
  } = payload;

  console.log(`The translated result is: ${translation}`);
}

const app = await client("abidlabs/en2fr");
const job = app.submit("/predict", ["Hello"]);

job.on("data", log_result);

地位

事件界面还允许你通过监听 "status" 事件来获取正在运行的作业的状态。 这将返回一个具有以下属性的对象： status （当前作业的人工可读状态， "pending" | "generating" | "complete" | "error" ）， code （作业的详细 gradio 代码）， position （此作业在队列中的当前位置）、 queue_size （总队列大小）、 eta （此作业完成的估计时间）、 success （表示作业是否成功完成的布尔值）和 time （作为 Date 对象详细说明时间状态已生成）。

The event interface also allows you to get the status of the running job by listening to the "status" event. This returns an object with the following attributes: status (a human readbale status of the current job, "pending" | "generating" | "complete" | "error"), code (the detailed gradio code for the job), position (the current position of this job in the queue), queue_size (the total queue size), eta (estimated time this job will complete), success (a boolean representing whether the job completed successfully), and time ( as Date object detailing the time that the status was generated).

import { client } from "@gradio/client";

function log_status(status) {
  console.log(
    `The current status for this job is: ${JSON.stringify(status, null, 2)}.`
  );
}

const app = await client("abidlabs/en2fr");
const job = app.submit("/predict", ["Hello"]);

job.on("status", log_status);

取消作业

作业实例还有一个 .cancel() 方法可以取消已排队但尚未启动的作业。 例如，如果你运行：

The job instance also has a .cancel() method that cancels jobs that have been queued but not started. For example, if you run:

import { client } from "@gradio/client";

const app = await client("abidlabs/en2fr");
const job_one = app.submit("/predict", ["Hello"]);
const job_two = app.submit("/predict", ["Friends"]);

job_one.cancel();
job_two.cancel();

如果第一个作业已经开始处理，那么它不会被取消，但客户端将不再监听更新（丢弃作业）。 如果第二个作业还没有开始，它会被成功取消并从队列中移除。

If the first job has started processing, then it will not be canceled but the client will no longer listen for updates (throwing away the job). If the second job has not yet started, it will be successfully canceled and removed from the queue.

生成器端点

一些 Gradio API 端点不返回单个值，而是返回一系列值。 你可以使用事件界面实时监听这些值：

Some Gradio API endpoints do not return a single value, rather they return a series of values. You can listen for these values in real time using the event interface:

import { client } from "@gradio/client";

const app = await client("gradio/count_generator");
const job = app.submit(0, [9]);

job.on("data", (data) => console.log(data));

这将注销端点生成的值。

This will log out the values as they are generated by the endpoint.

你还可以取消具有迭代输出的作业，在这种情况下作业将立即完成。

You can also cancel jobs that that have iterative outputs, in which case the job will finish immediately.

import { client } from "@gradio/client";

const app = await client("gradio/count_generator");
const job = app.submit(0, [9]);

job.on("data", (data) => console.log(data));

setTimeout(() => {
  job.cancel();
}, 3000);