构建演示
Blocks

Gradio 新手？从这里开始：入门指南

TabbedInterface

render

Blocks

with gradio.Blocks():

描述

Blocks 是 Gradio 的底层 API，与 Interfaces 相比，它允许您创建更自定义的 Web 应用程序和演示（但仍然完全使用 Python）。

与 Interface 类相比，Blocks 在以下方面提供了更大的灵活性和控制：（1）组件的布局；（2）触发函数执行的事件；（3）数据流（例如，输入可以触发输出，输出可以触发下一级输出）。Blocks 还提供了将相关演示分组的方法，例如使用选项卡。

Blocks 的基本用法如下：创建一个 Blocks 对象，然后将其用作上下文（使用 “with” 语句），然后在 Blocks 上下文中定义布局、组件或事件。最后，调用 launch() 方法启动演示。

用法示例

import gradio as gr
def update(name):
    return f"Welcome to Gradio, {name}!"

with gr.Blocks() as demo:
    gr.Markdown("Start typing below and then click **Run** to see the output.")
    with gr.Row():
        inp = gr.Textbox(placeholder="What is your name?")
        out = gr.Textbox()
    btn = gr.Button("Run")
    btn.click(fn=update, inputs=inp, outputs=out)

demo.launch()

初始化

🔗

theme: Theme | str | None

default = None

Theme 对象或代表主题的字符串。如果为字符串，将查找具有该名称的内置主题（例如 “soft” 或 “default”），或者尝试从 Hugging Face Hub 加载主题（例如 “gradio/monochrome”）。如果为 None，将使用默认主题。

🔗

analytics_enabled: bool | None

default = None

是否允许基本遥测。如果为 None，将使用 GRADIO_ANALYTICS_ENABLED 环境变量，否则默认为 True。

🔗

mode: str

default = "blocks"

正在创建的 Blocks 或 Interface 类型的易于理解的名称。在内部用于分析。

🔗

title: str

default = "Gradio"

当在浏览器窗口中打开时显示的标签页标题。

🔗

css: str | None

default = None

作为代码字符串的自定义 CSS。此 CSS 将包含在演示网页中。

🔗

css_paths: str | Path | list[str | Path] | None

default = None

作为 pathlib.Path 的 CSS 文件或此类路径的列表。这些 CSS 文件将被读取、连接并包含在演示网页中。如果还设置了 `css` 参数，则首先包含来自 `css` 的 CSS。

🔗

js: str | Literal[True] | None

default = None

作为代码字符串的自定义 JS。自定义 JS 应采用单个 JS 函数的形式。此函数将在页面加载时自动执行。为了获得更大的灵活性，请使用 head 参数将 JS 插入到 <script> 标签中。

🔗

head: str | None

default = None

要插入到演示网页 head 中的自定义 HTML 代码。这可用于向页面添加自定义元标记、多个脚本、样式表等。

🔗

head_paths: str | Path | list[str | Path] | None

default = None

作为 pathlib.Path 的 HTML 文件或此类路径的列表的自定义 HTML 代码。这些 HTML 文件将被读取、连接并包含在演示网页的 head 中。如果还设置了 `head` 参数，则首先包含来自 `head` 的 HTML。

🔗

fill_height: bool

default = False

是否垂直展开顶级子组件以适应窗口的高度。如果为 True，则当子组件的 scale 值 >= 1 时发生展开。

🔗

fill_width: bool

default = False

是否水平展开以完全填充容器。如果为 False，则居中并将应用程序限制为最大宽度。仅当这是 Gradio 应用程序中最外层的 `Blocks` 时才适用。

🔗

delete_cache: tuple[int, int] | None

default = None

对应于 [频率，年龄] 的元组，均以秒为单位表示。每隔 `frequency` 秒，如果自文件创建以来已过去 `age` 秒以上，则将删除此 Blocks 实例创建的临时文件。例如，将其设置为 (86400, 86400) 将每天删除临时文件。缓存将在服务器重新启动时完全删除。如果为 None，则不会发生缓存删除。

演示

