【Gradio】The Interface class 界面类

如 Quickstart 中所提到的， gr.Interface 类是 Gradio （4.36.1）中的一个高级抽象，它允许您通过指定输入类型和输出类型快速创建任何 Python 函数的演示。重新查看我们的第一个演示：

import gradio as gr


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


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


demo.launch()

我们看到 Interface 类是使用三个必需参数初始化的：

• fn ：用于围绕用户界面（UI）的函数

• inputs ：用于输入的 Gradio 组件。组件的数量应与函数中的参数数量相匹配。

• outputs ：用于输出的 Gradio 组件。组件的数量应与函数的返回值数量相匹配。

在本指南中，我们将深入探讨 gr.Interface 以及它可以定制的各种方式，但在此之前，让我们先更好地了解 Gradio 组件。

 Gradio 组件 

Gradio 包含 30 多个预构建组件（以及许多社区构建的自定义组件），这些组件可以在您的演示中用作输入或输出。这些组件对应于机器学习和数据科学中的常见数据类型，例如 gr.Image 组件旨在处理输入或输出图像， gr.Label 组件显示分类标签和概率， gr.Plot 组件显示各种类型的图表等等。

静态和交互式组件

每个组件都有一个静态版本，用于显示数据，大多数组件还有一个交互版本，允许用户输入或修改数据。通常，您不需要考虑这种区别，因为当您构建 Gradio 演示时，Gradio 会自动根据组件是用作输入还是输出来判断该组件应该是静态的还是交互的。但是，您可以使用每个组件都支持的 interactive 参数手动设置这一点。

预处理和后处理

当组件被用作输入时，Gradio 会自动处理所需的预处理，将数据从用户浏览器发送的类型（如上传的图像）转换为您的函数可以接受的形式（如 numpy 数组）。

同样，当一个组件被用作输出时，Gradio 会自动处理所需的后处理工作，将函数返回的数据（例如图片路径列表）转换为用户浏览器中可以显示的形式（一个图片库）。

组件属性 

我们使用了 gr.Textbox 和 gr.Slider 的默认版本，但如果您想更改 UI 组件的外观或行为呢？

假设您想自定义滑块，使其值从 1 到 10，默认值为 2。并且您想自定义输出文本字段——您希望它更大并且有标签。

如果您使用 gr.Textbox 和 gr.Slider 的实际类而不是字符串快捷方式，您可以通过组件属性访问更多的自定义选项。

import gradio as gr  # 导入gradio库


# 定义greet函数，接受名字(name)和强度(intensity)作为输入
def greet(name, intensity):
    return "Hello, " + name + "!" * intensity  # 返回与强度相符的问候次数


# 创建Gradio界面
demo = gr.Interface(
    fn=greet,  # 设置greet函数为界面的处理函数
    inputs=[  # 定义输入组件
        "text",  # 第一个输入组件是文本输入，用于输入名字
        gr.Slider(value=2, minimum=1, maximum=10, step=1)  # 第二个输入组件是滑块，用于选择问候的强度
    ],
    outputs=[  # 定义输出组件
        gr.Textbox(label="greeting", lines=3)  # 输出组件是文本框，标签为"greeting"，显示三行内容
    ],
)


demo.launch()  # 启动界面

此段代码构建了一个简单的Gradio界面，用来生成针对输入名字的问候语，并可以通过滑块调整问候语的重复次数。

用户有两个输入选项：一个文本输入用于输入名字，一个滑块用于控制问候语重复的强度，滑块的默认值为2，范围从1到10，步长为1。输出是一个附带"label"为"greeting"的文本框，文本框可显示多达三行文本。当用户输入名字和选择问候语强度后，界面会调用greet函数并在输出文本框中显示生成的问候语。

启动界面后，用户可以交互式地通过Web界面输入数据并接收到响应。

多个输入和输出组件 

假设您有一个更复杂的函数，也有多个输出。在下面的示例中，我们定义了一个函数，它接受一个字符串、一个布尔值和一个数字，并返回一个字符串和一个数字。

import gradio as gr  # 导入gradio库


# 定义问候函数greet，它接收三个参数：名字(name)，是否为早上(is_morning)和温度(temperature)
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)  # 返回问候语句子和转换后的摄氏温度，保留两位小数


