SGLang Diffusion WebUI 使用指南：一条命令启动图像与视频生成界面-平芜编程栈

SGLang Diffusion WebUI 使用指南：一条命令启动图像与视频生成界面

【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang

导读

SGLang Diffusion WebUI 是 SGLang 多模态生成框架内置的一套基于 Gradio 的图形化推理界面，它让开发者无需编写任何客户端代码，即可在浏览器中直接对文生图、文生视频、图生图、图生视频等 Diffusers 模型进行参数调优与实时预览。本文以 WebUI 官方说明为主体，结合仓库内 WebUI 前端实现、服务端启动链路与单元测试，系统讲解 WebUI 的安装前置条件、五种典型启动命令（含 MiniMax H3 多分区启动）、SSH 端口转发访问方式，以及界面中每个控件的含义与底层参数映射，帮助读者快速在本地或远程服务器上搭建一套可交互的多模态生成工作台。

前置条件：安装 Gradio

WebUI 基于 Gradio 构建，启动服务前需先安装与仓库版本匹配的 Gradio：

pip install gradio==6.1.0

从源码结构看，webui/main.py 中import gradio as gr被刻意放在函数内部执行（注释为 "import gradio in function to avoid CI crash"），因此即使环境里没有 Gradio，SGLang 其余模块也能正常导入；只有真正启动 WebUI 时才要求 Gradio 可用。

启动 WebUI 服务：一条命令完成

SGLang Diffusion 已集成 WebUI，无需单独部署前端服务，只需在启动命令中追加--webui参数即可：

sglang serve --model-path <MODEL_PATH_OR_ID> [其他参数] --webui --webui-port 2333

参数解析与默认值

--webui与--webui-port两个参数定义在 server_args.py：

--webui：布尔开关，默认False，含义为 "Whether to use webui for better display"；
--webui-port：WebUI 监听端口，默认值为12312（见 server_args.py 中webui_port: int | None = 12312）。示例命令中统一使用2333，读者可按需修改。

启动链路：服务端如何编排

当传入--webui后，启动流程在 serve.py 中分两步完成：

先调用dispatch_launch(server_args)拉起模型调度与推理进程；
再调用run_sgl_diffusion_webui(server_args)启动 Gradio 界面。

在 launch_server.py 中可以看到：启用 WebUI 时，FastAPI 服务器会被放入一个独立的子进程（进程名sglang-diffusion-webui）运行，从而避免 Gradio 与 FastAPI 在同一个进程内抢占事件循环；WebUI 主线程则通过sync_scheduler_client与推理后端通信。这种"推理后端 + FastAPI 子进程 + Gradio 界面"的三层结构是理解整个服务拓扑的关键。

场景一：启动文生图服务（Text-to-Image）

sglang serve --model-path black-forest-labs/FLUX.1-dev --num-gpus 1 --webui --webui-port 2333

--model-path black-forest-labs/FLUX.1-dev：FLUX.1-dev 文生图模型；
--num-gpus 1：单卡即可运行。

启动成功后，浏览器访问http://localhost:2333，即可输入 Prompt 生成图片，并通过界面右侧的 "Generated Image" 区域实时预览结果。

场景二：启动文生视频服务（Text-to-Video）

sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers --num-gpus 1 --webui --webui-port 2333

该命令加载 Wan2.2-T2V 文生视频 Diffusers 模型。启动后界面会自动切换为视频模式：num_frames（帧数）与frames_per_second（帧率）两个滑块变为可见，生成结果以视频文件形式在 "Generated Video" 区域播放。

场景三：启动图生图服务（Image-to-Image）

sglang serve --model-path Qwen/Qwen-Image-Edit-2511 --num-gpus 1 --webui --webui-port 2333

图生图场景下，需要在界面底部的 "reference images" 输入框中提供参考图路径（见下文界面说明），模型将基于参考图与 Prompt 生成编辑后的图像。

场景四：启动图生视频服务（Image-to-Video）

sglang serve --model-path Wan-AI/Wan2.2-TI2V-5B-Diffusers --num-gpus 1 --webui --webui-port 2333

Wan2.2-TI2V（Image-to-Video）模型以参考图为起点生成视频片段。与文生视频类似，界面会显示帧数与帧率控制项。

场景五：启动 MiniMax H3（原生音视频联合生成）

MiniMax H3 使用原生的"视频 + 音频联合"请求契约，服务启动时必须通过--model-variant显式选择权重分区（partition），不同分区对外提供不同的任务组合：

# 服务 t2va（文生视频+音频）与 fl2va（首帧/末帧生视频+音频） sglang serve --model-path MiniMaxAI/MiniMax-H3 --model-variant fl2va \ --num-gpus 4 --ulysses-degree 4 --webui --webui-port 2333 # 服务 ref2va（参考媒体生视频+音频） sglang serve --model-path MiniMaxAI/MiniMax-H3 --model-variant ref2va \ --num-gpus 4 --ulysses-degree 4 --webui --webui-port 2333

注意：MiniMax H3 体积较大，示例中采用--num-gpus 4 --ulysses-degree 4的四卡配置，请根据实际显存调整。

