gradio_client 使用指南用 3 行 Python 把任何 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 官方推出的轻量级 Python 客户端库它让你可以像调用本地函数一样调用任何运行中的 Gradio 应用无论是 Hugging Face Space 上托管的、还是通过 share URL 临时分享的应用把训练好的机器学习模型、有状态的聊天机器人、图像生成器等统一封装成远程 API。读完本文你将掌握如何用Client对象连接 Gradio 应用、用.view_api()查看可用的 API 端点、用.predict()/.submit()完成同步与异步调用以及通过Client.duplicate()复制一份属于自己的 Space 来绕开速率限制。一、gradio_client是什么本仓库的 client/python/ 目录承载着gradio_client的完整源码。它是一个独立的、轻量的 Python 包与完整的gradio框架解耦专门负责消费 Gradio 应用暴露的 API。一个最直观的例子假设有一个 Hugging Face Space 上的语音转文字应用Whisper 模型用gradio_client只需要三行代码即可完成一次音频转写from gradio_client import Client client Client(abidlabs/whisper) client.predict(audio_sample.wav) This is a test of the whisper speech recognition model.无论目标应用是图像生成器、有状态的聊天机器人还是税计算器只要它是 Gradio 应用gradio_client都能以统一的方式与之交互。从实现上看包的公共 API 定义在 client/python/gradio_client/init.py对外导出了Client、file、handle_file、FileData与__version__五个核心成员。其中 Client 类是使用入口负责连接远程应用、解析其配置并调度请求。二、安装与依赖gradio_client的版本与 Python 要求可以在 client/python/pyproject.toml 中确认requires-python 3.10即支持 Python 3.10 及以上版本项目许可证为 Apache-2.0。安装方式有两种如果你已经安装了较新版本的gradiogradio_client已经作为依赖被一并安装无需额外操作否则通过 pip 单独安装这个轻量包$ pip install gradio_client从 pyproject.toml 可以看到包的核心依赖包括httpxHTTP 客户端、huggingface_hubSpace 查找、复制、运行时状态查询、fsspec与packaging等这些依赖支撑了客户端连接远程应用、处理文件传输与协议协商的全部能力。三、基本用法3.1 连接到一个 Space 或任意 Gradio 应用创建Client对象时传入目标应用的地址即可完成连接地址有两种形式连接 Hugging Face Space——直接使用用户名/空间名格式from gradio_client import Client client Client(abidlabs/en2fr) # 一个英译法的 Space连接私有 Space——传入你的 Hugging Face Token可在 https://huggingface.co/settings/tokens 获取from gradio_client import Client client Client(abidlabs/my-private-space, hf_token...)连接其他位置运行的 Gradio 应用——只要提供完整的 URL包含http://或https://即可例如通过 share URL 临时分享的应用from gradio_client import Client client Client(https://bec81a83-5b5c-471e.gradio.live)从 Client.init的源码可以看到除了上述用法构造函数还支持更多底层参数参数类型默认值作用srcstr必填Space 名称如abidlabs/whisper或完整 URL如http://mydomain.com/apptokenstr \| NoneNone访问私有 Space 用的 HF Token默认使用本地已保存的 Tokenmax_workersint40同时向远程应用发起请求的最大线程数verboseboolTrue是否在控制台打印信息authtuple[str, str] \| NoneNone以用户名/密码元组登录启用了认证的应用headersdict[str, str] \| NoneNone每次请求附加的额外请求头同名键会覆盖默认头download_filesstr \| Path \| FalseGRADIO_TEMP_DIR输出文件下载到本地的目录为False时不下载返回FileData对象ssl_verifyboolTrue设为False可跳过证书校验用于连接使用自签名证书的应用httpx_kwargsdict \| NoneNone透传给httpx.Client/httpx.stream/httpx.get/httpx.post的额外参数可设置超时、代理、HTTP 认证等analytics_enabledboolTrue是否允许基础遥测oauth_tokenstr \| NoneNone代表你在应用内执行操作的 OAuth Token仅发送给声明需要它的端点连接建立后客户端会做几件关键的事见 client.py若传入的是 Space 名称会先解析出对应的 Space 地址并查询其运行时状态如果 Space 仍在构建BUILDING会每隔 2 秒轮询等待随后拉取应用的config根据配置中的protocol字段ws、sse、sse_v1、sse_v2、sse_v2.1等决定使用 WebSocket 还是 SSE 协议与队列通信最后获取 API 元信息并建立端点映射。3.2 复制一个 Space 供自己使用任何公开 Space 都可以当作 API 使用但如果请求过于频繁可能会被 Hugging Face 限流。想要无限量使用最直接的办法是把该 Space复制一份到自己的账号下默认创建为私有 Space然后随意调用。gradio_client提供了类方法Client.duplicate()来简化这一过程from gradio_client import Client client Client.duplicate(abidlabs/whisper) client.predict(audio_sample.wav) This is a test of the whisper speech recognition model.duplicate()是幂等的如果你之前已经复制过该 Space再次调用不会创建新 Space而是直接挂载到之前创建的那份上因此可以放心重复调用。费用提醒如果原 Space 使用 GPU你的私有副本也会使用 GPU并按 GPU 价格向你的 Hugging Face 账号计费。为了尽量降低费用副本会在闲置 1 小时后自动休眠sleep_timeout参数可调源码中默认 5 分钟你也可以通过hardware参数显式指定硬件。从 duplicate() 的实现可以看到完整流程先通过huggingface_hub.get_space_runtime检查原 Space 是否存在若目标副本已存在则复用并给出提示否则调用huggingface_hub.duplicate_space创建副本必要时写入secrets环境变量随后按需通过request_space_hardware升级硬件、通过utils.set_space_timeout设置自动休眠时间最后返回连接该副本的Client实例。其完整参数如下参数类型默认值作用from_idstr必填要复制的 Space格式{用户名}/{空间名}to_idstr \| NoneNone新 Space 名称不填则命名为{你的HF用户名}/{空间名}tokenstr \| NoneNone复制私有 Space 用的 HF TokenprivateboolTrue新 Space 是否私有hardwarestr \| SpaceHardware \| None原 Space 的硬件硬件档位可选cpu-basic、cpu-upgrade、t4-small、t4-medium、a10g-small、a10g-large、a100-large等secretsdict[str, str] \| NoneNone传递给新 Space 的密钥字典仅在首次创建副本时生效sleep_timeoutint5副本无请求多少分钟后自动休眠单位为分钟源码中会换算为秒max_workersint40最大并发线程数verboseboolTrue是否打印过程信息3.3 查看应用的 API 端点连接成功后调用.view_api()即可查看该应用暴露了哪些 API 及各自用法。以 Whisper Space 为例输出如下Client.predict() Usage Info --------------------------- Named API endpoints: 1 - predict(input_audio, api_name/predict) - value_0 Parameters: - [Audio] input_audio: str (filepath or URL) Returns: - [Textbox] value_0: str (value)这告诉我们该 Space 有 1 个命名 API 端点调用方式是调用.predict()传入类型为str文件路径或 URL的参数input_audio。同时应显式传入api_name/predict——虽然当应用只有一个命名端点时并非必须但当单个应用有多个端点时它用于区分要调用哪个端点。view_api()的完整签名见 client.pyall_endpoints为True时同时打印命名与未命名端点默认None时只打印命名端点若应用没有命名端点则自动展示未命名端点print_info是否打印到控制台return_format为str时返回将被打印的字符串为dict时返回可编程解析的字典该模式下无论all_endpoints取值如何都会返回全部端点字典包含named_endpoints与unnamed_endpoints两个键每个端点下含parameters含label、python_type、type_description、component、example_input等字段与returns列表。另外若应用存在未命名端点默认打印时会提示要查看请运行Client.view_api(all_endpointsTrue)。3.4 发起预测调用最直接的调用方式就是.predict()它会阻塞等待远程结果返回from gradio_client import Client client Client(abidlabs/en2fr) client.predict(Hello) Bonjour当端点有多个参数时按顺序依次传入即可from gradio_client import Client client Client(gradio/calculator) client.predict(4, add, 5) 9.0对于图片、音频等文件类输入应传入本地文件路径或 URL对应地文件类输出也会以本地文件路径或 URL 的形式返回from gradio_client import Client client Client(abidlabs/whisper) client.predict(https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3) My thought I have nobody by a beauty and will as you poured. ...从 predict() 的实现可以看到predict()本质上是对submit().result()的封装。它支持的参数包括api_name要调用的端点名以斜杠开头如/predict应用只有一个命名端点时可不传fn_index端点的索引如0作为api_name的替代两者同时提供且冲突时以api_name为准headers本次请求额外附加的请求头同名键会覆盖构造函数中设置的请求头其余位置参数/关键字参数对应端点的输入推荐使用关键字参数源码中的utils.construct_args会根据ParameterInfo做参数名匹配、默认值填充与缺失参数校验。四、进阶用法4.1 用submit()做异步调用与状态跟踪当预测耗时较长或你需要监控任务状态、在结果就绪时执行回调时应使用.submit()。它返回一个在后台线程中执行的Job对象不会阻塞主线程from gradio_client import Client client Client(srcgradio/calculator) job client.submit(5, add, 4, api_name/predict) job.status() Status.STARTING: STARTING job.result() # 阻塞直到拿到结果 9.0Job类定义于 client.py是对 Pythonconcurrent.futures.Future的包装除了result()之外还提供status()查询任务的当前状态如STARTING、RUNNING、FINISHED等可迭代性Job实现了__iter__/__next__/__aiter__可以直接在for循环中消费生成器端点的阶段性输出cancel()取消尚未完成的任务。submit()额外支持result_callbacks参数可传入一个或一组回调函数在结果就绪时按顺序调用多个返回值会作为多个位置参数展开传入回调非常适合把预测结果直接接入后续处理链路。predict()与submit()在参数形式上保持一致可以无缝互换。4.2 文件上传与handle_file()向端点传入本地文件时推荐使用handle_file()来构造文件数据from gradio_client import handle_file, Client client Client(abidlabs/whisper) client.predict(handle_file(audio_sample.wav))handle_file() 的实现会构造一个带gradio.FileData元信息的字典若传入的是 URL会附带orig_name与url字段若传入的是本地存在的路径则附带本地文件名两者都不是时抛出ValueError。在较新版本中file()已标记为废弃deprecated应统一使用handle_file()。默认情况下文件类输出会被下载到临时目录由环境变量GRADIO_TEMP_DIR控制未设置时为系统临时目录下的gradio子目录并返回本地路径若将Client的download_files参数设为False则不会下载文件而是返回FileData数据类对象定义于 data_classes.py包含name、data、size、orig_name、mime_type、is_stream等字段其中data字段保存 base64 编码的内容。4.3 多端点应用的调用当一个 Gradio 应用包含多个 API 端点时用api_name区分即可没有命名的端点则可以用fn_index指定其索引。.view_api(all_endpointsTrue)会列出所有命名与未命名端点及其索引方便你确认正确的调用方式。值得说明的是view_api(return_formatdict)返回的字典中永远包含全部端点不受all_endpoints影响适合在程序中自动发现端点结构。五、背后机制与测试佐证gradio_client与远程应用的通信建立在 Gradio 的队列协议之上。从 client.py 可以看到客户端会根据应用config中的protocol字段选择通信方式并据此构造api/predict/、queue/join、upload、reset、cancel等一系列内部端点 URL这些常量定义在 utils.py。请求在后台线程池中执行通过Job包装实现提交即返回、结果异步取的模型。仓库中的测试为这些行为提供了可验证的依据test_client.py 覆盖了端到端调用如test_space_with_files_v4_sse_v2、test_file_io、文件下载如test_download_private_file、test_download_stream_file_uses_url_directly、duplicate()的 secret 注入test_add_secrets以及超大文件限制test_raise_error_max_file_size等场景test_utils.py 与 test_documentation.py 则分别验证了工具函数与文档生成逻辑。六、总结gradio_client把消费一个 Gradio 应用压缩成了三步连接Client→ 查看view_api→ 调用predict/submit。它既支持 Hugging Face Space含私有 Space 与自动复制副本也支持任何以 URL 形式暴露的 Gradio 应用既支持同步阻塞调用也支持带状态跟踪与回调的异步任务文件类数据在客户端与远程应用之间以路径/URL 自动转换。对于任何需要把现成的机器学习应用接入自己代码流程的开发者来说它是比手写 HTTP 请求更省心、更健壮的选择。更完整的用法如流式输出、事件监听、OAuth 端点等可以参考官方关于 Python 客户端的专项指南也可直接阅读本仓库 client/python/ 下的源码、CHANGELOG.md 与 client/python/test/ 中的测试用例进行深入探索。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考