前言

本系列文章主要介绍WEB界面工具Gradio。Gradio是Hugging Face发布的简易webui开发框架，它基于FastAPI和svelte，可以使用机器学习模型、python函数或API开发多功能界面和部署人工智能模型，是当前热门的非常易于展示机器学习大语言模型LLM及扩散模型DM的WebUI框架。
本系列文章分为前置概念、安装运行与部署、Gradio高级特性、基础功能实战和高级功能实战五部分。第一部分前置概念：先介绍Gradio的详细技术架构、历史、应用场景、与其他框架Gradio/NiceGui/StreamLit/Dash/PyWebIO的区别，然后详细介绍了著名的资源网站Hugging Face，因为Gradio演示中经常用到Hugging Face的models及某些场景需要部署在spaces，这里主要包括三类资源models/datasets/spaces的使用以及六类工具库transformers/diffusers/datasets/PEFT/accelerate/optimum实战。第二部分安装运行与部署：讲解多种不同的安装、运行和部署方式，安装包括Linux/Win/Mac三类系统安装，运行包括普通方式和热重载方式，部署包括本地部署、HuggingFace托管、FastAPI挂载和Gradio-Lite浏览器集成。第三部分Gradio高级特性：按照先整体再细节的逻辑，讲解Gradio的多种高级特性，包括三种Gradio Clients（python/javascript/curl）、Gradio Tools、Gradio的模块架构和环境变量等，方便读者对Gradio整体把握。第四部分基础功能实战：深入细节，也是本系列文章的核心，实践基础功能Interface、Blocks和Additional Features。第五部分高级功能实战：详解高级功能Chatbots、Data Science And Plots和Streaming。
本系列文章讲解细致，涵盖Gradio大部分组件和功能，代码均可运行并附有大量运行截图，方便读者理解并应用到开发中，Gradio一定会成为每个技术人员实现各种奇思妙想的最称手工具。

本系列文章目录如下：

1. 《Gradio全解1——Gradio简介》
2. 《Gradio全解1——Gradio的安装与运行》
3. 《Gradio全解2——剖析Hugging Face：详解三类资源models/datasets/spaces》
4. 《Gradio全解3——剖析Hugging Face：实战六类工具库transformers/diffusers/datasets/PEFT/accelerate/optimum》
5. 《Gradio全解4——Gradio的3+1种部署方式实践》
6. 《Gradio全解4——浏览器集成Gradio-Lite》
7. 《Gradio全解5——Gradio Client：python客户端》
8. 《Gradio全解5——Gradio Client：javascript客户端》
9. 《Gradio全解5——Gradio Client：curl客户端》
10. 《Gradio全解6——Gradio Tools：将Gradio用于LLM Agents》
11. 《Gradio全解7——Gradio库的模块架构和环境变量》
12. 《Gradio全解8——Interface：高级抽象界面类（上）》
13. 《Gradio全解8——Interface：高级抽象界面类（下）》
14. 《Gradio全解9——Blocks：底层区块类（上）》
15. 《Gradio全解9——Blocks：底层区块类（下）》
16. 《Gradio全解10——Additional Features：补充特性（上）》
17. 《Gradio全解10——Additional Features：补充特性（下）》
18. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（1）》
19. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（2）》
20. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（3）》
21. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（4）》
22. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（5）》
23. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（6）》
24. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（7）》
25. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（8）》
26. 《Gradio全解11——Chatbot：融合大模型的多模态聊天机器人（9）》
27. 《Gradio全解系列12——Data Science And Plots：数据科学与绘图》
28. 《Gradio全解13——Streaming：数据流（上）》
29. 《Gradio全解13——Streaming：数据流（下）》

本篇摘要

本篇介绍如何使用Gradio创建聊天机器人，主要内容包括gr.ChatInterface快速创建Chatbot、与流行LLM库及API结合、组件Chatbot及消息格式ChatMessage、使用Blocks创建Chatbot、Chatbot的特殊Events、使用Agents和Tools智能代理工具、通过Gradio应用创建Discord Bot/Slack Bot/Website Widget。

11. Chatbot：融合大模型的多模态聊天机器人