import gradio as gr def welcome(name): return f"Welcome to Gradio, {name}!" with gr.Blocks() as demo: gr.Markdown( """ # Hello World! 开始在下面输入以查看输出。 """) inp = gr.Textbox(placeholder="你的名字是？") out = gr.Textbox() inp.change(welcome, inp, out) if __name__ == "__main__": demo.launch()

import gradio as gr

def welcome(name):
    return f"Welcome to Gradio, {name}!"

with gr.Blocks() as demo:
    gr.Markdown(
    """
    # Hello World!
    Start typing below to see the output.
    """)
    inp = gr.Textbox(placeholder="What is your name?")
    out = gr.Textbox()
    inp.change(welcome, inp, out)

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

import numpy as np import gradio as gr def flip_text(x): return x[::-1] def flip_image(x): return np.fliplr(x) with gr.Blocks() as demo: gr.Markdown("使用此演示翻转文本或图像文件。") with gr.Tab("翻转文本"): text_input = gr.Textbox() text_output = gr.Textbox() text_button = gr.Button("翻转") with gr.Tab("翻转图像"): with gr.Row(): image_input = gr.Image() image_output = gr.Image() image_button = gr.Button("翻转") with gr.Accordion("展开查看更多！", open=False): gr.Markdown("看看我...") temp_slider = gr.Slider( 0, 1, value=0.1, step=0.1, interactive=True, label="滑动我", ) text_button.click(flip_text, inputs=text_input, outputs=text_output) image_button.click(flip_image, inputs=image_input, outputs=image_output) if __name__ == "__main__": demo.launch()

import numpy as np
import gradio as gr

def flip_text(x):
    return x[::-1]

def flip_image(x):
    return np.fliplr(x)

with gr.Blocks() as demo:
    gr.Markdown("Flip text or image files using this demo.")
    with gr.Tab("Flip Text"):
        text_input = gr.Textbox()
        text_output = gr.Textbox()
        text_button = gr.Button("Flip")
    with gr.Tab("Flip Image"):
        with gr.Row():
            image_input = gr.Image()
            image_output = gr.Image()
        image_button = gr.Button("Flip")

    with gr.Accordion("Open for More!", open=False):
        gr.Markdown("Look at me...")
        temp_slider = gr.Slider(
            0, 1,
            value=0.1,
            step=0.1,
            interactive=True,
            label="Slide me",
        )

    text_button.click(flip_text, inputs=text_input, outputs=text_output)
    image_button.click(flip_image, inputs=image_input, outputs=image_output)

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

import pandas as pd import numpy as np import gradio as gr def plot(v, a): g = 9.81 theta = a / 180 * 3.14 tmax = ((2 * v) * np.sin(theta)) / g timemat = tmax * np.linspace(0, 1, 40) x = (v * timemat) * np.cos(theta) y = ((v * timemat) * np.sin(theta)) - ((0.5 * g) * (timemat**2)) df = pd.DataFrame({"x": x, "y": y}) return df demo = gr.Blocks() with demo: gr.Markdown( r"让我们做一些运动学！选择速度和角度以查看轨迹。记住范围 $R = v_0^2 \cdot \frac{\sin(2\theta)}{g}$" ) with gr.Row(): speed = gr.Slider(1, 30, 25, label="速度") angle = gr.Slider(0, 90, 45, label="角度") output = gr.LinePlot( x="x", y="y", overlay_point=True, tooltip=["x", "y"], x_lim=[0, 100], y_lim=[0, 60], width=350, height=300, ) btn = gr.Button(value="运行") btn.click(plot, [speed, angle], output) if __name__ == "__main__": demo.launch()

import pandas as pd
import numpy as np

import gradio as gr

def plot(v, a):
    g = 9.81
    theta = a / 180 * 3.14
    tmax = ((2 * v) * np.sin(theta)) / g
    timemat = tmax * np.linspace(0, 1, 40)

    x = (v * timemat) * np.cos(theta)
    y = ((v * timemat) * np.sin(theta)) - ((0.5 * g) * (timemat**2))
    df = pd.DataFrame({"x": x, "y": y})
    return df

demo = gr.Blocks()

