Deep-Live-Cam 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

Deep-Live-Cam 是一个使用 Python 编写的实时换脸与视频人脸替换项目。仓库 README 将其描述为：仅使用单张人脸图片，即可进行实时人脸替换和视频深度伪造；项目当前默认分支为 main，README 标题标注的版本为 2.1.6。

仓库元信息显示，该项目有 95966 个 Star、13995 个 Fork，采用 GNU Affero General Public License v3.0（AGPL-3.0）许可证。官方资料提供预构建版本和手动安装方式，手动方式涉及 Python、pip、Git、FFmpeg、模型文件以及可选的 GPU 执行提供程序。

“Real-time face swap and video deepfake with a single click and only a single image.”
来源：README

• 输入形态：单张人脸图片，以及摄像头、视频或其他 README 所列场景中的画面输入。
• 处理方式：通过人脸替换模型和人脸修复模型完成实时处理。
• 运行方式：可使用预构建版本，也可从源代码创建 Python 虚拟环境后运行。
• 合规前提：使用真实人物面孔前应取得本人同意，发布结果时应明确标注为深度伪造内容。

定位与目标用户

该项目定位于本地或预构建环境中的实时人脸替换工具，而不是通用的视频编辑套件。README 提到的使用方向包括定制角色动画、内容制作、服装设计、直播节目和表演等，但这些方向都必须建立在授权素材和合法发布流程之上。

从安装资料可以判断，项目同时面向希望直接使用预构建版本的用户，以及能够处理 Python 环境、模型文件和执行提供程序的技术用户。手动安装章节明确提醒该过程需要技术能力，并建议初学者考虑 Quickstart 版本。

目标工作流

项目的核心工作流是先选择作为替换源的人脸，再选择摄像头或其他画面来源，最后启动实时处理。README 用三个步骤概括该流程：选择人脸、选择摄像头、启动实时处理。

如果使用真人照片，输入图片和输出画面都涉及个人面部信息。部署者需要在采集、处理、保存和发布各环节分别确认授权范围；仓库资料没有提供数据保留策略、访问控制策略或企业审计接口，因此这些部分不能由项目默认承担。

核心功能

核心功能围绕“单张源人脸图片驱动实时替换”展开，附加能力主要改变面部区域的保留策略、多人映射方式和使用场景。每项能力的具体画质、帧率和硬件要求，官方仓库资料没有给出可核查的基准数据。

实时人脸替换

实时人脸替换以单张人脸图片作为源输入，将其映射到实时画面中的目标人脸区域。README 的快速流程要求用户先选择人脸，再选择摄像头，启动后由程序持续处理摄像头画面；因此该能力依赖摄像头输入、换脸模型和可用的执行提供程序。

输出是经过替换处理的实时画面，而不是仓库资料中定义的某个网络接口响应。README 未说明具体帧率、分辨率、多人并发上限或输出编码参数，使用者应以实际构建版本的界面和最新 README 为准。

嘴部遮罩（Mouth Mask）

Mouth Mask 用于保留原始嘴部区域，以便保留目标画面中的嘴部运动。它解决的是换脸后嘴部动作与原画面不一致的问题，触发方式和具体遮罩参数由程序界面或实现决定，仓库资料未提供命令行参数和配置字段。

该能力的输入仍是目标画面与源人脸，处理结果是面部替换区域中保留原始嘴部的画面。README 将其说明为“Retain your original mouth for accurate movement using Mouth Mask”，但没有提供定量准确率或适用边界。

多人脸映射（Face Mapping）

Face Mapping 用于同时为多个目标人物使用不同的人脸。其基本机制是把多个目标脸与多个源脸建立对应关系，而不是让所有目标人物共享同一张源图片。

该功能依赖画面中可识别的多个目标人脸，以及用户提供的映射选择。README 展示了多主体场景，但没有规定可映射的人数、映射保存格式、冲突处理方式或多人场景下的性能数据。

视频、电影与直播场景

README 将观看电影、直播节目和表演列为使用场景。对视频或电影而言，输入是连续的视频画面，输出是经过面部替换的连续画面；对直播而言，处理链路需要持续获取摄像头画面并实时显示结果。

