1. 构建演示
  2. Interface

刚开始使用 Gradio？ 从这里开始： 入门指南

查看 发布历史

ChatInterface

→

Interface

gradio.Interface(···)

描述

Interface 是 Gradio 的主要高级类，它允许您用几行代码为机器学习模型（或任何 Python 函数）创建一个基于 Web 的 GUI/演示。您必须指定三个参数：(1) 要为其创建 GUI 的函数，(2) 所需的输入组件，以及 (3) 所需的输出组件。其他参数可用于控制演示的外观和行为。

示例用法

import gradio as gr

def image_classifier(inp):
    return {'cat': 0.3, 'dog': 0.7}

demo = gr.Interface(fn=image_classifier, inputs="image", outputs="label")
demo.launch()

初始化

参数
🔗 
fn: Callable

用于包装界面的函数。通常是机器学习模型的预测函数。函数的每个参数对应一个输入组件，函数应返回单个值或值元组，元组中的每个元素对应一个输出组件。

🔗 
inputs: str | Component | list[str | Component] | None

单个 Gradio 组件或 Gradio 组件列表。组件可以作为实例化的对象传递，也可以通过它们的字符串快捷方式引用。输入组件的数量应与 fn 的参数数量匹配。如果设置为 None，则只显示输出组件。

🔗 
outputs: str | Component | list[str | Component] | None

单个 Gradio 组件或 Gradio 组件列表。组件可以作为实例化的对象传递，也可以通过它们的字符串快捷方式引用。输出组件的数量应与 fn 返回的值的数量匹配。如果设置为 None，则只显示输入组件。

🔗 
examples: list[Any] | list[list[Any]] | str | None
默认 = None

函数的示例输入；如果提供，将显示在 UI 组件下方，并可点击以填充界面。应为嵌套列表，外层列表包含示例，每个内层列表包含与每个输入组件对应的输入。也可以提供指向示例目录的字符串路径，但它应位于运行 Gradio 应用程序的 Python 文件所在的目录内。如果存在多个输入组件且提供了目录，则目录中必须存在 log.csv 文件以链接相应的输入。

🔗 
cache_examples: bool | None
默认 = None

如果为 True，则将示例缓存到服务器以获得快速的示例运行时。如果为“lazy”（懒加载），则示例将在第一次使用后（由任何应用程序用户使用）进行缓存（针对所有应用程序用户）。如果为 None，则将使用 GRADIO_CACHE_EXAMPLES 环境变量，该变量应为“true”或“false”。在 HuggingFace Spaces 中，此参数默认为 True（只要 `fn` 和 `outputs` 也已提供）。请注意，示例是与 Gradio 的 queue() 分开缓存的，因此某些功能（如 gr.Progress()、gr.Info()、gr.Warning() 等）将不会在 Gradio UI 中显示给缓存的示例。

🔗 
cache_mode: Literal['eager', 'lazy'] | None
默认 = None

如果为“lazy”（懒加载），则在首次使用后缓存示例。如果为“eager”（急切加载），则在应用程序启动时缓存所有示例。如果为 None，将使用 GRADIO_CACHE_MODE 环境变量（如果已定义），否则默认为“eager”（急切加载）。在 HuggingFace Spaces 中，此参数默认为“eager”（急切加载），除非是 ZeroGPU Spaces，在这种情况下，它默认为“lazy”（懒加载）。

🔗 
examples_per_page: int
默认 = 10

如果提供了示例，每页显示多少个。

🔗 
example_labels: list[str] | None
默认 = None

每个示例的标签列表。如果提供，此列表的长度应与示例的数量相同，并且这些标签将用于 UI，而不是渲染示例值。

🔗 
preload_example: int | Literal[False]
默认 = 0

如果提供一个整数（且示例正在急切地缓存，并且没有输入组件提供开发者定义的 `value`），则在 Gradio 应用程序首次加载时，将预加载示例列表中索引处的示例。如果为 False，则不会预加载任何示例。

🔗 
live: bool
默认 = False

如果任何输入发生更改，界面是否应自动重新运行。

🔗 
title: str | I18nData | None
默认 = None

界面的标题；如果提供，则显示在输入和输出组件上方，字体较大。在浏览器窗口中打开时也用作选项卡标题。

🔗 
description: str | None
默认 = None

界面的描述；如果提供，则显示在输入和输出组件上方，标题下方，字体正常。接受 Markdown 和 HTML 内容。

🔗 
article: str | None
默认 = None

一个扩展的文章，解释界面；如果提供，则显示在输入和输出组件下方，字体正常。接受 Markdown 和 HTML 内容。如果它是可下载远程文件的 HTTP(S) 链接，则将显示该文件内容。

🔗 
flagging_mode: Literal['never'] | Literal['auto'] | Literal['manual'] | None
默认 = None