with demo:
    gr.Markdown(
        r"Let's do some kinematics! Choose the speed and angle to see the trajectory. Remember that the range $R = v_0^2 \cdot \frac{\sin(2\theta)}{g}$"
    )

    with gr.Row():
        speed = gr.Slider(1, 30, 25, label="Speed")
        angle = gr.Slider(0, 90, 45, label="Angle")
    output = gr.LinePlot(
        x="x",
        y="y",
        overlay_point=True,
        tooltip=["x", "y"],
        x_lim=[0, 100],
        y_lim=[0, 60],
        width=350,
        height=300,
    )
    btn = gr.Button(value="Run")
    btn.click(plot, [speed, angle], output)

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

方法

launch

gradio.Blocks.launch(···)

描述

启动一个简单的 Web 服务器来服务演示。也可以通过设置 share=True 来创建一个公共链接，供任何人从浏览器访问演示。

用法示例

import gradio as gr
def reverse(text):
    return text[::-1]
with gr.Blocks() as demo:
    button = gr.Button(value="Reverse")
    button.click(reverse, gr.Textbox(), gr.Textbox())
demo.launch(share=True, auth=("username", "password"))

🔗

inline: bool | None

default = None

是否在 gradio 应用程序中以内联 iframe 显示。在 python notebook 中默认为 True；否则为 False。

🔗

inbrowser: bool

default = False

是否在默认浏览器的新标签页中自动启动 gradio 应用程序。

🔗

share: bool | None

default = None

是否为 gradio 应用程序创建公开可共享的链接。创建 SSH 隧道以使您的 UI 可以从任何地方访问。如果未提供，则每次默认设置为 False，但在 Google Colab 中运行时除外。当无法访问 localhost 时（例如 Google Colab），不支持设置 share=False。可以通过环境变量 GRADIO_SHARE=True 设置。

🔗

debug: bool

default = False

如果为 True，则阻止主线程运行。如果在 Google Colab 中运行，则需要此选项才能在单元格输出中打印错误。

🔗

max_threads: int

default = 40

Gradio 应用程序可以并行生成的最大总线程数。默认值继承自 starlette 库（当前为 40）。

🔗

auth: Callable[[str, str], bool] | tuple[str, str] | list[tuple[str, str]] | None

default = None

如果提供，则需要用户名和密码（或用户名-密码元组列表）才能访问应用程序。也可以提供一个函数，该函数接受用户名和密码，如果登录有效，则返回 True。

🔗

auth_message: str | None

default = None

如果提供，则在登录页面上提供 HTML 消息。

🔗

prevent_thread_lock: bool

default = False

默认情况下，gradio 应用程序在服务器运行时阻止主线程。如果设置为 True，则 gradio 应用程序将不会阻止，并且 gradio 服务器将在脚本完成后立即终止。

🔗

show_error: bool

default = False

如果为 True，则 gradio 应用程序中的任何错误都将显示在警报模态框中，并在浏览器控制台日志中打印

🔗

server_name: str | None

default = None

为了使应用程序可以在本地网络上访问，请将此项设置为 “0.0.0.0”。可以通过环境变量 GRADIO_SERVER_NAME 设置。如果为 None，将使用 “127.0.0.1”。

🔗

server_port: int | None

default = None

将在此端口（如果可用）上启动 gradio 应用程序。可以通过环境变量 GRADIO_SERVER_PORT 设置。如果为 None，将从 7860 开始搜索可用端口。

🔗

height: int

default = 500

包含 gradio 应用程序的 iframe 元素的高度（以像素为单位）（如果 inline=True）。

🔗

width: int | str

default = "100%"

包含 gradio 应用程序的 iframe 元素的宽度（以像素为单位）（如果 inline=True）。

🔗

favicon_path: str | None

default = None

如果提供了文件路径（.png、.gif 或 .ico），它将用作网页的网站图标。

🔗

ssl_keyfile: str | None

default = None

如果提供了文件路径，将使用它作为私钥文件来创建在 https 上运行的本地服务器。

🔗

ssl_certfile: str | None

default = None

如果提供了文件路径，将使用它作为 https 的签名证书。如果提供了 ssl_keyfile，则需要提供此项。

🔗

ssl_keyfile_password: str | None

default = None

如果提供了密码，将将其与 https 的 ssl 证书一起使用。

🔗

ssl_verify: bool

default = True

如果为 False，则跳过证书验证，允许使用自签名证书。

🔗