资料没有说明是否支持特定直播协议、推流地址、录制格式、音视频同步策略或网络传输端口，因此不能据此推导出 RTMP、WebRTC 或其他接口支持。

系统架构与关键模块

从 README 能确认的架构是“图形界面或运行脚本＋本地模型文件＋执行提供程序”的处理组合。仓库资料没有提供完整模块图、类图、函数签名或服务端部署说明，下面仅描述资料中能够直接确认的组件边界。

输入与界面层

用户通过预构建程序或 run.py 启动应用，并选择源人脸、摄像头及实时处理操作。macOS 安装说明明确指出需要安装 tkinter，并标注其为图形界面所需依赖；这表明至少有一部分运行流程依赖桌面图形界面。

人脸替换处理层

README 要求下载 inswapper_128_fp16.onnx，并将其放入 models 文件夹。根据文件名和项目描述，该文件承担人脸替换相关模型角色；具体的人脸检测、对齐、融合和后处理调用关系，资料没有完整说明，不应据此虚构内部 API。

人脸修复层

另一个模型文件为 GFPGANv1.4.onnx，同样需要放在 models 文件夹。README 将其作为安装所需模型列出，因此可以确认它是运行所需模型资源之一；模型在处理链路中的具体调用时机和可关闭选项，官方资料未提供。

执行提供程序层

README 明确给出 NVIDIA CUDA 和 Apple Silicon CoreML 两种执行路径，并提供 CPU 运行方式。CUDA 路径使用 --execution-provider cuda 启动，Apple Silicon 路径依赖随官方 onnxruntime macOS wheel 提供的 CoreML 执行提供程序。

执行提供程序决定模型计算使用的后端，但资料没有给出自动选择规则、后端回退顺序或不同设备的性能基准。根据本文作者的经验判断，在排查问题时应先确认 Python 环境、模型文件和执行提供程序三者是否来自同一套安装流程。

依赖与运行环境

手动安装所需的基础工具包括 Python、pip、Git 和 FFmpeg；Windows 还列出了 Visual Studio 2022 Runtimes。README 的手动安装文本标注 Python 3.14 为推荐版本，并写明支持 Python 3.11 至 3.14。

Apple Silicon 的安装资料要求通过 Homebrew 安装 python@3.14 和 python-tk@3.14，然后使用 python3.14 创建虚拟环境。Windows、Linux 和 macOS 的激活命令不同，不能直接混用。

快速开始

快速开始有两条路径：使用官网提供的预构建版本，或根据 README 手动安装。预构建版本面向减少依赖配置的场景，手动安装适合需要从源代码运行并自行管理 Python 环境的用户。

方式一：预构建版本

README 提供 Quickstart 页面，并列出 Windows、Mac Silicon、CPU、NVIDIA 和 AMD 等构建方向。资料只说明这些构建针对硬件进行了优化，没有提供下载文件名、校验值、安装目录或具体构建版本。

预构建版本还区分了名为 Ultimate 的版本，README 称其包含 30 多项专属功能、性能优化和优先支持。该说明属于项目页面中的产品说明，不能据此推导开源仓库版本具备这些全部功能。

方式二：手动安装

下面的命令严格采用 README 提供的 Windows 流程，并创建独立虚拟环境。它只针对本地运行，不包含网络服务、远程控制或未授权目标处理。

git clone --depth 1 https://github.com/hacksider/Deep-Live-Cam.git
cd Deep-Live-Cam
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

安装模型时，需要下载 GFPGANv1.4.onnx 和 inswapper_128_fp16.onnx，并将两个文件放入项目的 models 文件夹。README 还说明首次执行可能会自动下载约 300MB 的模型；该信息来自 README，不代表所有预构建版本都会采用同一下载行为。

最小可运行示例：安装、运行、验证

没有 GPU 时，README 给出的运行命令是 python run.py。该命令是本地桌面运行示例，不需要填写 API Key、端口或远程地址。

python run.py

验证步骤是确认程序能够启动并显示其操作界面，然后按“选择源人脸、选择摄像头、启动实时处理”的流程进行本地测试。若程序提示模型缺失，应先检查 models 目录中的两个 ONNX 文件；仓库资料未提供统一的自动化健康检查命令。

Linux 与 macOS 激活方式

