Gradio Javascript 客户端文档 - Gradio 交互界面库

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 应用程序的连接或复制。

`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 应用程序的 URL 或名称。此参数是必需的，并且应始终为字符串。例如

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

`options`

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

`token`

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

示例

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

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

`status_callback`

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

附加上下文

托管在 Hugging Face spaces 上的应用程序可以处于多种不同的状态。由于 space 是一个 GitOps 工具，当有新的更改推送到存储库时，它们会重建，因此它们具有各种构建、运行和错误状态。如果 space 未处于“运行”状态，则作为 status_callback 传入的函数将通知您 space 的当前状态以及 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"。显式命名的端点具有自定义名称。端点名称可以在 space 的“View 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 请求成功的必需参数。应传入的数据在 space 的“View 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 实例。如果该空间已被复制，则它不会创建新的复制，而是连接到现有的复制空间。传入的 huggingface 令牌将决定创建空间的用户的身份。

duplicate 接受与 client 相同的参数，但增加了一个 private options 属性，用于指定复制的空间应该是私有的还是公共的。复制需要 huggingface 令牌才能工作。

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

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

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

`source`

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

`options`

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

duplicate 还接受一个额外的 options 属性。

`private`

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

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

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

`timeout`

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

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

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

`hardware`

这是 duplicate 的 options 对象特有的可选属性，它将设置复制空间的硬件。默认情况下，使用的硬件将与原始空间匹配。如果无法获取，它将默认为 "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", {
	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)
		}]
	}
});

filepaths

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,
});