quiet: bool

default = False

如果为 True，则抑制大多数打印语句。

🔗

show_api: bool

default = True

如果为 True，则在应用程序的页脚中显示 API 文档。默认为 True。

🔗

allowed_paths: list[str] | None

default = None

Gradio 允许服务的完整文件路径或父目录的列表。必须是绝对路径。警告：如果您提供目录，则这些目录或其子目录中的任何文件都可供您的应用程序的所有用户访问。可以通过逗号分隔的环境变量 GRADIO_ALLOWED_PATHS 设置。这些文件通常被认为是安全的，并且在可能的情况下将在浏览器中显示。

🔗

blocked_paths: list[str] | None

default = None

Gradio 不允许服务的完整文件路径或父目录的列表（即，不允许您的应用程序的用户访问）。必须是绝对路径。警告：优先于 `allowed_paths` 和 Gradio 默认公开的所有其他目录。可以通过逗号分隔的环境变量 GRADIO_BLOCKED_PATHS 设置。

🔗

root_path: str | None

default = None

应用程序的根路径（或“挂载点”），如果它不是从域的根目录 (“/”) 提供服务。通常在应用程序位于反向代理之后时使用，该反向代理将请求转发到应用程序。例如，如果应用程序在 “https://example.com/myapp” 上提供服务，则应将 `root_path` 设置为 “/myapp”。可以提供以 http:// 或 https:// 开头的完整 URL，它将用作其整体的根路径。可以通过环境变量 GRADIO_ROOT_PATH 设置。默认为 “”。

🔗

app_kwargs: dict[str, Any] | None

default = None

要传递给底层 FastAPI 应用程序的其他关键字参数，作为参数键和参数值的字典。例如，`{"docs_url": "/docs"}`

🔗

state_session_capacity: int

default = 10000

要存储在内存中的会话信息的最大会话数。如果会话数超过此数字，则将删除最旧的会话。当使用 gradio.State 或从函数返回更新的组件时，减少容量以减少内存使用。默认为 10000。

🔗

share_server_address: str | None

default = None

使用此项可以为共享 Gradio 应用程序指定自定义 FRP 服务器和端口（仅在 share=True 时适用）。如果未提供，将使用默认的 FRP 服务器 https://gradio.live。有关更多信息，请参阅 https://github.com/huggingface/frp。

🔗

share_server_protocol: Literal['http', 'https'] | None

default = None

使用此项可以指定用于共享链接的协议。默认为 “https”，除非提供了自定义 share_server_address，在这种情况下，它默认为 “http”。如果您正在使用自定义 share_server_address 并且想要使用 https，则必须将其设置为 “https”。

🔗

share_server_tls_certificate: str | None

default = None

连接到自定义共享服务器时要使用的 TLS 证书文件的路径。此参数不与默认的 FRP 服务器 https://gradio.live 一起使用。否则，您必须提供相对于当前工作目录的有效 TLS 证书文件（例如 “cert.pem”），否则连接将不使用 TLS 加密，这不安全。

🔗

auth_dependency: Callable[[fastapi.Request], str | None] | None

default = None

接受 FastAPI 请求并返回字符串用户 ID 或 None 的函数。如果该函数为特定请求返回 None，则该用户无权访问该应用程序（他们将看到 401 Unauthorized 响应）。用于外部身份验证系统（如 OAuth）。不能与 `auth` 一起使用。

🔗

max_file_size: str | int | None

default = None

可以上传的最大文件大小（以字节为单位）。可以是 “<value><unit>” 形式的字符串，其中 value 是任何正整数，unit 是 “b”、“kb”、“mb”、“gb”、“tb” 之一。如果为 None，则不设置限制。

🔗

enable_monitoring: bool | None

default = None

通过 /monitoring 端点启用应用程序的流量监控。默认值为 None，这将启用此端点。如果显式设置为 True，还将向控制台打印监控 URL。如果为 False，将完全禁用监控。

🔗

strict_cors: bool

default = True

如果为 True，则阻止外部域向在 localhost 上运行的 Gradio 服务器发出请求。如果为 False，则允许源自 localhost 但也关键地来自 “null” 的对 localhost 的请求。此参数通常应为 True 以防止 CSRF 攻击，但在使用 Web 组件嵌入*本地运行的 Gradio 应用程序*时可能需要为 False。

