Gradio 实战：用 Python 快速搭建 AI 演示界面

想把训练好的模型或大模型 API 立刻变成一个能分享的网页？Gradio 是目前最省事的方案：几行 Python 就能把任意函数包装成带交互的 AI 演示界面，不用写一行前端代码，特别适合算法同学快速做 Demo、接 ChatGPT/本地大模型做原型验证。

一、为什么选 Gradio

Gradio 的设计哲学是“输入输出组件即界面”。你定义一个 Python 函数，再声明它的输入组件（文本框、图片、滑块）和输出组件，Gradio 就自动生成对应的网页。相比之下，Streamlit 更像一个脚本式的仪表盘框架，而 Gradio 在“把一个模型封装成可分享的 Demo”这件事上更轻、更快。它的核心优势有三点：上手成本极低、内置大量 AI 场景组件（Chatbot、Image、Audio）、一行 share=True 就能生成公网临时链接。

二、三分钟跑通第一个 Demo

先安装并确认版本。Gradio 对 Python 3.8+ 友好，建议用虚拟环境隔离依赖。

pip install gradio
python -c "import gradio; print(gradio.__version__)"

下面这个最小示例把“问候函数”变成网页：输入框输入名字，点击提交后返回问候语。gr.Interface 是 Gradio 最高层的封装，fn 是处理函数，inputs/outputs 声明组件类型。

import gradio as gr

def greet(name):
    return f"你好，{name}！"

demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()

运行后在终端会打印本地地址（默认 http://127.0.0.1:7860），浏览器打开即可看到界面。这就是一个能用的 AI 演示界面雏形。

三、核心组件：输入与输出

Gradio 用组件（Component）来描述界面元素。常用组件覆盖文本、图片、音频、文件、数值等类型，几乎能映射所有模型推理的输入输出。下面这张表列出了最常用的一组。

组件	用途	典型场景
gr.Textbox	多行文本输入/输出	提问、答案、代码
gr.Image	图片上传/显示	图像分类、OCR、文生图
gr.Audio	录音/播放	语音识别、TTS
gr.Slider	数值滑块	温度、Top-p 参数
gr.Dropdown	下拉选择	模型切换、语言
gr.Chatbot	对话气泡列表	多轮聊天机器人

把多个组件组合进 Interface 也很简单，inputs 和 outputs 用列表即可。下面示例同时接收文本与图片，返回一个字符串。

import gradio as gr

def describe(text, img):
    return f"收到文本：{text}，图片尺寸：{img.size}"

demo = gr.Interface(
    fn=describe,
    inputs=[gr.Textbox(label="描述"), gr.Image(label="图片", type="pil")],
    outputs=gr.Textbox(label="结果"),
)
demo.launch()

四、做一个真正能聊的 AI 对话界面

接大模型时，强烈建议走一层统一网关，避免把各家 API Key 写死在代码里。我们用前面介绍过的 One API 自建大模型网关 来聚合模型，再把 base_url 指向网关地址即可。如果你更想跑本地模型，可以参考 DeepSeek 本地部署 把推理端点起来。

import gradio as gr
from openai import OpenAI

# 指向 One API 网关，而不是官方地址
client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="sk-你的OneAPI令牌",
)

def chat(message, history):
    messages = [{"role": "system", "content": "你是一个友好的助手。"}]
    for u, a in history:
        messages.append({"role": "user", "content": u})
        messages.append({"role": "assistant", "content": a})
    messages.append({"role": "user", "content": message})
    resp = client.chat.completions.create(
        model="gpt-4o-mini", messages=messages, stream=False)
    return resp.choices[0].message.content

demo = gr.ChatInterface(fn=chat, title="我的 AI 助手",
                       description="基于 Gradio + One API 搭建")
demo.launch()

gr.ChatInterface 已经帮你做好了多轮历史、提交按钮、清空会话等交互，你只需要提供 fn。如果希望流式输出，把 stream=True 并用生成器返回片段即可（见第七节）。

五、多模态：图片上传与处理

很多 AI 应用需要用户上传图片，比如图像描述、证件识别。Gradio 的 gr.Image 配合 type="pil" 会直接把图片读成 Pillow 对象，方便后续处理。

import gradio as gr
from PIL import Image, ImageFilter

def blur(img):
    return img.filter(ImageFilter.GaussianBlur(8))

demo = gr.Interface(
    fn=blur,
    inputs=gr.Image(label="上传图片", type="pil"),
    outputs=gr.Image(label="模糊结果", type="pil"),
    title="图片高斯模糊",
)
demo.launch()

