1. 前言

1.1 课程回顾

前面几次课中，我们已经完成了大模型应用开发的基础准备。首先，我们学习了，了解了如何使用 VSCode、Miniconda、Python 环境以及相关依赖包，为后续的大模型应用开发搭建基础环境。随后，我们进一步学习了，理解了 API Key、base_url、model、messages 等核心参数在一次大模型调用中的作用。之后，我们又学，掌握了如何通过角色设定、任务描述、输出格式约束等方式，引导大模型生成更符合需求的回答。

经过前面这些学习，我们已经能够让 Python 程序和大模型完成一次基本交互。也就是说，用户提出问题，程序将问题整理成接口需要的格式并发送给大模型；大模型生成回答后，再由程序接收并输出结果。从技术链路上看，我们已经具备了调用大模型能力的基础。

但是，从真实应用开发的角度来看，仅仅能够在代码或终端中调用模型还不够。因为普通用户通常不会打开 Python 文件，也不会在终端中输入命令，更不会主动修改代码中的参数。他们更习惯的是打开一个页面，在输入框中输入问题，点击按钮，然后直接查看结果。

因此，一个真正可用的大模型应用，往往不能只停留在“代码能跑”的阶段，还需要提供清晰、直观、易操作的交互界面。用户可以通过页面输入文字、上传图片、上传语音或上传文件，程序则在后台接收这些输入，调用相应的大模型能力，并将处理结果返回到页面中展示。这样，大模型能力才能从开发者手中的代码脚本，进一步转化为普通用户也能直接使用的应用工具。

从本节课开始，我们将进入 Gradio 页面开发 部分。Gradio 可以帮助我们用较少的 Python 代码，把一个普通的 Python 函数快速包装成网页应用。本节课将先从最基础的 Interface 开始，重点理解“输入组件、处理函数、输出组件”这条主线，并在此基础上结合百炼大模型平台，构建能够调用文本模型、视觉理解模型和全模态模型的交互式大模型应用。

需要注意，Gradio 非常适合教学演示、原型验证和内部工具开发，但如果要构建复杂的生产级系统，还需要进一步考虑用户登录、权限控制、数据库、任务队列、日志监控、异常处理和前后端工程化等问题。

1.2 Gradio 简介

在正式学习 Gradio 的具体用法之前，我们需要先理解一个基础问题：一个大模型应用通常由哪些部分组成？

一个完整的大模型应用，通常并不只是一次模型调用，而是由前端页面、后端处理逻辑、API 调用和模型服务等部分共同组成。理解这些组成部分，有助于我们更清楚地认识 Gradio 在大模型应用开发中的作用。

首先是前端页面。前端页面是用户能够看到和操作的部分。例如，一个大模型应用中的输入框、按钮、图片上传区域、语音上传区域、文件上传区域和结果展示区域，都属于前端页面的一部分。对于用户来说，他们首先接触到的不是程序内部的模型调用逻辑，而是页面是否清晰、操作是否方便、结果是否能够正常显示。

其次是后端处理逻辑。后端是页面背后真正执行任务的程序。比如，当用户在页面中输入问题并点击提交按钮后，后端程序需要接收这个问题，将其整理成大模型 API 所需的格式，然后发送给模型平台。模型返回结果后，后端程序还需要提取结果，并交给页面进行展示。在完整的 Web 应用中，后端可以由 Flask、FastAPI、Spring Boot 等框架实现；而在本节 Gradio 入门案例中，我们会先把后端处理逻辑简化为一个 Python 函数。

再次是 API 调用。API 可以理解为程序之间进行通信的接口。在大模型应用中，本地程序通常不会直接进入模型内部，而是通过模型平台提供的 API，把用户输入发送给模型服务，再接收模型返回的结果。例如，当我们调用百炼平台上的文本模型、视觉理解模型或全模态模型时，本质上就是通过 API 向模型服务发送请求，并获取模型生成的响应。

最后是模型服务。模型服务是真正完成智能处理的部分。文本大模型可以根据用户问题生成回答，视觉理解模型可以结合图片和文字进行分析，全模态模型则可以进一步处理文字、图片、音频、视频等多种类型的数据。也就是说，模型服务负责真正的推理与生成，而页面和后端程序负责把用户输入传递给模型，并把模型结果展示出来。

因此，一个典型的大模型应用可以理解为这样一条链路：

