Stable Diffusion WebUI Forge 深度指南：平台架构、安装实战与 UnetPatcher 模型修补系统

人工智能大模型媒体生成本地部署深度学习【免费下载链接】stable-diffusion-webui-forge项目地址https://gitcode.com/GitHub_Trending/st/stable-diffusion-webui-forge点击查看免费下载Stable Diffusion WebUI Forge下文简称 Forge是基于 Stable Diffusion WebUI 与 Gradio 二次构建的增强型 WebUI 平台其核心目标是让开发更简单、资源管理更高效、推理速度更快并为实验性功能提供研究入口。本文以 Forge 官方 README 为主体结合仓库源码完整讲解 Forge 的定位、一键安装与高级安装方式、官方功能状态清单并深入剖析其最核心的扩展机制 —— UnetPatcher 模型修补系统以 FreeU V2 的完整实现为例带你掌握编写 Forge 内置扩展的完整套路。一、Forge 是什么定位与设计理念Forge 是一个搭建在 Stable Diffusion WebUI 之上的平台底层基于 Gradio 构建界面。命名灵感来源于 Minecraft Forge —— 正如 Minecraft Forge 之于 Minecraft 生态这个项目旨在成为 SD WebUI 的 Forge一个让社区能够更方便地开发扩展、优化资源、加速推理并研究实验特性的底层基座。从仓库看当前 Forge 基于 SD-WebUI 1.10.1 基线构建版本号记录在 modules_forge/forge_version.py 中2.0.1v1.10.1。由于原版 SD-WebUI 目前已基本停止活跃更新Forge 计划每 90 天或遇到重要修复时与原始 WebUI 同步一次基线。Forge 的官方动态新闻已迁移至仓库根目录的 NEWS.md其中记录了诸如 SD 3.5 分支贡献、Flux ControlNet 重写排期、以及新采样器 Flux Realistic推荐搭配 simple 调度器等迭代信息。在官方 Quick List 中Forge 团队也特别强调了几条针对当前版本的关键实践结论可作为使用前提Gradio 4 界面在 Forge 的画布Canvas上移动画布时必须使用鼠标右键拖拽Flux 模型性能调优不要将 GPU Weight 调得过高调低 GPU Weight 可以解决 99% 的 Flux 性能问题低比特模型的 LoRA 精度官方提供了关于 Patching LoRAs 跳过、以及让 LoRA 每次生成只加载一次而非每次采样都加载的讨论与做法模型格式支持Flux 的 BNB NF4 与 GGUFQ8_0/Q5_0/Q5_1/Q4_0/Q4_1均已原生支持带 GPU weight 滑杆、队列/异步交换开关与交换位置开关且所有 BNB NF4 与 GGUF Q8_0/Q5_0/Q4_0 均支持 LoRA。说明以上为仓库 README 与 NEWS 记录的项目事实具体参数数值与效果请在对应模型上自行验证。二、安装 Forge从一键包到 Git 高级安装2.1 一键安装包推荐官方推荐直接使用一键安装包内置 Git 与 Python下载解压后即可使用CUDA 12.1 PyTorch 2.3.1版本包 ——官方推荐推荐等级最高环境最稳妥CUDA 12.4 PyTorch 2.4版本包 —— 标注为 Fastest最快但官方提示MSVC 可能损坏、xformers 可能无法工作CUDA 12.1 PyTorch 2.1版本包 —— 旧环境版本供之前使用旧环境的用户过渡。安装包使用方式非常直接下载对应版本的.7z压缩包并解压使用update.bat更新到最新代码使用run.bat启动WebUI。官方特别强调运行update.bat这一步很重要否则你可能在使用带有未修复 Bug 的旧版本。这是官方反复提示的常见问题根源。2.2 高级安装作为 SD-WebUI 的另一个分支如果你熟悉 Git并且已经安装过原版 SD-WebUI可以把 Forge 作为 SD-WebUI 的另一个分支安装。这种方式的收益在于可以复用原 SD-WebUI 中已安装的全部 SD 检查点checkpoints和全部扩展前提是你清楚自己在做什么官方明确提示 you should know what you are doing。2.3 标准方式安装如果你了解 SD-WebUI 的标准安装流程也可以用与 SD-WebUI 完全相同的方式安装 Forge安装 Git 与 Pythongit cloneForge 仓库运行webui-user.batWindows启动。启动流程的源码入口是仓库根目录的 launch.py它先解析命令行参数来自modules/launch_utils执行prepare_environment()准备环境可通过--skip-prepare-environment跳过随后调用start()正式启动 WebUI。如果传入--dump-sysinfo会导出系统信息文件后退出--test-server则用于测试模式配置。Windows 一键包中的run.bat本质上就是在调用这一套启动链路。2.4 历史版本如需使用历史版本可在官方讨论区下载对应历史版本包下载地址见仓库 README 中的 Previous Versions 链接。三、Forge 功能状态清单官方逐项手动测试官方 README 提供了一张基于逐项手动测试的功能状态表是判断当前 Forge 能力边界的权威依据。下表完整保留原文信息组件状态最近测试时间基础扩散Basic Diffusion正常2024-08-26GPU 内存管理系统正常2024-08-26LoRA正常2024-08-26全部预处理器Preprocessors正常2024-08-26全部 ControlNet正常2024-08-26全部 IP-Adapter正常2024-08-26全部 Instant-ID正常2024-07-27全部 Reference-only 方法正常2024-07-27全部集成扩展Integrated Extensions正常2024-07-27热门扩展Adetailer 等正常2024-07-27Gradio 4 界面正常2024-07-27Gradio 4 Forge Canvas正常2024-08-26Gradio 4 的 LoRA/Checkpoint 选择界面正常2024-07-27ControlNet 的 Photopea/OpenposeEditor 等正常2024-07-27Canvas 的 Wacom 128 级触摸压感正常2024-07-15Canvas 的 Microsoft Surface 触摸压感损坏待修复2024-07-29ControlNets (Union)未实现待开发2024-08-26ControlNets (Flux)未实现待开发2024-08-26API 端点txt2img、img2img 等正常待改进 Flux 支持2024-08-29OFT LoRA损坏待修复2024-09-09官方承诺如果任何组件损坏可以直接开 issue维护者每隔几天会查看一次。同时给出一个重要提示如果该状态表长期未更新说明维护者无法复现问题此时全新重装fresh re-install通常能解决大部分问题。四、UnetPatcher 模型修补系统Forge 扩展机制的基石README 专门辟出一节介绍 UnetPatcher并以FreeU V2为例给出了官方自支持的单文件完整实现代码。这一节是全文档的技术核心也是理解 Forge 扩展开发范式的钥匙。4.1 UnetPatcher 是什么从源码结构看UnetPatcher 是 backend/patcher/unet.py 中定义的UnetPatcher类继承自 backend/patcher/base.py 中的ModelPatcher。它是对 UNet 模型的修补器封装通过clone()复制当前补丁配置后允许扩展在不修改原始模型权重的情况下注入各类钩子patch例如set_model_output_block_patch/set_model_input_block_patch给 UNet 的输入/输出块挂接处理函数set_model_attn1_patch/set_model_attn2_patch/set_model_attn1_replace等改写注意力层add_extra_model_patcher_during_sampling/add_extra_preserved_memory_during_sampling把额外模型纳入 Forge 内存管理系统采样期间统一调度显存与 CPU 内存卸载add_conditioning_modifier/add_sampler_pre_cfg_function修改条件或采样前处理。这些 patch 最终通过transformer_options字典传给 backend/nn/unet.py 中的IntegratedUNet2DConditionModel在其forward()里output_block_patch会在每个输出块前以p(h, hsp, transformer_options)的形式被调用见 backend/nn/unet.py 中forward对output_block_patch的展开处从而实现在每个输出块处改写隐藏状态与跳跃连接特征的自由能力。FreeU V2 正是利用set_model_output_block_patch完成其核心算法的。4.2 FreeU V2 完整实现README 原文代码以下代码来自 README 的 UnetPatcher 章节是官方自支持的单文件FreeU V2 实现仓库中的实际扩展位于 extensions-builtin/sd_forge_freeu/scripts/forge_freeu.py。import torch import gradio as gr from modules import scripts def Fourier_filter(x, threshold, scale): # FFT x_freq torch.fft.fftn(x.float(), dim(-2, -1)) x_freq torch.fft.fftshift(x_freq, dim(-2, -1)) B, C, H, W x_freq.shape mask torch.ones((B, C, H, W), devicex.device) crow, ccol H // 2, W // 2 mask[..., crow - threshold:crow threshold, ccol - threshold:ccol threshold] scale x_freq x_freq * mask # IFFT x_freq torch.fft.ifftshift(x_freq, dim(-2, -1)) x_filtered torch.fft.ifftn(x_freq, dim(-2, -1)).real return x_filtered.to(x.dtype) def patch_freeu_v2(unet_patcher, b1, b2, s1, s2): model_channels unet_patcher.model.diffusion_model.config[model_channels] scale_dict {model_channels * 4: (b1, s1), model_channels * 2: (b2, s2)} on_cpu_devices {} def output_block_patch(h, hsp, transformer_options): scale scale_dict.get(h.shape[1], None) if scale is not None: hidden_mean h.mean(1).unsqueeze(1) B hidden_mean.shape[0] hidden_max, _ torch.max(hidden_mean.view(B, -1), dim-1, keepdimTrue) hidden_min, _ torch.min(hidden_mean.view(B, -1), dim-1, keepdimTrue) hidden_mean (hidden_mean - hidden_min.unsqueeze(2).unsqueeze(3)) / (hidden_max - hidden_min).unsqueeze(2).unsqueeze(3) h[:, :h.shape[1] // 2] h[:, :h.shape[1] // 2] * ((scale[0] - 1) * hidden_mean 1) if hsp.device not in on_cpu_devices: try: hsp Fourier_filter(hsp, threshold1, scalescale[1]) except: print(Device, hsp.device, does not support the torch.fft.) on_cpu_devices[hsp.device] True hsp Fourier_filter(hsp.cpu(), threshold1, scalescale[1]).to(hsp.device) else: hsp Fourier_filter(hsp.cpu(), threshold1, scalescale[1]).to(hsp.device) return h, hsp m unet_patcher.clone() m.set_model_output_block_patch(output_block_patch) return m class FreeUForForge(scripts.Script): sorting_priority 12 # It will be the 12th item on UI. def title(self): return FreeU Integrated def show(self, is_img2img): # make this extension visible in both txt2img and img2img tab. return scripts.AlwaysVisible def ui(self, *args, **kwargs): with gr.Accordion(openFalse, labelself.title()): freeu_enabled gr.Checkbox(labelEnabled, valueFalse) freeu_b1 gr.Slider(labelB1, minimum0, maximum2, step0.01, value1.01) freeu_b2 gr.Slider(labelB2, minimum0, maximum2, step0.01, value1.02) freeu_s1 gr.Slider(labelS1, minimum0, maximum4, step0.01, value0.99) freeu_s2 gr.Slider(labelS2, minimum0, maximum4, step0.01, value0.95) return freeu_enabled, freeu_b1, freeu_b2, freeu_s1, freeu_s2 def process_before_every_sampling(self, p, *script_args, **kwargs): # This will be called before every sampling. # If you use highres fix, this will be called twice. freeu_enabled, freeu_b1, freeu_b2, freeu_s1, freeu_s2 script_args if not freeu_enabled: return unet p.sd_model.forge_objects.unet unet patch_freeu_v2(unet, freeu_b1, freeu_b2, freeu_s1, freeu_s2) p.sd_model.forge_objects.unet unet # Below codes will add some logs to the texts below the image outputs on UI. # The extra_generation_params does not influence results. p.extra_generation_params.update(dict( freeu_enabledfreeu_enabled, freeu_b1freeu_b1, freeu_b2freeu_b2, freeu_s1freeu_s1, freeu_s2freeu_s2, )) return4.3 代码逐段解读1Fourier_filter频域高通滤波x_freq torch.fft.fftn(x.float(), dim(-2, -1)) x_freq torch.fft.fftshift(x_freq, dim(-2, -1)) mask torch.ones((B, C, H, W), devicex.device) crow, ccol H // 2, W // 2 mask[..., crow - threshold:crow threshold, ccol - threshold:ccol threshold] scale x_freq x_freq * mask x_freq torch.fft.ifftshift(x_freq, dim(-2, -1)) x_filtered torch.fft.ifftn(x_freq, dim(-2, -1)).real该函数将特征图做二维 FFT 变换并中心化fftshift把频谱中心区域低频乘以scale系数、其余区域保持为 1再反变换回空间域从而实现对跳跃连接特征的低频抑制/增强。由于使用torch.fft部分设备如某些不支持 FFT 的环境会抛出异常代码通过try/except捕获后回退到 CPU 上执行 FFT并用on_cpu_devices字典记录已回退的设备避免反复尝试。2patch_freeu_v2把补丁挂到 UnetPatcher 上model_channels unet_patcher.model.diffusion_model.config[model_channels] scale_dict {model_channels * 4: (b1, s1), model_channels * 2: (b2, s2)}FreeU V2 按 UNet 的通道数自动匹配两个档位model_channels * 4较深输出块应用(b1, s1)model_channels * 2较浅输出块应用(b2, s2)。这解释了官方 UI 中 B1/S1 与 B2/S2 两组滑杆各自的作用对象。核心步骤hidden_mean h.mean(1).unsqueeze(1) hidden_max, _ torch.max(hidden_mean.view(B, -1), dim-1, keepdimTrue) hidden_min, _ torch.min(hidden_mean.view(B, -1), dim-1, keepdimTrue) hidden_mean (hidden_mean - hidden_min) / (hidden_max - hidden_min) h[:, :h.shape[1] // 2] h[:, :h.shape[1] // 2] * ((scale[0] - 1) * hidden_mean 1)这里先对通道维度取均值得到空间权重图再做 min-max 归一化得到取值在 0~1 的权重图然后对前半通道h[:, :h.shape[1] // 2]按(b - 1) * normalized 1缩放。当b 1时权重图值越大对应高频丰富的区域放大越多起到增强细节的作用后半通道保持不变。最后hsp跳跃连接特征通过Fourier_filter(hsp, threshold1, scalescale[1])做频域处理threshold1表示只对中心 1 像素半径的低频区域应用s系数。补丁的注册方式非常简洁m unet_patcher.clone() m.set_model_output_block_patch(output_block_patch) return mclone()复制一份当前 UnetPatcher 配置原对象不被污染set_model_output_block_patch把output_block_patch注入transformer_options[patches][output_block_patch]列表。之后 backend/nn/unet.py 的 UNet 前向过程中每个输出块都会依次调用该补丁并拿到修改后的h, hsp。3FreeUForForge作为 UI 脚本接入 txt2img/img2imgsorting_priority 12控制脚本在 UI 面板中的排序位置官方注释说明它会是 UI 上的第 12 项show()返回scripts.AlwaysVisible让扩展在txt2img 和 img2img 两个标签页都可见ui()用gr.Accordion(openFalse)折叠面板 若干滑杆构建参数区。滑杆参数与取值范围B10~2步长 0.01默认 1.01B20~2步长 0.01默认 1.02S10~4步长 0.01默认 0.99S20~4步长 0.01默认 0.95process_before_every_sampling()每次采样前被调用官方注释特别提醒如果使用 highres fix高清修复这个回调会被调用两次。方法内从p.sd_model.forge_objects.unet取出 UNet套上 FreeU 补丁后写回再把参数记录到p.extra_generation_params—— 这些参数不会影响生成结果只是为了让 UI 图片下方显示所用参数便于复现与信息记录。4.4 仓库实际扩展比 README 示例更完善的地方README 给出的代码是便于理解的最小自包含版本仓库内实际内置扩展 extensions-builtin/sd_forge_freeu/scripts/forge_freeu.py 在官方示例基础上增加了以下能力可作为进阶阅读材料内置预设presets_builtin一键填入不同模型的推荐参数# name, b1, b2, s1, s2, start step, end step (Forge default, 1.01, 1.02, 0.99, 0.95, 0.0, 1.0), (SD 1.4, 1.3, 1.4, 0.9, 0.2, 0.0, 1.0), (SD 1.5, 1.5, 1.6, 0.9, 0.2, 0.0, 1.0), (SD 2.1, 1.4, 1.6, 0.9, 0.2, 0.0, 1.0), (SDXL, 1.3, 1.4, 0.9, 0.2, 0.0, 1.0),可见 SD 1.x 系列推荐使用较大的 B 值1.3~1.6与较小的 S 值0.2而 Forge default 更温和。预设还可以通过外部freeu_presets模块追加自定义预设。Start step / End step 步进控制新增两个 0.0~1.0 的滑杆通过on_cfg_denoiser注册的去噪回调denoiser_callback按sampling_step / (total_sampling_steps - 1)计算当前归一化步进落在区间内才启用 FreeU从而实现只在扩散中段生效的精细控制。模型兼容性守卫patch_freeu_v2中改用config.get(model_channels)若模型没有该配置例如非传统 UNet 架构模型则通过gr.Info提示 freeU is not supported for this model! 并安全返回避免直接崩溃。回调清理postprocess中调用remove_current_script_callbacks()确保一次生成结束后清理去噪回调不污染后续采样。五、版本基线、维护节奏与使用注意事项版本基线当前 Forge 基于 SD-WebUI 1.10.1版本号见 modules_forge/forge_version.py2.0.1v1.10.1同步策略因原版 SD-WebUI 近乎停滞Forge 约每 90 天或出现重要修复时与上游同步一次状态可复现性官方在状态表中明确若表格长期不更新即意味着无法复现用户报告的问题此时全新重装通常能解决大部分问题处于持续建设中README 末尾声明 Forge 仍在建设之中Under Construction文档、界面与功能可能随版本更新而变化使用时请以当前仓库的实际代码与最新 NEWS 为准LoRA 生态Forge 的 LoRA 加载统一经由 backend/patcher/lora.py 的LoraLoader分派到packages_3rdparty/webui_lora_collection与packages_3rdparty/comfyui_lora_collection两套解析实现这也解释了为何 README 中强调低比特NF4/GGUF模型下 LoRA 的加载方式需要特殊对待。结语Stable Diffusion WebUI Forge 的价值不在于再造一个 WebUI而在于提供了一整套更易用的模型修补与内存调度底座通过 UnetPatcher 的cloneset_model_*_patch范式任何扩展都能在不改动模型权重的前提下于 UNet 前向路径的任意位置注入自定义逻辑FreeU V2 正是这一范式的教科书级样例。结合一键安装包与官方状态清单你可以快速上手 Forge并以此为模板开发自己的内置扩展。赞分享人工智能大模型媒体生成本地部署深度学习【免费下载链接】stable-diffusion-webui-forge项目地址https://gitcode.com/GitHub_Trending/st/stable-diffusion-webui-forge点击查看免费下载相关推荐deepwiki-rs与CI/CD集成每次代码提交自动更新架构文档的完整方案deepwiki rs与CI/CD集成每次代码提交自动更新架构文档的完整方案 deepwiki rs又名 Litho是一个基于 Rust 编写的高性能 AStable Diffusion WebUI Forge跨平台部署完整指南从安装到精通Stable Diffusion WebUI Forge跨平台部署完整指南从安装到精通 Stable Diffusion WebUI Forge是基于Stab人工智能大模型媒体生成本地部署深度学习Stable Diffusion WebUI Forge 安装与使用完整指南Stable Diffusion WebUI Forge 安装与使用完整指南 项目概述 Stable Diffusion WebUI Forge 是一个基于 S人工智能大模型媒体生成本地部署深度学习上一篇AndroidMock数据终极指南快速生成测试数据的10个实用技巧下一篇10分钟实现PDF预览器用pdf-lib和Canvas打造流畅阅读体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考