illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 Gradio 官方文档编写 —— 三大入口类 / 组件全表 / 事件 / 布局 / 流式 / launch 参数 / 部署

三大入口类对照 ​

类定位复杂度适用
gr.Interface最快，三行起界面低单函数 demo、教学
gr.Blocks最灵活，自由布局中高复杂多组件联动、定制 UI
gr.ChatInterface对话专用低LLM 对话、客服

gr.Interface 签名 ​

python
gr.Interface(
    fn,                          # 包装函数
    inputs,                      # str / Component / list
    outputs,                     # str / Component / list
    examples=None,               # 示例列表
    title=None,                  # 标题
    description=None,            # 描述
    article=None,                # 底部 Markdown
    theme=None,                  # 主题
    live=False,                  # 输入变化自动执行（无需点按钮）
    allow_flagging="never",      # never / auto / manual
    cache_examples=False,        # 预算示例结果
    api_name="predict",          # API 端点名
    concurrency_limit=None,      # 并发
)

gr.Blocks 签名 ​

python
gr.Blocks(
    title=None,
    theme=None,
    analytics_enabled=True,
    css=None,
    js=None,                     # 前端 JS
    delete_cache=None,           # (age, size) 清理缓存
)

gr.ChatInterface 签名 ​

python
gr.ChatInterface(
    fn,                          # 对话函数
    multimodal=False,            # 允许上传图片
    type="tuples",               # tuples / messages
    additional_inputs=None,      # 额外输入（如 system prompt）
    additional_inputs_accordion=None,
    examples=None,
    title=None,
    description=None,
    chatbot=None,                # 自定义 Chatbot 组件
    retry_btn="Retry",           # 重试按钮
    undo_btn="Undo",
    clear_btn="Clear",
    concurrency_limit=None,
)

组件全表 ​

输入输出通用 ​

组件简写用途
gr.Textbox"text"文本
gr.Number"number"数值
gr.Slider"slider"滑块
gr.Checkbox"checkbox"复选
gr.CheckboxGroup"checkboxgroup"多选
gr.Radio"radio"单选
gr.Dropdown"dropdown"下拉
gr.TextArea-多行文本
gr.Code-代码
gr.ColorPicker"colorpicker"取色
gr.Dataframe"dataframe"表格
gr.File"file"文件
gr.JSON"json"JSON
gr.State"state"状态

媒体 ​

组件简写type 取值
gr.Image"image"filepath / pil / numpy
gr.Audio"audio"filepath / numpy
gr.Video"video"filepath
gr.Gallery"gallery"-
gr.Model3D"model3d"-
gr.Plot-matplotlib/plotly/altair
gr.ImageSlider-图像对比

展示 ​

组件用途
gr.Markdown渲染 Markdown
gr.HTML原始 HTML
gr.HighlightedText高亮文本
gr.Label分类标签 + 概率
gr.Chatbot对话气泡
gr.ChatMessage单条消息（type="messages"）
gr.Image图片
gr.AnnotatedImage带标注图

布局与控制 ​

组件用途
gr.Row横排
gr.Column竖排
gr.Tabs / gr.Tab标签页
gr.Accordion折叠面板
gr.Group紧凑分组
gr.Box边框分组
gr.Button按钮
gr.Link链接
gr.LoginButtonHF 登录按钮

事件全表 ​

事件触发典型组件
.click()点击Button
.submit()回车Textbox
.change()值变化大多数
.input()实时输入Textbox/Slider
.select()选中项Dropdown/Radio/Gallery/Dataset
.upload()上传完成File/Image/Audio
.play() / .stop()播放控制Audio/Video
.clear()清空Chatbot
.like()点赞Chatbot
.then()上一个完成后任意（链式）
.success() / .error()成功/失败回调任意
gr.on()多触发器任意

事件通用参数 ​

参数说明
fn绑定函数
inputs / outputs组件或 list
trigger_modeonce / multiple / always_last
concurrency_limit并发上限
concurrency_id共享并发池
every定时触发（秒）
show_progressfull / hidden / minimal
show_api是否暴露 API
cancels取消其他事件
preprocess / postprocess是否预处理（API 模式）
scroll_output是否自动滚动
js前端 JS 代码

launch 参数全表 ​

参数默认说明
inlineNone在 notebook 内联
inbrowserFalse自动开浏览器
shareFalse生成 *.gradio.live 临时公网
debugFalse调试模式
authNone(user,pass) 或回调
auth_messageNone登录提示
prevent_thread_lockFalse不阻塞主线程
server_name127.0.0.1监听 IP
server_port7860端口
heightNone嵌入高度
widthNone嵌入宽度
favicon_pathNonefavicon
ssl_keyfile / ssl_certfileNoneHTTPS
ssl_verifyTrue校验 SSL
allowed_pathsNone允许访问的本地路径
blocked_pathsNone禁止访问路径
app_kwargsNoneFastAPI 额外参数
mcp_serverFalse启用 MCP server

queue 参数 ​

参数默认说明
max_sizeNone队列最大长度
default_concurrency_limitauto默认并发
api_openTrue队列 API 开放
max_threads40处理线程
status_rateauto状态更新频率

Image 组件 type ​

typefn 收到适用
"filepath"文件路径字符串通用，传给 CLI
"pil"PIL.Image 对象PIL 处理
"numpy"numpy ndarrayCV 计算

Chatbot type（重要） ​

typehistory 形式推荐
"tuples"（旧默认）[[user, assistant], ...] 列表对旧代码
"messages"（新）[{"role":"user","content":...}, ...]新代码推荐
python
gr.Chatbot(type="messages")   # 显式推荐 messages

HF Spaces 部署模板 ​

my-space/
├── README.md          # YAML front matter
├── app.py             # Gradio 代码
├── requirements.txt   # 依赖
└── packages/          # 离线包（可选）

README.md：

yaml
---
title: My Demo
emoji: 🚀
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: "5.0"
app_file: app.py
pinned: false
license: mit
---

硬件升级（免费 CPU → 付费 GPU）：Space Settings → Hardware。

gradio_client 速查 ​

python
from gradio_client import Client

# 连本地
client = Client("http://localhost:7860/")

# 连 HF Space
client = Client("user/space-name", hf_token="hf_xxx")

# 调用
result = client.predict(input, api_name="/predict")

# 流式
for chunk in client.submit(input).tuples():
    print(chunk)

# 查看 API 信息
client.view_api(return_format="dict")

主题预设 ​

python
gr.themes.Default()
gr.themes.Soft()
gr.themes.Monochrome()
gr.themes.Glass()
gr.themes.Origin()       # 复古

自定义：

python
gr.themes.Soft(
    primary_hue="emerald",      # 任何 Tailwind 颜色名
    secondary_hue="sky",
    neutral_hue="zinc",
    font=[gr.themes.GoogleFont("Noto Sans SC"), "ui-sans-serif"],
    radius_size="lg",
)

参考 ​