Gradio JavaScript Client 入门用 gradio/client 把任意 Gradio 应用当 API 调用【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradiogradio/client是 Gradio 官方提供的 TypeScript/JavaScript 客户端仓库内实现位于 client/js它让你无需手动拼 HTTP 请求就能把任何运行中的 Gradio 应用——语音转写、图像生成、文本翻译、带状态的聊天机器人、计算器等——当作标准的远程 API 来调用。读完本指南你将掌握从安装、连接含 Hugging Face Space、私有 Space、鉴权应用到查看端点、发起预测、监听流式事件与任务状态、取消任务的完整链路可直接把任意 Gradio App 集成进你自己的 Node.js 服务或前端页面。快速上手一段代码调用一个 Gradio App本指南以一个「音频转写」类应用Hugging Face Spaceabidlabs/whisper可将麦克风录制的音频转成文字为例。使用gradio/client仅需几行代码即可完成从拉取音频到拿到转写结果的完整流程import { Client, handle_file } from gradio/client; const response await fetch( https://example.com/sample-1.wav // 换成任何可访问的音频文件 URL ); const audio_file await response.blob(); const app await Client.connect(abidlabs/whisper); const transcription await app.predict(/predict, [handle_file(audio_file)]); console.log(transcription.data); // [ I said the same phrase 30 times. ]这条链路背后实际发生了三件事Client.connect拉取应用的运行时配置与 API 元数据handle_file把浏览器端拿到的Blob标记为待上传的文件对象predict完成上传与排队请求并等待最终结果。客户端并不限定只能连接 Hugging Face Space——任何部署在你自己服务器上的 Gradio 应用只要给出完整 URL 都能连接。前置知识使用 JS Client 不需要深入掌握gradio库本身但了解 Gradio 的「输入/输出组件」这一基本概念会很有帮助——API 的参数与返回值正是按照这些组件的类型来描述的。安装 gradio/client方式一通过 npm 安装在 Node.js 或前端工程中使用 npm 或其他兼容包管理器即可安装npm i gradio/client从仓库中的 client/js/package.json 可以看到该包的关键信息当前版本为2.5.1声明engines: { node: 18.0.0 }因此要求 Node.js 版本 ≥ 18.0.0包以type: module方式发布同时提供 ESMdist/index.js、CommonJSdist/index.cjs与浏览器构建dist/browser.js、dist/index.min.js等入口可被 Node 项目、打包工具及纯script场景分别消费。包的全部公开导出见 client/js/src/index.ts核心是Client类其余为predict、submit、upload_files、handle_file、upload以及SpaceStatus、Status、Config等类型。方式二通过 CDN 引入若只是想在网页里快速实验可以把最新版直接以 ES Module 形式引入!DOCTYPE html html langen head script typemodule import { Client } from https://cdn.jsdelivr.net/npm/gradio/client/dist/index.min.js; const client await Client.connect(abidlabs/en2fr); const result await client.predict(/predict, { text: My name is Hannah }); console.log(result); /script /head /html注意上面的import必须放在head的script typemodule中CDN 默认加载最新版本生产环境建议将 URL 中的版本号硬编码固定package.json 的exports字段中即暴露了./dist/index.min.js这一浏览器构建产物见 client/js/package.json。这种方式适合原型验证但存在版本漂移等局限。连接到正在运行的 Gradio 应用核心入口是Client类。连接的本质是两步先根据应用引用Space 名或完整 URL解析出应用配置config包括输入输出组件、依赖关系、协议版本等再通过配置中暴露的依赖信息建立可调用的 API 映射。这一初始化逻辑可在 client/js/src/client.ts 的init()/_resolve_config()中看到客户端解析端点、拉取 config、自动调用view_api()获取 API 信息并建立「端点名 → fn_index」映射。连接 Hugging Face Space传入 Space 名称即可abidlabs/en2fr是一个英译法翻译应用import { Client } from gradio/client; const app await Client.connect(abidlabs/en2fr);Client.connect是静态方法返回解析完成的Client实例源码见 client/js/src/client.ts。每个实例会自动生成一个session_hash用于区分会话、串联有状态应用的多轮交互。连接私有 Space如果 Space 是私有的需要在 options 中传入你的 Hugging Face 访问令牌Token 可在 Hugging Face 网站的Settings → Access Tokens页面创建import { Client } from gradio/client; const app await Client.connect(abidlabs/my-private-space, { token: hf_... })在 client/js/src/types.ts 的ClientOptions中可以看到token的类型被限定为hf_${string}形式说明它专用于 Hugging Face 鉴权。除token外ClientOptions还支持选项类型作用auth[string, string] \| null以用户名/密码元组方式登录启用账号鉴权的 Gradio 应用eventsEventType[]订阅的事件类型data \| status \| log \| render默认[data]status_callbackSpaceStatusCallback连接 Space 过程中的状态回调如 sleeping/running/error 等加载进度headersRecordstring, string \| Headers附加到每次 HTTP 请求的请求头query_paramsRecordstring, string附加的查询参数session_hashstring手动指定会话哈希默认随机生成cookiesstring手动提供 CookiecredentialsRequestCredentialsfetch 的 credentials 策略默认same-originwith_null_stateboolean是否把 State 组件的null一并返回hf_tokenhf_${string}旧版token别名标记为 deprecated仅为兼容保留oauth_tokenstring透传给应用的 OAuth 令牌仅发送给声明需要它的端点复制Duplicate一个 Space 供私人使用公共 Space 作为 API 高频调用时可能触发 Hugging Face 的频率限制。若需要不限量调用可以Client.duplicate把 Space 复制成你自己的私有 Spaceimport { Client, handle_file } from gradio/client; const response await fetch(https://example.com/sample-0.mp3); const audio_file await response.blob(); const app await Client.duplicate(abidlabs/whisper, { token: hf_... }); const transcription await app.predict(/predict, [handle_file(audio_file)]);Client.duplicate与Client.connect对外几乎一致唯一区别在于底层行为前者会通过 Hugging Face 的副本接口帮你创建一个 Space 并连接它。重复对同一个 Space 调用duplicate不会反复新建副本而是自动挂载到已创建的 Space 上因此多次调用是安全的。计费与硬件说明如果原 Space 使用了 GPU副本同样会使用 GPU 并按你的 Hugging Face 账户计费。为控制成本Space 闲置约 5 分钟后会自动休眠。你也可以在 options 中指定硬件规格与休眠超时import { Client } from gradio/client; const app await Client.duplicate(abidlabs/whisper, { token: hf_..., timeout: 60, // 空闲 60 分钟后休眠 hardware: a10g-small });DuplicateOptions见 client/js/src/types.ts在ClientOptions基础上增加了private、hardware、timeout。合法的hardware取值在 client/js/src/helpers/spaces.ts 中定义且duplicate在运行时会对传入值做白名单校验非法值会直接报错见 client/js/src/utils/duplicate.ts类别取值CPUcpu-basic、cpu-upgrade、cpu-xl入门 GPUt4-small、t4-mediumA10G 系列a10g-small、a10g-large、a10g-largex2、a10g-largex4高级 GPUa100-large、h100、h100x8其他zero-a10g连接任意位置的 Gradio 应用如果应用运行在 Hugging Face 之外例如自己的服务器、内网或 gradio.live 共享链接直接传入包含协议前缀的完整 URL 即可import { Client } from gradio/client; const app Client.connect(https://bec81a83-5b5c-471e.gradio.live);从源码看client/js/src/helpers/api_info.ts 的process_endpoint客户端会把传入引用解析为http_protocol host进而请求config与 API 信息Space 名与完整 URL 都走这条统一逻辑。连接带账号鉴权的 Gradio 应用如果目标应用在启动时启用了账号密码鉴权即服务端launch(auth...)原理可参考 sharing-your-app 指南中的 Authentication 部分把用户名和密码以元组形式传给auth选项即可import { Client } from gradio/client; Client.connect( space_name, { auth: [username, password] } )客户端在初始化时见 client/js/src/client.ts会先解析 Cookie 完成登录再把 Cookie 附加到后续所有请求Client.fetch/Client.stream会自动携带已保存的 Cookie 与 options 中的 headers源码见 client/js/src/client.ts。查看 API 端点连接成功后调用view_api()即可查看该应用对外暴露的全部 APIimport { Client } from gradio/client; const app await Client.connect(abidlabs/whisper); const app_info await app.view_api(); console.log(app_info);上述 whisper Space 返回的结构类似{ named_endpoints: { /predict: { parameters: [ { label: text, component: Textbox, type: string } ], returns: [ { label: output, component: Textbox, type: string } ] } }, unnamed_endpoints: {} }这告诉我们该应用只有 1 个命名端点/predict以及它的入参、出参各自的组件类型与类型定义。返回结构ApiInfo分为named_endpoints与unnamed_endpoints两组类型定义见 client/js/src/types.ts每个端点的EndpointInfo含parameters、returns等描述。客户端在init()阶段也会自动拉取一次 API 信息用于把/predict这类端点名映射到底层的fn_index依赖编号这一映射api_map的建立见 client/js/src/client.ts。实践中可以这样理解上面的信息调用时应使用.predict()方法下文详解其参数为类型string的输入显式传入api_name/predict并非必须应用只有单个命名端点时可省略但当一个应用暴露多个命名端点时这能让你精确指定调用哪一个。若应用存在未命名端点可以调用.view_api(all_endpointsTrue)把它们一并展示出来。备选「View API」页面与 API Recorder除了调用view_api()也可以在应用页脚点击Use via API链接打开可视化页面页面展示同样的端点信息并附有示例代码。该页面还内置了API Recorder录制器你可以照常操作 Gradio 界面录制器会把你的每次交互实时翻译成对应的 JS Client 代码片段是快速获取「正确参数格式」的捷径。相关内容可进一步阅读 view-api-page。发起一次预测.predict()基本调用最简单的方式是向.predict()传入端点名与参数数组import { Client } from gradio/client; const app await Client.connect(abidlabs/en2fr); const result await app.predict(/predict, [Hello]);predict的参数顺序与view_api()展示的parameters数组一一对应。当端点有多个入参时把它们按顺序放进数组即可例如gradio/calculator这个计算器应用接收两个数与一个运算符import { Client } from gradio/client; const app await Client.connect(gradio/calculator); const result await app.predict(/predict, [4, add, 5]);传入文件handle_file对图像、音频等文件类输入需要传入Buffer、Blob或File具体取决于运行环境Node.js 中用Buffer或Blob浏览器中用Blob或File。统一的推荐姿势是借助handle_file函数包装import { Client, handle_file } from gradio/client; const response await fetch(https://example.com/sample-0.mp3); const audio_file await response.blob(); const app await Client.connect(abidlabs/whisper); const result await app.predict(/predict, [handle_file(audio_file)]);handle_file的实现位于 client/js/src/helpers/data.ts其接受File | string | Blob | Buffer并按类型分流HTTP(S) URL 字符串直接构造为带path/url/orig_name的FileData客户端将告知服务端从该 URL 拉取无需本地上传本地路径字符串Node.js包装为一个Command(upload_file, ...)上传命令客户端会读取本地文件并上传File原样返回从而保留原始文件名与 MIME 类型Buffer在 Node 中包装成Blob后走上传流程Blob直接返回其他类型会抛出Invalid input: must be a URL, File, Blob, or Buffer object.。从源码看predict本质上是「完整跑完一次任务直到结束」的高层封装见 client/js/src/utils/predict.ts它调用submit(..., all_eventstrue)建立异步迭代器随后在循环里等待data消息拿到结果、以status.complete判断收尾任何error阶段都会转换为携带完整状态字段的真实Error抛出方便调用方捕获与排查。进阶用事件接口实时消费消息当端点本身支持排队、生成中阶段或你希望拿到任务状态、过程性结果时.predict()的「等全部完成」语义就不够用了。此时使用submit()返回的**异步可迭代对象iterable interface**更灵活——它特别适合会随时间产生一系列离散结果的迭代generator端点。import { Client } from gradio/client; function log_result(payload) { const { data: [translation] } payload; console.log(The translated result is: ${translation}); } const app await Client.connect(abidlabs/en2fr); const job app.submit(/predict, [Hello]); for await (const message of job) { log_result(message); }submit返回的SubmitIterable类型见 client/js/src/types.ts是一个 AsyncIterable额外带有cancel()、event_id()、wait_for_id()等方法。其底层消息处理逻辑client/js/src/utils/submit.ts会根据应用 config 中声明的protocol选择传输方式若该端点不经过队列直接向/run或/run/{api_name}POST若启用队列则通过 SSE/queue/data或流式协议持续接收服务端推送的status/data/log/generating等事件并逐个转发给迭代器。订阅任务状态events: [status, data]要拿到运行中的状态消息需要在连接时把events选项设为包含statusimport { Client } from gradio/client; const app await Client.connect(abidlabs/en2fr, { events: [status, data] });这样服务端的状态消息也会被推送给客户端。每个status对象包含下列属性属性说明status人类可读的任务阶段pending | generating | complete | errorcode任务对应的详细 Gradio 状态码position该任务在当前队列中的位置queue_size当前队列总长度eta预计完成时间success布尔值任务是否成功完成timeDate对象状态生成的时间戳Status类型在源码 client/js/src/types.ts 中也有完整定义含queue、stage、duration、progress_data、used_cache、cache_duration等字段可对照使用。在事件循环中按消息类型过滤即可import { Client } from gradio/client; function log_status(status) { console.log( The current status for this job is: ${JSON.stringify(status, null, 2)}. ); } const app await Client.connect(abidlabs/en2fr, { events: [status, data] }); const job app.submit(/predict, [Hello]); for await (const message of job) { if (message.type status) { log_status(message); } }取消任务.cancel()Job 实例提供.cancel()方法用于取消「已排队但尚未开始」的任务import { Client } from gradio/client; const app await Client.connect(abidlabs/en2fr); const job_one app.submit(/predict, [Hello]); const job_two app.submit(/predict, [Friends]); job_one.cancel(); job_two.cancel();取消的语义区分两种情况如果第一个任务已开始处理服务端不会真正中断它但客户端会停止监听相当于丢弃该任务的后续消息如果第二个任务尚未开始则会被成功取消并移出队列。底层实现会向/cancel与/reset端点分别发送请求见 client/js/src/utils/submit.ts其中/reset用于清理当前会话的排队状态。生成器端点实时接收一系列输出某些 Gradio 端点不返回单个值而是按时间依次产生一串值。以计数生成器gradio/count_generator为例可用异步迭代实时读取每个输出import { Client } from gradio/client; const app await Client.connect(gradio/count_generator); const job app.submit(0, [9]); for await (const message of job) { console.log(message.data); }注意这里的第一个参数传的是 **0fn_index / 依赖编号**而非/predict。在 client/js/src/utils/submit.ts 的get_endpoint_info中可以看到端点参数允许是字符串命名端点或数字依赖索引。未命名端点没有/predict这类名称只能或恰好只能用数字索引调用源码中也提示命名端点列表会在错误信息中列出便于排查。迭代输出的任务同样可以取消——取消后该任务会立即结束import { Client } from gradio/client; const app await Client.connect(gradio/count_generator); const job app.submit(0, [9]); for await (const message of job) { console.log(message.data); } setTimeout(() { job.cancel(); }, 3000);小结从源码理解完整调用链把上文各环节串起来一次完整调用的链路是连接Client.connect(space|url, options)解析端点、拉取 config 与 API 信息建立api_map端点名 → fn_index并处理鉴权token/Cookie/auth与 Space 唤醒client/js/src/client.ts构造请求submit/predict根据端点在 API 信息中定位参数结构handle_file把文件类入参解析为FileData/上传命令并先行走上传传输与事件依据 config 声明的协议非队列直连/run/{api_name}队列任务走 SSE接收服务端推送客户端把原始消息标准化为type: data | status | log | render的事件流供for await消费所有请求默认携带x-gradio-user: api请求头以标记 API 调用来源见 client/js/src/utils/submit.ts收尾收到complete状态后关闭事件流predict自动完成这一等待逻辑submit则把主动权交给调用方可中途取消。这套机制与仓库中的测试覆盖相互印证——客户端的浏览器/Node 双端测试位于 client/js/src/test前端各组件消费同一Client能力的代码在 js/core 目录中可作为深入理解事件协议细节的参考。延伸阅读如需了解 Python 版客户端的使用方式参见 getting-started-with-the-python-client想不依赖 SDK、直接以 HTTP/curl 调用 Gradio App参见 querying-gradio-apps-with-curl应用端的鉴权与分享配置参见 sharing-your-app「View API」页面的完整功能介绍参见 view-api-page。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考