第4章 Gradio库的模块架构和环境变量

第4章 Gradio库的模块架构和环境变量第4章 Gradio库的模块架构和环境变量4.1 构建演示模块4.2 块布局模块4.3 组件模块4.3.1 组件预处理和后处理4.3.2 支持事件4.3.3 组件类大全4.4 帮助模块及其他模块4.5 情态模块及路由模块4.6 设置环境变量第4章 Gradio库的模块架构和环境变量本章以Gradio库版本6.10.0为参考介绍Gradio的各个模块和环境变量不同版本的模块组件及环境变量会稍稍不同。内容Gradio库的模块架构包括构建演示模块、块布局模块、组件模块、帮助模块、情态模块及路由模块环境变量在了解其设置方法后列表详述各个环境变量的设置、默认值和作用描述。另外在组件模块中介绍了组件预处理和后处理方便读者理解Gradio背后运行原理。读者可在本章学习并查询Gradio应用的所有模块、组件、成员函数和各类参数方便在以后开发时查找起到Gradio字典的作用。4.1 构建演示模块构建演示Building Demo模块的作用是生成界面是Gradio的基础类。Gradio目前提供了五种构建演示类分别为Interface、ChatInterface、TabbedInterface、Blocks和Server详细介绍如表4-1所示表中的参数或函数只展示前三个常用项当多于三个时以省略号代替表4-1类名构造参数成员函数功能描述Interfacefn, inputs, outputs…launch(), load(), from_pipeline()…Interface是Gradio的主要高级抽象类它仅需几行代码即可为机器学习模型或任何Python函数创建基于Web的GUI或Demo。它必须指定三个参数fn、inputs和outputs其他参数可用于控制演示的外观和行为ChatInterfacefn, multimodal, type, chatbot…like()ChatInterface是Gradio用于创建聊天机器人UI的高级抽象类只需几行代码即可创建一个包含聊天模型的基于Web的Demo。它只需一个参数fn该函数根据用户输入和聊天历史来控制聊天机器人的响应。其他参数可用于控制演示的外观和行为TabbedInterfaceinterface_list, tab_namesTabbedInterface通过提供Interface或Blocks的列表来创建每个界面都在单独的tab项中呈现。只有Interface/Blocks中的组件才会在tab中显示但Blocks中的某些高级属性例如自定义css、js和head属性将不会加载Blockstheme, analytics_enabled, mode…launch(), queue(), integrate()…Blocks是Gradio的低级API抽象类但仍然完全基于Python它可以创建比Interface更多的自定义web应用程序和演示。与Interface相比Blocks在以下方面提供更大的灵活性和可控性1组件的布局2触发函数执行的事件3数据流例如输入可以触发输出从而触发后续流程。Blocks还提供方法将相关演示组合在一起例如使用标签Serverdebug, servers, responses…api(), launch()Server是一个在FastAPI应用上暴露的Gradio API引擎服务器模式,它继承自FastAPI因此所有标准FastAPI方法如.get()、.post()、.include_router()等都可以直接在该实例上使用。在FastAPI基础上新增的方法包括api()装饰器、mcp命名空间及launch()等。4.2 块布局模块块布局Block Layout模块可实现定制化Walkthrough的排版效果如渲染、分行、分列、分组、折叠及标签等其成员类包括render、Accordion、Column、Row、Group、Tab、Walkthrough等各类构造参数、成员函数和作用描述见表4-2所示表4-2类名构造参数成员函数功能描述renderinputs, triggers, queue…render渲染装饰器可以使Blocks具有动态布局以便应用中的组件和事件监听器可以根据自定义逻辑进行更改。将装饰符gr.render附加到某函数使其关联根据输入进行更新的组件和事件监听器这使函数在输入更改或指定的触发器被激活时重新运行Accordionlabel, open, visible…expand(), collapse()折叠类Accordion是一种布局元素它可以切换以显示/隐藏所包含的内容Columnscale, min_width, variant…Column列是Blocks中的一个布局元素它垂直呈现所有子元素。Column的宽度可以通过scale和min_width设置如果某个scale导致列宽度比min_width窄则min_width优先Groupvisible, elem_id, elem_classes…Group是Blocks中的一个布局元素它将子元素组合在一起使它们之间没有任何填充padding或边距marginRowvariant, visible, elem_id…Row是Blocks中的一个布局元素用于水平渲染所有子元素Tablabel, visible, interactive…select()Tab或其别名TabItem是一个布局元素当某个Tab被选中时Tab中定义的组件将被呈现Walkthroughselectedvisibleelem_id…change()select()Walkthrough 是 Blocks 中的布局元素可包含多个“Step”组件用于创建分步工作流。其中Step 组件是布局元素代表分步工作流中的单个步骤环节4.3 组件模块组件Component模块是Gradio中数量最多也是最重要的模块众多特效和功能需要组件实现。与其他模块不同组件模块中的组件类都有界面字符串快捷方式一般为组件名的小写格式如gr.Textbox()简写为textbox。Gradio包含预构建的组件这些组件只需一行代码即可在gr.Interface或gr.Blocks中用作输入或输出。4.3.1 组件预处理和后处理组件处理步骤一般包含预处理和后处理预处理步骤将通过浏览器提交的用户数据转换为Python函数可以使用的数据后处理步骤将Python函数返回的值转换为可以在浏览器中显示的数据。考虑一个有三个输入文本框、数字和图像和两个输出数字和图库的示例图4-1显示预处理步骤将向Python函数发送什么类型数据以及后处理将输出什么类型数据的示意图图4-1从图4-1可以看到输入组件的Textbot、Number和Image经过Gradio预处理后转换为str、int和numpy.array然后传递给Python函数。而函数返回的float及list[str]类型的值则经Gradio后处理可以输出到Number和Gallery组件类。4.3.2 支持事件组件累还附带支持某些事件event它们是由用户操作触发的调用方法一共有33种事件key_up、stop、undo、change、start_recording、example_select、preview_open、click、like、pause、retry、apply、input、preview_close、focus、blur、pause_recording、stream、edit、double_click、copy、end、tick、release、download、select、option_select、play、upload、clear、delete、stop_recording、submit。这些事件也会在组件的官方文档中进行带参数的详细讲解想进一步学习某事件请移步官网API文档这里不再深入。表4-3展示了每个组件支持的事件表中将支持相同事件的组件分为同组。表4-3组件类支持事件Audiostop change start_recording pause input pause_recording stream play upload clear stop_recordingBrowserState JSON Plot StatechangeButton ClearButton DeepLinkButton DownloadButton DuplicateButton LoginButtonclickChatbotundo change example_select like retry edit copy select option_select clearCheckbox CheckboxGroup Dataframe Radio FileExplorerchange input selectDateTimechange submitDropdownkey_up change input focus blur selectFilechange download select play upload clear deleteGallerychange preview_open preview_close select uploadHTMLchange clickImage ImageSliderchange input stream select upload clearLabelchange selectMarkdownchange copyModel3Dchange edit upload clearBarPlot LinePlot ScatterPlotdouble_click selectNumberchange input focus submitSliderchange releaseTextboxstop change input focus blurTimertickVideoinput stop change start_recording pause end play upload clear stop_recording限于篇幅只展示常用组件的事件此外还有组件AnnotatedImage、Code、Dialogue、ColorPicker、HighlightedText、ImageEditor、MultimodalTextbox、Navbar、ParamViewer、UploadButton、Sidebar、SimpleImage等全部组件的支持事件请在线上资源或官网查看。4.3.3 组件类大全本小节列出Gradio库当前版本6.10.0支持的所有组件类并列出组件的构造参数前三常用、成员函数前三常用和功能描述方便读者在后面实践用到时进行查阅。每个组件类都有或多或少的属性即构造参数有更改组件外观或数值的行为类属性也有label、title、info等表达信息的信息类属性成员函数也不尽相同各组件类简略介绍如表4-4所示表4-4类名构造参数成员函数功能描述Audiovalue, sources, type…stream(), change(), waveform_options() …创建可用于上传/录制音频作为输入或显示音频作为输出的音频组件BarPlotvalue, x, y…select(), double_click()创建条形图/柱状图组件以显示来自pandas.DataFrame的数据Buttonvalue, every, inputs…click()创建一个具有专属.click()事件的按钮按钮的标签值或赋值变量可用作函数的输入它的值也可以通过函数的输出进行设置Chatbotvalue, type, label…change(), select(), like()…创建一个聊天机器人界面以显示用户提交的消息和回复它通常用作输出组件。它支持Markdown的显示子集如粗体、斜体、代码、表格等它还支持显示音频/视频/图像文件以及显示为链接的其他类型的文件Checkboxchoices, value, type…change(), input(), select()创建一个可设置为True或False的复选框它即可以用作向函数传递布尔值的输入也可以用作显示布尔值的输出Codevalue, language, every…languages(), blur(), focus()…创建代码编辑器在作为输出组件时用于查看代码或作为输入组件时输入和编辑代码作为输入组件Dataframevalue, headers, row_count…change()input()select()此组件显示一个类似电子表格的数值表。它即可用于数据显示的输出组件也可作为收集用户数据的输入Datasetlabel, components, component_props…click(), select()创建库或表以显示数据示例此组件主要用于内部显示示例但也可以直接用于显示数据集并让用户选择示例DateTimevalue, include_time, type…change(), submit()用于选择日期和时间可选的组件Dialoguevalue, type, speakers…change(), input(), submit()创建一个Dialogue组件用于展示或收集多人对话。该组件既可作为输入组件录入多方对话也可作为输出组件展示经过分轨的语音内容例如语音转录或识别说话人模型的输出。每条消息均可关联特定说话人非常适用于对话、访谈或会议等应用场景Dropdownchoices, value, type…key_up(), change(), focus()…创建一个选项下拉列表从中可以选择单个条目或多个条目作为输入组件也可以作为显示结果的输出组件Filevalue, file_count, file_types…upload(), delete, download()…创建一个文件组件可以作为输入上传一个或多个通用文件或作为输出显示通用文件或URL以供下载Galleryvalue, format, file_types…select(), upload(), change()创建显示格栅图像或视频以及可选字幕的库组件。如果用作输入用户可以将图像或视频上传到Gallery。如果用作输出用户可以单击单个图像或视频以更高的分辨率查看它们HTMLvalue, label, every…change()创建一个显示任意HTML输出的组件。由于此组件不接受用户输入因此很少用作输入组件Imagevalue, format, height…clear(), change(), stream()…创建可用于上传图像作为输入或显示图像作为输出的图像组件LoginButtonvalue, logout_value, every…click()创建一个按钮使用OAuth协议将用户信息重定向到Hugging Face以验证登录Markdownvalue, label, every…change()用于呈现任意Markdown输出也可以渲染由符号$包围的latex公式。由于此组件不接受用户输入因此很少用作输入组件Model3Dvalue, display_mode, clear_color…change(), upload(), edit()…创建用于上传或查看三维模型3D Model文件如.obj、.glb、.stl、.gltf、.splat或.play的组件MultimodalTextboxvalue, file_types, file_count…change(), input(), stop()…创建一个文本区域供用户输入字符串或显示字符串输出还允许上传多媒体文件Navbarvalue, visible, main_page_name…change()为多页面Gradio应用创建导航栏组件它支持针对当前页面自定义导航栏外观它即可作为输入组件也可作为输出组件。在Blocks应用中其属性将覆盖默认导航栏行为且每个页面仅可存在一个Navbar组件可置于页面任意位置。Numbervalue, label, info…change(), input(), submit()…创建一个数字字段作为输入供用户输入数字或显示数字输出Plotvalue, format, label…change(), clear()创建绘图组件以显示各种绘图支持matplotlib、plotly、altair或bokeh plots散景图。由于此组件不接受用户输入因此很少用作输入组件Radiochoices, value, type…select(), change(), input()创建一组字符串或数字类型的单选按钮只能选择其中一个Sidebarlable, open, visible…expand (), collapse()侧栏是一个可折叠的面板用于“块”布局中在屏幕左侧呈现子组件Sliderminimum, maximum, value…change(), input(), release()以step size为步长创建一个范围从最小到最大的滑块Statevalue, render, time_to_live…change()用于定义所有输入/输出组件应具有的方法的基类Textboxvalue, lines, max_lines…change(), input(), blur()…创建一个文本区域供用户输入字符串或显示字符串输出Timervalue, active, rendertick()当被激活时以规律间隔定期计时的特殊组件。它不可见仅用于通过规律间隔计时的事件监听器以定期触发事件Videovalue, format, sources…play(), pause(), start_recording()…创建可用于上传/录制视频作为输入或显示视频作为输出的视频组件。为了在浏览器中播放视频它必须具有类似格式容器和编解码器的兼容式组合Gradio支持的组合包括.mp4与h264编解码器、.ogg与theora编解码器、.webm与vp9编解码器。当检测到输出视频无法在浏览器中播放将尝试将其转换为可播放的mp4视频如果转换失败则返回原始视频限于篇幅只展示组件模块的常用组件此外还有组件AnnotatedImage、CheckboxGroup、ClearButton、ColorPicker、DownloadButton、DuplicateButton、FileExplorer、HighlightedText、ImageEditor、ImageSlider、JSON、Label、LinePlot、ParamViewer、ScatterPlot、SimpleImage、UploadButton等全部组件请在线上资源查看。此外用户还可以自定义组件感兴趣读者可以参考自定义组件库Custom Component Gallery️链接4-1。4.4 帮助模块及其他模块为方便展示作者将帮助Helper模块和其他Other模块归到一起。同样以类名、构造参数、成员函数和功能描述的方式展示如表4-5所示表4-5类名构造参数成员函数功能描述EventDatatarget当gr.EventData或其子类作为隐变量hint类型添加到预测函数的参数时gr.EventData对象将自动作为该参数的值进行传递。此对象的属性包含触发监听器事件的信息。gr.EventData对象本身包含一个.target属性它与触发该事件的组件相关而gr.EventData的子类包含区别于其他类的附加属性SelectDataindex, value, selectedgr.SelectData类是gr.EventData的一个子类专门携带有关.select()事件的信息。当gr.SelectData作为隐变量添加到事件监听器方法的参数时gr.SelectData对象将自动作为该参数的值进行传递此对象的属性包含有关触发监听器事件的信息FileDatapath, url, size…FileData类是GradioModel类的一个子类它表示Gradio接口中的文件对象它用于在上传文件时存储文件数据和元数据Progresstrack_tqdm__call__(), tqdm()Progress类提供了一个在函数标记中使用的自定义进度跟踪器progress tracker。要将进度跟踪器附加到函数只需在输入参数后添加一个参数该参数的默认值设置为gradio.Progress()实例然后通过调用Progress对象或使用Iterable的tqdm方法在函数中更新Progress跟踪器。进度跟踪器目前仅在queue()中可用Examplesexamples, inputs, outputs…属性dataset, load_input_event,cache_event此类是Dataset组件的包装器可用于创建Blocks/Interface示例。用示例填充Dataset组件并分配事件监听器以便单击单个示例时用示例数据填充到输入/输出组件。也可以选择性的使用示例缓存以进行快速推理apifn,api_name, queue…为可以通过Gradio客户端调用的通用函数设置API端点。从函数签名中的类型提示派生其类型loadname, src, token…从Hugging Face的Model/Space的仓库或第三方API提供商提供的资源中自动构建Gradio应用程序。请注意如果加载自Space仓库将不会加载Blocks的某些高级属性例如自定义css、js和head属性load_chatbase_url, model, token…从OpenAI API聊天模块兼容的端点加载聊天界面ontriggers, fn, inputs…设置一个事件监听器当指定的事件发生时触发某函数。当同一函数应由多个事件触发时这尤其有用。对于触发器列表中的所有事件只生成一个API端点set_static_pathspaths设置供Gradio应用程序使用的静态路径。静态文件直接从文件系统被使用而不是被复制。在将这些文件发送给用户时需要将Content-Disposition HTTP设置为inline表示文件应直接展示在浏览器窗口中。当需要在Gradio应用的生命周期内不会被修改的文件如gr.Examples的文件时此功能非常有用。通过设置静态路径Gradio应用将更快地启动并消耗更少磁盘空间。此函数时将为同一解释器会话中的所有Gradio应用设置静态路径直到再次调用或会话结束Flaggingsimplify_file_data, verbose, dataset_file_name其他模块类在Gradio5.0版本及以上Flagging是FlaggingCallback抽象类的默认实现。每个标记的样本包括输入和输出数据都被记录到Gradio应用服务器的CSV文件中并有标题信息。与ClassicCSVLogger不同此实现是并发且安全的每当CSV的标题由组件的标签派生更改时它都会创建一个新的数据集文件。如果分别设置了flag_option和username则它只会为“flag”和“username”创建列ThemesAttributes: colors, sizes, GoogleFontDefault(), builder(), from_hub()…其他模块类Gradio具有内置的主题引擎可以自定义应用程序的外观和视觉效果。您可以从各种主题中进行选择也可以创建自己的主题然后将参数themekwarg传递给Blocks或Interface的构造函数即可。Theming内容较多需要实现酷炫主题的读者请仔细阅读Gradio Themes️链接4-2NO_RELOAD其他模块类重新加载源文件时代码块if gr.NO_RELOAD中的任何代码都不会被重新运行。它在避免重复导入模块如tiktoken、numpy、多次数据库连接和重复设置需长时间运行的代码等方面非常有用限于篇幅只展示帮助模块及其他模块的常用类此外还有DeletedFileData、KeyUpData、LikeData、RetryData、UndoData、EditData、DownloadData、CopyData、Dependency等全部组件类请在线上资源查看。4.5 情态模块及路由模块为方便展示作者将官方文档中的数量不多的情态Modal模块和路由Router模块归结到一张表。两个模块的各类见表4-6所示表4-6类名构造参数成员函数功能描述Errormessage, duration, visible…Modal模块此类将自定义Error消息传递给用户它可以通过在函数中的任意位置插入gr.Error(“custom message”)来实现当执行该行代码时自定义消息将出现在演示的Error情态中。默认情况下该模式为红色标题为“Error”。Queue必须启用此功能否则消息将打印到控制台Infomessage, duration, visible…Modal模块此功能将自定义Info消息传递给用户它可以通过在函数中的任意位置插入gr.Info(‘message here’)来实现当执行该行代码时自定义消息将出现在演示的Info情态中。默认情况下该模式为灰色标题为“Info”。Queue必须启用此功能否则消息将打印到控制台Warningmessage, duration, visible…Modal模块此类将自定义Warning消息传递给用户它可以通过在函数中的任意位置插入gr.Warning(‘message here’)来实现当执行该行代码时自定义消息将出现在演示的Warning情态中。默认情况下该模式为黄色标题为“Warning”。Queue必须启用此功能否则消息将打印到控制台mount_gradio_appapp, blocks, pathRoutes模块将一个gradio.Blocks挂载到现有的FastAPI程序上Requestrequest, username, session_hashRoutes模块Gradio的请求对象可用于在预测函数内访问请求头信息、cookies、查询参数及其他请求相关数据。它是对fastapi.Request类的轻量封装自身属性request又包括headers、client、query_params及path_params等。若启用身份验证可通过username获取登录信息。在某些运行环境该类的字典类属性会自动转换为字典类型为确保不同环境下行为一致建议在访问属性前先将其转换为字典4.6 设置环境变量Gradio中的环境变量提供了一种在不更改代码库的情况下自定义应用启动设置的方法。本节将探讨Gradio中支持的关键环境变量以及如何设置它们。设置方法Linux终端使用export命令后跟变量名及其值Windows系统CMD替换为setPowerShell为$env。以服务器端口为例设置命令如下exportGRADIO_SERVER_PORT8000查看及删除环境变量命令如下echo$GRADIO_SERVER_PORTenv|grepGRADIO_SERVER_PORTunsetGRADIO_SERVER_PORT如果使用.env文件来管理环境变量则可以在文件中添加如下内容RADIO_SERVER_PORT8000GRADIO_SERVER_NAMElocalhost然后使用命令source .env使文件设置立即生效。或者在编码时使用dotenv等工具加载这些变量。先安装库python-dotenv然后在程序中加入代码4-1代码4-1fromdotenvimportload_dotenv load_dotenv()常见环境变量下面列出大部分常见的GRADIO环境变量在后续实践时方便读者查阅。以环境变量名、可选值、默认值及作用描述见表4-7表4-7环境变量可选值默认值功能描述GRADIO_SERVER_PORT7860指定Gradio应用程序运行的端口GRADIO_SERVER_NAME“127.0.0.1”定义Gradio服务器的主机名。要使Gradio可从任意IP地址访问请将其设置为“0.0.0.0”GRADIO_ANALYTICS_ENABLED“True”, “False”“True”是否应提供Gradio解析GRADIO_FLAGGING_MODE“never”, “manual”, “auto”“manual”控制用户是否可以在Gradio界面中标记输入/输出。有关更多详细信息请参阅Flagging指南GRADIO_TEMP_DIR系统默认临时目录指定存储Gradio临时创建文件的目录GRADIO_ROOT_PATH“”设置Gradio应用程序的根路径。如果在反向代理后运行Gradio则这个设置很有用GRADIO_SHARE“True”, “False”“False”启用或禁用Gradio应用程序的互联网共享GRADIO_ALLOWED_PATHS“”设置允许Gradio访问的完整文件路径或父目录的列表必须是绝对路径可以通过用逗号分隔符来指定多个目录。警告如果设置了该目录则应用程序的所有用户都可以访问这些目录或其子目录中的任意文件GRADIO_CACHE_MODE“lazy”, eager““eager”如何缓存示例仅当cache_examples通过环境变量或显式参数设置为True并且gr.Interface、gr.ChatInterface或gr.Examples中的参数cache_mode没有传递显式参数时适用。设置为“lazy”则示例将在首次使用后缓存并可用于应用程序的所有用户如果是“eager”所有示例都会在应用程序启动时缓存GRADIO_EXAMPLES_CACHE“.gradio/cached_examples/”如果在gr.Interface、gr.ChatInterface或gr.examples中设置cache_examplesTrueGradio将运行预测函数并将结果保存到磁盘。默认位于应用程序工作目录中的.gradio/cached_examples/子目录。将GRADIO_EXAMPLES_CACHE设置为目录路径可以指定Gradio创建的缓存示例文件的位置GRADIO_SSR_MODE“True”, “False”“False”控制是否启用服务器端渲染SSR。启用后初始HTML在服务器上呈现而不是在客户端这可以提高初始页面加载性能和SEO。在Hugging Face Spaces中默认值会被设为TrueGRADIO_VIBE_MODE任何非空字符串均可启用该模式“”启用 Vibe 编辑器模式将提供浏览器内置聊天界面可使用自然语言编辑 Gradio 应用。该模式下任何能够访问 Gradio 端点的用户都可在主机上修改文件并执行任意代码因此请勿在生产环境中使用此功能。GRADIO_MCP_SERVER“True”, “False”“False”是否启用 Gradio 中的 MCP服务功能。启用后Gradio 应用将作为 MCP 服务器运行且经过文档化的函数将转换为 MCP 工具供LLM 使用。这使得 LLM 能够通过 MCP 协议与Gradio 应用功能进行交互。限于篇幅只展示常用环境变量此外还有GRADIO_NUM_PORTS、GRADIO_DEBUG、GRADIO_BLOCKED_PATHS、FORWARDED_ALLOW_IPS、GRADIO_CACHE_EXAMPLES、GRADIO_NODE_SERVER_NAME、GRADIO_NODE_NUM_PORTS、GRADIO_RESET_EXAMPLES_CACHE、GRADIO_CHAT_FLAGGING_MODE、GRADIO_WATCH_DIRS等全部环境变量请在线上资源查看。对于环境变量的详细解释请参考Gradio - Additional Features - Environment Variables️链接4-3。