本章介绍如何使用Gradio创建聊天机器人。聊天机器人是大型语言模型（LLMs）的一个流行应用，通过Gradio，我们可以轻松构建LLM演示并与其它用户分享，或者自己使用直观的聊天机器人界面进行开发尝试。本章主要内容包括gr.ChatInterface快速创建Chatbot、与流行LLM库及API结合、组件Chatbot及消息格式ChatMessage、使用Blocks创建Chatbot、Chatbot的特殊Events、使用Agents和Tools智能代理工具、通过Gradio应用创建Discord Bot/Slack Bot/Website Widget。

11.3 组件Chatbot及ChatMessage

本节我们将首先学习聊天机器人组件Chatbot，包括API参数、参数type演示和使用Gradio组件，然后学习消息格式ChatMessage，包括API参数、简单演示和metadata键。

11.3.1 Chatbot：聊天机器人组件

Chatbot聊天机器人组件的调用格式为：gradio.Chatbot(type="messages", ···)，这可以创建一个聊天机器人，用于显示用户提交的消息和回复。该组件通常用作输出组件，支持部分Markdown语法，包括加粗、斜体、代码、表格等；同时支持音频、视频和图片文件，这些文件会在聊天机器人中显示，而其他类型的文件则会显示为链接。下面讲述该组件的API参数和用法。

1. API参数

Chatbot较为重要或其独有的API参数如下表所示，更详细的API信息请参考官方文档：https://www.gradio.app/docs/gradio/chatbot。

Parameters	style	default	description
value	list[MessageDict | Message] | TupleFormat | Callable | None	None	默认显示在聊天机器人中的消息列表，其中每条消息的格式为 {“role”: “user”, “content”: “Help me.”}。role可以是"user"、“assistant"或"system” 之一；content可以是文本或者是通过Gradio组件传递的媒体文件，例如{“content”: gr.Image(“lion.jpg”)}。如果该值为可调用对象，则每当应用加载时都会调用该函数以设置组件的初始值。
type	Literal[‘messages’, ‘tuples’] | None	None	传入fn的chat history参数的消息格式。如果为"messages"，则传递的值是一个字典列表，字典中包含OpenAI风格的 “role” 和 “content” 键。“content"键的值应为以下之一：（1）有效的Markdown字符串；（2）包含"path” 键的字典，其值对应要显示的文件；（3）Gradio组件的实例，目前支持Image、Plot、Video、Gallery、Audio和HTML。“role” 键应为 ‘user’ 或 ‘assistant’ 之一，其他角色将不会在输出中显示。如果此参数为’tuples’，则期望传入一个list[list[str | None | tuple]]，即一个列表的列表，内部列表应包含2个元素：用户消息和响应消息，但此格式已被弃用。
container	bool	True	如果为True，则会将组件放置在一个容器中——为边框周围提供一些额外的内边距。
editable	Literal[‘user’, ‘all’] | None	None	允许用户编辑聊天机器人中的哪种消息。如果设置为"user"，则允许编辑用户消息；如果设置为"all"，则还允许编辑助手消息。
latex_delimiters	list[dict[str, str | bool]] | None	None	一个字典列表，格式为{“left”: 左分隔符 (str), “right”: 右分隔符 (str), “display”: 是否在新行显示 (bool)}，用于渲染LaTeX表达式。如果未提供，latex_delimiters将设置为[{“left”:“$$”, “right”:“$$”, “display”: True }]，因此只有用$$分隔符包裹的表达式才会被渲染为LaTeX，并且在新行中显示；还可以传入一个空列表以禁用LaTeX渲染。更多信息请参阅KaTeX文档：https://katex.org/docs/autorender.html。
show_share_button	bool | None	None	如果设置为True，将在组件的角落显示一个分享图标，允许用户将输出分享到Hugging Face Spaces Discussions。如果设置为False，不会显示分享图标。如果设置为None（默认行为），则当Gradio应用在Spaces上启动时图标会显示，否则不会显示。
show_copy_button	bool	False	如果设置为True，会在每个聊天机器人信息中显示一个copy按钮。
show_copy_all_button	<class ‘inspect._empty’>	False	如果设置为True，将显示一个“copy all”按钮，用于将所有chatbot消息复制到剪贴板。
allow_file_downloads	<class ‘inspect._empty’>	True	如果设置为True，将为包含媒体文件的聊天机器人消息显示download按钮。
avatar_images	tuple[str | Path | None, str | Path | None] | None	None	一个包含两个头像图片路径或URL的元组，分别用于用户和机器人（按此顺序）。如果不想显示用户或机器人的头像，可以传入None。图片路径必须在Gradio应用的工作目录内，或者是一个外部URL。
sanitize_html	bool	True	如果设置为False，将禁用聊天机器人消息的HTML sanitization（HTML净化）。不建议这样做，因为这可能会导致安全漏洞。
render_markdown	bool	True	如果设置为False，将禁用聊天机器人消息的Markdown渲染。
line_breaks	bool	True	如果设置为True（默认），将在聊天机器人消息中启用GitHub风格的Markdown换行符；如果设置为False，单行换行符将被忽略。它仅在render_markdown为True时生效。
feedback_options	list[str] | tuple[str, …] | None	(‘Like’, ‘Dislike’)	一个字符串列表，表示将向用户显示的反馈选项。区分大小写的字符串"Like"和"Dislike"将显示为拇指图标，而其他任何选项将显示在一个单独的旗帜图标下。
feedback_value	list[str | None] | None	None	一个字符串列表，表示整个聊天的反馈状态，仅在type="messages"时生效。列表中的每个条目按顺序对应一条助手消息，其值为用户给出的反馈（例如 “Like”、“Dislike” 或任何自定义反馈选项），如果该消息未收到反馈，则值为None。
layout	Literal[‘panel’, ‘bubble’] | None	“bubble”	如果设置为"panel"，将以LLM风格布局显示chatbot；如果设置为"bubble"，将以消息气泡的形式显示chatbot，用户和机器人的消息会交替显示在两侧。默认值为"bubble"。
group_consecutive_messages	bool	True	如果设置为True，将把来自同一角色的连续消息显示在同一个气泡中。如果设置为False，则每条消息将显示在单独的气泡中。默认值为True。
examples	list[ExampleMessage] | None	None	一个示例消息列表，用于在显示任何用户/助手消息之前展示在聊天机器人中。每个示例应为一个字典，包含以下可选键：（1）“text”：表示点击示例时应填充到聊天机器人中的消息；（2）“files”：其值应为一个文件列表，用于填充到聊天机器人中；（3）“icon”：其值应为文件路径或图片URL，用于在示例框中显示；（4）“display_text”：其值应为示例框中显示的文本，如果未提供"display_text"，则将显示"text"的值。