“never”（从不）、“auto”（自动）或“manual”（手动）之一。如果为“never”（从不）或“auto”（自动），用户将看不到标记输入的按钮和输出。如果为“manual”（手动），用户将看到一个标记按钮。如果为“auto”（自动），每次用户提交的输入都会被自动标记，以及生成的输出。如果为“manual”（手动），当用户点击标记按钮时，输入和输出都会被标记。此参数可以通过环境变量 GRADIO_FLAGGING_MODE 设置；否则默认为“manual”（手动）。

🔗 
flagging_options: list[str] | list[tuple[str, str]] | None
默认 = None

如果提供，允许用户在标记时从选项列表中进行选择。仅当 flagging_mode 为“manual”（手动）时适用。可以是形式为 (label, value) 的元组列表，其中 label 是按钮上显示的字符串，value 是标记 CSV 中存储的字符串；或者可以是字符串列表 ["X", "Y"]，在这种情况下，值是字符串列表，标签是 ["Flag as X", "Flag as Y"] 等。

🔗 
flagging_dir: str
默认 = ".gradio/flagged"

存储标记数据的目录路径。如果目录不存在，则会创建它。

🔗 
flagging_callback: FlaggingCallback | None
默认 = None

None 或 FlaggingCallback 的子类实例，当某个示例被标记时将被调用。如果设置为 None，将创建一个 gradio.flagging.CSVLogger 的实例，并将日志保存在 flagging_dir 的本地 CSV 文件中。默认为 None。

🔗 
analytics_enabled: bool | None
默认 = None

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

🔗 
batch: bool
默认 = False

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

🔗 
max_batch_size: int
默认 = 4

如果 batch=True，则一起批处理的最大输入数量（仅当从队列调用时相关）

🔗 
api_visibility: Literal['public', 'private', 'undocumented']
默认 = "public"

控制预测端点的可见性。可以是“public”（显示在 API 文档中并可调用）、“private”（隐藏在 API 文档中且不可调用）或“undocumented”（隐藏在 API 文档中但可调用）。

🔗 
api_name: str | None
默认 = None

定义预测端点在 API 文档中的外观。可以是一个字符串或 None。如果设置为字符串，则端点将以给定名称显示在 API 文档中。如果为 None，则使用函数的名称。

🔗 
api_description: str | None | Literal[False]
默认 = None

API 端点的描述。可以是字符串、None 或 False。如果设置为字符串，则该端点将在 API 文档中以给定描述显示。如果为 None，则使用函数的 docstring 作为 API 端点描述。如果为 False，则 API 文档中不会显示任何描述。

🔗 
allow_duplication: bool
默认 = False

如果为 True，则将在 Hugging Face Spaces 上显示“Duplicate Spaces”按钮。

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

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

🔗 
additional_inputs: str | Component | list[str | Component] | None
默认 = None

单个 Gradio 组件或 Gradio 组件列表。组件可以作为实例化的对象传递，也可以通过它们的字符串快捷方式引用。这些组件将在主输入组件下方的折叠面板中渲染。默认情况下，不会显示其他输入组件。

🔗 
additional_inputs_accordion: str | Accordion | None
默认 = None

如果提供字符串，这是用于包含其他输入的 `gr.Accordion` 的标签。也可以提供 `gr.Accordion` 对象来配置包含其他输入的容器的其他属性。默认为 `gr.Accordion(label="Additional Inputs", open=False)`。此参数仅在提供了 `additional_inputs` 时使用。

🔗 
submit_btn: str | Button
默认 = "Submit"

用于提交输入的按钮。默认为 `gr.Button("Submit", variant="primary")`。此参数不适用于仅输出的界面，在这种情况下，提交按钮始终显示“Generate”。可以设置为字符串（作为按钮标签）或 `gr.Button` 对象（允许更多自定义）。

🔗 
stop_btn: str | Button
默认 = "Stop"

用于停止界面的按钮。默认为 `gr.Button("Stop", variant="stop", visible=False)`。可以设置为字符串（作为按钮标签）或 `gr.Button` 对象（允许更多自定义）。

🔗 
clear_btn: str | Button | None
默认 = "Clear"

用于清除输入的按钮。默认为 `gr.Button("Clear", variant="secondary")`。可以设置为字符串（作为按钮标签）或 `gr.Button` 对象（允许更多自定义）。可以设置为 None，这将隐藏按钮。

🔗 
delete_cache: tuple[int, int] | None
默认 = None

一个元组，对应 [frequency, age]，均以秒为单位。每隔 `frequency` 秒，此 Blocks 实例创建的临时文件将被删除，如果文件创建时间已超过 `age` 秒。例如，将其设置为 (86400, 86400) 将每天删除临时文件。服务器重启时将完全删除缓存。如果为 None，则不会发生缓存删除。