🔗

node_server_name: str | None

default = None

🔗

node_port: int | None

default = None

🔗

ssr_mode: bool | None

default = None

如果为 True，Gradio 应用程序将使用服务器端渲染模式进行渲染，这种模式通常性能更高，并提供更好的 SEO，但这需要在系统上安装 Node 20+。如果为 False，应用程序将使用客户端渲染模式进行渲染。如果为 None，将使用 GRADIO_SSR_MODE 环境变量或默认为 False。

🔗

pwa: bool | None

default = None

如果为 True，则 Gradio 应用程序将设置为可安装的 PWA（渐进式 Web 应用程序）。如果设置为 None（默认行为），则如果此 Gradio 应用程序在 Spaces 上启动，则将启用 PWA 功能，否则不启用。

queue

gradio.Blocks.queue(···)

描述

通过启用队列，您可以控制用户何时知道他们在队列中的位置，并设置允许的最大事件数限制。

用法示例

with gr.Blocks() as demo:
    button = gr.Button(label="Generate Image")
    button.click(fn=image_generator, inputs=gr.Textbox(), outputs=gr.Image())
demo.queue(max_size=10)
demo.launch()

🔗

status_update_rate: float | Literal['auto']

default = "auto"

如果为 “auto”，则队列将在作业完成时向所有客户端发送状态估计。否则，队列将按照此参数设置的秒数间隔定期发送状态。

🔗

api_open: bool | None

default = None

如果为 True，则后端的 REST 路由将打开，允许直接向这些端点发出的请求跳过队列。

🔗

max_size: int | None

default = None

队列在任何给定时刻将存储的最大事件数。如果队列已满，则不会添加新事件，用户将收到一条消息，指出队列已满。如果为 None，则队列大小将不受限制。

🔗

default_concurrency_limit: int | None | Literal['not_set']

default = "not_set"

用于未指定值的事件侦听器的 `concurrency_limit` 的默认值。可以通过环境变量 GRADIO_DEFAULT_CONCURRENCY_LIMIT 设置。如果未另行设置，则默认为 1。

integrate

gradio.Blocks.integrate(···)

描述

与其他库集成的通用方法。此方法应在 launch() 之后运行

🔗

comet_ml: <class 'inspect._empty'>

default = None

如果提供了 comet_ml Experiment 对象，将与实验集成并显示在 Comet 仪表板上

🔗

wandb: ModuleType | None

default = None

如果提供了 wandb 模块，将与它集成并显示在 WandB 仪表板上

🔗

mlflow: ModuleType | None

default = None

如果提供了 mlflow 模块，将与实验集成并显示在 ML Flow 仪表板上

load

gradio.Blocks.load(block, ···)

描述

当 Blocks 最初在浏览器中加载时，将触发此监听器。

🔗

block: Block | None

🔗

fn: Callable | None | Literal['decorator']

default = "decorator"

触发此事件时要调用的函数。通常是机器学习模型的预测函数。函数的每个参数对应一个输入组件，函数应返回单个值或值元组，元组中的每个元素对应一个输出组件。

🔗

inputs: Component | BlockContext | list[Component | BlockContext] | Set[Component | BlockContext] | None

default = None

要用作输入的 gradio.components 列表。如果函数不接受任何输入，则应为空列表。

🔗

outputs: Component | BlockContext | list[Component | BlockContext] | Set[Component | BlockContext] | None

default = None

要用作输出的 gradio.components 列表。如果函数不返回任何输出，则应为空列表。

🔗

api_name: str | None | Literal[False]

default = None

定义端点在 API 文档中的显示方式。可以是字符串、None 或 False。如果设置为字符串，则端点将在 API 文档中以给定的名称公开。如果为 None（默认），则函数名称将用作 API 端点。如果为 False，则端点将不会在 API 文档中公开，并且下游应用程序（包括 `gr.load` 此应用程序的应用程序）将无法使用此事件。

🔗

scroll_to_output: bool

default = False

如果为 True，则完成后将滚动到输出组件

🔗

show_progress: Literal['full', 'minimal', 'hidden']

default = "full"

