Gradio：用 Python 构建机器学习 Web 应用

Gradio 是一个开源的 Python 包，可让您快速为自己的机器学习模型、API 或任意 Python 函数 构建 一个演示或 Web 应用。您只需几秒钟，即可通过 Gradio 内置的分享功能，将您的演示或 Web 应用 分享 给他人。无需任何 JavaScript、CSS 或 Web 托管经验！

只需几行 Python 代码，即可轻松创建属于自己的演示应用，让我们马上开始吧 💫

安装

前提条件：Gradio 需要 Python 3.10 或更高版本。

我们建议使用 pip 进行安装，因为 Python 默认已包含该工具。在终端或命令提示符中运行以下命令：

pip install --upgrade gradio

[!提示] 最好在虚拟环境中安装 Gradio。关于所有常见操作系统的详细安装说明，请参阅 此处。

构建你的第一个演示

你可以在自己最喜爱的代码编辑器、Jupyter Notebook、Google Colab，或者任何其他你可以编写 Python 代码的地方运行 Gradio。让我们来编写你的第一个 Gradio 应用：

import gradio as gr

def greet(name, intensity):
    return "Hello, " + name + "!" * int(intensity)

demo = gr.Interface(
    fn=greet,
    inputs=["text", "slider"],
    outputs=["text"],
    api_name="predict"
)

demo.launch()

[！提示] 我们将导入的 gradio 名称简写为 gr。这一命名约定已被广泛采用，以提升代码的可读性。

现在，运行你的代码。如果你将 Python 代码保存在名为 app.py 的文件中，那么你只需在终端中运行 python app.py 即可。

如果从文件中运行，下方的演示将在浏览器中打开，网址为 http://localhost:7860。如果你是在 Jupyter Notebook 中运行，演示将会嵌入到 Notebook 内部显示。

在左侧的文本框中输入你的名字，拖动滑块，然后点击“提交”按钮。你应该会在右侧看到一条友好的问候语。

[！提示] 在本地开发时，你可以将 Gradio 应用置于 热重载模式下运行，只要你在文件中进行修改，Gradio 应用就会自动重新加载。要实现这一点，只需在文件名前输入 <gradio>，而不是直接输入 python。在上面的示例中，你可以在终端中输入：gradio app.py。你还可以通过使用 --vibe 标志启用 Vibe 模式,例如：gradio --vibe app.py，该模式会提供一个浏览器内置的聊天窗口，可用于使用自然语言编写或编辑你的 Gradio 应用。更多详情请参阅 热重载指南。

理解 Interface 类

你会发现，为了构建你的第一个演示，你创建了一个 gr.Interface 类的实例。Interface 类旨在为机器学习模型创建演示，这些模型可以接受一个或多个输入，并返回一个或多个输出。

Interface 类有三个核心参数：

• fn：用于包裹用户界面（UI）的函数
• inputs：用于输入的 Gradio 组件。组件的数量应与函数中的参数数量一致。
• outputs：用于输出的 Gradio 组件。组件的数量应与函数返回的值数量一致。

fn 参数非常灵活——你可以传递任意你想用 UI 包装的 Python 函数。在上面的示例中，我们看到的是一个相对简单的函数，但这个函数可以是任何东西，从音乐生成器到税务计算器，再到预训练机器学习模型的预测函数。

inputs 和 outputs 参数则接收一个或多个 Gradio 组件。正如我们接下来将看到的那样，Gradio 已经内置了超过 30 种组件（如 gr.Textbox()、gr.Image() 和 gr.HTML() 等组件），这些组件专为机器学习应用而设计。

[！提示] 对于 inputs 和 outputs 参数，你可以以字符串形式（如 "textbox"）或类的实例（如 gr.Textbox()）来传入这些组件的名称。

如果你的函数接受多个参数，就像上面的例子一样，可以将输入组件列表传递给 inputs，每个输入组件对应函数的一个参数。同样地，如果你的函数返回多个值，只需将组件列表传递给 outputs 即可。这种灵活性使 Interface 类成为构建演示的极为强大的工具。

