@gradio/client

中文文档
2.8.0发布于 2026/11/13ISCTypeScriptESM + CJS构建来源已验证近 30 天下载 14.6万

Gradio API 客户端

中文使用文档
文档目录6 节
  1. JavaScript 客户端库
  2. 安装
  3. 使用量
  4. Client
  5. duplicate
  6. handle_file(file_or_url: File | string | Blob | Buffer)

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

版本与发布记录

@gradio/client 共发布 112 个版本,首次发布于 2023/03/23;过去 12 个月发布了 21 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.8.0latest2026/11/134 天前
2.8.0-dev.0dev2026/11/106 天前
2.7.22026/10/2819 天前
2.7.12026/09/301 个月前
2.7.02026/09/181 个月前
2.6.02026/09/112 个月前

关于 @gradio/client 的常见问题

@gradio/client 是什么?

Gradio API 客户端

如何安装 @gradio/client?

在项目目录运行 npm install @gradio/client,或使用 pnpm add / yarn add / bun add。

@gradio/client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gradio/client 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gradio/client 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gradio/client 可以商用吗?

@gradio/client 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gradio/client 的下载量有多少?

根据 npm 官方下载统计,@gradio/client 在 2026/10/17 – 2026/11/15 这 30 天内被下载 145,696 次,日均约 4,857 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gradio/client 还在维护吗?

最新版本 2.8.0 发布于 2026/11/13(4 天前);至今共发布 112 个版本,其中过去 12 个月发布了 21 个;首次发布于 2023/03/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。