Gradio 智能体 & MCP 黑客马拉松

获奖者
Gradio logo
  1. 构建演示
  2. Blocks

Gradio 新手?从这里开始:入门指南

查看发布历史

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

主题对象或表示主题的字符串。如果是一个字符串,将查找具有该名称的内置主题(例如“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 | I18nData
default = "Gradio"

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

🔗
css: str | None
default = None

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

🔗
css_paths: str | Path | list[str | Path] | None
default = None

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

🔗
js: str | Literal[True] | None
default = None

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

🔗
head: str | None
default = None

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

🔗
head_paths: str | Path | list[str | Path] | None
default = None

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

🔗
fill_height: bool
default = False

是否垂直展开顶级子组件以适应窗口高度。如果为 True,则当子组件的缩放值 >= 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!
    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()

		

方法

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 笔记本中默认为 True;否则为 False。

🔗
inbrowser: bool
default = False

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

🔗
share: bool | None
default = None

是否为 Gradio 应用程序创建可公开共享的链接。创建一个 SSH 隧道,使您的 UI 可以从任何地方访问。如果未提供,则除在 Google Colab 中运行外,每次默认为 False。当无法访问 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 应用程序中的任何错误都将显示在警报模态框中并打印在浏览器控制台日志中。它们也将在 gr.load() 此应用程序的下游应用程序的警报模态框中显示。

🔗
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 | Path | None
default = None

如果提供了文件路径(.png、.gif 或 .ico),它将用作网页的 favicon。

🔗
ssl_keyfile: str | None
default = None

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

🔗
ssl_certfile: str | None
default = None

如果提供了文件路径,将使用此文件作为 HTTPS 的签名证书。如果提供了 ssl_keyfile,则必须提供此文件。

🔗
ssl_keyfile_password: str | None
default = None

如果提供了密码,将与 SSL 证书一起用于 HTTPS。

🔗
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 时适用)。如果未提供,将使用 https://gradio.live 的默认 FRP 服务器。有关更多信息,请参阅 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 证书文件的路径。此参数不与 https://gradio.live 的默认 FRP 服务器一起使用。否则,您必须提供一个相对于当前工作目录的有效 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 (Progressive Web App)。如果设置为 None(默认行为),则此 Gradio 应用程序在 Spaces 上启动时将启用 PWA 功能,否则不启用。

🔗
mcp_server: bool | None
default = None

如果为 True,Gradio 应用程序将被设置为 MCP 服务器,并且文档化的函数将作为 MCP 工具添加。如果为 None(默认行为),则 GRADIO_MCP_SERVER 环境变量将用于确定是否应启用 MCP 服务器(在 Hugging Face Spaces 上为“True”)。

🔗
i18n: I18n | None
default = None

一个 I18n 实例,包含自定义翻译,用于翻译组件中的字符串(例如组件的标签或 Markdown 字符串)。此功能只能用于翻译前端的静态文本,而不能翻译后端的值。

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()` 之外所有事件的默认值),则在事件待处理时不允许任何提交。如果设置为“multiple”,则在待处理时允许无限次提交,而“always_last”(`.change()` 和 `.key_up()` 事件的默认值)则允许在待处理事件完成后进行第二次提交。

🔗
js: str | Literal[True] | None
default = None

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

🔗
concurrency_limit: int | None | Literal['default']
default = "default"

如果设置,这是此事件可以同时运行的最大数量。可以设置为 None 表示没有并发限制(任何数量的此事件都可以同时运行)。设置为“default”以使用默认并发限制(由 `Blocks.queue()` 中的 `default_concurrency_limit` 参数定义,其本身默认为 1)。

🔗
concurrency_id: str | None
default = None

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

🔗
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
default = 0.5
🔗
like_user_message: bool
default = False
🔗
key: int | str | tuple[int | str, ...] | None
default = None

此事件监听器的唯一键,用于 @gr.render()。如果设置,此值将标识在键相同时跨重新渲染的相同事件。

unload

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]

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

指南