在后续的系列文章中，我们将深入探讨 gr.Interface，重点讲解如何构建接口（构建接口）。

分享你的演示

如果一个演示再美观，却无法分享，又有什么意义呢？Gradio 让你轻松分享机器学习演示，而无需担心在 Web 服务器上托管的繁琐流程。只需在 launch() 中设置 share=True，即可为你的演示生成一个公开可访问的 URL。让我们回到之前的示例演示，但将最后一行修改为如下内容：

import gradio as gr

def greet(name):
    return "Hello " + name + "!"

demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
    
demo.launch(share=True)  # 仅需一个额外参数，即可与他人共享你的演示 🚀

当你运行这段代码时，你的演示将在几秒钟内生成一个公开的 URL，例如：

👉   https://a23dsf231adb.gradio.live

现在，世界各地的任何人都可以通过浏览器试用你的 Gradio 演示，而机器学习模型和所有计算仍将继续在你电脑本地运行。

如需了解更多关于分享演示的信息，请阅读我们的专属指南——分享你的 Gradio 应用。

Gradio 概述

到目前为止，我们一直在探讨 Interface 类——这是一个高级别类，能够帮助您快速使用 Gradio 构建各种演示应用。不过，Gradio 还有哪些其他功能呢？

使用 gr.Blocks 自定义演示应用

Gradio 提供了一种低级的开发方式，通过 gr.Blocks 类，您可以设计出布局更加灵活、数据流更富于变化的 Web 应用。Blocks 支持多种功能，例如：控制组件在页面中的显示位置、处理多条数据流以及实现更为复杂的交互（例如，输出可以作为其他函数的输入）、根据用户交互动态更新组件的属性或可见性——所有这一切都完全基于 Python 语言来实现。

借助 gr.Blocks()，您可以构建出高度定制化且功能强大的应用程序。以广受欢迎的图像生成工具 Automatic1111 Web UI 为例，其正是基于 Gradio 的 Blocks 功能打造而成。在后续的系列文章中，我们将深入探讨 gr.Blocks 的更多细节，重点介绍如何利用它来构建各类应用（详见 使用 Blocks 构建应用）。

使用 gr.ChatInterface 构建聊天机器人

Gradio 还提供了一个高级别的类——gr.ChatInterface，专为创建聊天机器人界面而设计。与 Interface 类类似，您只需提供一个函数，Gradio 就会自动为您搭建起一个功能完备的聊天机器人界面。如果您对创建聊天机器人感兴趣，可以直接跳转至我们的专属指南——使用 gr.ChatInterface 创建聊天机器人。

Gradio 的 Python 与 JavaScript 生态系统

以上便是 Gradio 核心 Python 库的核心内容，但 Gradio 其实远不止于此！它是一个完整的 Python 和 JavaScript 库生态系统，让您能够使用 Python 或 JavaScript 构建机器学习应用，或者以编程方式对这些应用进行查询与操作。以下是 Gradio 生态系统的其他相关组成部分：

• Gradio Python 客户端（gradio_client）：通过 Python 程序代码，以编程方式查询任意 Gradio 应用。
• Gradio JavaScript 客户端（@gradio/client）：通过 JavaScript 程序代码，以编程方式查询任意 Gradio 应用。
• Hugging Face Spaces：Gradio 应用最热门的托管平台——免费使用！
• 服务器模式（gradio.Server）：借助 Gradio 的后端，构建自定义前端——支持队列、流式处理、MCP、ZeroGPU 以及 Spaces 托管服务。

接下来该做什么？

请持续按顺序学习 Gradio 相关知识，通过 Gradio 指南，您将获得详尽的讲解、示例代码以及嵌入式的交互式演示。接下来，我们将深入探讨 Interface 类的相关内容（详见 Interface 类详解）。

或者，如果您已经掌握了基本知识，并且正寻找特定的功能，也可以查阅更详细的 技术 API 文档。

AI 编程技能

