Gradio 是 HuggingFace 出品的轻量级 Python 可视化库，核心优势是：一行代码就能把 Python 函数/模型，快速封装成带网页交互的可视化应用，无需前端知识、无需部署复杂框架，本地运行即可访问，对机器学习/深度学习模型演示、算法可视化、快速做 DEMO 极其友好。
✅ 核心特点：极简语法、实时预览、支持所有 Python 函数、一键分享、可部署，是Python开发者做「可视化交互界面」的首选工具，没有之一！
一、基础准备：安装 Gradio + 环境兼容说明
✅ 1. Gradio 安装命令（conda/venv 通用，推荐2种方式）
无论你用 conda 虚拟环境还是 venv 虚拟环境，安装命令完全一致，先激活你的环境，再执行安装，二选一即可：
1
2
3
4
5
| # 方式1：pip 安装（推荐，速度快，完整版，包含所有功能）
pip install gradio -i https://pypi.tuna.tsinghua.edu.cn/simple
# 方式2：conda 安装（conda环境用户首选，兼容性更好）
conda install -c conda-forge gradio
|
✅ 版本检查（验证安装成功）：
1
2
| import gradio as gr
print(gr.__version__) # 输出版本号即安装成功，当前最新稳定版4.x
|
✅ 2. 环境兼容说明（重要）
- Gradio 完全兼容 Python3.8+，所有 conda/venv 虚拟环境通用；
- 和 HuggingFace 的
transformers/datasets 无缝衔接，完美解决你之前的 HF 模型可视化需求； - 无系统限制：Windows/Mac/Linux 均可正常运行，无额外依赖。
二、Gradio 核心核心概念（必懂，一通百通）
Gradio 所有的界面构建，都基于 3个核心概念，记住这3个概念，所有用法都能举一反三，不用死记语法：
✅ 1. 核心执行逻辑
Gradio 应用 = Python函数 + 输入组件 + 输出组件
- Python函数：你的业务逻辑（比如文本处理、模型推理、数据计算、图片生成等），是应用的核心；
- 输入组件(Input Component)：网页上的交互控件，用于接收用户输入，比如「文本框、输入框、上传图片、下拉选择框」等；
- 输出组件(Output Component)：网页上的展示控件，用于显示函数运行的结果，比如「文本框、图片展示区、表格、音频播放器」等。
✅ 2. 两种核心开发模式（重中之重，所有教程的基础）
Gradio 有 两种开发范式，对应不同的开发场景，99%的需求都基于这两种模式，新手建议先学「快速模式」，再学「进阶模式」，循序渐进。
✔️ 模式一：快速模式 gr.Interface() （推荐新手，90%场景够用）
别称：接口模式/简洁模式
- 语法：
gr.Interface(fn=你的函数, inputs=输入组件, outputs=输出组件) - 核心特点：一行代码构建应用，语法极简，适合「单输入/单输出」「固定逻辑」的简单应用，比如：文本翻译、情感分析、图片分类、公式计算等。
- 优点：开发速度极快，无需布局，开箱即用；
- 缺点：页面布局固定，组件样式和位置无法自定义。
✔️ 模式二：进阶模式 gr.Blocks() （进阶必学，万能模式）
别称：块模式/自定义模式
- 语法：基于
with gr.Blocks() 代码块，自由添加组件、自定义布局； - 核心特点：完全自由的页面定制，支持「多输入多输出、组件嵌套、复杂交互、自定义样式、事件绑定」，可以做出任意你想要的网页界面，功能无上限。
- 优点：灵活性拉满，能构建复杂的工业级应用，支持所有高级功能；
- 缺点：语法比 Interface 稍复杂，但学习成本极低。
✅ 3. 通用启动命令（所有应用通用，固定写法）
无论你用哪种模式构建应用，最后都需要一行命令启动应用，固定语法，必写：
1
2
| # 核心启动命令
demo.launch()
|
启动命令的常用参数（高频必用，建议熟记）
1
2
3
4
5
6
7
| demo.launch(
server_name="0.0.0.0", # 允许局域网内其他设备访问你的应用（手机/另一台电脑）
server_port=7860, # 指定运行端口，默认7860，冲突时改比如7861
share=True, # 生成一个公网临时链接，可分享给任何人访问（有效期72小时）
inbrowser=True, # 启动后自动打开浏览器
debug=True # 开启调试模式，报错时显示详细信息
)
|
✅ 启动成功后，终端会显示：Running on local URL: http://localhost:7860，直接点击链接，浏览器会自动打开你的 Gradio 应用！
三、gr.Interface() 快速模式 完整教程
✅ 核心语法（固定模板，复制即用）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| import gradio as gr
# 步骤1：定义你的业务函数（核心逻辑，任意Python函数都可以）
def 自定义函数名(输入参数):
# 你的逻辑：处理输入、计算、模型推理等
return 输出结果
# 步骤2：创建Gradio界面，绑定函数+输入组件+输出组件
demo = gr.Interface(
fn = 自定义函数名, # 必填：绑定你的Python函数
inputs = 输入组件, # 必填：指定网页的输入控件
outputs = 输出组件, # 必填：指定网页的输出控件
title = "你的应用标题", # 可选：网页标题
description = "应用描述", # 可选：网页描述文本
examples = [["测试用例1"], ["测试用例2"]] # 可选：提供测试输入，用户一键点击
)
# 步骤3：启动应用
demo.launch()
|
✅ 基础组件速查表（输入+输出，高频必用）
Gradio 内置了几十种组件，输入组件和输出组件可以一一对应，以下是最常用的核心组件，满足90%的开发需求，直接复制使用：
| 组件类型 | 输入组件写法 | 输出组件写法 | 适用场景 |
|---|
| 文本框 | gr.Textbox() | gr.Textbox() | 文本输入/输出（翻译、摘要、问答） |
| 纯文本 | gr.Text() | gr.Text() | 简单文本，无输入框样式 |
| 数字输入 | gr.Number() | gr.Number() | 数值计算、参数调节 |
| 滑块 | gr.Slider(min=0, max=100) | gr.Number() | 连续数值调节（比如置信度阈值） |
| 下拉选择框 | gr.Dropdown(["选项1","选项2"]) | gr.Text() | 固定选项选择（比如模型选择） |
| 单选框 | gr.Radio(["选项1","选项2"]) | gr.Text() | 单选场景 |
| 图片上传 | gr.Image() | gr.Image() | 图片处理（分类、裁剪、生成） |
| 音频上传 | gr.Audio() | gr.Audio() | 语音识别、语音合成 |
| 表格 | gr.Dataframe() | gr.Dataframe() | 数据处理、表格展示 |
✅ 3个经典入门案例（复制运行即可，新手必练）
案例1：最简单的文本处理（文本翻转，入门首选）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| import gradio as gr
# 定义函数：输入文本，输出翻转后的文本
def reverse_text(text):
return text[::-1]
# 创建界面：文本输入 → 文本输出
demo = gr.Interface(
fn=reverse_text,
inputs=gr.Textbox(label="请输入文本", placeholder="在这里输入要翻转的文字"),
outputs=gr.Textbox(label="翻转后的文本"),
title="文本翻转工具",
description="输入任意文本，点击提交即可得到翻转后的结果"
)
demo.launch()
|
案例2：多输入+多输出（计算两数的加减乘除，必学）
重点：函数的入参数量 = inputs组件数量，函数的返回值数量 = outputs组件数量，一一对应即可！
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| import gradio as gr
# 多入参函数：2个数字输入，返回4个计算结果
def calculate(a, b):
return a + b, a - b, a * b, a / b if b != 0 else "除数不能为0"
# 多输入组件：2个数字框；多输出组件：4个文本框
demo = gr.Interface(
fn=calculate,
inputs=[gr.Number(label="数字A"), gr.Number(label="数字B")], # 列表形式放多组件
outputs=[gr.Text(label="加法"), gr.Text(label="减法"), gr.Text(label="乘法"), gr.Text(label="除法")],
title="简易计算器",
examples=[[10,5], [20,3], [0,10]] # 测试用例，用户一键点击
)
demo.launch()
|
案例3：结合HuggingFace模型（文本情感分析，实战高频）
完美衔接你之前的需求！Gradio + Transformers 是机器学习可视化的黄金组合，这是你最可能用到的场景
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| import gradio as gr
from transformers import pipeline
# 加载HuggingFace情感分析模型（自动下载，已配置镜像不会超时）
sentiment_analysis = pipeline("sentiment-analysis", model="uer/roberta-base-finetuned-dianping-chinese")
# 定义函数：输入文本，返回情感分析结果
def predict_sentiment(text):
result = sentiment_analysis(text)[0]
return f"情感标签：{result['label']}，置信度：{round(result['score'], 4)}"
# 创建界面
demo = gr.Interface(
fn=predict_sentiment,
inputs=gr.Textbox(label="请输入评价文本", placeholder="比如：这家店的服务太棒了！"),
outputs=gr.Textbox(label="情感分析结果"),
title="中文情感分析工具",
examples=[["这家餐厅味道一般，环境也不好"], ["电影超级好看，强烈推荐！"], ["物流太慢了，差评"]]
)
demo.launch(server_name="0.0.0.0")
|
四、gr.Blocks() 自定义模式
gr.Blocks() 是 Gradio 的核心灵魂，也是你必须掌握的进阶用法，所有复杂的 Gradio 应用都是基于 Blocks 构建的。
✅ 核心特点
- 完全自由的布局：可以自由排列组件的位置、分组、嵌套；
- 支持事件绑定：组件可以绑定点击、输入、变化等事件（比如「点击按钮执行函数」）；
- 多函数复用：一个界面可以绑定多个Python函数，实现复杂交互；
- 支持组件更新：可以动态修改组件的内容、样式、状态（比如点击按钮后显示结果）；
- 支持标签页、折叠面板：可以做更美观的复杂界面。
✅ 核心语法（固定模板，复制即用，重中之重）
Blocks 基于 Python 的 with 语法糖，缩进内的所有代码都属于这个界面，逻辑清晰，所有组件都需要手动定义，再绑定函数：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
| import gradio as gr
# 步骤1：定义你的业务函数（可以是多个）
def func1(input1):
return input1 * 2
def func2(input1, input2):
return input1 + input2
# 步骤2：创建Blocks自定义界面
with gr.Blocks(title="自定义应用") as demo:
# 步骤3：自由添加组件，自定义布局（组件可以定义变量名，方便后续绑定）
gr.Markdown("# 我的自定义Gradio应用") # 标题文本，支持markdown语法
with gr.Tab("功能1"): # 标签页1
input_box = gr.Textbox(label="输入框")
output_box = gr.Textbox(label="输出框")
btn1 = gr.Button("执行功能1") # 按钮组件
with gr.Tab("功能2"): # 标签页2
num1 = gr.Number(label="数字1")
num2 = gr.Number(label="数字2")
res_box = gr.Text(label="计算结果")
btn2 = gr.Button("执行功能2")
# 步骤4：事件绑定（核心）：组件.click(函数, 输入源, 输出目标)
btn1.click(fn=func1, inputs=input_box, outputs=output_box)
btn2.click(fn=func2, inputs=[num1, num2], outputs=res_box)
# 步骤5：启动应用
demo.launch(inbrowser=True)
|
✅ Blocks 核心知识点（必懂，所有进阶功能的基础）
1. 组件事件绑定（最核心）
Blocks 的核心是「事件驱动」，所有交互都是通过「组件触发事件 → 执行函数 → 更新输出」实现的，最常用的是 click 点击事件，还有其他高频事件：
1
2
3
4
| # 语法：组件.事件类型(fn=函数, inputs=输入组件, outputs=输出组件)
btn.click(fn=func, inputs=input_comp, outputs=output_comp) # 点击按钮触发（最常用）
input_box.change(fn=func, inputs=input_box, outputs=output_comp) # 输入框内容变化时触发
input_box.submit(fn=func, inputs=input_box, outputs=output_comp) # 输入框按回车时触发
|
2. 常用布局容器（让界面更美观，必用）
Blocks 提供了多种布局容器，用于对组件进行分组和排版，缩进即可实现嵌套，语法极简：
gr.Tab("标签名")：标签页，同一个界面可以分多个标签页，切换显示不同功能；gr.Row()：行容器，组件在同一行排列；gr.Column()：列容器，组件在同一列排列（默认布局）；gr.Accordion("折叠面板名")：折叠面板，点击展开/收起组件，适合放次要功能。
3. 组件值的动态更新（实战高频）
可以在函数中返回 gr.update() 对象，动态修改组件的内容、样式、状态，比如：点击按钮后修改文本框内容、隐藏/显示组件、修改按钮文字等。
1
2
3
4
5
6
7
8
| def update_text():
# 返回gr.update()，修改输出框的内容和占位符
return gr.update(value="按钮点击成功！", placeholder="新的占位符文本")
with gr.Blocks() as demo:
output = gr.Textbox(label="动态更新示例")
btn = gr.Button("点击更新文本")
btn.click(fn=update_text, inputs=None, outputs=output)
|
✅ 经典进阶案例（实战必用，Gradio+HF模型+自定义布局）
这个案例是 「中文文本分类+文本生成二合一工具」，结合了 HuggingFace 模型、Blocks 标签页、多函数绑定，是你大概率会用到的实战场景，复制运行即可使用：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
| import gradio as gr
from transformers import pipeline
# 加载两个HuggingFace模型
sentiment_model = pipeline("sentiment-analysis", model="uer/roberta-base-finetuned-dianping-chinese")
generate_model = pipeline("text2text-generation", model="uer/t5-base-chinese-summary")
# 定义函数1：情感分析
def sentiment_func(text):
res = sentiment_model(text)[0]
return f"【情感结果】：{res['label']} | 置信度：{round(res['score'], 4)}"
# 定义函数2：文本生成/摘要
def generate_func(text, max_len=50):
res = generate_model(text, max_length=max_len)[0]
return f"【生成结果】：{res['generated_text']}"
# 构建自定义界面
with gr.Blocks(title="NLP工具合集") as demo:
gr.Markdown("## 📚 HuggingFace + Gradio NLP 可视化工具")
gr.Markdown("支持：中文情感分析、文本摘要生成")
# 标签页1：情感分析
with gr.Tab("✨ 文本情感分析"):
text_input1 = gr.Textbox(label="请输入待分析文本", placeholder="输入评价/评论/句子", lines=3)
text_output1 = gr.Textbox(label="分析结果")
btn1 = gr.Button("开始分析", variant="primary") # primary是高亮按钮
btn1.click(fn=sentiment_func, inputs=text_input1, outputs=text_output1)
# 标签页2：文本生成/摘要
with gr.Tab("✍️ 文本摘要生成"):
text_input2 = gr.Textbox(label="请输入原文", placeholder="输入需要生成摘要的文本", lines=5)
max_len_slider = gr.Slider(min=20, max=200, value=50, label="生成最大长度")
text_output2 = gr.Textbox(label="生成结果")
btn2 = gr.Button("开始生成", variant="primary")
btn2.click(fn=generate_func, inputs=[text_input2, max_len_slider], outputs=text_output2)
# 启动应用，支持局域网访问+自动打开浏览器
demo.launch(server_name="0.0.0.0", inbrowser=True, share=False)
|
五、Gradio 高频高级功能
✅ 1. 应用的「临时公网分享」功能（超实用）
Gradio 提供了一个逆天好用的功能：启动时添加 share=True，会自动生成一个 公网临时链接（格式：https://xxxx.gradio.live），可以分享给任何人（无论对方在何地）访问你的应用，无需部署到服务器！
1
| demo.launch(share=True) # 生成公网链接，有效期72小时，无访问次数限制
|
✅ 适用场景：演示模型给同事/客户、远程调试、分享成果，无需配置域名/服务器，极其方便。
✅ 2. 组件的「样式自定义」（让界面更好看）
所有组件都可以通过 elem_id、css、variant 等参数自定义样式，无需写CSS，新手推荐用内置的样式参数：
1
2
3
4
5
6
7
| # 高亮按钮（primary）、次要按钮（secondary）、危险按钮（stop）
gr.Button("提交", variant="primary")
gr.Button("重置", variant="secondary")
gr.Button("停止", variant="stop")
# 文本框设置高度、占位符、是否可编辑
gr.Textbox(label="输入框", lines=5, placeholder="请输入内容", interactive=True)
|
✅ 3. 批量处理 + 进度条显示（处理大任务必备）
如果你的函数需要处理大文件/大模型推理（比如图片生成、长文本处理），可以添加进度条，让用户看到处理进度，提升体验：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| import gradio as gr
import time
# 带进度条的函数：用gr.Progress()装饰器
@gr.Progress()
def process_big_task(text):
for i in range(10):
time.sleep(0.5)
yield f"处理中：{i*10}% → {text}"
return f"处理完成！最终结果：{text}"
with gr.Blocks() as demo:
input = gr.Textbox(label="输入")
output = gr.Textbox(label="输出")
btn = gr.Button("开始处理")
btn.click(fn=process_big_task, inputs=input, outputs=output)
demo.launch()
|
✅ 4. 缓存机制（提升重复请求速度）
如果你的函数/模型推理耗时较长，且用户会频繁输入相同的内容，可以添加 @gr.cache() 缓存装饰器，相同的输入会直接返回缓存结果，无需重新计算，大幅提升速度：
1
2
3
4
| @gr.cache() # 缓存装饰器，放在函数上方
def predict(text):
# 耗时的模型推理逻辑
return result
|
六、Gradio 部署
如果你想把Gradio应用永久部署到公网，让任何人都能随时访问，有3种主流方式，难度从低到高，新手推荐前两种：
✅ 方式1：HuggingFace Spaces 部署（零成本，推荐，和Gradio无缝衔接）
- 核心优势：免费、无需服务器、一键部署、自动适配Gradio，HuggingFace官方提供的部署平台；
- 操作步骤：注册HF账号 → 创建Spaces → 选择Gradio框架 → 上传代码 → 自动部署，全程5分钟搞定；
- 适用场景：个人项目、演示、小流量应用，无访问次数限制。
✅ 方式2：Gradio 部署到本地服务器/云服务器
- 核心优势：完全可控，适合企业内部使用、大流量应用；
- 操作步骤：在云服务器（阿里云/腾讯云）安装Python+Gradio → 上传代码 → 用
nohup python app.py & 后台运行即可； - 访问方式：通过服务器IP+端口访问，比如
http://47.xxx.xxx.xxx:7860。
✅ 方式3：打包成Docker镜像（工业级部署）
适合团队协作、大规模部署，需要掌握Docker基础，这里不展开，感兴趣可以自行学习。
核心命令速查
1
2
3
4
5
6
7
8
9
10
11
12
13
| # 安装
pip install gradio -i https://pypi.tuna.tsinghua.edu.cn/simple
# 快速模式核心
gr.Interface(fn=func, inputs=input_comp, outputs=output_comp)
# 自定义模式核心
with gr.Blocks() as demo:
组件定义
组件.click(fn=func, inputs=inputs, outputs=outputs)
# 启动应用（万能参数）
demo.launch(server_name="0.0.0.0", server_port=7860, inbrowser=True, debug=True)
|
本文链接：Gradio快速上手教程