🔗 
show_progress: Literal['full', 'minimal', 'hidden']
默认 = "full"

事件运行时如何显示进度动画：“full”显示一个覆盖输出组件区域的加载指示器，并在右上角显示运行时信息，“minimal”仅显示运行时信息，“hidden”不显示任何进度动画。

🔗 
fill_width: bool
默认 = False

是否水平扩展以完全填充容器。如果为 False，则居中并限制应用程序的最大宽度。

🔗 
time_limit: int | None
默认 = 30

流运行的时间限制。默认为 30 秒。仅当界面为实时且输入组件设置为“streaming=True”时，才用于流式传输图像或音频。

🔗 
stream_every: float
默认 = 0.5

流块发送到后端的延迟（以秒为单位）。默认为 0.5 秒。仅当界面为实时且输入组件设置为“streaming=True”时，才用于流式传输图像或音频。

🔗 
validator: Callable | None
默认 = None

一个函数，它接收输入并可以选择为每个输入返回一个 `gr.validate()` 对象。

演示

方法

launch 

gradio.Interface.launch(···)

Description

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

Example Usage 

import gradio as gr
def reverse(text):
    return text[::-1]
demo = gr.Interface(reverse, "text", "text")
demo.launch(share=True, auth=("username", "password"))
参数
🔗 
inline: bool | None
默认 = None

是否在 Gradio 应用程序内嵌 iframe 中显示。在 Python notebook 中默认为 True；否则为 False。

🔗 
inbrowser: bool
默认 = False

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

🔗 
share: bool | None
默认 = None

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

🔗 
debug: bool
默认 = False

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

🔗 
max_threads: int
默认 = 40

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

🔗 
auth: Callable[[str, str], bool] | tuple[str, str] | list[tuple[str, str]] | None
默认 = None

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

🔗 
auth_message: str | None
默认 = None

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

🔗 
prevent_thread_lock: bool
默认 = False

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

🔗 
show_error: bool
默认 = False

如果为 True，则 Gradio 应用程序中的任何错误都将显示在警报模态框中，并在浏览器控制台日志中打印。它们还将显示在 `gr.load()` 此应用程序的下游应用程序的警报模态框中。

🔗 
server_name: str | None
默认 = None

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

🔗 
server_port: int | None
默认 = None

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

🔗 
height: int
默认 = 500

包含 Gradio 应用程序的 iframe 元素的像素高度（如果 inline=True 时使用）

🔗 
width: int | str
默认 = "100%"

包含 Gradio 应用程序的 iframe 元素的像素宽度（如果 inline=True 时使用）

🔗 
favicon_path: str | Path | None
默认 = None

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

🔗 
ssl_keyfile: str | None
默认 = None

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

🔗 
ssl_certfile: str | None
默认 = None

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

🔗 
ssl_keyfile_password: str | None
默认 = None

如果提供密码，将与 HTTPS 的 SSL 证书一起使用。

🔗 
ssl_verify: bool
默认 = True

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

🔗 
quiet: bool
默认 = False

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

🔗 
allowed_paths: list[str] | None
默认 = None

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

🔗 
blocked_paths: list[str] | None
默认 = None

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

🔗 
root_path: str | None
默认 = None

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

🔗 
app_kwargs: dict[str, Any] | None
默认 = None

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

🔗 
state_session_capacity: int
默认 = 10000

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

🔗 
share_server_address: str | None
默认 = None

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

🔗 
share_server_protocol: Literal['http', 'https'] | None
默认 = None

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

🔗 
share_server_tls_certificate: str | None
默认 = None

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

🔗 
auth_dependency: Callable[[fastapi.Request], str | None] | None
默认 = None

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

🔗 
max_file_size: str | int | None
默认 = None

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

🔗 
enable_monitoring: bool | None
默认 = None

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

🔗 
strict_cors: bool
默认 = True

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

🔗 
node_server_name: str | None
默认 = None
🔗 
node_port: int | None
默认 = None
🔗 
ssr_mode: bool | None
默认 = None

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

🔗 
pwa: bool | None
默认 = None

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

🔗 
mcp_server: bool | None
默认 = None

如果为 True，Gradio 应用程序将被设置为 MCP 服务器，并且文档化的函数将被添加为 MCP 工具。如果为 None（默认行为），则将使用 GRADIO_MCP_SERVER 环境变量来确定是否启用 MCP 服务器。

🔗 
i18n: I18n | None
默认 = None

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

🔗 
theme: Theme | str | None
默认 = None

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

🔗 
css: str | None
默认 = None

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

🔗 
css_paths: str | Path | list[str | Path] | None
默认 = None

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

🔗 
js: str | Literal[True] | None
默认 = None

自定义 JS 作为代码字符串。JS 代码将在页面加载时自动执行。为了获得更大的灵活性，可以使用 `head` 参数在 `

gradio