Avatarify Python 视频会议数字人实战指南从安装部署到 First Order Motion Model 驱动原理【免费下载链接】avatarify-pythonAvatars for Zoom, Skype and other video-conferencing apps.项目地址: https://gitcode.com/gh_mirrors/ava/avatarify-python导读Avatarify Python 是一个开源的照片级真实感数字人Photorealistic Avatar项目它把经典的 First Order Motion Model 图像动画算法与虚拟摄像头技术结合起来让你在 Zoom、Skype、Teams、Slack 等任意可切换视频源的会议软件中用自己的面部动作实时驱动任意一张静态人像名人、StyleGAN 生成的不存在之人乃至你自己的照片。本指南完整覆盖该仓库 README.md 与 安装文档 的全部内容并深入 afy/ 源码层讲解本地 GPU 与远程 GPU 两种运行模式、三平台安装步骤、完整键盘控制集、头像对齐技巧以及模型推理管线的底层实现。读完你将能够独立完成 Avatarify Python 的部署、调参、运行与问题排查。提示Avatarify Python 需要手动下载并安装一些依赖适合具备基础命令行经验的用户。若你希望开箱即用仓库维护者更推荐使用图形界面的 Avatarify Desktop 版本本文档仍以 Avatarify Python 为主线展开。一、项目定位与两种运行模式Avatarify Python 基于 First Order Motion Model一阶运动模型实现——该算法仅需一张静态源图与一段驱动视频即可通过关键点keypoint与局部仿射变换Jacobian的迁移生成高度逼真的人脸动画。项目在仓库根目录 README.md 中明确说明这一点整个推理核心正是围绕该模型展开。根据 安装文档 的 Requirements 一节Avatarify 支持两种运行模式本地模式locally在你的电脑上直接跑完整推理需要一块支持 CUDA 的 NVIDIA 显卡没有 NVIDIA GPU 时会回退到 CPU速度极慢。远程模式remotely把繁重的神经网络推理放到 Google Colab 或带 GPU 的专用服务器上本机只负责采集摄像头画面并显示合成视频流。此模式对电脑本身没有特殊要求仅需稳定的网络连接。无论哪种模式你都需要一个可用的摄像头webcam——它是驱动头像的输入设备。二、系统要求与硬件基线安装文档给出了本地模式在部分 NVIDIA 显卡上的性能基线帧率数据来自官方文档的实测记录实际表现会因驱动、分辨率与后台负载而异显卡帧率fpsGeForce GTX 1080 Ti33GeForce GTX 107015GeForce GTX 9509无 NVIDIA GPU 时PyTorch 会回退到 CPU官方 FAQ 明确说明性能会大幅下降1 fpsMacBook 用户尤其会感受到这一点——Mac 笔记本普遍没有 CUDA 显卡。没有 NVIDIA GPU 又想流畅运行官方给出的路线是远程模式把推理任务卸载到 Colab 或远程 GPU 服务器笔记本只负责视频流的收发。三、安装部署Install3.1 下载网络权重无论哪种平台第一步都是下载模型权重文件vox-adv-cpk.pth.tar约 228 MBmd5sum8a45a24037871c045fbb8a6a8aa95ebc。权重文件从安装文档提供的公开下载渠道获取后直接放置在仓库根目录avatarify-python 目录下不要解压。该文件名与 run.sh 中FOMM_CKPTvox-adv-cpk.pth.tar的约定一一对应启动脚本会在该路径下加载检查点。3.2 Linux 安装Linux 通过v4l2loopback内核模块创建虚拟摄像头。安装步骤如下下载并安装 [Miniconda Python 3.7]bash Miniconda3-latest-Linux-x86_64.sh克隆仓库并执行安装脚本需要 sudo 权限git clone https://gitcode.com/gh_mirrors/ava/avatarify-python.git cd avatarify-python bash scripts/install.sh下载网络权重并放入仓库根目录。来看 scripts/install.sh 究竟做了什么它能帮你理解依赖结构先校验conda与git是否可用克隆并编译安装v4l2loopbackmake sudo make install这是虚拟摄像头的内核基础创建名为avatarify的 conda 环境Python 3.7环境名与 scripts/settings.sh 中CONDA_ENV_NAMEavatarify对应安装numpy1.19.0、scikit-image、python-blosc1.7.0以及pytorch1.7.1、torchvision、cudatoolkit11.0克隆 First Order Motion Model 实现到fomm/子目录执行 requirements.txt 安装其余 Python 依赖opencv-python4.2.0.34视频采集、face-alignment1.3.3人脸关键点检测、pyzmq20.0.0远程模式消息传输、msgpack-numpy张量序列化、pyyaml配置解析、requests、pyfakewebcam0.1.0Linux 虚拟摄像头写入。3.3 Mac 安装Mac 平台使用 CamTwist 创建虚拟摄像头安装 Miniconda Python 3.7或通过 Homebrew Caskbrew install --cask miniconda下载/克隆仓库并运行安装脚本git clone https://gitcode.com/gh_mirrors/ava/avatarify-python.git cd avatarify-python bash scripts/install_mac.sh下载并安装 CamTwist。注意在 Mac 上 Avatarify 只能通过 Google Colab 或带 GPU 的专用服务器远程模式运行——这是官方文档的明确说明原因是 Mac 缺少 CUDA 显卡。3.4 Windows 安装Windows 指南针对 Windows 10 测试通过核心链路是Avatarify 输出窗口 OBS Studio VirtualCam 插件安装 [Miniconda Python 3.8]安装 [Git]打开 Anaconda Prompt逐条执行不要改动命令git clone https://gitcode.com/gh_mirrors/ava/avatarify-python.git cd avatarify-python scripts\install_windows.bat下载权重文件放入仓库根目录运行run_windows.bat。安装成功后会出现 cam 和 avatarify 两个窗口保持它们打开安装 OBS Studio 与 VirtualCam 插件选择 Install and register only 1 virtual camera运行 OBS Studio → Sources 添加 Windows Capture窗口选择 [python.exe]: avatarify随后 Edit → Transform → Fit to screenOBS 菜单 Tools → VirtualCam勾选 AutoStart、Buffered Frames 设为 0点击 Start此时 Zoom 等软件中即可选择OBS-Camera摄像头。步骤 10-11OBS 配置只需在首次设置时执行一次。Windows 的安装脚本与配置文件对应关系run_windows.bat对应启动入口scripts/settings_windows.bat中维护摄像头索引等设置。3.5 Docker 方式仅 LinuxDocker 镜像只在 Linux 上提供。部署步骤按 Docker 官方文档安装 Docker并配置非 root 用户权限使用 GPU强烈建议安装 NVIDIA 驱动与 nvidia-docker克隆仓库并安装依赖即 v4l2loopback 内核模块git clone https://gitcode.com/gh_mirrors/ava/avatarify-python.git cd avatarify-python bash scripts/install_docker.sh构建镜像cd avatarify-python docker build -t avatarify .scripts/install_docker.sh 与 install.sh 的区别在于它只安装 v4l2loopback 内核模块Python 环境全部封装进镜像。仓库根目录的 Dockerfile 揭示了镜像内容基础镜像为nvcr.io/nvidia/cuda:10.0-cudnn7-runtime-ubuntu18.04默认 Python 3.7镜像内克隆了 avatarify 与 fomm 源码并固定 commitpip安装 PyTorch CUDA 10.0 wheel 与两份 requirements暴露 5557/5558 两个端口远程 worker 的输入/输出通信端口默认 CMD 以--is-worker模式启动——也就是说 Docker 镜像默认就是一台远程 GPU worker与 afy/arguments.py 中--is-worker、--in-port、--out-port的参数设计完全对应。四、添加自定义头像Setup avatars仓库自带一批名人头像位于 avatars/ 目录einstein.jpg、eminem.jpg、jobs.jpg、mona.jpg、obama.jpg、potter.jpg、ronaldo.png、schwarzenegger.png 等开箱即用。想扩充头像库非常简单把任意人像图片复制进avatars文件夹即可运行时可随时用键盘热键切换。官方文档给出了三条提升画面质量的头像图片建议对头像图片做正方形裁剪人脸在画面中的占比要适中——不要太近也不要太远以自带标准头像为参考优先选择背景均匀的照片可显著减少合成时的视觉伪影artifacts。五、运行 AvatarifyRun运行前必须插好摄像头。官方强调务必在 Avatarify 启动之后再启动视频会议软件这样会议软件才能正确枚举到虚拟摄像头。5.1 Linuxbash run.sh运行脚本会自动创建虚拟摄像头/dev/video9相关配置在 scripts/settings.sh 中CAMID_VIRT9虚拟摄像头设备号注释特别提醒该值必须大于v4l2-ctl --list-devices列出的最大设备号但不要设得过大——已知 Zoom 无法识别类似 99 这样的高设备号、CONDA_ENV_NAMEavatarifyconda 环境名。可用v4l2-ctl --list-devices查看系统所有视频设备。没有安装 GPU 时加--no-gpus标志想用 Docker 运行加--docker标志。启动后会出现两个窗口cam窗口用于控制你的面部位置对齐参考avatarify窗口用于预览头像动画效果。随后参照下文驱动你的头像小节进行操作。5.2 Mac由于 Mac 无法本地推理运行流程为先按 Google Colab 或专用服务器的方式启动远程推理端在 Mac 上 Avatarify 只支持远程模式打开 CamTwist选择Desktop并点击Select在 Settings 中选择Confine to Application Window并在下拉菜单里选中python (avatarify)窗口。同样会弹出cam与avatarify两个窗口。5.3 Windowscd C:\path\to\avatarify run_windows.bat随后运行 OBS Studio它会自动把 Avatarify 的画面推流到OBS-Camera虚拟摄像头。降低延迟技巧在 OBS 预览窗口上右键取消勾选 Enable Preview。5.4 run.sh 深度解析启动参数与调用链run.sh 是 Linux 启动的核心入口其参数解析逻辑值得展开源码可查run.sh 参数作用透传效果--no-conda跳过 conda 环境激活适用于已手动激活环境的情况无--no-vcam跳过虚拟摄像头创建并向程序透传--no-stream强制不输出视频流--keep-ps不 kill 掉残留的afy/cam_fomm.py进程无--docker改用 docker run 方式启动自动附加 GPU 运行时参数--no-gpusDocker 模式不使用 GPU跳过--gpus all/--runtimenvidia--is-worker以远程 worker 身份启动透传Docker 下映射 5557/5558 端口--is-client/--is-local-client以客户端身份启动透传Docker 下设置网络模式非 Docker 路径下脚本会先 kill 残留进程source scripts/settings.sh调用 scripts/create_virtual_camera.sh 执行sudo modprobe v4l2loopback exclusive_caps1 video_nr$CAMID_VIRT card_labelavatarify创建虚拟摄像头激活 conda 环境最终以如下参数启动推理主程序见 afy/cam_fomm.pypython afy/cam_fomm.py \ --config fomm/config/vox-adv-256.yaml \ --checkpoint vox-adv-cpk.pth.tar \ --virt-cam 9 \ --relative \ --adapt_scale注意--relative相对关键点坐标与--adapt_scale根据关键点凸包自适应运动幅度默认开启这是获得自然动画的两个关键开关对应 afy/predictor_local.py 中normalize_kp()的use_relative_movement与adapt_movement_scale逻辑。六、键盘控制全集Controls官方文档给出了完整的控制键位表运行时可通过这些热键实时操控键位功能1-9立即切换前 9 个头像Q开启 StyleGAN 生成头像按下即采样一个从未存在过的人每次按下换一个新面孔0切换头像显示开/关A / D上一个/下一个头像按文件夹顺序W / S摄像头画面放大/缩小U / H / J / K平移摄像头画面H-左、K-右、U-上、J-下每次 5 像素按住 Shift 则每次 1 像素Shift-Z重置摄像头缩放与平移Z / C调节头像目标叠加层overlay透明度X重置参考帧以当前帧为新的驱动参考F切换参考帧自动搜索模式R镜像参考窗口T镜像输出窗口L重新加载头像列表新增头像后无需重启I显示 FPSO切换人脸检测叠加层ESC退出七、驱动你的头像对齐与参考帧原理这是获得高质量动画效果的关键章节。官方文档给出的核心原则对齐在cam窗口中尽可能让你的脸在比例和位置上与目标头像对齐。使用 W/S 缩放、U/H/J/K 平移来微调。对齐满意后按X以当前帧作为参考帧reference frame来驱动后续整个动画。表情匹配使用图像叠加层Z/C 键或人脸检测叠加层O 键来尽量对齐你与头像的面部表情。进阶参考帧自动搜索F 键。手动对齐不理想时可以按 F 让程序自动寻找更优的参考帧。代价是帧率会下降但搜索期间你可以继续转动头部——当程序发现你的面部姿态与头像的匹配度高于当前参考帧时预览窗口会闪烁绿色提示。屏幕上还会显示两个数字第一个是你当前与头像的对齐程度第二个是当前参考帧的对齐程度。让第一个数字尽量小10 左右通常就是很好的对齐状态。完成后再按 F 退出搜索模式。官方同时说明不需要做到完全精确某些非标准配置也可能取得更好效果以上只是良好的起点。从源码看这一机制对应 afy/predictor_local.py 中的状态管理start_frame/start_frame_kp记录参考帧及其关键点set_source_image()通过kp_detectorFOMM 的关键点检测器提取源图关键点kp_source驱动过程中normalize_kp()计算kp_driving相对kp_driving_initial的位移差kp_value_diff叠加到源关键点上并用源/驱动关键点凸包面积之比ConvexHull(...).volume开方做运动幅度自适应缩放——这正是--relative与--adapt_scale两个参数在推理层的具体实现也是参考帧对齐质量决定动画自然度这一经验的数学根源。八、配置视频会议软件Avatarify 输出的是一个虚拟摄像头因此任何允许更换视频输入源的会议软件都能接入Zoom、Skype、Hangouts、Slack 等。不同平台使用的虚拟摄像头名称不同平台虚拟摄像头名称Linuxavatarifyv4l2loopbackcard_label 即 avatarifyMacCamTwistDesktop 捕获 avatarify 窗口WindowsOBS-CameraOBS VirtualCam 插件各主流软件的接入方式Skype设置 → 音频和视频选择avatarifyLinux、CamTwistMac或OBS-CameraWindows摄像头。Zoom设置 → 视频在 Camera 下拉菜单中选择对应虚拟摄像头。Teams头像 → 设置 → 设备在 Camera 下拉菜单中选择。Slack发起通话允许浏览器使用摄像头点击设置图标在 Video settings 下拉菜单中选择。九、源码级原理本地推理管线与远程传输9.1 推理主程序与命令行参数程序入口为 afy/cam_fomm.py所有命令行参数在 afy/arguments.py 中集中定义完整参数表如下默认值均取自源码参数默认值说明--config无FOMM 模型配置文件路径--checkpointvox-cpk.pth.tar权重检查点路径本地运行实为vox-adv-cpk.pth.tar--relativeFalse关闭使用相对/绝对关键点坐标run.sh 默认开启--adapt_scaleFalse关闭基于关键点凸包自适应运动幅度run.sh 默认开启--no-padFalse不对输出图像做 padding--enc_downscale1.0编码器输入下采样倍数牺牲少量画质换取性能提升--virt-cam0虚拟摄像头设备 IDLinux--no-streamFalseLinux 下强制不输出视频流--verboseFalse打印额外调试信息--hide-rectFalse隐藏预览窗口中的辅助矩形--avatars./avatars头像目录路径--is-workerFalse作为远程 GPU worker 进程运行--is-clientFalse作为客户端运行--in-port5557远程 worker 输入端口--out-port5558远程 worker 输出端口--in-addrNone入站消息 socket 地址如example.com:5557--out-addrNone出站消息 socket 地址如example.com:5558--jpg_quality95视频帧 JPEG 压缩质量远程传输用源码中的校验逻辑值得注意以--is-client启动时必须同时提供--in-addr与--out-addr否则直接抛出ValueError——这是远程模式下客户端与 worker 建立连接的强制约束。9.2 模型加载与推理afy/predictor_local.py 中的PredictorLocal类展示了完整的模型装配过程load_checkpoints()从 YAML 配置读取model_params实例化 FOMM 的OcclusionAwareGenerator遮挡感知生成器与KPDetector关键点检测器再用检查点中的generator、kp_detector键加载权重并置为 eval 模式设备选择逻辑为device or (cuda if torch.cuda.is_available() else cpu)——与文档无 NVIDIA GPU 自动回退 CPU的描述一致同时初始化face_alignment.FaceAlignment2D 关键点flip_inputTrue用于实时人脸姿态对齐与参考帧搜索打分对应 F 键功能输入图像经to_tensor()归一化/255、NCHW 布局后送入kp_detector提取关键点。9.3 摄像头选择与全局配置仓库根目录的 config.yaml 控制摄像头枚举行为# how many cameras to query at the first start query_n_cams: 4 # camera configuration path cam_config: ./cam.yamlquery_n_cams: 4表示首次启动时最多探测 4 个摄像头设备cam_config指向./cam.yaml该文件由程序运行时生成/维护用于持久化摄像头选择。摄像头探测与多设备选择逻辑在 afy/camera_selector.py 与 afy/videocaptureasync.py 中实现后者提供了异步视频帧读取封装避免摄像头帧读取阻塞推理主循环。9.4 远程模式网络架构仓库通过afy/下多个模块实现了完整的远程 worker/client 架构worker 端为 afy/predictor_worker.py客户端为 afy/predictor_remote.py底层通信基于 afy/networking.py 的 ZMQpyzmq消息封装帧数据经msgpack-numpy序列化、JPEG--jpg_quality控制压缩比编码后传输。这与 Dockerfile 暴露的 5557/5558 端口、arguments.py 的--in-port/--out-port/--in-addr/--out-addr参数形成闭环远程 GPU 服务器以--is-worker监听 5557/5558本地客户端以--is-client携带地址参数连接笔记本因此可以完全不依赖本地 GPU。官方文档还提供了基于 ngrok/SSH 的公网隧道脚本scripts/open_tunnel_ngrok.sh、scripts/open_tunnel_ssh.sh用于打通云端 worker 与本机客户端的网络通道。十、FAQ 精选Q运行 Avatarify 需要编程知识吗A不需要真正编程但需要基本的命令行操作经验Windows 用户可按官方视频教程操作。Q为什么在我的 MacBook 上运行很慢A模型需要 CUDA 显卡执行重计算MacBook 没有这类 GPU只能回退到 CPU算力不足以流畅运行。Q没有 NVIDIA GPU 能运行吗A能但性能会骤降1 fps。推荐改用 Google Colab 或远程 GPU 服务器的远程模式。Q如何添加新头像A把头像图片放入avatars文件夹即可详见上文添加自定义头像一节。Q头像看起来扭曲变形A需要校准面部位置按上文驱动你的头像的对齐技巧操作对齐后按 X 设置参考帧。Q可以用在商业用途吗A不可以。Avatarify 与 First Order Motion Model 均采用 Creative Commons 非商业Non-Commercial许可禁止商业使用。Q支持哪些视频会议软件A任何能更换视频输入源的软件都支持Zoom、Skype、Hangouts、Slack 等因为它本质是一个虚拟摄像头。十一、卸载与故障排查卸载官方 Wiki 提供了完整的 Avatarify 及相关程序v4l2loopback、OBS 插件等移除指引。故障排查若程序崩溃先在官方 Wiki 的 Troubleshooting 页面查找错误找不到再检索项目 issues仍无解可基于 issue 模板新建问题反馈。结语Avatarify Python 的价值在于把 First Order Motion Model 的研究成果封装成了普通人可用的实时视频会议工具--relative--adapt_scale的默认组合保证了自然的表情迁移v4l2loopback / CamTwist / OBS-VirtualCam 三套虚拟摄像头方案覆盖了 Linux / Mac / Windows 全平台而 ZMQ 远程架构则让无 GPU 用户也能通过云服务器获得流畅体验。本文所涉及的配置、脚本与源码均可直接在仓库中查阅验证动手跑通一遍run.sh再配合 X/F 键掌握参考帧技巧你就能在下一场会议中以数字分身出场了。【免费下载链接】avatarify-pythonAvatars for Zoom, Skype and other video-conferencing apps.项目地址: https://gitcode.com/gh_mirrors/ava/avatarify-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考