ComfyUI CacheDit 插件

这是一个为 ComfyUI 提供扩散模型推理加速的强大插件，完全兼容标准 CacheDiT API，同时提供丰富的 ComfyUI 节点支持。

🎉 新版本特性：

• ✅ 完全兼容标准 CacheDiT API - 支持 cache_dit.enable_cache() 等标准接口
• ✅ 多种缓存策略 - 固定、动态、自适应三种策略可选
• ✅ 灵活配置 - 支持跳步间隔、预热步数、噪声缩放等参数调整
• ✅ 详细统计 - 提供多层级的性能统计和监控
• ✅ 向后兼容 - 保持所有原有功能不变

---

✨ 特性

核心功能

• 简单直接：开箱即用，无需额外配置
• 加速明显：在 FLUX 等模型上能获得接近 2x 的推理提速
• 即插即用：和普通节点一样放到工作流中使用
• 调试方便：带有基础的性能统计信息

新增功能

• 标准 API 兼容：支持原版 CacheDiT 的所有 API 调用
• 多种缓存策略：固定跳步、动态跳步、自适应策略
• 高级配置：可配置的跳步间隔、预热步数、噪声缩放
• 多模型支持：同时管理多个模型的缓存状态
• 详细监控：模型级别的统计信息和性能分析

---

📦 安装

1. 把插件文件夹放到 ComfyUI 的 custom_nodes 目录下
2. 重启 ComfyUI 即可

---

🔧 使用方法

方法一：标准 CacheDiT API （推荐）

完全兼容原版 CacheDiT API，可以直接替换现有代码：

# 导入 CacheDiT API
import cache_dit

# 基础用法
cache_dit.enable_cache(model)

# 高级用法
cache_dit.enable_cache(model, 
                      skip_interval=3,      # 每3步跳过1步
                      warmup_steps=5,       # 前5步预热
                      strategy='adaptive',  # 自适应策略
                      noise_scale=0.002)    # 噪声缩放

# 获取统计信息
stats = cache_dit.summary(model)
print(stats)

# 禁用缓存
cache_dit.disable_cache(model)

方法二：ComfyUI 节点

基础节点（向后兼容）

1. 在工作流中添加 CacheDit 模型加速 节点
2. 把模型连接到该节点
3. 使用加速后的模型进行推理

高级节点（新功能）

1. CacheDit 高级配置 - 支持多种策略和参数调整
2. CacheDit 缓存控制 - 动态启用/禁用缓存
3. CacheDit 详细统计 - 查看详细性能分析

推荐工作流：

模型加载 → CacheDit 高级配置 → 推理节点 → CacheDit 详细统计

---

📊 缓存策略

1. 固定策略 (Fixed)

• 按固定间隔跳过计算
• 适合稳定的推理场景
• 参数：skip_interval（跳步间隔）

2. 动态策略 (Dynamic)

• 随着步数增加，跳步频率提高
• 适合长序列推理
• 自动优化性能

3. 自适应策略 (Adaptive)

• 根据性能监控自动调整
• 智能优化缓存策略
• 最佳的性能表现

---

⚡ 性能表现

• FLUX 模型：加速可达约 2x
• 缓存命中率：理论上约 50%（固定策略）
• 质量影响：肉眼几乎看不出差别
• 多模型支持：同时加速多个模型

---

🔧 高级配置

API 方式

import cache_dit

# 设置全局配置
cache_dit.set_global_config(
    default_skip_interval=3,
    default_strategy='adaptive',
    global_debug=True
)

# 获取全局统计
stats = cache_dit.get_global_stats()
print(f"总缓存命中: {stats['total_cache_hits']}")

# 重置统计信息
cache_dit.reset_cache_stats()

节点方式

使用 CacheDit 高级配置 节点：

• 策略选择：fixed/dynamic/adaptive
• 跳步间隔：1-10
• 预热步数：0-20
• 噪声缩放：0.0-0.1
• 调试模式：开启/关闭

---

📊 工作原理

基础原理

• 前几步正常运行（预热阶段）
• 之后根据策略跳过部分计算，直接复用之前的结果
• 在复用的结果上加入轻微噪声，避免图像出现明显伪影

这种做法利用了扩散模型相邻步之间结果相似的特点，因此可以节省大量计算。

策略详解

1. 固定策略：每 N 步跳过 1 步，简单可靠
2. 动态策略：随着步数增加动态调整跳步频率
3. 自适应策略：根据性能监控智能优化跳步决策

---

🛠 故障排查

如果节点没有生效，可以尝试：

1. 查看控制台输出的调试日志
2. 确认模型类型是否兼容（目前主要支持 transformer 架构）
3. 检查统计信息，确认缓存是否真的被使用
4. 使用调试模式：cache_dit.enable_cache(model, debug=True)
5. 查看详细统计：使用 CacheDit 详细统计 节点

常见问题

• 缓存效果不佳：调整跳步间隔和预热步数
• 图像质量下降：减小噪声缩放因子或增加预热步数
• 找不到 transformer：检查模型类型兼容性

---

📚 更多资源

• 使用示例：查看 examples.py 文件了解详细用法
• API 文档：所有函数都有详细的文档字符串
• 调试指南：启用 debug 模式获取详细日志
• 性能测试：使用统计功能监控加速效果

---

🚧 开发计划

• ✅ 实现标准 CacheDiT API 兼容性
• ✅ 支持多种缓存策略
• ✅ 添加详细统计和监控
• ✅ 创建高级配置节点
• 🔄 添加更多自适应策略算法
• 🔄 支持更多模型架构
• 🔄 性能基准测试套件

---

📄 License

开源项目，欢迎 issue 和 PR。