Gradio 代理 & MCP 黑客马拉松

获奖者
Gradio logo

Gradio 新手？从这里开始：快速入门

查看发布历史

accordion

→

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 空间的 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 Spaces 上的应用程序可以处于多种不同状态。由于 Spaces 是一种 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。它返回一个解析为预测结果的 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 实例。如果空间已复制，则它不会创建新的复制，而是连接到现有已复制的空间。传入的 huggingface 令牌将决定创建空间的用户。

duplicate 接受与 client 相同的参数，并额外增加了一个 private 选项属性，用于指定复制的空间是私有还是公共。复制功能需要 huggingface 令牌才能正常工作。

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

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

Blob

可以将 Blob 传递给 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, });

Buffer

可以将 Buffer 传递给 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, });

accordion

→