# 创建Gradio界面的配置
demo = gr.Interface(
    fn=greet,  # 指定greet函数为界面的处理函数
    inputs=[  # 定义输入控件
        "text",  # 文本输入控件，用于用户输入名字
        "checkbox",  # 复选框控件，用于用户选择是否为早上
        gr.Slider(0, 100)  # 滑块控件，用于用户输入温度值，范围从0到100
    ],
    outputs=[  # 定义输出控件
        "text",  # 文本输出控件，用于显示问候语句子
        "number"  # 数字输出控件，用于显示摄氏温度
    ],
)
demo.launch()  # 启动Gradio界面

此代码创建了一个Gradio界面，它会根据用户提供的名称、时间（是否早上）以及温度（用华氏度表示）来生成一个问候语。该问候语会提及当前的温度，并且后面附加一个转换得到的摄氏度温度值。

用户的输入包括：

• 一个文本框，用于输入名称。

• 一个复选框，用户可以勾选以指示当前是否为早上。

• 一个滑块，用户可以滑动选择范围在0到100之间的温度值。

输出包括：

• 一个文本显示，会根据输入生成问候语。

• 一个数字显示，会展示转换成摄氏度的温度值。

在用户输入数据并触发函数后，问候语和摄氏温度会呈现在界面的输出部分。调用launch方法会启动界面，使用户可以通过Web浏览器与之交互。

正如 inputs 列表中的每个组件按顺序对应函数的一个参数， outputs 列表中的每个组件也按顺序对应函数返回的一个值。

 图像示例

Gradio 支持许多类型的组件，例如 Image 、 DataFrame 、 Video 或 Label 。让我们尝试一个图像到图像的功能来感受一下这些！

import numpy as np  # 导入numpy库，用于数值计算
import gradio as gr  # 导入gradio库，用于创建GUI界面


# 定义sepia函数，它接收一个图像作为输入，并将其转换为棕褐色风格
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)
    # 将转换后的图像归一化，使其值位于0到1之间
    sepia_img /= sepia_img.max()
    # 返回棕褐色风格的图像
    return sepia_img


# 创建Gradio界面的配置
demo = gr.Interface(
    sepia,          # 指定sepia函数为界面的处理函数
    gr.Image(),     # 输入控件是一个图像上传控件
    "image"         # 输出控件是一个图像展示控件
)
demo.launch()  # 启动Gradio界面

当使用 Image 组件作为输入时，您的函数将接收一个形状为 (height, width, 3) 的 NumPy 数组，其中最后一个维度代表 RGB 值。我们也会以 NumPy 数组的形式返回一张图片。

如上所述，Gradio 处理预处理和后处理，以将图像转换为 NumPy 数组，反之亦然。您还可以使用 type= 关键字参数控制执行的预处理。例如，如果您希望您的函数接受图像的文件路径而不是 NumPy 数组，输入 Image 组件可以写为：

gr.Image(type="filepath", shape=...)

您可以在 Gradio 文档中了解更多关于内置 Gradio 组件以及如何自定义它们的信息。

示例输入

您可以提供用户可以轻松加载到 Interface 中的示例数据。这有助于演示模型期望的输入类型，以及提供一种方法与您的模型一起探索您的数据集。要加载示例数据，您可以向接口构造函数的 examples= 关键字参数提供一个嵌套列表。外部列表中的每个子列表代表一个数据样本，子列表中的每个元素代表每个输入组件的一个输入。每个组件的示例数据格式在文档中有说明。

import gradio as gr  # 导入gradio库


# 定义计算器函数，接收两个数字（num1和num2）和一个运算符
def calculator(num1, operation, num2):
    if operation == "add":  # 如果运算符是加法
        return num1 + num2  # 返回加法结果
    elif operation == "subtract":  # 如果运算符是减法
        return num1 - num2  # 返回减法结果
    elif operation == "multiply":  # 如果运算符是乘法
        return num1 * num2  # 返回乘法结果
    elif operation == "divide":  # 如果运算符是除法
        if num2 == 0:  # 如果除数为0
            raise gr.Error("Cannot divide by zero!")  # 抛出错误，不能除以0
        return num1 / num2  # 返回除法结果


