roop：一键换脸的 Stable Diffusion WebUI 扩展｜部署与使用全指南
项目仓库： https://github.com/s0md3v/sd-webui-roop（扩展）；原仓库 s0md3v/roop 已归档
维护方：s0md3v · 依赖：insightface 0.7.3、inswapper_128.onnx · 形态：AUTOMATIC1111 WebUI 扩展 · 状态：原项目已归档（archived）
1 项目简介
roop 是最早走红的一键换脸工具之一。本仓库 sd-webui-roop
是它的 AUTOMATIC1111 Stable Diffusion WebUI 扩展：在
WebUI 里导入一张人脸图，生成结果自动换成该人脸。底层基于 insightface 的
inswapper_128.onnx 模型。
重要状态说明：作者 s0md3v 已归档原 roop 仓库，理由是对这类生成式媒体的二阶影响（deepfake 滥用）有了新认识，主动停止开发。本扩展仓库也随之停止维护。本文仅作历史技术整理，不推荐新项目用于严肃生产。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | roop（sd-webui-roop 扩展） |
| 仓库地址 | github.com/s0md3v/sd-webui-roop |
| 原仓库 | s0md3v/roop（已归档） |
| 依赖 | insightface==0.7.3、inswapper_128.onnx |
| 形态 | A1111 WebUI 扩展 |
| 状态 | 已归档，停止维护 |
1.2 适用场景
- 在 A1111 WebUI 中给生成的人物换脸。
- 历史研究：了解早期开源换脸技术。
1.3 能力边界（官方口径）
- 作者已明确归档，不再接受 PR。
- 内置 NSFW 检测，不当素材无法运行。
- 官方要求：使用真人脸需获本人同意，公开发布须标注 deepfake。
2 功能特性
- 一键换脸：导入人脸图即可在生成结果中替换。
- 多脸选择：可指定替换第几张脸。
- 人脸修复 + 放大：配合 Restore Face / Upscaler 提升质量。
- img2img 微调：denoise 0.1 起步逐步调，平衡质量与相似度。
3 官方界面预览
示例图见开篇图。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 扩展仓库 | github.com/s0md3v/sd-webui-roop | A1111 扩展 |
| 原仓库 | github.com/s0md3v/roop | 已归档 |
| 换脸模型 | inswapper_128.onnx | 权重 |
5 前置要求与服务器配置
5.1 软件前提
- 已安装 AUTOMATIC1111 stable-diffusion-webui。
- Windows 需安装 Visual Studio（含 Python 与 C++ 包）。
pip install insightface==0.7.3。
6 方式一：A1111 扩展安装
# 1. 安装 insightface
pip install insightface==0.7.3
# 2. 在 WebUI 扩展页：
# Extensions → Install from URL
# 填入 https://github.com/s0md3v/sd-webui-roop
# 3. 关闭并重启 WebUI
# 4. 若遇 'NoneType' object has no attribute 'get' 错误：
# 下载 inswapper_128.onnx 放到 <webui_dir>/models/roop/6.1 使用
- 在 "roop" 下拉菜单导入含人脸的图。
- 勾选 "Enable"。
- 生成结果即换上所选人脸。
7 质量调优
- 开启 "Restore Face"。
- 试 "Upscaler" 或在 Extras 页用更精细的放大器。
- img2img 模式 denoise 从 0.1 起步逐步上调。
- 多人图用 "Comma separated face number(s)" 指定替换哪几张脸。
8 常用参数
| 参数 | 说明 |
|---|---|
| Enable | 开关 |
| Restore Face | 人脸修复 |
| Upscaler | 放大器 |
| Comma separated face number(s) | 指定替换的脸序号 |
9 常用运维命令
# 查看 WebUI 进程
ps aux | grep webui10 常见故障排查
- 脸没被换：确认点了 Enable；控制台无错说明被判为 NSFW 或没检测到脸。
- insightface 安装失败：Windows 需 Visual Studio C++ 包。
- 想找活跃维护的替代：原作者已归档；社区有 facefusion 等活跃替代，但本文不展开。
11 风险与合规说明
- deepfake 滥用风险：作者已因伦理顾虑归档项目；使用时必须遵守当地法律。
- 官方要求：使用真人脸需获本人同意，公开发布须标注 deepfake。
- 内置 NSFW 检测；法律要求时可加水印或停止服务。
- 不得用于伪造、冒充、诽谤等违法用途。
本文基于官方 README 整理，仅供学习与部署参考；项目已归档，不建议新生产环境采用。