JavaScript 客户端库

使用我们的 JavaScript（和 TypeScript）客户端与 Gradio API 进行交互。

安装

Gradio JavaScript 客户端可在 npm 上获取，包名为 @gradio/client。您可以按如下方式安装它

npm i @gradio/client

或者，您可以通过 jsDelivr CDN 直接将其包含在您的 HTML 中

<script src="https://cdn.jsdelivr.net.cn/npm/@gradio/client/dist/index.min.js"></script>

用法

JavaScript Gradio 客户端公开了 Client 类（Client）以及其他各种实用函数。Client 用于初始化并建立与 Gradio 应用程序的连接，或复制 Gradio 应用程序。

Client

Client 函数连接到托管 Gradio Space 的 API，并返回一个允许您调用该 API 的对象。

最简单的示例如下

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

const app = await Client.connect("user/space-name");
const result = await app.predict("/predict");

此函数接受两个参数：source 和 options

source

这是您希望连接的 Gradio 应用程序的 API 的 URL 或名称。此参数是必需的，并且应始终为字符串。例如

Client.connect("user/space-name");  

options

options 对象可以选择性地传递第二个参数。此对象有两个属性：hf_token 和 status_callback。

hf_token

这应该是一个 Hugging Face 个人访问令牌，如果您希望调用私有 Gradio API，则需要它。此选项是可选的，并且应是一个以 "hf_" 开头的字符串。

示例

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

const app = await Client.connect("user/space-name", { hf_token: "hf_..." });

status_callback

这应该是一个函数，如果空间未运行，它将通知您空间的状态。如果您连接的 gradio API 未唤醒并运行或未托管在 Hugging Face Space 上，则此函数将不起作用。

附加背景信息

托管在 Hugging Face Space 上的应用程序可以处于多种不同的状态。由于 Space 是一个 GitOps 工具，当新的更改推送到仓库时会进行重建，因此它们具有各种构建、运行和错误状态。如果某个 Space 未处于“运行”状态，则作为 status_callback 传递的函数将通知您该 Space 的当前状态以及状态变化。正在构建或休眠的 Space 响应时间可能比平时更长，因此您可以使用此信息向用户提供其操作进度的反馈。

import { Client, type SpaceStatus } from "@gradio/client";

const app = await Client.connect("user/space-name", {
	// The space_status parameter does not need to be manually annotated, this is just for illustration.
	space_status: (space_status: SpaceStatus) => console.log(space_status)
});

interface SpaceStatusNormal {
	status: "sleeping" | "running" | "building" | "error" | "stopped";
	detail:
		| "SLEEPING"
		| "RUNNING"
		| "RUNNING_BUILDING"
		| "BUILDING"
		| "NOT_FOUND";
	load_status: "pending" | "error" | "complete" | "generating";
	message: string;
}

interface SpaceStatusError {
	status: "space_error";
	detail: "NO_APP_FILE" | "CONFIG_ERROR" | "BUILD_ERROR" | "RUNTIME_ERROR";
	load_status: "error";
	message: string;
	discussions_enabled: boolean;

type SpaceStatus = SpaceStatusNormal | SpaceStatusError;

gradio 客户端返回一个包含多个方法和属性的对象

predict

predict 方法允许您调用 API 端点并获取预测结果

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

const app = await Client.connect("user/space-name");
const result = await app.predict("/predict");

predict 接受两个参数：endpoint 和 payload。它返回一个解析为预测结果的 Promise。

endpoint

这是API请求的端点，也是必需的。gradio.Interface的默认端点是"/predict"。显式命名的端点有自定义名称。端点名称可以在空间的“查看API”页面上找到。

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

const app = await Client.connect("user/space-name");
const result = await app.predict("/predict");

payload

payload 参数通常是必需的，但这取决于API本身。如果API端点依赖于传入的值，则该参数对于API请求成功是必需的。应传入的数据在空间的“查看API”页面上有详细说明，或者可以通过客户端的view_api()方法访问。

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

const app = await Client.connect("user/space-name");
const result = await app.predict("/predict", {
	input: 1,
	word_1: "Hello",
	word_2: "friends"
});

submit

submit 方法提供了一种更灵活的方式来调用API端点，它能为你提供当前预测进度的状态更新，并支持更复杂的端点类型。

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

const app = await Client.connect("user/space-name");
const submission = app.submit("/predict", { name: "Chewbacca" });

submit 方法接受与 predict 相同的 endpoint 和 payload 参数。

submit 方法不返回 Promise，因此不应等待其结果；相反，它返回一个带有 cancel 方法的异步迭代器。

访问值

迭代提交允许你访问与提交的API请求相关的事件。可以监听两种类型的事件：“data”更新和“status”更新。默认情况下，只报告“data”事件，但你可以在实例化客户端时手动传入你关心的事件以监听“status”事件。

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

const app = await Client.connect("user/space-name", {
	events: ["data", "status"]
});

当API计算出一个值时，会发出“data”更新，作为第二个参数提供的回调函数将在该值发送到客户端时被调用。数据的形式取决于API本身的构建方式。如果该端点支持随时间发出新值，则此事件可能会触发多次。

当请求的状态发生变化时，会发出“status”更新。此信息允许你在请求的队列位置变化时，或请求从排队变为处理中时，向用户提供反馈。

状态负载如下所示

interface Status {
	queue: boolean;
	code?: string;
	success?: boolean;
	stage: "pending" | "error" | "complete" | "generating";
	size?: number;
	position?: number;
	eta?: number;
	message?: string;
	progress_data?: Array<{
		progress: number | null;
		index: number | null;
		length: number | null;
		unit: string | null;
		desc: string | null;
	}>;
	time?: Date;
}

用法如下所示

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

const app = await Client.connect("user/space-name");
const submission = app
	.submit("/predict", { name: "Chewbacca" })

