构建演示
ChatInterface

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

Interface

TabbedInterface

ChatInterface

gradio.ChatInterface(fn, type="messages", ···)

描述

ChatInterface 是 Gradio 用于创建聊天机器人 UI 的高级抽象，它允许您用几行代码围绕聊天机器人模型创建一个基于 Web 的演示。只需一个参数：fn，它接受一个函数，该函数根据用户输入和聊天历史管理聊天机器人的响应。其他参数可用于控制演示的外观和行为。

示例用法

基本示例：一个能复述用户消息的聊天机器人

import gradio as gr

def echo(message, history):
    return message

demo = gr.ChatInterface(fn=echo, type="messages", examples=["hello", "hola", "merhaba"], title="Echo Bot")
demo.launch()

自定义聊天机器人：一个带有自定义 `gr.Chatbot` 的 `gr.ChatInterface`，其中包括一个占位符以及点赞/点踩按钮。当 `.like()` 事件附加到 `gr.Chatbot` 时，点赞/点踩按钮会自动添加。为了将事件监听器附加到您的自定义聊天机器人，请像这样将 `gr.Chatbot` 和 `gr.ChatInterface` 包装在 `gr.Blocks` 中

import gradio as gr

def yes(message, history):
    return "yes"

def vote(data: gr.LikeData):
    if data.liked:
        print("You upvoted this response: " + data.value["value"])
    else:
        print("You downvoted this response: " + data.value["value"])

with gr.Blocks() as demo:
    chatbot = gr.Chatbot(placeholder="<strong>Your Personal Yes-Man</strong><br>Ask Me Anything")
    chatbot.like(vote, None, None)
    gr.ChatInterface(fn=yes, type="messages", chatbot=chatbot)
    
demo.launch()

初始化

🔗

fn: Callable

要封装聊天界面的函数。通常（假设 `type` 设置为“messages”），该函数应接受两个参数：表示输入消息的 `str` 和一个 OpenAI 风格的字典 `list`：{"role": "user" | "assistant", "content": `str` | {"path": `str`} | `gr.Component`} 表示聊天历史。该函数应返回/生成一个 `str`（用于简单消息）、一个受支持的 Gradio 组件（例如，gr.Image 返回图像）、一个 `dict`（用于完整的 OpenAI 风格消息响应），或此类消息的 `list`。

🔗

multimodal: bool

默认值 = False

如果为 True，聊天界面将使用 `gr.MultimodalTextbox` 组件作为输入，该组件允许上传多媒体文件。如果为 False，聊天界面将使用 `gr.Textbox` 组件作为输入。如果此值为 True，则 `fn` 的第一个参数不应接受 `str` 消息，而应接受包含“text”和“files”键的 `dict` 消息。

🔗

type: Literal['messages', 'tuples'] | None

默认值 = None

传递到 `fn` 的聊天历史参数中的消息格式。如果为“messages”，则将历史记录作为字典列表传递，其中包含 OpenAI 风格的“role”和“content”键。“content”键的值应为以下之一——（1）有效的 Markdown 字符串（2）包含“path”键和对应要显示的文件值的字典（3）Gradio 组件实例：目前支持 gr.Image、gr.Plot、gr.Video、gr.Gallery、gr.Audio 和 gr.HTML。“role”键应为“user”或“assistant”之一。任何其他角色将不会显示在输出中。如果此参数为“tuples”（已弃用），则将聊天历史记录作为 `list[list[str | None | tuple]]` 传递，即一个列表的列表。内部列表应包含 2 个元素：用户消息和响应消息。

🔗

chatbot: Chatbot | None

默认值 = None

用于聊天界面的 `gr.Chatbot` 组件实例，如果您想自定义聊天机器人属性。如果未提供，将创建一个默认的 `gr.Chatbot` 组件。

🔗

textbox: Textbox | MultimodalTextbox | None

默认值 = None

用于聊天界面的 `gr.Textbox` 或 `gr.MultimodalTextbox` 组件实例，如果您想自定义文本框属性。如果未提供，将创建一个默认的 `gr.Textbox` 或 `gr.MultimodalTextbox` 组件。

🔗

additional_inputs: str | Component | list[str | Component] | None

默认值 = None

用作聊天机器人附加输入的 Gradio 组件实例（或其字符串快捷方式）的一个实例或列表。如果组件尚未在周围的 Blocks 中渲染，则组件将显示在聊天机器人下方的一个折叠面板中。这些组件的值将作为参数在聊天历史之后依次传递给 `fn`。

🔗

additional_inputs_accordion: str | Accordion | None

默认值 = None

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

🔗