实际项目里，把 blur 换成你的视觉模型推理函数，就能做成图像理解 Demo。注意生产环境要限制上传文件大小和类型，避免被大图打爆内存。

六、用 Blocks 自定义复杂布局

当界面不只是“一个输入一个输出”时，用 gr.Blocks 可以自由编排行、列、标签页，甚至事件回调。下面做一个“文本生成 + 参数调节”的布局。

import gradio as gr

def generate(prompt, max_len, temperature):
    # 占位：这里换成真实推理调用
    return f"[max_len={max_len}, temp={temperature}] {prompt}"

with gr.Blocks(title="生成器") as demo:
    gr.Markdown("# 简易文本生成器")
    with gr.Row():
        with gr.Column():
            prompt = gr.Textbox(label="提示词")
            max_len = gr.Slider(16, 1024, value=128, label="最大长度")
            temp = gr.Slider(0.0, 1.0, value=0.7, label="温度")
            btn = gr.Button("生成")
        with gr.Column():
            out = gr.Textbox(label="输出", lines=8)
    btn.click(generate, inputs=[prompt, max_len, temp], outputs=out)
demo.launch()

btn.click(...) 把按钮点击事件绑定到函数，并声明输入与输出组件。这种声明式事件模型让前端逻辑非常直观，不用手写任何 JS。

七、状态保持与流式输出

复杂对话需要跨多次调用保存状态，用 gr.State 即可；而流式输出能让大模型“边想边说”，体验更好。下面把两者结合：用生成器逐字吐出内容。

import gradio as gr
import time

def stream_reply(message, history, state):
    answer = f"针对「{message}」的回答："
    for ch in "这是一段模拟的流式输出，逐字返回让界面更生动。":
        answer += ch
        time.sleep(0.05)
        yield "", history + [(message, answer)]
    state += 1
    return state

with gr.Blocks() as demo:
    state = gr.State(0)
    chatbot = gr.Chatbot()
    msg = gr.Textbox(label="消息")
    msg.submit(stream_reply, [msg, chatbot, state], [msg, chatbot])
demo.launch()

八、部署：本地、Docker 与分享链接

本地跑通后就要考虑怎么给别人用。launch() 的几个参数决定了暴露范围：server_name="0.0.0.0" 允许局域网访问，share=True 生成公网临时隧道，server_port 指定端口。注意 share 链接有时长限制，正式服务要走 Docker 或反向代理。

# app.py
import gradio as gr

def greet(name):
    return f"你好，{name}！"

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

if __name__ == "__main__":
    demo.launch(server_name="0.0.0.0", server_port=7860)

用 Docker 打包最稳妥，镜像自带 Python 与依赖，跨机器一致。下面是一个非常精简的 Dockerfile。

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 7860
CMD ["python", "app.py"]

方式	优点	适用
本地 launch	零配置	本机调试
share=True	免部署公网可访问	临时演示
Docker + 反向代理	稳定、可域名访问	生产/长期服务

当你用 Docker 跑在服务器上，再用 Nginx 反向代理 套一层 HTTPS 与域名，就接近生产可用了。

九、嵌入 FastAPI 与生产化建议

Gradio 本身也可以挂载进已有的 FastAPI 应用，复用同一套鉴权、日志和端口。配合我们讲过的 FastAPI 流式大模型对话 API，你可以把后端推理和前端 Demo 放在一个服务里。

from fastapi import FastAPI
import gradio as gr

app = FastAPI()

def echo(x):
    return x

gradio_app = gr.Interface(fn=echo, inputs="text", outputs="text")
app = gr.mount_gradio_app(app, gradio_app, path="/gradio")

生产化还需注意：用 queue() 处理并发请求、设置超时与最大文件大小、把密钥放在环境变量而非代码里、用 VS Code 远程调试或用 GitHub Actions 做自动化部署。若需要编排多步 AI 流程，也可以把 Gradio 作为 LangGraph 多智能体 的可视化入口。

十、常见坑与排障

现象	原因	解决办法
端口被占用	7860 已用	指定 server_port 或加 server_name
图片上传报 413	反向代理限制体积	Nginx 调大 client_max_body_size
share 链接打不开	隧道服务波动	改用 Docker+域名，勿依赖临时链接
并发卡死	未启用队列	调用 demo.queue()
依赖冲突	全局包混乱	用虚拟环境或 Docker 隔离

小结：Gradio 用极低的代码量把模型和函数变成可交互的 AI 演示界面，从单函数 Interface 到自由布局 Blocks，再到流式输出与 Docker 部署，覆盖了从原型到上线的完整路径。配合 One API 网关统一模型接入，你几乎可以在一个下午里交付一个能对外演示的 AI 应用。