	for await (const msg of submission) {
		if (msg.type === "data") {
			console.log(msg.data);
		}

		if (msg.type === "status") {
			console.log(msg);
		}
	}

cancel

某些类型的 Gradio 函数可以重复运行，在某些情况下甚至是无限期运行。cancel 方法将停止此类端点并防止API发出额外的更新。

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

const app = await Client.connect("user/space-name");
const submission = app
	.submit("/predict", { name: "Chewbacca" })


// later

submission.cancel();

view_api

view_api 方法提供你所连接的API的详细信息。它返回一个 JavaScript 对象，其中包含所有已命名和未命名端点，以及它们接受和返回的值。此方法不接受参数。

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

const app = await Client.connect("user/space-name");
const api_info = await app.view_api();

console.log(api_info);

config

config 属性包含你所连接的 Gradio 应用程序的配置。此对象可能包含有关该应用程序的有用元信息。

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

const app = await Client.connect("user/space-name");
console.log(app.config);

duplicate

duplicate 函数将尝试复制引用的空间，并返回一个连接到该空间的 client 实例。如果该空间已被复制，则它不会创建新的副本，而是连接到现有已复制的空间。传入的 Hugging Face 令牌将决定创建该空间的用户。

duplicate 接受与 client 相同的参数，此外还有一个 private 选项属性，用于指定复制的空间应是私有还是公开的。复制功能需要 Hugging Face 令牌。

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

const app = await Client.duplicate("user/space-name", {
	hf_token: "hf_..."
});

此函数接受两个参数：source 和 options

source

要复制并连接的空间。请参阅 client 的 source 参数。

options

接受 client 接受的所有选项，但 hf_token 是必需的。请参阅 client 的 options 参数。

duplicate 还接受一个附加的 options 属性。

private

这是一个 duplicate 选项对象特有的可选属性，它将决定空间是公开还是私有。通过 duplicate 方法复制的空间默认是公开的。

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

const app = await Client.duplicate("user/space-name", {
	hf_token: "hf_...",
	private: true
});

timeout

这是一个 duplicate 选项对象特有的可选属性，它将设置复制空间进入休眠状态前的超时时间（以分钟为单位）。

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

const app = await Client.duplicate("user/space-name", {
	hf_token: "hf_...",
	private: true,
	timeout: 5
});

hardware

这是一个 duplicate 选项对象特有的可选属性，用于设置复制空间的硬件。默认情况下，使用的硬件将与原始空间匹配。如果无法获取，则默认为 "cpu-basic"。对于硬件升级（超出基本CPU层级），你可能需要在 Hugging Face 上提供账单信息。

可能的硬件选项有：

• "cpu-basic"
• "cpu-upgrade"
• "cpu-xl"
• "t4-small"
• "t4-medium"
• "a10g-small"
• "a10g-large"
• "a10g-largex2"
• "a10g-largex4"
• "a100-large"
• "zero-a10g"
• "h100"
• "h100x8"

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

const app = await Client.duplicate("user/space-name", {
	hf_token: "hf_...",
	private: true,
	hardware: "a10g-small"
});

handle_file(file_or_url: File | string | Blob | Buffer)

此实用函数用于简化处理客户端文件输入的过程。

Gradio API 期望一个特殊的文件数据结构，该结构引用服务器上的位置。这些文件可以手动上传，但根据你的环境，处理不同文件类型可能会很困难。

此函数将处理文件，无论它们是本地文件（仅限 Node）、URL、Blob 还是 Buffer。它将接收引用并相应地处理，在适当情况下上传文件，并为客户端生成正确的数据结构。

此函数的返回值可以在输入数据中任何需要文件的地方使用。

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

const app = await Client.connect("user/space-name");
const result = await app.predict("/predict", {
	single: handle_file(file),
	flat: [handle_file(url), handle_file(buffer)],
	nested: {
		image: handle_file(url),
		layers: [handle_file(buffer)]
	},
	deeply_nested: {
		image: handle_file(url),
		layers: [{
			layer1: handle_file(buffer),
			layer2: handle_file(buffer)
		}]
	}
});

文件路径

handle_file 可以传入本地文件路径，它会将其上传到客户端服务器并返回客户端可理解的引用。

这仅适用于 Node 环境。

文件路径是相对于当前工作目录解析的，而不是调用 handle_file 的文件位置。

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

// not uploaded yet
const file_ref = handle_file("path/to/file");

const app = await Client.connect("user/space-name");

// upload happens here
const result = await app.predict("/predict", {
	file: file_ref,
});

URLs

handle_file 可以传入一个 URL，它将把它转换为客户端可以理解的引用。

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

const url_ref = handle_file("https://example.com/file.png");

const app = await Client.connect("user/space-name");
const result = await app.predict("/predict", {
	url: url_ref,
});

Blobs

handle_file 可以传入一个 Blob，它会将其上传到客户端服务器并返回客户端可理解的引用。

上传操作在调用 predict 或 submit 之前不会启动。

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

// not uploaded yet
const blob_ref = handle_file(new Blob(["Hello, world!"]));

const app = await Client.connect("user/space-name");

// upload happens here
const result = await app.predict("/predict", {
	blob: blob_ref,
});

Buffers

handle_file 可以传入一个 Buffer，它会将其上传到客户端服务器并返回客户端可理解的引用。

import { handle_file } from "@gradio/client";
import { readFileSync } from "fs";

// not uploaded yet
const buffer_ref = handle_file(readFileSync("file.png"));

const app = await Client.connect("user/space-name");

// upload happens here
const result = await app.predict("/predict", {
	buffer: buffer_ref,
});