如果按照传统 Web 开发方式来实现这个过程，开发者通常需要分别编写前端页面和后端接口。前端可能需要使用 HTML、CSS、JavaScript，或者 Vue、React 等框架；后端可能需要使用 Flask、FastAPI、Spring Boot 等框架。对于初学者来说，这样的开发成本相对较高，也容易把注意力分散到复杂的前后端工程细节中。

而 Gradio 的价值就在于，它简化了这个过程。Gradio 可以帮助我们用较少的 Python 代码，快速生成一个可交互的网页页面，并自动把页面上的输入组件和后端 Python 函数连接起来。也就是说，我们不需要一开始就学习复杂的前端开发技术，也可以快速做出一个能够输入文字、上传图片、上传语音，并调用大模型 API 的应用页面。

在 Gradio 应用中，前端页面通常由各种组件构成。例如，Textbox 可以用来输入文字，Image 可以用来上传图片，Audio 可以用来上传语音，File 可以用来上传文件，Button 可以用来触发操作，输出区域则可以用来展示模型返回的结果。后端逻辑则由 Python 函数负责完成，这个函数可以接收 Gradio 页面传入的数据，并在函数内部调用大模型 API。

因此，可以把 Gradio 理解为连接“用户页面”和“Python 后端函数”的桥梁。它本身并不是大模型，也不是模型平台，而是一个轻量级的交互式应用开发工具。真正完成文本生成、图像理解、语音识别等任务的，仍然是后端函数调用的模型服务。

2. gr.Interface() 页面构建基础

2.1 环境准备

在使用 Gradio 构建页面之前，需要先完成开发环境的准备工作。大家可以参考第一节课中关于 VSCode、Miniconda 和 Python 环境配置的内容，确保本地已经具备基本的 Python 开发条件。

为了避免不同课程或项目之间的依赖包相互影响，建议单独创建一个用于大模型应用开发的 Conda 环境。例如，可以新建一个名为 llm_development 的环境，并指定 Python 版本为 3.12：

conda create -n llm_development python=3.12 -y
conda activate llm_development

环境创建并激活后，后续安装的依赖包都会被放在这个独立环境中，便于管理和维护。接下来，我们需要安装本节课用到的核心依赖包，主要包括 Gradio 和 DashScope 以及前面提到的 openai：

pip install gradio dashscope openai

其中，gradio 用于快速构建交互式网页页面，dashscope 用于调用阿里云百炼平台提供的大模型服务。安装完成后，就可以开始后续的 Gradio 页面构建与大模型 API 调用实验。

2.2 Gradio 页面构建方式

安装完成 Gradio 后，接下来我们就可以开始学习如何使用 Gradio 构建交互式页面。Gradio 提供了多种页面构建方式，常见的主要包括 Interface、ChatInterface、TabbedInterface 和 Blocks。

其中，Interface 是最基础、最常用、也最适合初学者入门的一种页面构建方式。它主要用于把一个 Python 函数快速包装成网页应用。开发者只需要指定处理函数、输入组件和输出组件，就可以快速生成一个可交互的页面。

ChatInterface 更适合构建聊天类应用，例如智能客服、AI 助手、多轮对话机器人等。它在界面形式上更接近常见的聊天窗口，能够更方便地展示用户和模型之间的一问一答过程。

TabbedInterface 主要用于将多个 Gradio Interface 页面整合到同一个应用中，并通过标签页的方式进行切换。例如，一个应用中既包含文本问答功能，又包含图片理解功能，还包含语音识别功能，就可以使用标签页将它们组织在一起。

Blocks 则是 Gradio 中更加灵活、功能更强的页面构建方式。相比 Interface，Blocks 可以自定义页面布局、控制组件之间的交互关系，并支持更复杂的事件绑定。因此，当页面结构比较复杂、组件较多、交互逻辑较强时，通常会使用 Blocks。

本节课我们先重点学习比较通用、简单且易上手的 Interface。通过它，大家可以先掌握 Gradio 页面构建的基本思想：输入组件负责接收用户数据，Python 函数负责处理数据，输出组件负责展示处理结果。

2.3 Interface 基本写法

gr.Interface() 的实现方式非常简洁。它的核心思想是：将一个 Python 函数与页面输入、页面输出绑定起来。用户在页面中输入内容后，Gradio 会自动把输入内容传递给指定的 Python 函数，函数处理完成后，再将返回结果显示到页面上。

