%20(1).png)
ComfyUI-hvBlockswap 插件完整使用教程
1. 插件简介
插件地址： https://github.com/fluffydiveX/ComfyUI-hvBlockswap
ComfyUI-hvBlockswap 是一个专门为 HunyuanVideo 视频生成模型设计的内存优化插件。就像给你的电脑装了个"智能搬运工"，它能把不常用的模型组件暂时搬到普通内存里，只在需要时才搬回显卡内存，这样就能让显卡内存不够的小伙伴也能愉快地生成视频了。
主要作用： - 减少显卡内存占用，让低显存用户也能跑HunyuanVideo - 通过智能的"块交换"技术，在不影响生成质量的前提下节省内存 - 专门针对HunyuanVideo模型优化，比通用方案更高效
2. 如何安装
方法一：通过ComfyUI Manager安装（推荐）
- 打开ComfyUI，点击右下角的"Manager"按钮
- 选择"Install Custom Nodes"
- 在搜索框输入"hvBlockswap"
- 找到插件后点击"Install"
- 重启ComfyUI
方法二：手动安装
- 打开ComfyUI安装目录下的
custom_nodes文件夹 - 在命令行中输入：
bash git clone https://github.com/fluffydiveX/ComfyUI-hvBlockswap.git - 重启ComfyUI
3. 节点详解
3.1 HV BlockSwap 节点
这是插件的核心节点，就像一个"智能内存管理器"。它能把HunyuanVideo模型的某些部分临时搬到普通内存里，需要时再搬回来，从而节省显卡内存。
3.2 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 模型 | model | MODEL类型 | 必填 | 就像给搬运工指定要管理哪个模型 | 输入需要进行块交换的HunyuanVideo模型 | 连接你的HunyuanVideo模型加载节点 |
| 交换块数量 | swap_blocks | 0-40 | 10-20 | 决定要把多少个"房间"搬到普通内存里 | 设置要交换到CPU的模型块数量 | 显存8GB建议用20，16GB建议用10 |
| 开启图像编码器卸载 | offload_img_emb | True/False | True | 把图像理解的部分也搬走，进一步节省内存 | 是否将图像编码器移至CPU以节省VRAM | 内存紧张时开启，充足时可关闭 |
| 开启文本编码器卸载 | offload_txt_emb | True/False | True | 把文字理解的部分也搬走，省更多内存 | 是否将文本编码器移至CPU以节省VRAM | 内存紧张时开启，充足时可关闭 |
| 交换策略 | swap_strategy | auto/manual | auto | 让系统自动决定搬哪些，还是你手动指定 | 选择自动或手动的块交换策略 | 新手建议用auto，高手可以用manual |
3.3 HV BlockSwap Loader 节点
这个节点就像一个"专业搬运工招聘处"，专门为HunyuanVideo模型配置最合适的搬运策略。
3.4 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 模型路径 | model_path | 文件路径 | 必填 | 告诉系统你的HunyuanVideo模型放在哪里 | 指定HunyuanVideo模型文件的路径 | 选择你下载的.safetensors模型文件 |
| 预设配置 | preset | low/medium/high | medium | 就像选择搬运工的"工作强度" | 预设的内存优化级别 | 显存少选high，显存多选low |
| 自定义块列表 | custom_blocks | 数字列表 | 空 | 手动指定要搬走哪些"房间" | 手动指定要交换的块索引 | 高级用户可以填[0,1,2,3]这样的数字 |
| 动态调整 | dynamic_adjust | True/False | True | 让系统根据实际情况自动调整搬运策略 | 是否根据当前VRAM使用情况动态调整 | 建议开启，让系统更智能 |
3.5 HV Memory Monitor 节点
这个节点就像一个"内存使用情况监控器"，实时告诉你现在显卡内存用了多少。
3.6 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 显示模式 | display_mode | simple/detailed | detailed | 选择看简单的还是详细的内存信息 | 选择内存信息的显示详细程度 | 新手选simple，想了解详情选detailed |
| 更新频率 | update_freq | 1-10秒 | 2 | 多久刷新一次内存使用情况 | 设置内存监控的更新频率 | 2秒刷新一次比较合适 |
| 警告阈值 | warning_threshold | 50-95% | 80% | 内存用到多少时开始提醒你 | 设置内存使用警告的阈值 | 80%时警告，可以提前做准备 |
| 显示图表 | show_chart | True/False | True | 是否显示内存使用的图表 | 是否在界面显示内存使用的可视化图表 | 开启后可以看到内存使用的曲线图 |
4. 使用技巧和建议
4.1 显卡内存不同的推荐配置
8GB显卡内存： - 交换块数量：20-30 - 开启所有卸载选项 - 预设配置选择"high" - 动态调整开启
12GB显卡内存： - 交换块数量：15-20 - 开启图像编码器卸载 - 预设配置选择"medium" - 动态调整开启
16GB及以上显卡内存： - 交换块数量：5-10 - 可以关闭部分卸载选项 - 预设配置选择"low" - 根据需要开启动态调整
4.2 优化建议
-
先从保守设置开始：第一次使用时，建议从较高的交换块数量开始，然后逐步降低直到找到最适合你显卡的设置。
-
监控内存使用：使用Memory Monitor节点实时监控内存使用情况，避免内存溢出。
-
合理搭配：如果你同时使用其他内存优化插件，注意不要重复优化，可能会产生冲突。
-
定期更新：HunyuanVideo模型在不断更新，插件也会相应优化，建议定期更新插件。
5. 常见问题解答
5.1 为什么开启插件后生成速度变慢了？
原因： 块交换需要在显卡内存和普通内存之间搬运数据，这个过程需要时间。 解决方案： 适当减少交换块数量，或者升级到更快的内存条。
5.2 设置了很高的交换块数量，但内存还是不够用？
原因： 可能是其他部分占用了太多内存，或者你的模型本身就很大。 解决方案： - 检查是否有其他程序占用显卡内存 - 尝试使用量化版本的HunyuanVideo模型 - 开启所有卸载选项
5.3 生成的视频质量下降了？
原因： 过度的块交换可能会影响模型的性能。 解决方案： - 减少交换块数量 - 关闭部分卸载选项 - 在质量和内存使用之间找到平衡点
5.4 插件报错"CUDA out of memory"？
原因： 即使开启了块交换，某些操作仍然需要大量显卡内存。 解决方案： - 增加交换块数量 - 开启所有卸载选项 - 检查是否有其他程序占用显卡内存 - 考虑使用更小的模型
6. 高级用法
6.1 自定义块交换策略
对于有经验的用户，可以通过分析HunyuanVideo模型的结构，手动指定要交换的块。一般来说： - 编码器层可以优先交换 - 注意力层交换后对质量影响较小 - 输出层建议保留在显卡内存中
6.2 与其他优化插件配合使用
可以与以下插件配合使用以获得更好的优化效果： - ComfyUI-WAS-Node-Suite（工作流优化） - ComfyUI-Manager（插件管理） - ComfyUI-Impact-Pack（后处理优化）
6.3 性能监控和调优
建议在工作流中加入性能监控节点，实时查看： - 显卡内存使用率 - 生成速度 - 队列处理时间 - 系统温度
通过这些数据可以更精准地调整块交换参数，找到最佳的性能与质量平衡点。
这个插件就像给你的ComfyUI装了个"智能内存管家"，让你在显卡内存不够的情况下也能愉快地生成高质量视频。记住，合适的设置比极端的设置更重要，慢慢调试找到最适合你电脑的配置就行了！