使用 Gradio 构建聊天机器人从简单对话到流式与多模态界面【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio聊天机器人是自然语言处理NLP研究与工程落地的典型载体而它又往往被客户与最终用户直接使用因此验证其面对各种输入提示时的行为是否可靠至关重要。本教程将以当前 Gradio 仓库中的官方示例为主线讲解如何借助gr.Blocks与gr.Chatbot组件依次构建三类聊天机器人界面简单的历史文本对话界面、带流式输出的响应界面、以及可同时处理文本与图片/音频/视频的多模态界面。学完本文你将掌握聊天历史的数据结构、事件链式编排.submit().then()、生成器流式输出与排队机制并能够把这些能力替换成自己的模型或 API 调用逻辑。说明本仓库的中文指南原文位于 guides/cn/07_other-tutorials/creating-a-chatbot.md文中演示代码均已收录在仓库的 demo 目录下可对应阅读、直接运行。前置知识与环境要求本教程使用gradio.Blocks来搭建聊天机器人界面。如果你对 Blocks 的布局与事件监听器还不熟悉建议先阅读仓库内的 Blocks 与事件监听器指南。同时请确保本地安装了最新版本的 Gradiopip install --upgrade gradio本文涉及的核心组件源码位于 gradio/components/chatbot.py其类文档明确写道Chatbot组件“创建一个展示用户提交消息与响应的聊天机器人支持部分 Markdown加粗、斜体、代码、表格也支持音频/视频/图片文件”。简单聊天机器人演示先从一个最简单的示例开始机器人随机从固定回复中抽取一句作为应答。完整代码见 demo/chatbot_simple/run.pyimport gradio as gr import random import time with gr.Blocks() as demo: chatbot gr.Chatbot() msg gr.Textbox() clear gr.ClearButton([msg, chatbot]) def respond(message, chat_history): bot_message random.choice([How are you?, Today is a great day, Im very hungry]) chat_history.append({role: user, content: message}) chat_history.append({role: assistant, content: bot_message}) time.sleep(2) return , chat_history msg.submit(respond, [msg, chatbot], [msg, chatbot]) if __name__ __main__: demo.launch()界面中一共出现了三个 Gradio 组件gr.Chatbot值保存整个对话历史。在当前版本中对话历史以消息字典列表的形式存储每条消息包含roleuser/assistant等与content字段即 OpenAI 风格的消息格式见 gradio/components/chatbot.py#L112-L116 中MessageDict的定义gr.Textbox用户键入消息并按下 Enter / 提交按钮触发机器人回复gr.ClearButton同时清空文本框与整个聊天历史。ClearButton在构造时接收要清空的组件列表属于组件自带能力见 gradio/components/clear_button.py。事件绑定上respond()接收用户消息与聊天历史把用户消息和一段随机回复依次追加进历史然后返回两个值空字符串用于清空输入框和更新后的历史记录。实际项目里你只需把respond()中“随机选择”的部分替换为更复杂的逻辑——例如调用某个预训练模型、LLM 或远端 API 生成真实回复界面部分无需改动。为聊天机器人添加流式响应简单的“一次性返回”体验不够好原因有二其一模型逐字生成往往耗时较长用户会一直等待其二在机器人回复生成期间用户的消息迟迟不显示在会话里。仓库中的 demo/chatbot_streaming/run.py 给出了改进方案import gradio as gr import random import time with gr.Blocks() as demo: chatbot gr.Chatbot() msg gr.Textbox() clear gr.Button(Clear) def user(user_message, history: list): return , history [{role: user, content: user_message}] def bot(history: list): bot_message random.choice([How are you?, I love you, Im very hungry]) history.append({role: assistant, content: }) for character in bot_message: history[-1][content] character time.sleep(0.05) yield history msg.submit(user, [msg, chatbot], [msg, chatbot], queueFalse).then( bot, chatbot, chatbot ) clear.click(lambda: None, None, chatbot, queueFalse) if __name__ __main__: demo.launch()这里的关键是当用户提交消息后代码用.then()把三个事件链接起来依次执行user(user_message, history)立即把用户消息追加到历史中此时机器人回复位置为空并清空输入字段。代码返回与新的历史前端同步更新。同时通过queueFalse跳过排队保证即时反馈避免机器人回复期间用户重复发送在生成阶段你也可以将输入框设为interactiveFalse以禁用输入。bot(history)以历史记录作为输入更新Chatbot。它不是追加一条新消息而是把上一步预留的空回复逐字符填充先追加{role: assistant, content: }再用for循环把字符拼进history[-1][content]每一步time.sleep(0.05)模拟生成耗时并通过yield不断产出中间态的历史。收尾阶段示例中以.then()链中的后续逻辑或组件状态恢复完成重新把输入框恢复为可交互让用户能发送下一条消息。Gradio 会自动把任何带yield关键字的函数转换为流式输出接口并将每轮产出的中间结果推送到前端这部分能力由 Blocks 的事件系统与队列共同支撑详见 gradio/blocks.py 中事件链与queue()的实现。与前一版代码相比这里把“消息入库 清空输入”与“生成回复”拆成了两个独立函数分别绑定到submit事件和它的后继事件上这种“占位 逐步填充”写法是构建流式聊天机器人的核心套路。为什么需要 demo.queue()流式中间输出的推送给用户依赖服务端排队机制因此该示例在if __name__ __main__:分支内通过demo.queue()启用队列后再demo.launch()。Blocks.queue()负责控制事件何时进入队列、位置如何展示以及单事件的最大并发等见 gradio/blocks.py#L2556-L2570 对queue()参数status_update_rate、max_size、default_concurrency_limit的说明。若想体验流式效果可在运行该示例后连续输入几句问候语观察逐字输出。注意上面代码片段中的queueFalse与文件末尾的demo.queue()并不冲突——前者表示“该事件跳过排队直接执行”用于立即可见的用户消息回显后者为“流式输出所需的总体排队通道”。Chatbot 的消息结构与底层原理要写出正确的聊天逻辑理解gr.Chatbot的数据契约很重要。从源码看消息消息对象有多个层级MessageDictgradio/components/chatbot.py#L112-L116即应用层使用的字典格式必填role与content可选metadata与options规范化后内部使用NormalizedMessageDict其content是TextMessageDict | FileMessageDict | ComponentMessageDict的列表gradio/components/chatbot.py#L131-L138分别对应纯文本消息、文件消息与 Gradio 组件消息面向用户的ChatMessagedataclass 提供content、role、metadata、options字段gradio/components/chatbot.py#L161-L176。值得留意的是Chatbot的校验逻辑_check_format()要求每条消息要么是带role与content键的字典、要么是ChatMessage对象否则会抛出Error提示数据与 messages 格式不兼容gradio/components/chatbot.py#L389-L403。因此上文的流式示例中bot()里history[-1][content]的逐字符累加正是作用在最近一条assistant消息的content上。添加 Markdown、图片、音频或视频gr.Chatbot天然支持一部分 Markdown 语法。例如下面的bot()函数会以粗体文本 “Thats cool!” 回复用户def bot(history): response **Thats cool!** history[-1][1] response return history除了 MarkdownChatbot还能直接渲染图片、音频与视频等媒体文件。向会话中传入媒体时需要以包含两个字符串的元组(filepath, alt_text)表示其中alt_text是可选的因此也可以只传单元素元组(filepath,)def add_file(history, file): history history [((file.name,), None)] return history文件之所以能被识别为媒体消息是因为Chatbot的content字段支持FileDataDict/FileDatagradio/components/chatbot.py#L109后端会把上传文件保存并转换为带path、url、mime_type、orig_name等信息的文件数据后展示。一个真正的多模态聊天机器人把文本输入与文件上传整合到同一入口可以使用gr.MultimodalTextbox。仓库的 demo/chatbot_multimodal/run.py 展示了完整的多模态聊天机器人用户既可以输入文本也可以同时上传图片/音频/视频。import gradio as gr import time def print_like_dislike(x: gr.LikeData): print(x.index, x.value, x.liked) def add_message(history, message): user_msg {role: user, content: []} for x in message[files]: # type: ignore user_msg[content].append({path: x}) # type: ignore if message[text] is not None: # type: ignore user_msg[content].append(message[text]) # type: ignore history.append(user_msg) return history, gr.MultimodalTextbox(valueNone, interactiveFalse) def bot(history: list): response **Thats cool!** history.append({role: assistant, content: }) for character in response: history[-1][content] character time.sleep(0.05) yield history with gr.Blocks() as demo: chatbot gr.Chatbot(elem_idchatbot, like_user_messageTrue) chat_input gr.MultimodalTextbox( interactiveTrue, file_countmultiple, placeholderEnter message or upload file..., show_labelFalse, sources[microphone, upload], ) chat_msg chat_input.submit( add_message, [chatbot, chat_input], [chatbot, chat_input] ) bot_msg chat_msg.then(bot, chatbot, chatbot, api_namebot_response) bot_msg.then(lambda: gr.MultimodalTextbox(interactiveTrue), None, [chat_input]) chatbot.like(print_like_dislike, None, None) if __name__ __main__: demo.launch()要点拆解用户侧组装add_message()把MultimodalTextbox的输出解析成一条用户消息。由于一条多模态消息可同时包含多个文件与一段文本其content被构造成列表每个上传文件追加{path: x}文本则直接 append 到列表中源码中的message[files]与message[text]正是MultimodalTextbox的输出结构。回复仍可流式机器人回复沿用上一节的“占位 逐字 yield”套路且回复正文使用了 Markdown 加粗说明文本流式与富文本渲染可以同时工作。交互状态管理提交后立即把输入组件设为interactiveFalse并清空value等机器人回复结束再在链的末尾把组件恢复为可交互避免生成期间重复提交。api_namebot_response为该事件命名便于客户端以稳定名称调用。点赞/点踩chatbot.like(print_like_dislike, None, None)注册了对消息的 like 事件监听示例中仅打印回调参数消息下标、值、是否点赞你可以在回调里接入日志或反馈收集。文件来源MultimodalTextbox的sources[microphone, upload]允许从麦克风或本地上传file_countmultiple支持一次传多个文件。该界面就是原文开篇所展示的多模态效果——用户在输入框敲文字、夹带图片上传机器人以带格式的文本回复。运行与后续扩展所有示例都可以直接在仓库demo目录下运行例如python demo/chatbot_simple/run.py # 简单聊天机器人 python demo/chatbot_streaming/run.py # 流式聊天机器人 python demo/chatbot_multimodal/run.py # 多模态聊天机器人以Blocks方式编写的一大优势是上文把“处理输入—生成回复—恢复状态”拆成了独立函数与事件链你可以在任意一环插入真实业务逻辑。仓库中还提供了大量进阶变体可供对照学习demo/chatbot_consecutive/run.py非流式的“用户消息立即上屏 机器人随后回复”写法适合作为理解事件链的对照版demo/chatbot_with_tools/run.py、demo/agent_chatbot/run.py展示Chatbot在 Agent/工具调用场景下的元数据thought 等用法demo/chatbot_core_components/run.py展示在会话中直接嵌入gr.HTML、gr.Plot等 Gradio 组件消息对应源码中的ComponentMessagedemo/chatinterface_artifacts/run.py如果你更希望用高层封装gr.ChatInterface而非手写 Blocks 事件可参考该示例对消息内容与文件附件的处理。小结回顾构建聊天机器人的三个关键节点数据结构把gr.Chatbot的值视为“带role与content的消息列表”用户消息即时追加、机器人回复原地填充流式输出把生成逻辑写成yield生成器函数配合demo.queue()启用排队即可逐 token/逐字推送到界面显著改善等待体验多模态扩展content支持文件路径与文本混排搭配gr.MultimodalTextbox即可在一个输入框内同时接收文本与媒体gr.Chatbot对 Markdown 与媒体文件的渲染能力让会话展示更丰富。掌握了这些模式之后只需把示例中的随机回复与固定文案替换成你自己的模型推理或 API 调用一个可共享、可交互的聊天机器人演示就搭建完成了。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
