ReActor ComfyUI 换脸节点部署指南
ReActor — ComfyUI 换脸节点部署与应用指南
适用场景：人物换脸、面容迁移、角色面容一致性 硬件约束：12GB VRAM / 24GB RAM（WSL2） 特性：CPU 推理为主，显存占用极小（<0.3GB）
目录
1. ReActor 是什么
ReActor 是 ComfyUI 的一个自定义节点，专门做面部替换（face swap）。它的核心依赖是 InsightFace——目前最主流的开源人脸分析库。
一句话功能：给定一张”源脸”和一张”目标图”，把目标图里的人脸替换为源脸。
为什么不在 FLUX 扩散管线里做
FLUX 整个扩散去噪过程是随机生成——面部特征在每一步降噪中都有微小的随机偏差。即使提示词精确描述了某个人的面部特征，最终结果也只是”像”，不会是”同一个人”。
ReActor 不走扩散路线。它做的是：
目标脸 → 提取面部特征向量（确定性数学运算）→ 贴到目标图的人脸坐标上这是复制+粘贴+融合，不是生成。所以面容身份可以精确保留。
2. 为什么换脸是专门问题
工程层面的答案
换脸需求有三个硬约束，通用图像生成模型满足不了任何一个：
- 身份保真度（Identity fidelity）：新脸必须是”那个人”，不是”大概像”
- 空间精度（Spatial precision）：只换脸，不动发型、脖子、耳朵、背景
- 一致性（Consistency）：多张图中同一张源脸应该看起来完全一样
FLUX 为代表的扩散模型在设计上就不满足这三条——扩散模型是”创造”而非”复制”。
所以需要专门工具
换脸工具（ReActor/InsightFace/Roop 等）走的是”检测→对齐→替换→融合”管线，每条都针对这个任务的物理约束做了专门优化。它不是 AI 画图，它是 AI 图像处理。
3. 工作原理
┌──────────────────┐ ┌──────────────────┐
│ 源脸图像 │ │ 目标图像 │
│ (source face) │ │ (target image) │
└────────┬─────────┘ └────────┬─────────┘
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ InsightFace │ │ InsightFace │
│ 人脸检测 │ │ 人脸检测 │
│ ← buffalo_l │ │ ← buffalo_l │
└────────┬────────┘ └────────┬────────┘
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ 提取 512 维 │ │ 定位人脸 │
│ 面部嵌入向量 │ │ 关键点 + 边界框 │
│ (唯一的"身份证") │ │ │
└────────┬────────┘ └────────┬────────┘
│ │
└────────┬───────────────┘
▼
┌───────────────────┐
│ 面部对齐 + 投射 │ ← 源脸的 embedding
│ 颜色校正 + 融合 │ 映射到目标脸的位置
└────────┬──────────┘
▼
┌───────────────────┐
│ 输出图像 │
│ 脸 = 源脸人物 │
│ 其他 = 目标图不变 │
└───────────────────┘核心概念：InsightFace 产出的 512 维面部嵌入向量（embedding）是同一张脸的”数学身份证”。同一个人的不同照片，embedding 之间的距离很近；不同人的 embedding 距离很远。ReActor 把源脸的 embedding 强映射到目标脸的坐标上。
4. 部署步骤
4.1 安装 ReActor 节点
⚠️ 注意：原仓库
Gourieff/comfyui-reactor-node已被 GitHub 禁用。新官方仓库地址去掉了-node后缀。
cd /home/doebk/ai/image-generation/ComfyUI/custom_nodes
# 克隆 ReActor 仓库（新地址）
git clone https://github.com/Gourieff/comfyui-reactor.git
# 进入目录
cd comfyui-reactor
# 安装 Python 依赖（使用你的 venv）
source /home/doebk/ai/image-generation/venv/bin/activate
pip install -r requirements.txt
# 额外依赖
pip install insightface onnxruntime opencv-pythonℹ️ v0.7.0 新变化：新版本自带 ReActor Core，不再需要 C++ 编译工具，且同时支持 NumPy 1.x 和 2.x（你的 venv 里是 numpy 2.4.4，完全兼容）。
⚠️ WSL2 注意：ReActor 的 GPU 依赖（onnxruntime-gpu）在 WSL2 下可能有兼容问题。如果遇到 CUDA 相关错误，回退到 CPU 版本的 onnxruntime——ReActor 的推理本来就以 CPU 为主，速度差别不大（几秒一张）。
4.2 下载所需模型
ReActor 首次运行时会自动下载模型。如果自动下载失败（WSL2 网络问题很常见），手动下载到对应目录。
4.2.1 核心换脸模型（必装）
mkdir -p /home/doebk/ai/image-generation/ComfyUI/models/insightface
# 下载 inswapper_128.onnx（核心换脸模型，~528MB）
curl -L -o /home/doebk/ai/image-generation/ComfyUI/models/insightface/inswapper_128.onnx \
"https://huggingface.co/datasets/Gourieff/ReActor/resolve/main/models/inswapper_128.onnx"4.2.2 InsightFace buffalo_l 人脸检测模型（必装）
# 新版将模型放在 ComfyUI/models/insightface/models/buffalo_l/
mkdir -p /home/doebk/ai/image-generation/ComfyUI/models/insightface/models/buffalo_l
# 方式一：下载整包 zip 解压
curl -L -o buffalo_l.zip "https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_l.zip"
unzip buffalo_l.zip -d /home/doebk/ai/image-generation/ComfyUI/models/insightface/models/buffalo_l/
rm buffalo_l.zip
# 方式二：从 HuggingFace 镜像逐个下载所需文件：
# det_10g.onnx (~16 MB) 人脸检测
# 1k3d68.onnx (~130 MB) 3D 人脸对齐
# 2d106det.onnx (~4 MB) 106 点人脸关键点
# genderage.onnx (~1 MB) 性别年龄（可选）
# w600k_r50.onnx (~165 MB) 面部识别/embedding 提取HuggingFace 镜像：
https://huggingface.co/deepinsight/insightface/resolve/main/buffalo_l/4.2.3 面部修复模型（可选，推荐）
mkdir -p /home/doebk/ai/image-generation/ComfyUI/models/facerestore_models
# CodeFormer（推荐）和 GFPGAN 可从以下地址下载：
# https://huggingface.co/datasets/Gourieff/ReActor/tree/main/models/facerestore_models4.3 验证安装
重启 ComfyUI 后，在节点列表中搜索 “ReActor”，应出现以下节点：
ReActorFaceSwap— 主换脸节点ReActorLoadFaceModel— 加载源脸模型（高级用法）ReActorSaveFaceModel— 保存/缓存人脸特征（可选）ReActorFaceSimilarity— 面部相似度比对（v0.7.0 新增）
ℹ️ v0.7.0 新增：Face Similarity 节点可以计算两张脸 embedding 的余弦相似度，用于验证换脸效果或选择最佳源脸图。
4.4 显存/内存账
InsightFace buffalo_l 模型： ~320 MB
inswapper_128.onnx 换脸模型： ~500 MB
面部修复模型（CodeFormer 等）： ~600 MB（可选）
─────────────────────────────────────────
模型总计（必装）： ~820 MB
模型总计（含可选）： ~1.4 GB
实际加载到 GPU 的部分： ~200-250 MB（推理时）
ReActor 节点开销： < 50 MB
FLUX 管线（你现有的）： ~12.8 GB
─────────────────────────────────────────
总额外增量： ~0.2-0.3 GB
总显存（FLUX + ReActor）： ~13 GB
结论：12GB 显存在边界，可能有少量 swap 但能跑。
如果显存紧张，可以先跑 FLUX 生图 → 保存 → 再单独用 ReActor 换脸（不同时加载 UNET）。5. 工作流结构
5.1 纯换脸工作流（独立于 FLUX）
┌──────────────────┐ ┌──────────────────┐
│ LoadImage │ │ LoadImage │
│ (source: 源脸) │ │ (target: 目标图) │
│ 正脸、清晰、光照好 │ │ 要换成谁的图片 │
└────────┬─────────┘ └────────┬─────────┘
│ │
▼ ▼
┌─────────────────────────────────────────┐
│ ReActorFaceSwap │
│ │
│ 参数: │
│ source_faces_index: 0 (第一张脸) │
│ face_index: 0 (目标图中第一个人) │
│ face_restore_model: CodeFormer │
│ face_restore_visibility: 0.8 │
│ codeformer_weight: 0.75 │
│ restore_first: true │
│ │
└────────────────────┬────────────────────┘
▼
┌──────────────────┐
│ SaveImage │
└──────────────────┘5.2 FLUX 生图 → ReActor 换脸（串联管线）
把你现有的 FLUX 文生图连到 ReActor：
你的现有管线 ReActor 部分
────────────── ────────────
CLIPTextEncode → CFGGuider
↘
UnetLoaderGGUF → ModelSamplingFlux
↘
EmptyLatentImage → SamplerCustom → VAEDecode → 生成图像
│
▼
LoadImage(源脸图) ────────────────────→ ReActorFaceSwap
│
▼
SaveImage(最终输出)连通要点：把 VAEDecode 输出的 IMAGE 直接连到 ReActorFaceSwap 的 input_image。LoadImage(源脸) 的输出连到 source_image。完全不需要中间保存文件。
6. 参数调节速查
6.1 核心参数
| 参数 | 推荐值 | 作用 | 调节建议 |
|---|---|---|---|
| face_restore_model | CodeFormer | 换脸后的面部修复算法 | CodeFormer > GFPGAN。CodeFormer 更自然 |
| face_restore_visibility | 0.75 - 0.85 | 修复强度 | 过高(>0.9)像塑料，过低残余感重 |
| codeformer_weight | 0.6 - 0.75 | CodeFormer 去噪力度 | 越低越自然但瑕疵多；越高越光滑但像 AI |
| restore_first | true | 先修复再换脸 vs 先换脸再修复 | 通常 true 效果更好 |
| face_detection_size | 640 | 检测分辨率 | 640 是平衡点；人脸太小(<64px)设更高 |
| source_faces_index | 0 | 源图中的第几张脸 | 多人合照选对应索引 |
| face_index | 0 | 目标图中的第几张脸 | 同上 |
6.2 常见效果问题及修复
| 问题 | 原因 | 解决 |
|---|---|---|
| 贴合不自然/颜色色差 | 源脸和目标脸光照差异大 | 换一张光照接近的源脸图 |
| 边缘生硬/像贴上去的 | 遮罩融合不足 | 提高 face_restore_visibility 到 0.85 |
| 面部太”塑料” | CodeFormer 过重 | 降到 0.5-0.6 |
| 面容不够像源脸 | embedding 匹配不够 | 用更正、更清晰、光照均匀的源脸图 |
| 检测不到脸 | 侧脸/分辨率不足 | face_detection_size 提到 960，或用正脸图 |
| 换错了人 | 多张脸时索引不对 | 检查 source_faces_index / face_index |
6.3 源脸图片的最佳实践
✅ 好的源脸图:
- 正面照，五官清晰无遮挡
- 光照均匀、自然（不要强光/逆光/闪光灯）
- 分辨率 512×512 以上
- 单人、表情自然
❌ 差的源脸图:
- 侧面、大仰角/俯角
- 戴墨镜/口罩/大面积刘海
- 过度滤镜/美颜/磨皮
- 漫画/绘画（InsightFace 训练在真实人脸）7. 常见问题排查
Q: 安装后报错 “No module named ‘insightface‘“
source /home/doebk/ai/image-generation/venv/bin/activate
pip install insightfaceQ: numpy 版本冲突报错
你的 venv 中 numpy 是 2.4.4，属于 2.x 系列。旧版 ReActor（v0.5.x）只支持 numpy 1.x，新版（v0.7.0+）已同时支持 numpy 1.x 和 2.x。确保从新仓库安装：
git clone https://github.com/Gourieff/comfyui-reactor.git # 新地址，不是 -node 结尾Q: 报错 onnxruntime / CUDA 相关
WSL2 下 onnxruntime-gpu 可能不兼容。解决方法：
pip uninstall onnxruntime-gpu
pip install onnxruntime # CPU 版，ReActor 推理速度差距不到 1 秒Q: 模型下载失败
InsightFace 会尝试从 Google Drive 下载。如果网络不通：
- 从 HuggingFace 镜像手动下载（见 4.2 节）
- 放到
ComfyUI/models/insightface/models/buffalo_l/
Q: 换脸后图片质量下降
ReActor 本身不降画质——但 CodeFormer 修复步骤会在低质量目标图上产生模糊。如果目标图本身已经很清晰（如 FLUX 输出的 1024px 图），可以把 codeformer_weight 设低（0.4-0.5）甚至关闭修复。
8. 组合使用：ReActor + FLUX 管线
8.1 叠加方案对照
| 场景 | 管线 |
|---|---|
| 纯换脸 | LoadImage(源脸) + LoadImage(目标) → ReActor |
| FLUX 文生图后换脸 | FLUX 管线 → ReActor → SaveImage |
| FLUX Fill 换衣后统一面容 | Fill 管线 → ReActor（固定同一张源脸） |
| 批量生成统一面容 | FLUX 多 seed 生成 → 同一张源脸 ReActor 批量替换 |
8.2 显存管理策略
当你需要同时跑 FLUX 和 ReActor 时（12GB 紧张）：
策略 A（推荐）：分步执行
1. FLUX 生图 → SaveImage 保存
2. 关掉 ComfyUI，重开后 LoadImage + ReActor（不加载 FLUX UNET）
显存占用：~1-2 GB（只有 ReActor）
策略 B：同一次启动
1. FLUX 生图
2. 同一个工作流内连 ReActor
显存占用：~13 GB（略紧张但能跑，可能有少量 swap）
策略 C：只跑 ReActor
如果你是从已有图片换脸（不是 FLUX 生成的目标图），FLUX 不需要加载
显存占用：~1-2 GB附录：与当前环境的关系
你的 ComfyUI: /home/doebk/ai/image-generation/ComfyUI/
Python venv: /home/doebk/ai/image-generation/venv/
numpy 版本: 2.4.4（需 ReActor v0.7.0+，已兼容）
需要安装的 nodes: comfyui-reactor（注意不含 -node 后缀）
仓库地址: https://github.com/Gourieff/comfyui-reactor
需要下载的模型:
- inswapper_128.onnx → ComfyUI/models/insightface/
- buffalo_l 人脸检测模型 → ComfyUI/models/insightface/models/buffalo_l/
- 面部修复模型（可选） → ComfyUI/models/facerestore_models/
额外显存: ~0.2-0.3 GB
是否需要 GPU: 推理以 CPU 为主，不需要 CUDA 加速也可用
与 FLUX 的关系:
┌──────────────────────────────────────────────┐
│ FLUX 负责 → 创造画面（人物、场景、光照） │
│ ReActor 负责 → 把画面里的脸换成指定的人 │
│ 两者互不冲突，可以串联 │
│ 依赖包完全独立，无版本冲突 │
└──────────────────────────────────────────────┘安全与伦理提醒
ReActor 是一个换脸工具。合法用途包括：
- 生成内容中保持角色面容一致性
- 隐私保护（遮罩敏感面容）
- 创意表达（自己的照片做风格变化）
请勿用于冒充他人、制作非自愿内容或任何违法用途。