additional_outputs: Component | list[Component] | None

默认值 = None

用作聊天函数附加输出的 Gradio 组件实例（或其列表）。这些必须是已在同一 Blocks 范围内定义的组件。如果提供，聊天函数应为这些组件返回附加值。请参阅 demo/chatinterface_artifacts。

🔗

editable: bool

默认值 = False

如果为 True，用户可以编辑过去的消息以重新生成响应。

🔗

examples: list[str] | list[MultimodalValue] | list[list] | None

默认值 = None

函数的示例输入；如果提供，则显示在聊天机器人中，可以点击以填充聊天机器人输入。应为表示纯文本示例的字符串列表，或表示多模态示例的字典列表（包含 `text` 和 `files` 键）。如果提供了 `additional_inputs`，则示例必须是列表的列表，其中每个内部列表的第一个元素是字符串或字典示例消息，其余元素是附加输入的示例值——在这种情况下，示例将显示在聊天机器人下方。

🔗

example_labels: list[str] | None

默认值 = None

示例的标签，用于代替示例本身显示。如果提供，应为与示例列表长度相同的字符串列表。仅当示例显示在聊天机器人中时有效（即未提供 `additional_inputs` 时）。

🔗

example_icons: list[str] | None

默认值 = None

示例的图标，显示在示例上方。如果提供，应为与示例列表长度相同的字符串 URL 或本地路径列表。仅当示例显示在聊天机器人中时有效（即未提供 `additional_inputs` 时）。

🔗

run_examples_on_click: bool

默认值 = True

如果为 True，单击示例将通过聊天机器人函数运行示例，并在聊天机器人中显示响应。如果为 False，单击示例只会将示例消息填充到聊天机器人输入中。如果 `cache_examples` 为 True，则无效。

🔗

cache_examples: bool | None

默认值 = None

如果为 True，则在服务器中缓存示例，以加快示例运行时。HuggingFace Spaces 中的默认选项为 True。其他地方的默认选项为 False。请注意，示例与 Gradio 的 `queue()` 分开缓存，因此某些功能（例如 `gr.Progress()`、`gr.Info()`、`gr.Warning()` 等）将不会在 Gradio 的 UI 中显示已缓存的示例。

🔗

cache_mode: Literal['eager', 'lazy'] | None

默认值 = None

如果为“eager”，所有示例在应用程序启动时缓存。如果为“lazy”，示例在任何用户首次使用应用程序后为所有用户缓存。如果为 None，将使用已定义的 GRADIO_CACHE_MODE 环境变量，或默认使用“eager”。

🔗

title: str | I18nData | None

默认值 = None

界面的标题；如果提供，将以大字体显示在聊天机器人上方。当在浏览器窗口中打开时，也用作标签页标题。

🔗

description: str | None

默认值 = None

界面的描述；如果提供，将以常规字体显示在聊天机器人上方和标题下方。接受 Markdown 和 HTML 内容。

🔗

theme: Theme | str | None

默认值 = None

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

🔗

flagging_mode: Literal['never', 'manual'] | None

默认值 = None

“never”、“manual”之一。如果为“never”，用户将看不到标记输入和输出的按钮。如果为“manual”，用户将看到标记按钮。

🔗

flagging_options: list[str] | tuple[str, ...] | None

默认值 = ('Like', 'Dislike')

一个字符串列表，表示用户在标记消息时可以选择的选项。默认为 ["Like", "Dislike"]。这两个区分大小写的字符串将分别显示为每个机器人消息旁边的“竖拇指”和“倒拇指”图标，但任何其他字符串将显示在单独的旗帜图标下。

🔗

flagging_dir: str

默认值 = ".gradio/flagged"

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

🔗

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 应为单个 JS 函数的形式。此函数将在页面加载时自动执行。为了获得更大的灵活性，请使用 head 参数在 <script> 标签内插入 JS。

🔗

head: str | None

默认值 = None

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

🔗

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

默认值 = None

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

🔗

analytics_enabled: bool | None

默认值 = None

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

🔗

autofocus: bool

默认值 = True

如果为 True，页面加载时自动聚焦到文本框。

🔗

autoscroll: bool

默认值 = True

如果为 True，当新消息出现时，将自动滚动到聊天机器人底部，除非用户向上滚动。如果为 False，将不会自动滚动到聊天机器人底部。

🔗

submit_btn: str | bool | None

默认值 = True

如果为 True，将在文本框内显示一个带有提交图标的提交按钮。如果为字符串，将使用该字符串作为提交按钮文本代替图标。如果为 False，将不显示提交按钮。

🔗

stop_btn: str | bool | None

默认值 = True