2. 参数type演示

Chatbot组件众多API参数中最重要的是type，下面以type为例讲述Chatbot用法。Chatbot组件接受的数据格式由type参数决定，该参数可以取两个值：‘tuples’ 和 ‘messages’，其中’tuples’类型已被弃用，并将在未来的Gradio版本中移除。如果type为 ‘messages’，则聊天机器人发送或接收的数据将是一个字典列表，每个字典包含role和content键。这种格式符合大多数LLM API（如 HuggingChat、OpenAI、Claude）的预期格式。说明如下：

• role：role键的值为’user’ 或 ‘assistant’，分别表示用户消息和小助手消息；
• content：content键的值可以是字符串（以Markdown/HTML渲染）、包含"path" 键的字典（其值对应要显示的文件）或Gradio组件（用于显示各类文件）。

简单演示如下：

import gradio as grhistory = [{"role": "assistant", content="How can I help you?"}{"role": "user", content="Can you make me a plot of quarterly sales?"}{"role": "assistant", content="I am happy to provide you that report and plot."}
]with gr.Blocks() as demo:gr.Chatbot(history, type='messages')demo.launch()

运行界面如下：

注意，虽然type中的tuples类型已被废弃，但目前版本（5.12.0）仍需要设置type=‘messages’，否则会报错：Error: ‘Data incompatible with tuples format. Each message should be a list of length 2.’

3. 使用Gradio组件

Chatbot组件支持在聊天机器人中使用许多核心Gradio组件（例如gr.Image、gr.Plot、gr.Audio和 gr.HTML）。只需在元组列表中包含这些组件之一即可，以下是一个示例：

import gradio as grdef load():return [("Here's an audio", gr.Audio("https://github.com/gradio-app/gradio/raw/main/test/test_files/audio_sample.wav")),("Here's an video", gr.Video("https://github.com/gradio-app/gradio/raw/main/demo/video_component/files/world.mp4"))]with gr.Blocks() as demo:chatbot = gr.Chatbot()button = gr.Button("Load audio and video")button.click(load, None, chatbot)demo.launch()