事件运行时如何显示进度动画：“full” 显示一个覆盖输出组件区域的微调器以及右上角的运行时显示，“minimal” 仅显示运行时显示，“hidden” 完全不显示进度动画

🔗

show_progress_on: Component | list[Component] | None

default = None

要在其上显示进度动画的组件或组件列表。如果为 None，则将在所有输出组件上显示进度动画。

🔗

queue: bool

default = True

如果为 True，则将请求放入队列中（如果已启用队列）。如果为 False，即使已启用队列，也不会将此事件放入队列中。如果为 None，将使用 gradio 应用程序的队列设置。

🔗

batch: bool

default = False

如果为 True，则该函数应处理一批输入，这意味着它应接受每个参数的输入值列表。列表的长度应相等（且长度最大为 `max_batch_size`）。然后*需要*该函数返回列表元组（即使只有一个输出组件），元组中的每个列表对应一个输出组件。

🔗

max_batch_size: int

default = 4

如果从队列调用此方法，则最多可将多少个输入批处理在一起（仅当 batch=True 时相关）

🔗

preprocess: bool

default = True

如果为 False，则在运行 ‘fn’ 之前不会运行组件数据的预处理（例如，如果使用 `Image` 组件调用此方法，则将其保留为 base64 字符串）。

🔗

postprocess: bool

default = True

如果为 False，则在将 ‘fn’ 输出返回到浏览器之前，不会运行组件数据的后处理。

🔗

cancels: dict[str, Any] | list[dict[str, Any]] | None

default = None

当此监听器被触发时，要取消的其他事件的列表。例如，设置 cancels=[click_event] 将取消 click_event，其中 click_event 是另一个组件的 .click 方法的返回值。尚未运行（或正在迭代的生成器）的函数将被取消，但当前正在运行的函数将允许完成。

🔗

trigger_mode: Literal['once', 'multiple', 'always_last'] | None

default = None

如果设置为 "once"（除 `.change()` 之外的所有事件的默认值），则在事件 pending 期间不允许任何提交。如果设置为 "multiple"，则在 pending 期间允许无限次提交；如果设置为 "always_last"（`.change()` 和 `.key_up()` 事件的默认值），则在 pending 事件完成后允许第二次提交。

🔗

js: str | Literal[True] | None

default = None

可选的前端 js 方法，在运行 'fn' 之前运行。js 方法的输入参数是 'inputs' 和 'outputs' 的值，返回值应该是输出组件的值列表。

🔗

concurrency_limit: int | None | Literal['default']

默认 = "default"

如果设置，则这是可以同时运行的此事件的最大数量。可以设置为 None，表示没有 concurrency_limit（可以同时运行任意数量的此事件）。设置为 "default" 以使用默认的并发限制（由 `Blocks.queue()` 中的 `default_concurrency_limit` 参数定义，默认为 1）。

🔗

concurrency_id: str | None

default = None

如果设置，则这是并发组的 ID。具有相同 concurrency_id 的事件将受到最低设置的 concurrency_limit 的限制。

🔗

show_api: bool

default = True

是否在 Gradio 应用程序的“查看 API”页面或 Gradio 客户端的 “.view_api()” 方法中显示此事件。与将 api_name 设置为 False 不同，将 show_api 设置为 False 仍然允许下游应用程序以及客户端使用此事件。如果 fn 为 None，show_api 将自动设置为 False。

🔗

time_limit: int | None

default = None

🔗

stream_every: float

默认 = 0.5

🔗

like_user_message: bool

default = False

卸载

gradio.Blocks.unload(fn, ···)

描述

当用户关闭或刷新标签页，结束用户会话时，此监听器会被触发。它对于在应用程序关闭时清理资源非常有用。

使用示例

import gradio as gr
with gr.Blocks() as demo:
    gr.Markdown("# When you close the tab, hello will be printed to the console")
    demo.unload(lambda: print("hello"))
demo.launch()

🔗

fn: Callable[..., Any]

用于清除资源的可调用函数。该函数不应接受任何参数，并且不使用输出。

指南

Blocks 和事件监听器

控制布局

Blocks 中的状态

自定义 CSS 和 JS

像函数一样使用 Blocks

←

TabbedInterface

render

→