ComfyUI-KEEP：基于卡尔曼特征传播的视频人脸超分辨率方案，时序特征传播稳住人脸一致性

ComfyUI-KEEP 是一款专为视频与图像人脸超分辨率设计的自定义节点包。其底层算法基于 ECCV 2024 发表的 KEEP（Kalman-Inspired Feature Propagation for Video Face Super-Resolution）。传统的人脸修复方法通常对视频进行逐帧独立处理，这容易导致帧与帧之间人脸身份特征闪烁或不稳定。KEEP 算法通过沿时间轴的卡尔曼式特征传播（光流路径），确保人脸身份在整个视频序列中保持高度一致，而非在每一帧中重新检测和合成。

GitHub：https://github.com/wildminder/ComfyUI-KEEP

该插件将原始算法完整移植至 ComfyUI 环境，提供了一套纯 V3 架构的节点，支持单张图像修复与帧序列处理。

ComfyUI-KEEP：基于卡尔曼特征传播的视频人脸超分辨率方案，时序特征传播稳住人脸一致性

核心工程特性

时序一致性保障（视频感知）：序列处理节点利用光流在帧间传播特征，有效解决了传统逐帧修复带来的身份闪烁问题，确保视频主体的一致性。
双路放大架构（任意放大器）：支持为图像背景连接一个 ComfyUI 原生 UPSCALE_MODEL，同时为修复后的人脸补丁连接第二个独立的放大模型，实现背景与主体的差异化精细处理。
多检测器支持：内置四种人脸检测器供选择，包括 RetinaFace（ResNet50 / MobileNet 0.25）和 YOLOv5（n / l），以适配不同精度与性能需求的场景。
自动化权重管理：模型检查点在首次运行时自动下载，并严格对照其 SHA-256 哈希值进行完整性校验，确保运行环境的安全与稳定。
纯净的 V3 架构：仅使用 comfy_api.latest 节点标准，无遗留映射代码，无导入时自动安装行为，无 sys.path 路径劫持，保证了插件的兼容性与系统环境的清洁。

核心节点与参数详解

该插件注册了三个核心节点，共同构成完整的工作流。

1. Load KEEP Models (节点 ID: KEEP_ModelLoader)

功能：加载 KEEP 检查点、人脸检测/解析模型以及可选的放大模型，生成一个可被后续节点复用的模型包（keep_model_pack）。
参数配置：
- model：选择检查点版本。默认为 KEEP（通用模型），也可选择 Asian（针对亚洲人脸优化的检查点，需参考权重部分说明）。
- detection_model：选择人脸检测器。可选 retinaface_resnet50（默认）、retinaface_mobile0.25、YOLOv5l 或 YOLOv5n。
- bg_upscale_model：（可选）用于图像背景放大的 UPSCALE_MODEL。
- face_upscale_model：（可选）专用于恢复的人脸补丁放大的 UPSCALE_MODEL。
运行机制：该模型包在加载后会被工作流中的每个节点复用。它仅在节点实际运行时加载至 GPU，处理完成后立即释放，以优化显存占用。

2. KEEP Single Image (节点 ID: KEEP_FaceUpscaleImage)

功能：接收单张图像（IMAGE），恢复并增强其中的人脸细节，输出处理后的图像。
参数配置：
- final_upscale_factor：输出图像的最终缩放比例（范围 0.5 – 4.0，步长 0.1，默认 1.0）。若背景放大器为 4× 但期望最终输出为 2×，可将其设为 2.0；设为 1.0 则保持放大器输出的原始尺寸。
高级选项：
- has_aligned_face：若输入已是预先对齐的 512×512 人脸裁剪图，勾选此项可跳过检测步骤。
- only_center_face：若画面中存在多张人脸，默认仅恢复最接近图像中心的那一张。
- draw_bounding_box：在输出图像上绘制检测到的人脸边界框，便于调试。

3. KEEP Image Sequence (节点 ID: KEEP_ProcessImageSequence)

功能：接收帧序列（如视频抽帧），利用 KEEP 的光流传播路径恢复序列中的人脸，输出处理后的图像序列（processed_images）。
参数配置：
- final_upscale_factor：输出帧的最终缩放比例（范围 0.5 – 4.0，步长 0.1，默认 1.0）。
- max_clip_length：KEEP 网络在单批次中处理的帧数（范围 1 – 100，默认 20）。这是控制长序列 VRAM 占用的核心旋钮。
高级选项：与单图节点相同，包含 has_aligned_frames、only_center_face 和 draw_bounding_box。

安装与环境配置

正确的环境配置是节点正常运行的前提。本插件支持通过图形界面或命令行两种方式安装，权重文件将在首次运行时自动处理，无需手动干预。

方式一：通过 ComfyUI Manager 安装（推荐）

打开 ComfyUI Manager。
在搜索框中输入 ComfyUI-KEEP。
点击安装，随后重启 ComfyUI 服务。

方式二：手动源码安装

若需进行二次开发或 Manager 安装失败，可通过命令行手动部署：

# 1. 进入 ComfyUI 的自定义节点目录
cd ComfyUI/custom_nodes/

# 2. 克隆仓库

git clone https://github.com/wildminder/ComfyUI-KEEP.git

# 3. 进入插件目录并安装 Python 依赖
cd ComfyUI-KEEP
pip install -r requirements.txt

安装完成后，必须重启 ComfyUI 服务。

权重自动下载机制：

首次运行工作流时，节点会自动从官方源下载所需的 KEEP 检查点及辅助模型权重，并自动校验 SHA-256 哈希值。若校验失败或网络中断，节点将抛出明确的错误提示（包含具体的文件名与路径），绝不会静默返回空图像，便于快速定位问题。

工作流配置与工程最佳实践

为确保在不同硬件条件下获得最佳的修复效果与运行效率，建议遵循以下工程实践：

显存（VRAM）调节策略：max_clip_length 是控制显存占用的关键参数。长视频序列会被切割成该参数指定长度的片段进行分批处理。在显存较小的 GPU 上，建议将其降低至 8 左右；若显存充裕，可提高至 50 以获得更长的时序上下文，提升特征传播的稳定性。
最终尺寸控制逻辑：final_upscale_factor 作用于放大器模型处理之后。放大器模型（如 4× 模型）会先输出放大后的结果，此参数再对该结果进行二次缩放。若需保持放大器输出的原始尺寸，请保持默认值 1.0。
对齐裁剪的性能优化：若输入图像或帧序列已经是经过对齐处理的 512×512 人脸裁剪图，务必勾选 has_aligned_face 或 has_aligned_frames。这将直接跳过人脸检测与解析步骤，显著提升处理速度并获得更锐利的边缘细节。
主体优先级控制：在复杂场景（如多人合照）中，保持 only_center_face 为 true，可确保模型将计算资源集中于画面最核心的主体，避免因检测多张人脸导致的算力分散或边缘人脸修复质量下降。
兼容性保障：该插件严格遵循 V3 架构规范。节点 ID、显示名称、类别、套接字类型（IMAGE、KEEP_MODEL_PACK、UPSCALE_MODEL）及控件顺序均作为兼容性契约固定。使用早期 V1 节点保存的旧版工作流文件，在加载此插件后仍可保持原样正常运行。