Gradio 应用 API 编程调用指南用info与predict命令驱动 Hugging Face Spaces 上的 Gradio 应用【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradiohf-gradio技能SKILL定义了一套可直接通过命令行调用 Gradio 应用 API 的标准流程先使用info命令探测应用暴露的全部端点与参数格式再使用predict命令携带 JSON 载荷请求远端 Space 或公网 Gradio 应用生成预测结果。本文以此技能文档为骨架结合当前仓库中 Gradio CLI 的命令注册、/info服务端实现与gradio_clientPython 客户端的源码讲解如何在 Agent、脚本或 CI 流水线中稳定地编程调用任意 Gradio 应用。一、hf-gradioCLI 技能总览gradioCLI 中用于以编程方式与 Gradio 应用交互的命令主要有两个命令用途gradio info space_id_or_url探测目标应用的全部端点返回每个端点的参数类型、默认值、是否必填与返回值结构gradio predict space_id_or_url endpoint json_payload向指定端点提交预测请求返回带命名输出键的 JSON 对象这三个位置参数均支持三种等价形式gradio、hf-gradio与hf gradio。这是因为该技能既可作为gradioCLI 的子命令使用也可作为 Hugging FacehfCLI 的扩展插件使用下文简称 Gradio 的info/predict命令。从当前仓库源码可以印证这条命令链路pyproject.toml将gradio命令入口指向gradio.cli:cli见 pyproject.toml而 gradio/cli/cli.py 中显式注册了gradio info与gradio predict两个命令其实现从hf_gradio.cli模块导入见 gradio/cli/commands/init.py。也就是说hf-gradio扩展为 Gradio 提供了可组合在 Agent 技能中的探测 预测能力。二、第 1 步验证安装在使用前请确认当前虚拟环境中已安装hf-gradio或gradio。如果本机已安装hfCLI 应用则可通过以下命令安装hf-gradio扩展hf extensions install gradio-app/hf-gradio安装完成后可先运行任意一条info命令验证可用性如果命令能够返回 JSON说明扩展已经就绪。三、第 2 步使用info探测端点与载荷格式在向应用发起任何预测之前必须先了解其公开 API 的形状这正是info命令的价值所在。它接受一个 Space ID 或公网 URL 作为唯一参数三种调用形式如下gradio info space_id_or_urlhf-gradio info space_id_or_urlhf gradio info space_id_or_urlinfo返回一个 JSON 载荷描述该应用全部端点、每个端点的参数含类型与默认值以及返回值。例如探测示例计算器应用gradio info gradio/calculator # { # /predict: { # parameters: [ # {name: num1, required: true, default: null, type: {type: number}}, # {name: operation, required: true, default: null, type: {enum: [add, subtract, multiply, divide], type: string}}, # {name: num2, required: true, default: null, type: {type: number}} # ], # returns: [{name: output, type: {type: number}}], # description: # } # }这个输出呈现了三个关键事实可直接作为构造predict载荷的依据端点名是应用的 API 名gradio/calculator暴露的是名为/predict的端点。Gradio 应用在定义函数事件时通过api_name指定端点名服务端在汇总 API 信息时会把/predict写入named_endpoints见 blocks.py 处api_info[named_endpoints][f/{fn.api_name}]的拼接逻辑。仓库中的 demo/calculator/run.py 即是一个设置了api_namepredict的本地等价示例。参数名与顺序parameters中的name就是构造 JSON 载荷时使用的键required标明该参数是否必须提供default给出可选参数的缺省值。参数类型结构type字段刻画 JSON 取值方式——普通数值类型如{type: number}枚举型参数如计算器中的operation会以{enum: [...], type: string}的形式列出全部合法取值add/subtract/multiply/divide。服务端视角上这些信息由 Gradio 应用运行时动态计算仓库在 routes.py 中为应用注册了GET /info/与GET /info路由并通过get_api_info见 blocks.py枚举出named_endpoints与unnamed_endpoints。Python 客户端Client._get_api_info()会请求info?serializeFalse这类接口并解析出同样的端点结构见 client.py与hf-gradioCLI 的info输出模型一致。文件类型参数的特殊约定当端点接收文件时info输出中的类型会显示为type: filepath并且要求调用方在载荷中附带meta: {_type: gradio.FileData}标记表示该文件将被上传到远端服务器。例如gradio info gradio/image_mod这类图像处理应用会提示其图像入参应按文件路径 FileData 元数据的形式提交。Python 侧与此对应的是gradio_client.data_classes中的FileData结构见 data_classes.py它支持name、database64 编码数据、orig_name、mime_type等字段当载荷中的文件需要发送到远端时就会触发真正的上传流程。仓库中的 demo/image_mod/run.py 是这类接受图像文件输入的本地示例应用。四、第 3 步使用predict生成预测结果掌握了端点信息后即可通过predict提交预测。命令形式为gradio predict space_id_or_url endpoint json_payload同样支持hf-gradio predict与hf gradio predict两种等价写法返回带命名输出键的 JSON 对象。4.1 数值/枚举参数最简单的一类载荷以计算器为例将 JSON 载荷按info输出的参数名直接映射即可# Simple numeric prediction gradio predict gradio/calculator /predict {num1: 5, operation: multiply, num2: 3} # {output: 15}由于operation是枚举参数载荷值必须取自info输出的 enum 列表这里使用了multiply否则远端函数校验将无法通过。4.2 图像生成类应用对于图像生成类应用入参通常是文本提示词返回对象则包含生成结果文件路径与随机种子等多个命名输出# Image generation gradio predict black-forest-labs/FLUX.2-dev /infer {prompt: A majestic dragon} # {Result: /tmp/gradio/.../image.webp, Seed: 1117868604}结果中的文件路径如/tmp/gradio/.../image.webp是远端应用返回后落地到本地的临时文件可用后续命令读取、展示或继续处理。4.3 文件上传必须携带 meta 键当载荷需要包含本地文件时必须以path指向本地文件并携带meta._type gradio.FileData# File upload (must include meta key) gradio predict gradio/image_mod /predict {image: {path: /path/to/image.png, meta: {_type: gradio.FileData}}} # {output: /tmp/gradio/.../output.png}这条约定的机制可以追溯到客户端实现Python 客户端predict()见 client.py本质上是submit()见同文件 L569-L649的阻塞封装内部会根据endpoint.parameters_info借助utils.construct_args组装参数L605凡是文件类参数都会被转换为带 FileData 元数据的上传请求。同时utils.py 中的常量也列出了客户端实际使用的协议端点如UPLOAD_URL upload、API_URL api/predict/、API_INFO_URL info?all_endpointsTrue等说明完整的调用链路包含获取配置/API 信息 → 上传文件 → 提交预测 → 下载结果。五、访问私有 Space--token参数info与predict两个命令都支持--token参数用于访问私有privateSpacegradio info private_space_id --token $HF_TOKEN gradio predict private_space_id /predict {...} --token $HF_TOKEN私有 Space 的配置、API 信息与预测接口都要求身份认证token 通常来自 Hugging Face 账户设置中的访问令牌也可通过环境变量注入以免明文出现在 shell 历史中。六、端到端调用实践与注意事项将上面几步组合成一个完整的探测 → 预测工作流用gradio info space确认端点名、参数名、参数类型number/string/enum与返回结构依据返回的 schema 构造合法 JSON——键名、枚举值、可选参数都必须与info输出严格一致若含本地文件将文件包装为{path: ..., meta: {_type: gradio.FileData}}用gradio predict space endpoint json提交并解析带命名键的 JSON 结果私有应用补传--token。实操中还有几个值得注意的点Shell 引号JSON 载荷建议整体使用单引号包裹避免 shell 对双引号内内容做变量与转义展开载荷内部的双引号保持原样。枚举值必须合法如计算器的operation只能取 add/subtract/multiply/divide 之一取值越界会直接导致远端校验失败。返回文件是本地路径图像等输出会先下载到本机临时目录形如/tmp/gradio/...随后可被后续工具继续消费。命名端点优先多数 Blocks 与 Interface 应用都通过api_name暴露/predict之类的具名端点参考 demo/calculator/run.py 的api_namepredict写法对存在多个端点的复杂应用info会逐一列出选取目标端点名提交即可。这与 Python 侧Client.view_api()见 client.py打印的 Usage Info 定位相同——都是面向调用方的 API 发现机制只是hf-gradio将它下沉到了纯命令行与 Agent 可执行的 JSON 工作流中。若希望直接在 Python 脚本中完成同样的探测与调用可以参考 getting-started-with-the-python-client 指南若想绕开客户端、直接用 HTTP 语义理解底层请求则可阅读 querying-gradio-apps-with-curl。七、小结一条可被 Agent 直接执行的调用范式hf-gradio技能给出的模式是通用的任何托管在 Hugging Face Spaces 或公网 URL 上的 Gradio 应用只要提供其space_id_or_url都可以先info后predict地以编程方式驱动——从数值计算、文本生成到图像生成、文件处理均适用。整套流程以先探测 schema、再提交精确载荷为原则既保证了调用方的载荷总是与应用实际签名匹配也天然适合作为大模型 Agent 工具链中的一个稳定步骤技能文档的description建议在收到基于某个 Gradio 应用生成结果的请求如使用 black-forest-labs/FLUX.2-dev 生成一张图时触发本流程。在当前仓库中这条命令行链路与 Pythongradio_client共享同一套服务端协议/info、upload、api/predict/而仓库内的 demo/calculator/run.py 与 demo/image_mod/run.py 则为验证上述命令提供了可在本地启动的等价应用样例。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gradio 应用 API 编程调用指南：用 `info` 与 `predict` 命令驱动 Hugging Face Spaces 上的 Gradio 应用
Gradio 应用 API 编程调用指南用info与predict命令驱动 Hugging Face Spaces 上的 Gradio 应用【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradiohf-gradio技能SKILL定义了一套可直接通过命令行调用 Gradio 应用 API 的标准流程先使用info命令探测应用暴露的全部端点与参数格式再使用predict命令携带 JSON 载荷请求远端 Space 或公网 Gradio 应用生成预测结果。本文以此技能文档为骨架结合当前仓库中 Gradio CLI 的命令注册、/info服务端实现与gradio_clientPython 客户端的源码讲解如何在 Agent、脚本或 CI 流水线中稳定地编程调用任意 Gradio 应用。一、hf-gradioCLI 技能总览gradioCLI 中用于以编程方式与 Gradio 应用交互的命令主要有两个命令用途gradio info space_id_or_url探测目标应用的全部端点返回每个端点的参数类型、默认值、是否必填与返回值结构gradio predict space_id_or_url endpoint json_payload向指定端点提交预测请求返回带命名输出键的 JSON 对象这三个位置参数均支持三种等价形式gradio、hf-gradio与hf gradio。这是因为该技能既可作为gradioCLI 的子命令使用也可作为 Hugging FacehfCLI 的扩展插件使用下文简称 Gradio 的info/predict命令。从当前仓库源码可以印证这条命令链路pyproject.toml将gradio命令入口指向gradio.cli:cli见 pyproject.toml而 gradio/cli/cli.py 中显式注册了gradio info与gradio predict两个命令其实现从hf_gradio.cli模块导入见 gradio/cli/commands/init.py。也就是说hf-gradio扩展为 Gradio 提供了可组合在 Agent 技能中的探测 预测能力。二、第 1 步验证安装在使用前请确认当前虚拟环境中已安装hf-gradio或gradio。如果本机已安装hfCLI 应用则可通过以下命令安装hf-gradio扩展hf extensions install gradio-app/hf-gradio安装完成后可先运行任意一条info命令验证可用性如果命令能够返回 JSON说明扩展已经就绪。三、第 2 步使用info探测端点与载荷格式在向应用发起任何预测之前必须先了解其公开 API 的形状这正是info命令的价值所在。它接受一个 Space ID 或公网 URL 作为唯一参数三种调用形式如下gradio info space_id_or_urlhf-gradio info space_id_or_urlhf gradio info space_id_or_urlinfo返回一个 JSON 载荷描述该应用全部端点、每个端点的参数含类型与默认值以及返回值。例如探测示例计算器应用gradio info gradio/calculator # { # /predict: { # parameters: [ # {name: num1, required: true, default: null, type: {type: number}}, # {name: operation, required: true, default: null, type: {enum: [add, subtract, multiply, divide], type: string}}, # {name: num2, required: true, default: null, type: {type: number}} # ], # returns: [{name: output, type: {type: number}}], # description: # } # }这个输出呈现了三个关键事实可直接作为构造predict载荷的依据端点名是应用的 API 名gradio/calculator暴露的是名为/predict的端点。Gradio 应用在定义函数事件时通过api_name指定端点名服务端在汇总 API 信息时会把/predict写入named_endpoints见 blocks.py 处api_info[named_endpoints][f/{fn.api_name}]的拼接逻辑。仓库中的 demo/calculator/run.py 即是一个设置了api_namepredict的本地等价示例。参数名与顺序parameters中的name就是构造 JSON 载荷时使用的键required标明该参数是否必须提供default给出可选参数的缺省值。参数类型结构type字段刻画 JSON 取值方式——普通数值类型如{type: number}枚举型参数如计算器中的operation会以{enum: [...], type: string}的形式列出全部合法取值add/subtract/multiply/divide。服务端视角上这些信息由 Gradio 应用运行时动态计算仓库在 routes.py 中为应用注册了GET /info/与GET /info路由并通过get_api_info见 blocks.py枚举出named_endpoints与unnamed_endpoints。Python 客户端Client._get_api_info()会请求info?serializeFalse这类接口并解析出同样的端点结构见 client.py与hf-gradioCLI 的info输出模型一致。文件类型参数的特殊约定当端点接收文件时info输出中的类型会显示为type: filepath并且要求调用方在载荷中附带meta: {_type: gradio.FileData}标记表示该文件将被上传到远端服务器。例如gradio info gradio/image_mod这类图像处理应用会提示其图像入参应按文件路径 FileData 元数据的形式提交。Python 侧与此对应的是gradio_client.data_classes中的FileData结构见 data_classes.py它支持name、database64 编码数据、orig_name、mime_type等字段当载荷中的文件需要发送到远端时就会触发真正的上传流程。仓库中的 demo/image_mod/run.py 是这类接受图像文件输入的本地示例应用。四、第 3 步使用predict生成预测结果掌握了端点信息后即可通过predict提交预测。命令形式为gradio predict space_id_or_url endpoint json_payload同样支持hf-gradio predict与hf gradio predict两种等价写法返回带命名输出键的 JSON 对象。4.1 数值/枚举参数最简单的一类载荷以计算器为例将 JSON 载荷按info输出的参数名直接映射即可# Simple numeric prediction gradio predict gradio/calculator /predict {num1: 5, operation: multiply, num2: 3} # {output: 15}由于operation是枚举参数载荷值必须取自info输出的 enum 列表这里使用了multiply否则远端函数校验将无法通过。4.2 图像生成类应用对于图像生成类应用入参通常是文本提示词返回对象则包含生成结果文件路径与随机种子等多个命名输出# Image generation gradio predict black-forest-labs/FLUX.2-dev /infer {prompt: A majestic dragon} # {Result: /tmp/gradio/.../image.webp, Seed: 1117868604}结果中的文件路径如/tmp/gradio/.../image.webp是远端应用返回后落地到本地的临时文件可用后续命令读取、展示或继续处理。4.3 文件上传必须携带 meta 键当载荷需要包含本地文件时必须以path指向本地文件并携带meta._type gradio.FileData# File upload (must include meta key) gradio predict gradio/image_mod /predict {image: {path: /path/to/image.png, meta: {_type: gradio.FileData}}} # {output: /tmp/gradio/.../output.png}这条约定的机制可以追溯到客户端实现Python 客户端predict()见 client.py本质上是submit()见同文件 L569-L649的阻塞封装内部会根据endpoint.parameters_info借助utils.construct_args组装参数L605凡是文件类参数都会被转换为带 FileData 元数据的上传请求。同时utils.py 中的常量也列出了客户端实际使用的协议端点如UPLOAD_URL upload、API_URL api/predict/、API_INFO_URL info?all_endpointsTrue等说明完整的调用链路包含获取配置/API 信息 → 上传文件 → 提交预测 → 下载结果。五、访问私有 Space--token参数info与predict两个命令都支持--token参数用于访问私有privateSpacegradio info private_space_id --token $HF_TOKEN gradio predict private_space_id /predict {...} --token $HF_TOKEN私有 Space 的配置、API 信息与预测接口都要求身份认证token 通常来自 Hugging Face 账户设置中的访问令牌也可通过环境变量注入以免明文出现在 shell 历史中。六、端到端调用实践与注意事项将上面几步组合成一个完整的探测 → 预测工作流用gradio info space确认端点名、参数名、参数类型number/string/enum与返回结构依据返回的 schema 构造合法 JSON——键名、枚举值、可选参数都必须与info输出严格一致若含本地文件将文件包装为{path: ..., meta: {_type: gradio.FileData}}用gradio predict space endpoint json提交并解析带命名键的 JSON 结果私有应用补传--token。实操中还有几个值得注意的点Shell 引号JSON 载荷建议整体使用单引号包裹避免 shell 对双引号内内容做变量与转义展开载荷内部的双引号保持原样。枚举值必须合法如计算器的operation只能取 add/subtract/multiply/divide 之一取值越界会直接导致远端校验失败。返回文件是本地路径图像等输出会先下载到本机临时目录形如/tmp/gradio/...随后可被后续工具继续消费。命名端点优先多数 Blocks 与 Interface 应用都通过api_name暴露/predict之类的具名端点参考 demo/calculator/run.py 的api_namepredict写法对存在多个端点的复杂应用info会逐一列出选取目标端点名提交即可。这与 Python 侧Client.view_api()见 client.py打印的 Usage Info 定位相同——都是面向调用方的 API 发现机制只是hf-gradio将它下沉到了纯命令行与 Agent 可执行的 JSON 工作流中。若希望直接在 Python 脚本中完成同样的探测与调用可以参考 getting-started-with-the-python-client 指南若想绕开客户端、直接用 HTTP 语义理解底层请求则可阅读 querying-gradio-apps-with-curl。七、小结一条可被 Agent 直接执行的调用范式hf-gradio技能给出的模式是通用的任何托管在 Hugging Face Spaces 或公网 URL 上的 Gradio 应用只要提供其space_id_or_url都可以先info后predict地以编程方式驱动——从数值计算、文本生成到图像生成、文件处理均适用。整套流程以先探测 schema、再提交精确载荷为原则既保证了调用方的载荷总是与应用实际签名匹配也天然适合作为大模型 Agent 工具链中的一个稳定步骤技能文档的description建议在收到基于某个 Gradio 应用生成结果的请求如使用 black-forest-labs/FLUX.2-dev 生成一张图时触发本流程。在当前仓库中这条命令行链路与 Pythongradio_client共享同一套服务端协议/info、upload、api/predict/而仓库内的 demo/calculator/run.py 与 demo/image_mod/run.py 则为验证上述命令提供了可在本地启动的等价应用样例。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考