Gradio 提供了一项“技能”，可为 AI 编程助手（如 Cursor、Claude Code、Codex 等）注入 Gradio 特有的知识，从而帮助它们更高效地构建 Gradio 应用。尤其是在创建自定义 Gradio 组件或进行样式设计时，这项技能尤为实用。只需一条命令，即可为您的编程助手安装 Gradio 技能：

gradio skills add --cursor   # 或者 --claude, --codex, --opencode

使用 --global 命令，可将其安装于用户级别（适用于所有项目）。您的技能将自动为特定的编程代理所用。

您还可以为某个 特定的 Gradio Space 安装技能，该技能可自动生成 API 使用文档（包括 Python、JS、cURL 等格式）：

gradio skills add abidlabs/en2fr --cursor

有问题吗？

如果您想报告错误或提出功能建议，请前往 GitHub 上提交问题（GitHub 问题表单）。如需了解有关使用 Gradio 的通用问题，欢迎随时访问我们的 Discord 服务器（Discord 服务器链接），我们非常乐意为您提供帮助。

如果您喜欢 Gradio，也请在 GitHub 上为我们留下一个 ⭐！

开源生态

Gradio 依托众多优秀的开源库而构建！

许可证

Gradio 采用 Apache License 2.0 许可协议，该协议位于本仓库根目录下的 LICENSE 文件中。

引用文献

此外，还请参阅论文 Gradio: 在真实世界中轻松分享与测试 ML 模型, ICML HILL 2019，并在您的工作中使用 Gradio 时，务必予以引用。

@article{abid2019gradio,
  title = {Gradio: 在真实世界中轻松分享与测试 ML 模型},
  author = {Abid, Abubakar and Abdalla, Ali and Abid, Ali and Khan, Dawood and Alfozan, Abdulrahman and Zou, James},
  journal = {arXiv preprint arXiv:1906.02569},
  year = {2019},
}

Gradio 快速上手指南

Gradio 是一个开源 Python 库，让你只需几行代码即可为机器学习模型、API 或任意 Python 函数构建演示界面或 Web 应用，并轻松分享链接。无需掌握 JavaScript、CSS 或 Web 托管知识。

环境准备

• 操作系统：Windows、macOS 或 Linux
• Python 版本：3.10 或更高（下载地址）
• 推荐：在虚拟环境中安装以避免依赖冲突

安装步骤

使用 pip 安装（推荐使用国内镜像源加速）：

pip install --upgrade gradio -i https://pypi.tuna.tsinghua.edu.cn/simple

💡 提示：建议先在虚拟环境中安装。详细安装指南请参考 官方文档。

基本使用

创建第一个 Demo

在任意 Python 环境（如脚本文件、Jupyter Notebook、Google Colab）中运行以下代码：

import gradio as gr

def greet(name, intensity):
    return "Hello, " + name + "!" * int(intensity)

demo = gr.Interface(
    fn=greet,
    inputs=["text", "slider"],
    outputs=["text"],
    api_name="predict"
)

demo.launch()

保存为 app.py 后，在终端运行：

python app.py

应用将在浏览器中打开，地址为：http://localhost:7860

💡 开发提示：使用 gradio app.py 替代 python app.py 可启用热重载模式，修改代码后自动刷新页面。还可添加 --vibe 参数启用自然语言编程辅助功能。

核心概念说明

gr.Interface 是构建演示的核心类，包含三个关键参数：

• fn：要包装的 Python 函数
• inputs：输入组件列表（需与函数参数数量和顺序一致）
• outputs：输出组件列表（需与函数返回值数量一致）

Gradio 提供 30+ 内置组件，如 gr.Textbox()、gr.Image()、gr.HTML() 等，可直接用于构建 ML 应用界面。

分享你的 Demo

添加 share=True 参数即可生成公网可访问链接：

demo.launch(share=True)

运行后将获得类似 https://xxx.gradio.live 的链接，全球用户均可通过浏览器访问，而计算仍在本地执行。

---

下一步可探索更强大的 gr.Blocks 自定义布局、gr.ChatInterface 聊天机器人构建，或使用 Gradio 客户端进行程序化调用。完整指南请访问 Gradio 官方文档。