Linux 使用 README 给出的 Python 3.14 虚拟环境命令。命令中的 python3 必须对应已经安装的 Python 3.14，这是原始安装说明中的要求。

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run.py

macOS Apple Silicon 需要先安装 Python 3.14 和 tkinter，再使用 python3.14 创建虚拟环境。README 将该路径限定为 Apple Silicon，并列出了 M1 至 M5 的具体处理说明；Intel Mac 的兼容性信息，官方仓库未提供。

配置说明

项目的公开资料主要通过命令行参数、固定目录和安装命令表达配置，没有提供独立的配置文件示例、环境变量清单或端口配置。下表只列出资料中实际出现的字段或运行约定，未提供的默认值明确保留为空。

表中的“默认值”仅表示 README 中明确给出的推荐值或目录名，不表示程序一定会在所有平台自动采用该值。程序还包含 Mouth Mask、Face Mapping 等界面能力，但资料没有给出对应的配置键、配置文件路径或命令行开关。

进阶用法

进阶运行的主要变化是把计算从 CPU 切换到 README 明确支持的执行后端。切换前应完成对应平台的工具链安装，并确认虚拟环境中的运行时包没有同时保留相互冲突的 CPU 和 GPU 包。

NVIDIA CUDA 执行路径

README 要求安装 CUDA Toolkit 12.8.0、cuDNN v8.9.7 for CUDA 12.x，并确保 cuDNN 的 bin 目录在系统 PATH 中。随后需要升级 CUDA 版本的 PyTorch 相关包，卸载现有的 onnxruntime 与 onnxruntime-gpu，再安装 onnxruntime-gpu==1.21.0。

pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip uninstall onnxruntime onnxruntime-gpu
pip install onnxruntime-gpu==1.21.0
python run.py --execution-provider cuda

这段命令来自 README 的 CUDA 章节。它没有提供 CUDA 设备型号、显存要求、吞吐量或延迟保证，因此不能据此承诺某一硬件上的实时性能。

Apple Silicon CoreML 执行路径

Apple Silicon 路径使用 CoreML 执行提供程序。README 说明不需要额外安装 CoreML 运行时，官方 onnxruntime 的 macOS wheel 已包含该执行提供程序，但前提是已经完成 Python 3.14 和 tkinter 的 macOS 设置。

README 截取的资料在 CoreML 小节末尾不完整，未给出完整的启动命令或额外参数。官方仓库未提供该信息，建议以最新 README 为准，不应把 CUDA 的 --execution-provider cuda 参数直接套用于 CoreML。

虚拟环境重建

如果依赖安装出现问题，README 给出了删除并重建 venv 的流程，还列出 BasicSR 与 GFPGAN 的源码安装修复命令。该流程会从远程 Git 仓库安装依赖，适用于需要按 README 提示修复相关安装问题的本地环境。

rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install git+https://github.com/xinntao/BasicSR.git@master
pip uninstall gfpgan -y
pip install git+https://github.com/TencentARC/GFPGAN.git@master

Windows 用户不能直接执行 rm -rf 和 source；应根据自身系统改用 README 对应的虚拟环境操作方式。上述修复步骤没有在资料中标出兼容版本，执行前应审查依赖变更并保留原环境记录。

可观测性与运维

仓库资料没有提供 Prometheus 指标、日志格式、健康检查接口、端口、服务级别目标（SLA）或集中式运维组件。项目 README 的运行方式更接近本地桌面应用，而不是已定义 HTTP 接口的后台服务。

本地运维可以围绕四类可核查对象建立记录：项目提交版本、Python 版本、模型文件名称以及执行提供程序。由于资料没有给出模型哈希和官方基准，部署记录应保存实际下载来源和文件校验结果；校验算法或命令不在仓库资料中，不能虚构成项目官方要求。

故障记录建议

• 记录操作系统、Python 版本和虚拟环境目录，避免只记录“安装失败”这一结果。
• 记录运行命令，例如 python run.py 或 python run.py --execution-provider cuda。
• 记录 models 目录是否包含两个 README 指定的 ONNX 文件。
• 记录实际使用的是 CPU、CUDA 还是 CoreML 路径，不要把不同后端的错误混在一起。
• 不把未公开的帧率、资源占用或并发能力写成部署承诺。

安全与合规边界

