Gradio 快速开始指南：用几行 Python 为机器学习模型构建并共享 Web 演示

Gradio 快速开始指南：用几行 Python 为机器学习模型构建并共享 Web 演示

【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. 🌟 Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio

Gradio 是一个开源的 Python 库，让你仅凭 Python 代码就能把一个机器学习模型、API 或任意 Python 函数包装成交互式 Web 演示，并一键把演示分享给浏览器里的任何人——全程无需编写 JavaScript、CSS，也不需要自己搭建 Web 服务器。本文以当前仓库中的中文快速开始指南为主体，结合仓库内真实的demo/示例与源码，带你走通从安装、写出第一个Interface、定制组件、处理多输入多输出、处理图像数据，到切换Blocks构建复杂布局的完整路径。

完成本文后，你将能够：使用pip install gradio完成环境搭建；用约 10 行代码让一个 Python 函数变成可在浏览器中交互的演示；用组件属性定制界面；让函数接收/返回多种类型数据；以及用gr.Blocks自定义布局与数据流，并用launch(share=True)在几秒内生成公网分享链接。

说明：文中的示例代码均直接取自仓库中可独立运行的演示脚本（位于demo/目录），可复制后在本机原样运行验证。

Gradio 是做什么的？

把机器学习模型、API 或数据科学处理流程分享给他人的最直接方式之一，是创建一个交互式应用程序，让用户或同事在自己的浏览器中亲手尝试演示。Gradio 允许你用 Python 构建并共享这类演示，通常只需要几行代码。

这样的应用形态覆盖了很广的场景：从简单的文本函数，到音乐生成器、税款计算器，再到预训练机器学习模型的预测函数，都可以成为被包装的对象。在仓库的demo/目录下可以看到大量对应真实场景的示例，例如agent_chatbot（聊天机器人）、stable-diffusion（文生图）、asr（语音识别）、image_segmentation（图像分割）等，它们都建立在本文将要介绍的Interface或Blocks之上。

环境准备与安装

先决条件：按照当前指南的描述，Gradio 需要Python 3.10 或更高版本，没有其他必须的依赖。

推荐的安装方式是通过随 Python 自带的pip在终端中执行：

pip install gradio

仓库根目录下的pyproject.toml与requirements.txt分别定义了 Python 包构建元数据与核心依赖清单，如需从源码开发或构建，可进一步查阅这两个文件。日常使用直接pip install即可。

第一个应用：Hello, World

通过一个简单的 Hello, World 示例跑通 Gradio，只需要三步：

第 1 步：安装

pip install gradio

第 2 步：编写代码

将下面的代码保存为 Python 脚本，或在 Jupyter Notebook（乃至 Google Colab）中逐格运行。这段代码与仓库中的 demo/hello_world/run.py 完全一致：

import gradio as gr def greet(name): return "Hello " + name + "!" demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox", api_name="predict") if __name__ == "__main__": demo.launch()

注意我们把导入名从gradio缩短为gr，这是 Gradio 社区广泛采用的约定，遵循它可以让任何阅读或协作你代码的人更容易理解。

第 3 步：运行并查看结果

• 在Jupyter Notebook中运行时，演示界面会自动内嵌显示在单元格下方；
• 如果作为Python 脚本运行，程序会在默认浏览器中弹出页面，地址为http://localhost:7860。

下图为该示例运行时的界面，左侧为Name文本输入框与Clear/Submit按钮，右侧为Output结果框（附处理耗时、Flag与Screenshot辅助按钮）：

在文本框中输入任意名字并点击Submit，即可在右侧得到问候结果。这个界面上默认出现的Flag、Screenshot、Clear等按钮由 Gradio 自动生成，无需任何额外代码。

关于api_name="predict"：演示脚本为接口指定了api_name，这相当于为该调用点起了一个稳定标识，后续可用gradio_client等客户端以编程方式调用同一应用时引用它。

本地开发进阶：热重载（reload）模式

在本地把代码作为 Python 脚本开发时，更推荐用 Gradio CLI 以重载模式启动应用——每次保存文件，应用会自动重载，带来无缝且快速的开发体验：

gradio app.py

注意：直接执行python app.py也可以运行，但它不会提供自动重载机制。重载模式对调试 UI 布局和函数逻辑非常省事，改完即所见即所得。

认识gr.Interface：包装任意 Python 函数

你会注意到上面的演示创建了gr.Interface。Interface类可以把任意 Python 函数与用户界面配对——函数可以是一段简单文本处理逻辑，也可以是音乐生成器、税款计算器或预训练模型的预测函数。

Interface的核心在于用三个必需参数完成初始化（类定义位于仓库的 gradio/interface.py）：

关于inputs/outputs，有两个非常实用的灵活性：

1. 传字符串快捷方式或组件实例均可：如"textbox"与gr.Textbox()等价，字符串更简短，组件类则支持传入更多自定义参数（见下一节）。
2. 传单个组件或组件列表：当函数只有一个参数、只返回一个值时，传单个组件即可；函数接受多个参数或返回多个值时，就传一个与函数参数/返回值顺序一一对应的列表。

