# @gradio/client 中文文档

规范地址：https://npmcn.com/package/%40gradio/client/

版本：2\.8\.0
npm 元数据更新时间：2026-11-12T19:32:44.195Z
中文译文更新时间：2026-11-16T21:35:23.793Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gradio/client
原文对照：https://npmcn.com/package/%40gradio/client/?lang=original
项目主页：https://github.com/gradio-app/gradio#readme
源码仓库：https://github.com/gradio-app/gradio

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：849 kB，105 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2023-03-22T17:54:34.212Z
- 最新版本发布：2026-11-12T19:32:43.341Z
- 近 30 天下载量：145696（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 21 个）

## 中文简介

Gradio API 客户端

## 安装

```sh
npm install @gradio/client
```

也可以使用：`pnpm add @gradio/client`、`yarn add @gradio/client`、`bun add @gradio/client`

## README

## JavaScript 客户端库

使用我们的JavaScript(和TypeScript)客户端与Gradio API进行交互.

## 安装

Gradio JavaScript 客户端在 npm 上可用为 `@gradio/client`。可以安装如下:

```shell
npm i @gradio/client
```

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

```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打电话的对象.

最简单的例子是这样的:

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

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

此函数接受两个参数: `source` 财务报告和审定财务报表 `options`数字 :

#### `source`

这是您想要连接的 Gradio 应用程序的 URL 或名称 。 这个参数是需要的,并且应该始终是一个字符串. 例如:

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

#### `options`

选项对象可以选择通过第二个参数. 这个对象有两个属性, `token` 财务报告和审定财务报表 `status_callback`。 。 。 .

##### `token`

这应该是Hugging Face个人访问标志,如果您想给私人gradio api打电话,则需要它。 此选项是可选的, 应该是一个字符串, 起始于 `"hf_"`。 。 。 .

示例

```ts
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` 将通知您当前空间的状况以及空间的变化状况。 正在建设或睡觉的空间需要比平时更长的时间来响应,因此可以使用这些信息来给用户反馈其行动的进展.

```ts
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)
});
```

```ts
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 端点并获得预测结果 :

```ts
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"页面上找到.

```ts
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()` 客户端的方法.

```ts
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端点提供了更灵活的方法,为您提供了当前预测进度的状态更新,以及支持更复杂的端点类型.

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

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

这个 `submit` 方法接受相同的 [`endpoint`](https://npmcn.com/package/%40gradio/client/#readme-endpoint) 财务报告和审定财务报表 [`payload`](https://npmcn.com/package/%40gradio/client/#readme-payload) 参数为 `predict`。 。 。 .

这个 `submit` 方法不返回一个承诺,不应等待,而是返回一个带 `cancel` 方法.

##### 访问值

使用提交文件可以访问与提交的API请求相关的事件。 有两种活动可以听: `"data"` 更新和 `"status"` 更新。 默认仅为 `"data"` 事件报告,但您可以收听 `"status"` 通过手动传递您在即时切换客户端时所关心的事件 :

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

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

`"data"` 当 API 计算一个值时会发布更新,作为第二个参数提供的回调在发送到客户端时会被调用。 数据的形状取决于API本身的构造方式. 如果该端点支持随时间推移而释放出新的值,此事件可能不止一次起火.

`"status` 当请求状态发生变化时,将发布更新。 此信息允许您在请求的队列位置发生变化时,或在请求从队列变为处理时,向用户提供反馈.

状态有效载荷是这样的:

```ts
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;
}
```

用法是这样的:

```ts
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发布额外的更新.

```ts
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对象,未命名终点以及它们接受并返回的价值观. 这种方法不接受论证.

```ts
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 应用程序的配置。 此对象可能包含有关应用程序的有用元信息 .

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

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

### `duplicate`

重复功能将试图复制引用的空间并返回实例 `client` 和那个空间有关 如果空间已经重复,那么它不会产生新的重复,而是会连接到现有的重复空间. 插入的拥抱面符将支配创建空间的用户.

`duplicate` 接受与 `client` 加上一个 `private` 选项属性,说明重复的空间应该是私有还是公有。 重复工作需要一个拥抱相容标志.

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

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

此函数接受两个参数: `source` 财务报告和审定财务报表 `options`数字 :

#### `source`

复制和连接的空间 . [见 `client`是因为 `source` 参数](https://npmcn.com/package/%40gradio/client/#readme-source)。 。 。 .

#### `options`

接受所有选项 `client` 接受,但 `token` 需要时间. [见 `client`是因为 `options` 参数](https://npmcn.com/package/%40gradio/client/#readme-source)。 。 。 .

`duplicate` 还接受增加一个 `options` 属性.

##### `private`

这是针对 `duplicate`选项对象,并将决定空间是公用还是私用。 通过 `duplicate` 方法默认是公开的.

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

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

##### `timeout`

这是针对 `duplicate`选项对象, 并会在重复空间入睡前几分钟设置超时 .

```ts
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 上收费信息](https://huggingface.co/settings/billing)。 。 。 .

可能的硬件选项有:

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

```ts
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, 或缓冲 。 它将采用参考材料并相应处理,酌情加载文件,并为客户生成正确的数据结构.

此函数的返回值可以在文件预期的输入数据中任意使用:

```ts
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`。 。 。 .

```ts
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.

```ts
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,它会上传到客户端服务器并返回客户端能够理解的引用.

在调用预测或提交之前不会启动上传.

```ts
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` 可以通过缓冲器,它会上传到客户端服务器并返回客户端能够理解的引用.

```ts
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 是什么？

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 和提交记录判断。