该项目直接处理人脸图像并生成深度伪造内容，风险重点是肖像权、隐私、误导性传播和敏感内容处理。README 已明确要求用户合法、负责地使用；使用真实人物面孔时，应取得本人同意，并在在线分享输出时清楚标注其为深度伪造内容。

授权与隐私

• 只在已获得授权的本地或测试环境中处理人脸图片、摄像头画面和视频。
• 在处理前确认源人脸、目标画面以及发布渠道的授权范围，不能把“能够读取文件”视为“拥有使用权”。
• 对测试素材采取最小化保存原则；仓库未提供自动删除、加密存储或访问审计功能说明。
• 发布结果时保留清晰的深度伪造标识，避免让观看者误以为内容是原始记录。

内容限制与隔离

README 声明软件包含内置检查，用于阻止处理裸体、图形化内容、战争画面等不当或敏感媒体。该检查不应被视为法律审查、内容审核或授权验证的替代品；项目资料没有提供检查规则、覆盖范围、误报率或绕过方式。

不得将该工具用于未授权人物换脸、冒充身份、欺骗他人、制造虚假证据或规避平台规则。本文不提供绕过内容检查、隐藏深度伪造来源或面向未授权目标处理素材的方法。

部署隔离

如果组织需要试用，应使用专门的测试账户、授权素材和隔离工作目录，并限制输出文件的传播范围。由于官方仓库未提供远程服务认证、网络访问控制或审计接口，不能把本项目直接描述为满足企业合规部署要求。

许可证与商用条款

仓库元信息和 LICENSE 文件均指向 AGPL-3.0。LICENSE 的序言明确说明该许可证属于自由软件许可证，并允许在满足许可证条件的前提下复制、修改、分发和运行；序言还说明可以对软件收费，因此“采用 AGPL-3.0”本身不等于禁止商业使用。

商业使用、二次开发和分发都必须遵守仓库附带的完整 LICENSE。分发时应保留适用的版权和许可证信息，并履行对应的源代码提供、修改版本和交互式界面法律声明等义务；具体边界应以仓库 LICENSE 为准，不能仅依据 README 的简短说明判断。

网络服务场景

AGPL-3.0 针对网络服务器场景设置了相应的源代码提供要求。LICENSE 说明，若修改版本在公开网络服务器上运行并向用户提供交互，相关义务可能被触发；实际是否构成许可证所说的 covered work、convey 或对应网络交互场景，应结合具体部署方式和法律意见判断。

项目许可证不自动授予第三方人脸图片、视频、音乐、商标或其他素材的权利，也不替使用者完成肖像权、隐私权和内容发布合规审查。软件无担保等条款也应以 LICENSE 的完整文本为准。

局限性与已知限制

已知限制首先来自安装和资料完整性：手动安装不是面向初学者的流程，GPU 路径需要额外运行时组件，模型文件需要单独准备。README 没有给出统一硬件最低要求、显存要求、分辨率限制、帧率指标和长时间运行稳定性数据。

• 不同平台的安装步骤不完全相同，Windows、Linux 和 Apple Silicon 不能共用同一套激活命令。
• CPU 运行命令虽然由 README 提供，但资料没有给出 CPU 场景的性能保证。
• CUDA 相关版本要求较具体，但没有提供支持的 NVIDIA GPU 型号列表。
• CoreML 章节资料不完整，官方仓库未提供该信息，建议以最新 README 为准。
• 没有公开的端口、远程 API、容器镜像、日志协议或服务端扩展说明。
• 内置内容检查的具体规则和覆盖边界没有公开，不能将其当作完整安全防护。
• Face Mapping、Mouth Mask 等功能的详细参数、导出格式和自动化接口没有在给定资料中说明。

根据本文作者的经验判断，实时视觉处理的结果会受到源图片质量、目标画面角度、光照、遮挡和设备执行后端影响，但仓库资料没有提供这些因素的量化测试，因此这里只能将其作为测试设计关注点，不能当作项目基准结论。

适合谁

以下信号表明项目与使用者的工作流较匹配，判断依据来自 README 的功能、安装和平台说明，而不是对效果或性能的额外承诺。