Gradio 内置了面向机器学习场景的丰富组件（实现集中在仓库的 gradio/components 目录），常见的包括：

用组件属性定制界面

前一节我们看到了一些简单的Textbox。如果想改变 UI 组件的外观或行为（例如让输入框更大、带占位文本、配合滑块），就需要使用组件类而非字符串快捷方式，通过组件属性获得更精细的控制。

下面的例子（与 demo/hello_world_2/run.py 一致）演示了组件属性的自定义：函数接收名字和一个“热情程度”整数，Slider通过value/minimum/maximum/step控制默认值、范围与步长，输出Textbox通过label/lines自定义标签与行高：

import gradio as gr def greet(name, intensity): return "Hello, " + name + "!" * intensity demo = gr.Interface( fn=greet, inputs=["text", gr.Slider(value=2, minimum=1, maximum=10, step=1)], outputs=[gr.Textbox(label="greeting", lines=3)], api_name="predict" ) if __name__ == "__main__": demo.launch()

这里的inputs混合了字符串快捷方式（"text"）与带参数的组件类（gr.Slider(...)），outputs使用带label与lines参数的gr.Textbox。可以看到，凡是需要细粒度定制，就替换成组件实例并传入属性即可。

多个输入和输出组件

真实函数往往不止一个输入输出。下面这个例子定义了接受字符串、布尔值、数字三个参数、返回字符串与数字两个值的函数，代码与 demo/hello_world_3/run.py 一致：

import gradio as gr def greet(name, is_morning, temperature): salutation = "Good morning" if is_morning else "Good evening" greeting = f"{salutation} {name}. It is {temperature} degrees today" celsius = (temperature - 32) * 5 / 9 return greeting, round(celsius, 2) demo = gr.Interface( fn=greet, inputs=["text", "checkbox", gr.Slider(0, 100)], outputs=["text", "number"], api_name="predict" ) if __name__ == "__main__": demo.launch()

要点就一句话：把组件包装成列表。

• inputs列表中的每个组件按顺序对应函数的一个参数：第一个文本框 →name，复选框 →is_morning，滑块 →temperature；
• outputs列表中的每个组件按顺序对应函数返回的一个值：第一个文本 →greeting，数字框 → 摄氏温度结果。

这种“列表即顺序映射”的设计让Interface包装多参函数既直观又无额外样板代码。

图像示例：当输入输出是图片

Gradio 支持大量组件类型，例如Image、DataFrame、Video、Label。下面用一个图像到图像（sepia 怀旧滤镜）的函数感受这些组件（代码与 demo/sepia_filter/run.py 一致）：

import numpy as np import gradio as gr def sepia(input_img): sepia_filter = np.array([ [0.393, 0.769, 0.189], [0.349, 0.686, 0.168], [0.272, 0.534, 0.131] ]) sepia_img = input_img.dot(sepia_filter.T) sepia_img /= sepia_img.max() return sepia_img demo = gr.Interface(sepia, gr.Image(), "image", api_name="predict") if __name__ == "__main__": demo.launch()

在这个示例中值得注意两点：

1. NumPy 数组约定：以Image组件作为输入时，你的函数收到的是一个形状为（高度，宽度，3）的 NumPy 数组，最后一个维度表示 RGB 三个通道；返回图像时同样返回 NumPy 数组即可。
2. type=关键字：组件可以通过type参数切换传给函数的数据类型。例如希望函数直接接收图像文件路径而非 NumPy 数组时，输入Image组件可写成：

gr.Image(type="filepath")

此外，Image输入组件自带一个编辑按钮 🖉，允许用户在提交前对图像做裁剪与缩放。借助这种交互式预处理，往往能更容易暴露机器学习模型在图像处理上的偏见或隐藏缺陷——例如模型对小区域、裁剪构图等输入是否仍然稳健。

把演示分享给其他人：launch(share=True)

一个漂亮的演示如果无法分享出去价值会大打折扣。Gradio 通过launch()的参数让你免去服务器托管烦恼——把最后一行改为：

import gradio as gr def greet(name): return "Hello " + name + "!" demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox") demo.launch(share=True) # 只需多传一个参数即可分享

运行后几秒钟内会为演示生成一个类似https://a23dsf231adb.gradio.live的公网可访问 URL。任何地方的访问者都能从自己的浏览器试用该演示，而模型与所有计算仍然运行在你本地机器上。

从源码看，launch()是Interface与Blocks统一使用的启动入口，定义在 gradio/blocks.py。其文档字符串说明：share参数用于创建公网分享链接，会建立一条 SSH 隧道使 UI 可从任何地方访问；默认值为False，但在 Google Colab 等无法访问 localhost 的环境中除外——这种环境下设置share=False不受支持。除share外，launch()还支持server_name/server_port（绑定地址与端口）、inbrowser（是否自动打开浏览器）、auth（用户名密码或回调鉴权）、debug、ssl_keyfile/ssl_certfile（HTTPS）等常用参数，完整签名可阅读上述源码。