下面先来看一个最简单的示例：

import gradio as gr

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

demo = gr.Interface(
    fn=greet,
    inputs=gr.Textbox(),
    outputs=gr.Textbox()
)

if __name__ == "__main__":
    demo.launch()

在这段代码中，首先通过 import gradio as gr 导入 Gradio 库。随后定义了一个 greet() 函数，它接收一个 name 参数，并返回一段问候语，也就是说输入和输出都是文本字符串（str）。

接着，使用 gr.Interface() 创建页面。其中，fn=greet 表示页面提交后要调用的 Python 函数；inputs=gr.Textbox() 表示页面输入区域是一个文本框；outputs=gr.Textbox() 表示函数返回结果会显示在一个文本框中。

最后，通过 demo.launch() 启动 Gradio 应用。程序运行后，Gradio 会生成一个本地访问地址，用户在浏览器中打开该地址，就可以看到一个简单的网页页面。在页面中输入姓名并点击提交按钮后，后端的 greet() 函数就会被执行，返回的问候语也会展示在输出区域中。

比如此时我们在左边的文本框中输入 ljf 并点击 Submit 按钮，此时右边文本框返回的结果为：

除了 fn、inputs 和 outputs 这三个核心参数外，gr.Interface() 还可以设置一些常用参数，用来完善整个页面的显示效果。例如，可以通过 title 设置页面标题，通过 description 设置页面说明文字，通过 examples 提供示例输入，方便用户快速体验页面功能。

例如，可以在前面代码的基础上进一步完善页面信息：

import gradio as gr

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

demo = gr.Interface(
    fn=greet,
    inputs=gr.Textbox(),
    outputs=gr.Textbox(),
    title="简单问候页面",
    description="在输入框中输入姓名，点击提交后，页面会返回一句问候语。",
    examples=[
        ["张三"],
        ["李四"],
    ]
)

demo.launch()

此时的页面展示如下：

在这段代码中，fn、inputs 和 outputs 仍然是最核心的三个参数。其中，fn=greet 表示页面提交后要调用 greet() 函数；inputs=gr.Textbox() 表示页面使用文本框接收用户输入；outputs=gr.Textbox() 表示函数返回结果会显示在文本框中。

而 title、description 和 examples 主要用于完善页面展示效果。title 会显示为页面标题，description 会显示为页面说明，examples 会在页面下方提供示例内容。用户可以直接点击示例内容进行测试，不需要每次都手动输入。

因此，初学阶段可以先把 gr.Interface() 的常用参数分成两类理解：

简单来说，fn、inputs 和 outputs 决定这个页面“如何运行”，而 title、description 和 examples 则让这个页面“更容易看懂和使用”。对于初学者来说，先掌握这几个常用参数，就已经可以完成大多数简单 Gradio 页面构建。

2.4 Interface 工作机制

在前面我们已经知道，gr.Interface() 的核心作用，就是把一个 Python 函数快速包装成一个可交互的网页应用。不过，如果只看代码，初学者往往只能看到 fn、inputs 和 outputs 这些参数，却不太容易真正理解：页面中的输入内容是如何传给 Python 函数的？函数的返回结果又是如何显示到页面上的？

为了解释这个过程，可以结合下图来理解 Gradio Interface 的基本工作机制。

从图中可以看到，Gradio Interface 的整体流程可以分为几个连续的环节。

首先是 Input Components（输入组件）。这部分对应页面中用户能够直接操作的输入区域，例如 Textbox、Number、Image 等。用户在页面中输入文本、数字，或者上传图片，本质上都是先交给这些输入组件来接收。

接着，Gradio 会对这些输入内容进行一次 pre-processing（预处理）。所谓预处理，就是把页面组件接收到的数据，自动转换成 Python 函数能够直接处理的参数类型。例如，文本框中的内容可能会被转换成字符串 str，数字输入框中的内容可能会被转换成整数 int 或浮点数 float，图片组件中的内容则可能会被转换成 numpy.array 等数据形式。这样一来，开发者在编写 Python 函数时，就不需要自己手动解析页面输入数据，Gradio 会提前帮我们做好这一步。

预处理完成后，这些数据会作为 Parameters（参数） 传递给我们定义的 Python 函数，也就是图中的 Your Function。这也是 Interface 最核心的地方：页面输入最终会变成函数参数，函数执行逻辑决定了页面应用到底完成什么任务。

当函数执行完成后，会得到相应的 Return Value(s)（返回值）。这些返回值可能是一个文本结果、一个数字结果，也可能是一个列表、一张图片，或者其他 Python 数据类型。

不过，函数返回的这些数据还不能直接原样显示在页面上，因此 Gradio 还会再执行一次 post-processing（后处理）。所谓后处理，就是把 Python 函数返回的数据，转换成适合页面展示的格式。例如，返回的数字可以显示到 Number 组件中，返回的图片列表可以显示到 Gallery 组件中，返回的文本可以显示到 Textbox 中。

最后，这些处理完成的结果会被交给 Output Components（输出组件），并展示在页面上。至此，就完成了一次完整的交互流程。因此，gr.Interface() 的本质可以概括为这样一条链路：

用户输入
→ 输入组件接收数据
→ Gradio 预处理
→ 传递给 Python 函数
→ 函数返回结果
→ Gradio 后处理
→ 输出组件展示结果

从这个角度来看，Interface 的核心并不只是“生成一个页面”，更重要的是自动完成页面组件与 Python 函数之间的数据连接和类型转换。这也是 Gradio 非常适合初学者入门的重要原因：开发者不需要一开始就编写复杂的前后端交互逻辑，只需要关注两个关键问题：函数需要接收什么输入，函数最终返回什么结果。

只要输入组件提供的数据格式能够满足函数参数的要求，函数返回值的格式也能够被输出组件正确展示，我们就可以快速搭建出一个可交互的网页页面。后续无论是普通文本处理、图片识别，还是调用大模型 API，本质上都是在这个流程基础上更换或扩展 Python 函数内部的处理逻辑。

2.5 常见组件简介

理解了 Interface 的工作机制后，接下来就需要进一步认识 Gradio 中的 组件。简单来说，组件就是页面上的功能控件。用户看到的文本框、图片上传区域、文件上传区域、视频上传区域、音频录制区域等，都可以理解为 Gradio 组件。

在 gr.Interface() 中，组件通常会出现在 inputs 和 outputs 这两个位置。需要注意的是，组件本身并不固定区分为“只能输入”或“只能输出”。同一个组件放在 inputs 中，就用于接收用户输入；放在 outputs 中，就用于展示函数返回结果。

例如，gr.Textbox() 放在 inputs 中，可以让用户输入文字；放在 outputs 中，则可以用来展示函数返回的文字结果。gr.Image() 也是类似的，既可以用于接收用户上传的图片，也可以用于展示处理后的图片。

除了前面提到的组件外，Gradio 里提供了大量的组件帮助我们构建应用，不过在初学阶段不需要记住所有组件，先了解几个常见组件即可：

这里的数据类型只需要先了解常见情况即可。部分组件可以通过参数调整数据格式，例如 gr.Image() 可以通过 type 参数设置传入函数的是图片路径、PIL 图片对象，还是 NumPy 数组；gr.Audio() 也可以根据参数设置返回音频路径或音频数组。对于初学者来说，先掌握一个基本对应关系即可：文本通常对应 str，图片、音频、视频和文件通常对应路径或对象。

除了决定页面上显示什么控件之外，组件还可以通过参数调整显示效果和交互方式。以 Textbox 为例：

gr.Textbox(
    label="请输入问题",
    placeholder="例如：请介绍一下 Gradio 的作用",
    lines=3,
    value=""
)

其中，label 用来设置组件标题，placeholder 用来设置输入提示，lines 用来设置文本框显示行数，value 用来设置默认内容。其他组件也有类似参数，例如图片、音频、视频和文件组件通常可以设置标题、默认值、是否可交互等；一些选择类组件还可以通过 choices 设置可选项。

设置完成后，页面中的文本框会显示对应标题、提示语和默认内容。

简单来说，学习 Gradio 组件时，先记住一个核心思路即可：组件就是页面控件，它决定用户通过什么形式提交数据，也决定函数返回结果以什么形式展示。 后续无论是文本问答、图片理解、文件分析，还是语音识别，本质上都是根据任务需要选择合适的组件，并把组件和 Python 函数连接起来。

下节课，我们将正式结合大模型 API，来实现实际应用场景的讲解。