• 具备本地 Python 环境管理能力：能够创建虚拟环境、安装依赖、准备模型文件，并处理平台差异。
• 需要桌面实时预览：工作内容涉及授权的摄像头、直播节目、表演或本地视频测试，需要在实时画面中查看换脸结果。
• 已经拥有合规素材：源人脸和目标视频均有明确授权，且能够对发布结果进行深度伪造标识。
• 需要研究模型执行后端：设备属于 README 提到的 CPU、NVIDIA、AMD 或 Apple Silicon 使用范围，并愿意分别验证对应安装路径。
• 接受 AGPL-3.0 合规工作：团队能够审查修改、分发和网络服务部署带来的许可证义务。

不适合谁

以下信号意味着应谨慎采用或暂缓采用，因为项目资料没有覆盖相应的产品化保证或合规能力。

• 需要未经同意处理真人面孔：该用法直接违反 README 所要求的同意和负责任使用边界。
• 需要隐藏或误导性传播合成内容：README 要求在线分享时明确标注深度伪造，项目不适合作为隐蔽冒充工具。
• 需要企业级远程服务：如果要求认证、权限、审计、端口协议、SLA 或高并发指标，官方资料没有提供这些能力说明。
• 无法处理原生依赖安装：手动安装明确要求技术能力；预构建版本的具体平台覆盖和下载细节仍需以官网页面为准。
• 需要有法律效力的内容鉴别或审核：内置内容检查不是授权证明，也不是完整的法律或平台审核系统。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分“程序无法启动”“模型缺失”“后端不可用”和“内容处理不符合预期”四类问题。README 提供了部分安装修复路径，但没有提供统一错误码或诊断命令。

为什么启动后提示模型相关问题

检查项目目录下是否存在 models 文件夹，以及其中是否放置 GFPGANv1.4.onnx 和 inswapper_128_fp16.onnx。README 还说明首次执行会下载约 300MB 的模型，因此应确认本地环境能够完成该下载；若下载行为或文件路径与当前版本不同，官方仓库未提供该信息，建议以最新 README 为准。

为什么 CUDA 命令无法使用

先核对 CUDA Toolkit 12.8.0、cuDNN v8.9.7 for CUDA 12.x 和 onnxruntime-gpu==1.21.0 是否按照 README 的顺序配置，并确认 cuDNN bin 目录已经加入 PATH。随后确认运行命令确实包含 --execution-provider cuda；项目资料没有提供 GPU 型号兼容表和错误码解释。

macOS 是否需要安装额外的 CoreML 包

README 说明 Apple Silicon 不需要额外安装 CoreML 执行提供程序，官方 onnxruntime macOS wheel 已包含该提供程序。前提是完成 Python 3.14、python-tk@3.14 和虚拟环境设置；更具体的 CoreML 启动参数，官方仓库未提供该信息。

是否需要 API Key 或端口

给定资料没有出现 API Key、环境变量、端口或远程接口配置。当前可核查的启动方式是本地执行 python run.py，或使用 README 给出的 CUDA 参数；不要为项目臆造不存在的 API 配置。

安装依赖冲突如何处理

README 给出的处理方式是删除并重建虚拟环境，然后重新安装 requirements.txt；在涉及 GFPGAN 和 BasicSR 问题时，README 还给出从 Git 仓库安装 BasicSR、卸载 GFPGAN 后从其官方 Git 仓库安装的修复命令。执行前应保存错误日志和当前依赖状态，避免在无法回滚的环境中直接覆盖安装。

如何确认测试使用的是授权素材

在启动前建立源人脸和目标画面的授权记录，并在输出文件名或测试记录中标明“测试合成”。发布前必须再次确认深度伪造标识和传播范围；软件的内置内容检查不能代替使用者完成这一流程。

项目地址与资源

以下链接均来自仓库元信息或 README 中出现的项目、文档和依赖官方页面，版本与安装细节应以页面当前内容为准。

• Deep-Live-Cam GitHub 仓库
• Deep-Live-Cam 官网与文档
• Deep-Live-Cam Quickstart 页面
• GFPGANv1.4 ONNX 模型
• inswapper_128_fp16 ONNX 模型
• NVIDIA CUDA Toolkit 12.8.0
• NVIDIA cuDNN Archive
• Visual Studio C++ Build Tools
• BasicSR 官方 GitHub 仓库
• GFPGAN 官方 GitHub 仓库