Blocks：更灵活、更可控的低层 API

Gradio 提供两个类来构建应用，它们解决不同粒度的需求：

1. Interface：创建演示的高层抽象，前面几节都在使用它。传入fn、inputs、outputs三要素即可快速成型，适合大多数演示与分享场景。
2. Blocks：用于以更灵活的布局与数据流设计 Web 应用的低层 API。Blocks允许你实现这些能力——控制组件在页面上的出现位置、处理多条数据流、支持把某个输出继续作为另一个函数的输入（复杂交互），以及基于用户交互更新组件的属性与可见性——而这一切仍然全部用 Python 完成。如果应用需要这样的可定制性，请选用Blocks。

Blocks的 API 形态与Interface明显不同，接下来用两个示例说明。

Hello, Blocks：事件驱动入门

最简单的Blocks示例（与 demo/hello_blocks/run.py 一致）：

import gradio as gr def greet(name): return "Hello " + name + "!" with gr.Blocks() as demo: name = gr.Textbox(label="Name") output = gr.Textbox(label="Output Box") greet_btn = gr.Button("Greet") greet_btn.click(fn=greet, inputs=name, outputs=output, api_name="greet") if __name__ == "__main__": demo.launch()

需要记住的要点：

• Blocks通过with子句创建，在with gr.Blocks() as demo:作用域内创建的任何组件都会自动加入应用；
• 未显式布局时，组件按创建顺序从上到下垂直排列在页面中（自定义布局稍后展开）；
• 这里创建了一个Button，然后在其上挂载了click事件监听器。事件 API 与Interface的思想一脉相承：click方法同样接受一个 Python 函数、一组输入组件和一组输出组件。

一个更复杂的 Blocks 应用

下面这个应用（与 demo/blocks_flipper/run.py 一致）展示了Blocks能做的更多事情——Markdown说明文本、Tab页签、Row行布局、可折叠的Accordion以及同一页面上的多条数据流：

import numpy as np import gradio as gr def flip_text(x): return x[::-1] def flip_image(x): return np.fliplr(x) with gr.Blocks() as demo: gr.Markdown("Flip text or image files using this demo.") with gr.Tab("Flip Text"): text_input = gr.Textbox() text_output = gr.Textbox() text_button = gr.Button("Flip") with gr.Tab("Flip Image"): with gr.Row(): image_input = gr.Image() image_output = gr.Image() image_button = gr.Button("Flip") with gr.Accordion("Open for More!", open=False): gr.Markdown("Look at me...") temp_slider = gr.Slider( 0, 1, value=0.1, step=0.1, interactive=True, label="Slide me", ) text_button.click(flip_text, inputs=text_input, outputs=text_output) image_button.click(flip_image, inputs=image_input, outputs=image_output) if __name__ == "__main__": demo.launch()

从这段代码可以体会到Blocks的布局与数据流组织方式：

• 布局控制：gr.Tab创建页签，gr.Row把两个组件并排放入同一行，gr.Accordion("...", open=False)生成默认折叠的扩展区域——布局信息以嵌套with的结构化方式表达，直观且可控；
• 多条数据流并存：文本翻转与图像翻转各自拥有独立的输入、按钮与输出，互不干扰，共处同一应用；
• 事件按需绑定：两个Button各自通过.click(fn, inputs, outputs)绑定处理函数，inputs/outputs可以只关联到应用中的部分组件，数据流向完全由你决定。

上述Tab、Row、Button、Textbox、Slider等布局与组件类都位于仓库的 gradio/layouts 与 gradio/components 目录，所有交互均以 Python API 驱动，前端由框架自动渲染。

小结与下一步

到这里你已经掌握了 Gradio 的基础用法：安装、用gr.Interface快速包装任意 Python 函数、通过组件属性与列表式inputs/outputs支持多输入多输出、用Image等组件处理图像数据并通过type控制数据类型、用launch(share=True)一键分享，以及切换到gr.Blocks自定义布局与事件流。仓库 demo 目录下的数百个示例（hello_world_4、calculator_blocks、chatbot_*、各类*_component等）都可在本地直接运行，是继续演练的最好素材。

后续可以沿着中文指南目录 guides/cn 继续深入：进阶学习Interface类更多参数（examples、title、theme等）、Blocks的事件监听与布局系统，以及gr.ChatInterface（在 gradio/chat_interface.py）等面向聊天机器人的高层封装。若需要以编程方式调用已部署的 Gradio 应用，还可查阅仓库中的 client/python（gradio_client）与 client/js（@gradio/client）客户端实现。

恭喜，你现在已经熟悉了 Gradio 的基础！🥳 从写下一行gr.Interface到把模型演示分享给全世界，全部只需 Python。

【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. 🌟 Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio