模型修补和 LoRA

相关源文件

• comfy/ldm/chroma/layers.py
• comfy/ldm/chroma/model.py
• comfy/lora.py
• comfy/model_patcher.py
• comfy_extras/nodes_optimalsteps.py

本文档介绍了 ComfyUI 的动态模型修改系统，包括 ModelPatcher 架构、LoRA（低秩适配）集成、权重管理和高级修补机制。该系统支持非破坏性模型修改、内存高效的权重加载以及运行时模型定制，而无需永久更改基础模型。

有关更广泛的模型系统架构的信息，请参阅 模型系统。有关特定模型类型及其配置的详细信息，请参阅 模型配置与检测。

核心 ModelPatcher 架构

ModelPatcher 类是 ComfyUI 中所有模型修改操作的中央协调器。它提供了一个非破坏性的修补系统，可以动态修改模型权重、应用 LoRA 适配并高效管理内存。

来源： comfy/model_patcher.py201-254

ModelPatcher 维护着几个关键的数据结构

组件	目的	数据结构
patches	待应用的权重修改	dict[str, list[tuple]]
backup	修补前的原始权重	dict[str, namedtuple]
object_patches	运行时对象替换	dict[str, Any]
hook_patches	基于 Hook 的修改	dict[HookRef, dict]
model_options	Transformer 和采样选项	dict

LoRA 集成系统

LoRA 集成通过 comfy.lora 模块处理，该模块为各种 LoRA 格式和权重适配器类型提供了全面的支持。该系统支持多种 LoRA 命名约定，并自动将其映射到正确的模型参数。

来源： comfy/lora.py37-95 comfy/lora.py97-173 comfy/lora.py175-296

LoRA 系统支持多种命名约定

• 通用格式：text_encoders.{layer_name}，实现通用兼容性
• SDXL 格式：lora_te1_*、lora_te2_*，用于双文本编码器
• Diffusers 格式：text_encoder.text_model.encoder.layers.*
• UNet 格式：lora_unet_* 和 diffusers 风格的映射
• 特定模型格式：SD3、Flux、HunyuanDiT 等

权重计算与应用

权重修改系统使用复杂的修补机制，支持多种修补类型，并在不同数据类型之间保持数值精度。

来源： comfy/lora.py332-395 comfy/model_patcher.py122-133

系统中的每个修补程序都存储为一个元组，其中包含

• strength_patch：修补程序的缩放因子
• patch_data：实际的权重修改数据
• strength_model：基础模型的缩放因子
• offset：可选的张量切片信息
• function：可选的转换函数

内存管理和低 VRAM 支持

ComfyUI 的修补系统包含复杂的内存管理，以处理有限 VRAM 系统上的大型模型。该系统可以按需选择性地加载模型组件并应用修补。

来源： comfy/model_patcher.py571-690 comfy/model_patcher.py748-834

内存管理系统实现了几项关键策略

1. 基于模块的加载：根据可用内存，按模块加载模型
2. 低 VRAM 修补：在前向传播过程中应用修补，而不是预先计算
3. 部分卸载：在需要 VRAM 时选择性地将模块移至 CPU
4. 权重函数包装：为内存受限的场景动态计算权重

高级修补功能

ModelPatcher 支持除简单权重修改之外的高级修补功能，包括 Transformer 级修补、注意力修改和自定义函数注入。

来源： comfy/model_patcher.py385-426 comfy/model_patcher.py365-383

高级修补系统提供了几种机制

• Transformer 修补：在前向传播过程中修改特定的 Transformer 组件
• 注意力替换：用自定义实现替换整个注意力机制
• 块级修补：在块边界处拦截和修改激活
• 函数包装：用自定义逻辑包装整个 UNet 或采样函数

Hook 系统集成

ModelPatcher 与 ComfyUI 的 Hook 系统集成，提供动态模型修改功能，这些功能可以在无需完全重新加载模型的情况下进行应用和移除。

来源： comfy/model_patcher.py234-242 comfy/model_patcher.py1097-1188

Hook 系统提供

1. 动态修补：在不完全重新加载模型的情况下应用修改
2. Hook 组：组织相关的 Hook 进行批量操作
3. 缓存：缓存 Hook 计算以提高性能
4. 备份/恢复：维护原始状态以便干净地取消修补

克隆与状态管理

ModelPatcher 实现了一个复杂的克隆系统，该系统能够高效地共享模型状态和独立的修改分支。

来源： comfy/model_patcher.py267-323 comfy/model_patcher.py325-361

克隆系统支持

• 高效分支：创建独立的修改路径，无需复制基础模型
• 状态验证：检查克隆体是否具有等效的权重，以避免冗余操作
• UUID 跟踪：通过唯一标识符跟踪修补程序状态的变化
• 选择性共享：共享不可变状态，同时保持修改的独立性

使用模式和集成

ModelPatcher 通过几种关键模式与 ComfyUI 的执行系统集成，这些模式可在工作流执行期间实现无缝的模型修改。

来源： comfy/model_patcher.py692-747 comfy/model_patcher.py158-181 comfy/model_patcher.py852-857

关键集成模式包括

1. 上下文管理：AutoPatcherEjector 确保在操作期间修补程序状态的正确性
2. 懒加载：仅在执行需要时才修补和加载模型
3. 内存优化：根据可用资源自动进行部分加载/卸载
4. 干净的生命周期：在不再需要模型时进行适当的清理和状态恢复