自定义脚本

相关源文件

• extensions-builtin/extra-options-section/scripts/extra_options_section.py
• modules/config_states.py
• modules/extensions.py
• modules/scripts.py
• modules/sd_samplers_kdiffusion.py
• modules/shared_options.py
• modules/ui_common.py
• modules/ui_extensions.py
• modules/ui_settings.py
• scripts/xyz_grid.py

本页面介绍如何创建自定义脚本来扩展 Stable Diffusion Web UI 的功能。自定义脚本允许您在不修改核心代码的情况下向界面添加新功能，从而使您的添加内容在更新时也易于维护。

有关使用 X/Y/Z Plot 等内置脚本的信息，请参阅 高级功能 和 X/Y/Z Plot。如果您想了解扩展开发，请参考 扩展系统。

1. 脚本系统概述

Stable Diffusion Web UI 包含一个灵活的脚本系统，允许开发者添加自定义功能。脚本可以是独立的，也可以是扩展的一部分。脚本主要有两种类型：

1. 可选脚本：这些脚本会显示在 txt2img 和 img2img 界面的 Scripts 下拉菜单中，用户可以在需要时选择它们。
2. 始终运行脚本：这些脚本会在每次生成时运行，提供后台功能，无需用户选择。

来源：modules/scripts.py52-364 scripts/xyz_grid.py415-538

2. 脚本架构

Web UI 中的脚本基于 modules/scripts.py 中定义的 Script 类。此类提供了创建脚本的结构，并定义了它们如何与 UI 和处理管道集成。

来源：modules/scripts.py52-348 modules/scripts.py542-577

2.1 脚本加载流程

脚本在启动时从两个主要位置加载到 WebUI 中：

• 内置脚本：位于 scripts/ 目录
• 扩展脚本：位于 extensions/*/scripts/ 目录

来源：modules/scripts.py487-530 modules/extensions.py179-190

3. 创建自定义脚本

要创建自定义脚本，您需要继承 Script 类，并至少实现必需的方法。

3.1 必需的方法

每个脚本都必须实现这些方法：

方法	描述
title()	返回脚本在下拉菜单中显示的名称。
ui(is_img2img)	创建脚本的用户界面元素。
run(p, *args)	可选脚本的主要处理函数。
show(is_img2img)	决定是否在 txt2img 或 img2img 界面中显示脚本。

3.2 可选方法

这些方法允许更深入地集成到处理管道中。

方法	描述
setup(p, *args)	在处理开始前为 AlwaysOn 脚本调用。
before_process(p, *args)	在 AlwaysOn 脚本处理早期调用。
process(p, *args)	在 AlwaysOn 脚本处理前立即调用。
process_batch(p, *args, **kwargs)	为每个图像批次调用。
postprocess_batch(p, *args, **kwargs)	在每个图像批次生成后调用。
postprocess_image(p, pp, *args)	为每个生成的图像调用。
postprocess(p, processed, *args)	在所有处理完成后调用。

来源：modules/scripts.py99-289

3.3 创建脚本 UI

您可以在 ui(is_img2img) 方法中定义脚本的 UI 元素。您可以使用 Gradio 组件来创建界面。

ui() 方法返回的任何组件都将作为参数传递给 run() 方法和其他处理方法。

来源：scripts/xyz_grid.py419-536

4. 脚本生命周期

当 WebUI 处理图像生成请求时，脚本会在多个阶段参与其中。

来源：modules/scripts.py124-288 modules/scripts.py542-577

5. 脚本集成点

脚本可以在 UI 和生成管道的多个点进行集成。

5.1 UI 集成

脚本可以：

• 向界面添加自己的 UI 组件。
• 注册回调函数，用于在 UI 组件创建之前/之后。
• 响应 UI 事件。

来源：modules/scripts.py290-306

5.2 图像生成管道集成

脚本可以在生成管道的多个点进行干预。

来源：modules/scripts.py142-288

6. 示例：XYZ Plot 脚本的解剖

XYZ Plot 脚本（scripts/xyz_grid.py）是一个复杂的脚本示例，它：

1. 创建了一个精心设计的 UI。
2. 与图像生成管道集成。
3. 提供了用于探索参数空间的有用功能。

XYZ Plot 脚本允许用户：

1. 选择三个要变化的参数（X、Y 和 Z 轴）。
2. 为每个参数输入值。
3. 生成具有不同参数组合的图像网格。
4. 将结果查看为带注释的网格。

来源：scripts/xyz_grid.py214-283 scripts/xyz_grid.py415-536 scripts/xyz_grid.py287-397

7. 创建一个简单的自定义脚本

以下是创建基本自定义脚本的分步指南：

1. 在 scripts 目录中创建一个新的 Python 文件，例如 my_script.py。

2. 导入必需的模块。

3. 创建一个继承 Script 的类。

4. 实现所需的方法

   • title()：返回脚本的名称。
   • show(is_img2img)：返回何时显示脚本。
   • ui(is_img2img)：创建 UI 组件。
   • run(p, *args)：实现主要功能。

5. 将脚本放在 scripts 目录中。

7.1 基本脚本模板

以下是一个基本脚本的模板：

8. 始终运行脚本

始终运行脚本会在每次生成时自动运行。它们对于实现需要一致应用的后台功能非常有用。

8.1 创建始终运行脚本

要创建始终运行脚本，请覆盖 show() 方法以返回 scripts.AlwaysVisible。

始终运行脚本使用与可选脚本不同的方法：

• setup(p, *args)：初始设置。
• before_process(p, *args)：早期处理。
• process(p, *args)：主要处理。
• postprocess(p, processed, *args)：最终处理。

来源：modules/scripts.py113-120 modules/scripts.py137-158

9. 脚本回调

Web UI 提供了一个回调系统，允许脚本在图像生成过程的各个阶段进行挂钩。

来源：modules/scripts.py553-576

10. 高级功能和最佳实践

10.1 访问脚本元素 ID

使用 elem_id() 辅助方法生成一致的元素 ID。

来源：modules/scripts.py334-342

10.2 脚本设置

脚本可以通过使用全局 shared.opts 对象来保存和加载设置，或者通过与扩展系统集成来实现更复杂的设置。

10.3 错误处理

始终在脚本中包含适当的错误处理，以避免 Web UI 崩溃。

10.4 脚本依赖

脚本可以使用元数据系统指定对其他脚本或扩展的依赖。这可确保您的脚本按正确的顺序加载。

来源：modules/extensions.py43-102

11. 结论

自定义脚本提供了一种强大的方式来扩展 Stable Diffusion Web UI 的功能，而无需修改核心代码。通过理解脚本架构和生命周期，您可以创建与 UI 和图像生成管道无缝集成的自定义脚本。

有关更多示例，请查看 scripts 目录中的内置脚本，特别是 xyz_grid.py，它演示了本页面讨论的许多概念。