如果为 True，在生成器执行期间将显示一个带有停止图标的按钮，以停止生成。如果为字符串，将使用该字符串作为提交按钮文本代替停止图标。如果为 False，将不显示停止按钮。

🔗

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

默认值 = "default"

如果设置，这是可以同时运行的聊天机器人提交的最大数量。可以设置为 None 表示没有限制（任意数量的聊天机器人提交可以同时运行）。设置为“default”以使用默认并发限制（由 `.queue()` 中的 `default_concurrency_limit` 参数定义，默认为 1）。

🔗

delete_cache: tuple[int, int] | None

默认值 = None

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

🔗

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

默认值 = "minimal"

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

🔗

fill_height: bool

默认值 = True

如果为 True，聊天界面将展开到窗口高度。

🔗

fill_width: bool

默认值 = False

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

🔗

api_name: str | Literal[False]

默认值 = "chat"

定义聊天端点在 API 文档中如何显示。可以是字符串或 False。如果设置为字符串，则聊天端点将在 API 文档中以给定名称公开。如果为 False，则聊天端点将不会在 API 文档中公开，并且下游应用程序（包括那些 `gr.load` 此应用程序的应用程序）将无法调用此聊天端点。

🔗

save_history: bool

默认值 = False

如果为 True，将聊天历史保存到浏览器的本地存储，并在侧面板中显示以前的对话。

演示

import random import gradio as gr def random_response(message, history): return random.choice(["Yes", "No"]) demo = gr.ChatInterface(random_response, type="messages", autofocus=False) if __name__ == "__main__": demo.launch()

import random
import gradio as gr

def random_response(message, history):
    return random.choice(["Yes", "No"])

demo = gr.ChatInterface(random_response, type="messages", autofocus=False)

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

import time import gradio as gr def slow_echo(message, history): for i in range(len(message)): time.sleep(0.05) yield "You typed: " + message[: i + 1] demo = gr.ChatInterface( slow_echo, type="messages", flagging_mode="manual", flagging_options=["Like", "Spam", "Inappropriate", "Other"], save_history=True, ) if __name__ == "__main__": demo.launch()

import time
import gradio as gr

def slow_echo(message, history):
    for i in range(len(message)):
        time.sleep(0.05)
        yield "You typed: " + message[: i + 1]

demo = gr.ChatInterface(
    slow_echo,
    type="messages",
    flagging_mode="manual",
    flagging_options=["Like", "Spam", "Inappropriate", "Other"],
    save_history=True,
)

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

import gradio as gr python_code = """ def fib(n): if n <= 0: return 0 elif n == 1: return 1 else: return fib(n-1) + fib(n-2) """ js_code = """ function fib(n) { if (n <= 0) return 0; if (n === 1) return 1; return fib(n - 1) + fib(n - 2); } """ def chat(message, history): if "python" in message.lower(): return "Type Python or JavaScript to see the code.", gr.Code(language="python", value=python_code) elif "javascript" in message.lower(): return "Type Python or JavaScript to see the code.", gr.Code(language="javascript", value=js_code) else: return "Please ask about Python or JavaScript.", None with gr.Blocks() as demo: code = gr.Code(render=False) with gr.Row(): with gr.Column(): gr.Markdown("<center><h1>Write Python or JavaScript</h1></center>") gr.ChatInterface( chat, examples=["Python", "JavaScript"], additional_outputs=[code], type="messages" ) with gr.Column(): gr.Markdown("<center><h1>Code Artifacts</h1></center>") code.render() demo.launch()

import gradio as gr

python_code = """
def fib(n):
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return fib(n-1) + fib(n-2)
"""

js_code = """
function fib(n) {
    if (n <= 0) return 0;
    if (n === 1) return 1;
    return fib(n - 1) + fib(n - 2);
}
"""

def chat(message, history):
    if "python" in message.lower():
        return "Type Python or JavaScript to see the code.", gr.Code(language="python", value=python_code)
    elif "javascript" in message.lower():
        return "Type Python or JavaScript to see the code.", gr.Code(language="javascript", value=js_code)
    else:
        return "Please ask about Python or JavaScript.", None

with gr.Blocks() as demo:
    code = gr.Code(render=False)
    with gr.Row():
        with gr.Column():
            gr.Markdown("Write Python or JavaScript")
            gr.ChatInterface(
                chat,
                examples=["Python", "JavaScript"],
                additional_outputs=[code],
                type="messages"
            )
        with gr.Column():
            gr.Markdown("Code Artifacts")
            code.render()

demo.launch()

指南

快速创建聊天机器人

分享您的应用

←

Interface

TabbedInterface

→