# 创建Gradio界面的配置
demo = gr.Interface(
    calculator,  # 指定calculator函数为界面处理函数
    [
        "number",  # 第一个输入控件是数字输入，用于输入第一个数
        gr.Radio(["add", "subtract", "multiply", "divide"]),  # 第二个输入控件是单选按钮，用于选择运算符
        "number"  # 第三个输入控件是数字输入，用于输入第二个数
    ],
    "number",  # 输出控件是数字，显示计算结果
    examples=[  # 提供样例输入
        [45, "add", 3],
        [3.14, "divide", 2],
        [144, "multiply", 2.5],
        [0, "subtract", 1.2],
    ],
    title="Toy Calculator",  # 设置界面标题
    description="Here's a sample toy calculator. Allows you to calculate things like $2+2=4$",  # 设置界面描述
)


demo.launch()  # 启动Gradio界面

您可以将大型数据集加载到示例中，通过 Gradio 浏览和与数据集交互。示例将自动进行分页（您可以通过 Interface 的 examples_per_page 参数来配置此项）。

继续学习《更多示例》指南中的示例。https://www.gradio.app/guides/more-on-examples

描述性内容 

在前面的示例中，您可能已经注意到在 Interface 构造函数中有 title= 和 description= 关键字参数，这有助于用户理解您的应用程序。

构造函数 Interface 中有三个参数，用于指定内容应放置的位置：

• title ：它接受文本，并可以将其显示在界面的最顶部，同时也成为页面标题。

• description ：它接受文本、Markdown 或 HTML，并将其直接放在标题下方。

• article ：它还接受文本、Markdown 或 HTML，并将其放置在界面下方。

注意：如果您使用 Blocks 类，可以使用 gr.Markdown(...) 或 gr.HTML(...) 组件在应用程序中的任何位置插入文本、markdown 或 HTML。

另一个有用的关键字参数是 label= ，它存在于每个 Component 中。这会修改每个 Component 顶部的标签文本。您还可以向表单元素如 Textbox 或 Radio 添加 info= 关键字参数，以提供有关其使用方式的更多信息。

gr.Number(label='Age', info='In years, must be greater than 0')

附加输入在手风琴Accordion 内 Additional Inputs within an Accordion

如果您的预测功能需要许多输入，您可能希望将其中一些隐藏在折叠手风琴中，以避免界面杂乱。 Interface 类接受一个 additional_inputs 参数，该参数与 inputs 类似，但此处包含的任何输入组件默认情况下都不可见。用户必须点击手风琴才能显示这些组件。额外的输入将按顺序在标准输入之后传递给预测功能。

您可以通过使用可选的 additional_inputs_accordion 参数来自定义手风琴的外观，该参数接受一个字符串（在这种情况下，它成为手风琴的标签），或者 gr.Accordion() 类的一个实例（例如，这允许您控制手风琴默认是打开还是关闭的）。

这是一个例子： 

import gradio as gr  # 导入gradio库


# 定义一个函数，用于生成假的图像
# 这个函数模拟生成假图片的过程。它接受三个参数：prompt（提示词），seed（随机种子），以及可选的initial_image（初始图片）。函数执行后，返回一个字符串（表明使用的种子）和一个示例图片的URL。
def generate_fake_image(prompt, seed, initial_image=None):
    return f"Used seed: {seed}", "https://dummyimage.com/300/09f.png"  # 返回一段文本和假图像的URL


# 创建Gradio界面的配置
demo = gr.Interface(
    generate_fake_image,  # 指定generate_fake_image函数为界面处理函数
    inputs=[
        "textbox",  # 第一个输入控件是文本框
    ],
    outputs=[
        "textbox",  # 第一个输出控件是文本框，用于显示使用的种子值
        "image"  # 第二个输出是图像控件，用于显示生成的假图像
    ],
    additional_inputs=[
        gr.Slider(0, 1000),  # 第二个输入是滑块，用来输入种子值seed，范围0到1000
        "image"  # 第三个输入是图像上传控件，可用作初始图像
    ]
)


demo.launch()  # 启动Gradio界面

创建Gradio接口：

通过调用gr.Interface，创建了一个Gradio接口实例命名为demo。此接口配置了以下几点：

• 函数：generate_fake_image是此接口展示的函数。

• 输入：定义了一个文本框"textbox"输入。

• 输出：定义了文本框和图片两种输出。

• 额外输入：通过additional_inputs参数添加了额外的输入，包括一个从0到1000的滑动条以及一个图片上传字段。