注意：这里的消息类型type为当前版本默认的tuples，保留此示例只是为展示tuples的用法，实际应用中还是使用messages，上例load的消息改为messages格式，如下：

return [{"role": "assistant", "content": "Here's an audio"}{"role": "assistant", "content": gr.Audio("https://github.com/gradio-app/gradio/raw/main/test/test_files/audio_sample.wav")}{"role": "assistant", "content": "Here's an video"}{"role": "assistant", "content": gr.Video("https://github.com/gradio-app/gradio/raw/main/demo/video_component/files/world.mp4")}
]

11.3.2 ChatMessage：聊天消息格式

在表示消息时，为了方便起见，可以使用ChatMessage组件，这样文本编辑器可以提供自动补全提示和类型检查。ChatMessage是一个数据类，用于表示Chatbot组件中的消息（type=“messages”），其调用格式为：gradio.ChatMessage(···)。

1. API参数

ChatMessage的API参数较少，如下表所示，或参考官方文档：https://www.gradio.app/docs/gradio/chatbot。

Parameters	style	default	description
content	str | FileData | Component | FileDataDict | tuple | list |		消息的内容，可以是字符串、文件或Gradio组件。
role	Literal[‘user’, ‘assistant’, ‘system’]	“assistant”	消息的角色，用于确定消息在chatbot中的对齐方式。可以是"user"、“assistant"或"system”，默认值为"assistant"。
metadata	MetadataDict | Metadata	_HAS_DEFAULT_FACTORY_CLASS()	消息的元数据，用于显示中间思考过程或工具使用情况。它应为一个字典，包含以下键：“title”（显示思考内容时为必填项）以及可选项：“id” 和"parent_id"（用于嵌套思考）、“duration”（显示思考的持续时间）、“status”（显示思考的状态）。
options	Optional[list[Option]]	None	消息的选项，是一个Option对象列表，每个对象是一个字典，包含以下键： “label”（选项中显示的文本）以及可选项：“value”（如果Option的值与标签不同，则返回该值）。

2. 简单演示

先看一个简单示例，将上一节演示的history内容替换为gr.ChatMessage，代码如下：

history = [gr.ChatMessage(role="assistant", content="How can I help you?"),gr.ChatMessage(role="user", content="Can you make me a plot of quarterly sales?"),gr.ChatMessage(role="assistant", content="I am happy to provide you that report and plot.")
]

运行界面同上，不再重复截图。

3. metadata键

除了role和content键之外，messages字典还接受一个metadata键，可以将它设置为生成响应时使用的任意相关工具的信息，这对于显示LLM代理的思考过程非常有用。目前metadata键接受一个包含单个键title的字典，它将会显示在一个可折叠的框中，其它设置请参考API表。以下是一个示例，展示了代理使用天气API工具来回答用户查询的思考过程：

import gradio as gr
def generate_response(message, history):history.append(gr.ChatMessage(role="user", content="input message: "+ message))history.append(gr.ChatMessage(role="assistant",content="The weather API says it is 20 degrees Celcius in San Francisco.",metadata={"title": "🛠️ Used tool Weather API", "id": 123, "parent_id": "think"}))return "", historywith gr.Blocks() as demo:chatbot  = gr.Chatbot(type="messages",value=[{"role": "user", "content": "What is the weather in San Francisco?"},{"role": "assistant", "content": "I need to use the weather API tool","metadata": {"title":  "🧠 Thinking", "id": "think"}}])msg = gr.Textbox()msg.submit(generate_response, [msg, chatbot], [msg, chatbot])demo.launch()

输入test后，运行截图如下：

注意：history定义时可添加多条消息，但append追加时，只能一条一条的添加，否则报错：TypeError: list.append() takes exactly one argument (2 given)。
我们也可以使用普通的Python字典来指定元数据，代码如下：

def generate_response(message, history):history.append(dict(role="user", content=message))history.append(dict(role="assistant",content="The weather API says it is 20 degrees Celcius in San Francisco.",metadata={"title": "🛠️ Used tool Weather API"}))return "", history

参考文献

1. Gradio - guides - Chatbots