H3 的界面能力与限制

WebUI 针对 H3 暴露了task任务选择、条件媒体（首帧/末帧/参考图/参考视频/参考音频）、目标短边（short edge）/宽高比（aspect ratio）/时长（duration）、联合去噪步数、视频与音频的 flow shift、随机种子等控制项（见 minimax_h3.py 的 Gradio 布局）。

同时必须理解 H3 的以下约束（README 明确说明）：

H3 是CFG-distilled（CFG 蒸馏）模型，因此通用的负向提示词（negative prompt）、guidance scale、手动 FPS、帧数、宽高、TeaCache 等控制项不适用；
H3 输出固定为24 FPS，其帧数与画布尺寸由目标时长与宽高比推导得出。

这与仓库中 sampling_params.py 的fps: int = 24默认值一致，印证了 H3 固定帧率的设定。

H3 请求校验逻辑

从源码看，minimax_h3.py 的build_minimax_h3_sampling_params_kwargs对三类任务做了严格的媒体校验：

t2va：不接受任何条件媒体，条件列表为空；
fl2va：必须提供首帧和/或末帧，且只接受 keyframe 类条件，传入参考媒体会报错；
ref2va：必须提供参考图、参考视频或参考音频中的至少一种。

路径与 URL 统一通过_material_uri转换为file://或http(s)://URI 后再进入请求体。这些规则在 test_webui.py 中有对应的单元测试（如test_h3_webui_rejects_invalid_task_media）覆盖验证。

端口转发：远程安全访问

WebUI 服务运行在远端服务器上时，需要通过SSH 端口转发将远程端口安全地映射到本地：

ssh -L ${WEBUI_PORT}:localhost:${WEBUI_PORT} user_name@machine_name

例如--webui-port 2333对应的转发命令为：

ssh -L 2333:localhost:2333 user_name@machine_name

多数 IDE（VS Code、Cursor 等）的远程开发/端口转发功能可以自动完成这一过程；若未自动转发，再手动执行上述命令。

界面说明：控件与参数映射

启动成功后，在浏览器访问http://localhost:${WEBUI_PORT}。界面上方直接展示当前加载的模型路径（Model）与任务名（Task name）。任务名由 WebUI 在启动时自动识别：优先查询 HuggingFace Hub 的pipeline_tag（或 ModelScope 的任务标签），Hub 查询失败时回退到本地 pipeline 自身的task_type；识别为text-to-video、image-to-video、video-to-video时切换为视频模式，否则为图像模式（见 main.py）。若使用 ModelScope 拉取模型，可通过环境变量SGLANG_USE_MODELSCOPE开启对应查询路径。

通用生成控件

以下控件定义于 main.py，其取值范围、默认值及与采样参数的对应关系如下：

控件	类型	范围 / 默认值	对应采样参数
Prompt	文本框	默认 "A curious raccoon"	`prompt`
Negative_prompt	文本框	内置一段较长的通用负向提示词	`negative_prompt`
seed	数字	默认 1234	`seed`
width / height	数字	默认 720 × 480	`width`/`height`
num_inference_steps	滑块	0 ~ 50，默认 20	`num_inference_steps`
guidance_scale	滑块	0.0 ~ 10.0，默认 5.0，步长 0.01	`guidance_scale`
num_frames	滑块（仅视频模式可见）	1 ~ 181，默认 81	`num_frames`
frames_per_second	滑块（仅视频模式可见）	4 ~ 60，默认 16	`fps`
reference images	文本框	参考图路径或 URL，多个用英文逗号分隔	`image_path`
enable_teacache	复选框	默认关闭	`enable_teacache`

使用 "reference images" 时注意：

多个参考图之间必须使用英文逗号分隔；代码会自动将中文全角逗号"，"替换为英文逗号，但会打印告警日志提示用户改用英文逗号；
支持本地路径（如image1.png, image2.png）与 URL（如https://example.com/image1.png）。

所有控件点击Generate按钮后，会组装成SamplingParams并交给sync_scheduler_client.forward()执行推理；视频结果以文件路径形式返回播放，图像结果以np.ndarray帧数据渲染（见 main.py）。此外，sampling_params.py 中的align_num_frames_for_num_gpus会在多卡场景下自动把帧数对齐到 GPU 可整除的数值，因此即使手动输入的num_frames与显卡数不整除，后端也会自动规整，无需用户担心。

小结

SGLang Diffusion WebUI 把"模型加载、采样参数调优、结果预览"整合进了一个 Gradio 页面：对普通 Diffusers 模型，一条sglang serve ... --webui命令即可获得完整的文生图/文生视频/图生图/图生视频交互界面；对 MiniMax H3 这类原生音视频联合模型，则通过--model-variant分区选择与专用 H3 控件提供定制化支持。结合 serve.py 的启动编排、launch_server.py 的进程拆分、minimax_h3.py 的请求校验以及 test_webui.py 的测试覆盖，开发者既可以开箱即用地完成推理演示，也可以以此为模板扩展新的多模态生成模型接入。

【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考