JavaScript 客户端库
使用我们的JavaScript(和TypeScript)客户端与Gradio API进行交互.
安装
Gradio JavaScript 客户端在 npm 上可用为 @gradio/client。可以安装如下:
npm i @gradio/client
或者,您可以通过 jsDelivr CDN 直接将其包含在您的 HTML 中:
<script type="module">
import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
</script>
使用量
JavaScript Gradio客户端曝光客户端类, Client,以及各种其他公用事业功能. Client 用于初始化并建立一个连接或复制Gradio app.
Client
客户端功能连接到主机Gradio空间的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
选项对象可以选择通过第二个参数. 这个对象有两个属性, 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 空间上主机, 那么此功能将不起作用 .
其他背景
在 Hugging Face 空间上托管的应用程序可能分布在一些不同的状态. 由于空格是一个 GitOps 工具,并将在被推入寄存器时重建,它们有各种建筑,运行和出错状态. 如果空格不是“ 运行” , 函数会随 status_callback 将通知您当前空间的状况以及空间的变化状况。 正在建设或睡觉的空间需要比平时更长的时间来响应,因此可以使用这些信息来给用户反馈其行动的进展.
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。它返回一个承诺 解决预测结果.
endpoint
这是 api 请求的终点, 需要 。 a 的默认终点 gradio.Interface 实值 "/predict"。明确命名的终点有一个自定义名称。 端点名称可以在一个空格的"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 请求要成功就需要参数 。 应在空间的“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 方法接受相同的 endpoint 财务报告和审定财务报表 payload 参数为 predict。 。 。 .
这个 submit 方法不返回一个承诺,不应等待,而是返回一个带 cancel 方法.
访问值
使用提交文件可以访问与提交的API请求相关的事件。 有两种活动可以听: "data" 更新和 "status" 更新。 默认仅为 "data" 事件报告,但您可以收听 "status" 通过手动传递您在即时切换客户端时所关心的事件 :
import { Client } from "@gradio/client";
const app = await Client.connect("user/space-name", {
events: ["data", "status"]
});
"data" 当 API 计算一个值时会发布更新,作为第二个参数提供的回调在发送到客户端时会被调用。 数据的形状取决于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函数可以反复运行,在某些情况下可以无限地运行. 页:1 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
重复功能将试图复制引用的空间并返回实例 client 和那个空间有关 如果空间已经重复,那么它不会产生新的重复,而是会连接到现有的重复空间. 插入的拥抱面符将支配创建空间的用户.
duplicate 接受与 client 加上一个 private 选项属性,说明重复的空间应该是私有还是公有。 重复工作需要一个拥抱相容标志.
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选项对象,并将决定空间是公用还是私用。 通过 duplicate 方法默认是公开的.
import { Client } from "@gradio/client";
const app = await Client.duplicate("user/space-name", {
token: "hf_...",
private: true
});
timeout
这是针对 duplicate选项对象, 并会在重复空间入睡前几分钟设置超时 .
import { Client } from "@gradio/client";
const app = await Client.duplicate("user/space-name", {
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", {
token: "hf_...",
private: true,
hardware: "a10g-small"
});
handle_file(file_or_url: File | string | Blob | Buffer)
此工具功能用于简化处理客户端文件输入的过程.
Gradio APIs期望有一个特殊的文件数据结构,可以引用服务器上的位置. 这些文件可以手动上传,但根据您所处的环境,想用不同的文件类型做什么可能很困难.
此函数将处理文件, 不管它们是否是本地文件( 仅是节点), URL, Blobs, 或缓冲 。 它将采用参考材料并相应处理,酌情加载文件,并为客户生成正确的数据结构.
此函数的返回值可以在文件预期的输入数据中任意使用:
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 可以通过本地文件路径,它会上传到客户端服务器并返回客户端能够理解的引用.
这只在节点环境中工作.
文件路径是相对于当前工作目录而不是调用文件的位置解决的 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,
});
URL( URL)
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,
});
块
handle_file 可以传递一个 Blob,它会上传到客户端服务器并返回客户端能够理解的引用.
在调用预测或提交之前不会启动上传.
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,
});
缓冲
handle_file 可以通过缓冲器,它会上传到客户端服务器并返回客户端能够理解的引用.
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,
});