AniPortrait 保姆级部署教程：音频驱动写实人像动画，腾讯智影开源框架

一、项目介绍

AniPortrait 是由腾讯游戏智影（Tencent Games Zhiji）团队发布的音频驱动人像动画框架，论文标题为「AniPortrait: Audio-Driven Synthesis of Photorealistic Portrait Animations」（Huawei Wei、Zejun Yang、Zhisheng Wang）。官方 README 对其定位是：给定一张参考人像照片与一段音频，生成高质量的动画肖像；也可以额外提供一段视频，实现人脸重演（face reenacment）。

项目基于扩散模型（Diffusion）与 AnimateDiff 风格的运动模块，将音频信号转换为头部姿态与表情序列，再驱动 Stable Diffusion 1.5 的 UNet 生成逐帧肖像视频。官方在 Hugging Face Spaces 提供了在线 Gradio Demo（ZJYang/AniPortrait_official），同时在 Hugging Face 与 Wisemodel 上发布了全部预训练权重。项目在 GitHub 持续活跃维护（核验日期 2026-11-01），权重约 10GB 量级，单卡 GPU 即可运行推理。

二、功能拆解

按官方 README，AniPortrait 的核心能力如下：

功能	说明
音频驱动视频（audio2vid）	输入人像参考图 + 音频，直接生成口型同步的说话视频
人脸重演（vid2vid / face reenacment）	输入源视频 + 参考人像图，把源视频中人物的表情与头部姿态迁移到参考人像上
姿态驱动视频（pose2vid / self driven）	输入姿态序列（关键点视频）+ 参考图，生成按指定姿态运动的人像视频
Gradio Web UI	官方提供 `python -m scripts.app` 一键启动网页 Demo
帧插值加速（-acc）	下载 film_net_fp16.pt 后加 `-acc` 参数，使用 RIFE 类帧插值加速推理
头部姿态控制（generate_ref_pose）	生成 `pose_temp.npy`，便于手动控制生成视频的头部运动轨迹
两阶段训练	提供 stage1 / stage2 训练脚本（accelerate launch），支持基于 VFHQ、CelebV-HQ 自研数据训练

三、官方/GitHub 链接

GitHub 仓库：https://github.com/Zejun-Yang/AniPortrait
论文（arXiv）：https://arxiv.org/abs/2403.17694
Hugging Face 模型权重：https://huggingface.co/ZJYang/AniPortrait/tree/main
Hugging Face 在线 Demo：https://huggingface.co/spaces/ZJYang/AniPortrait_official
国内镜像权重（Wisemodel）：https://wisemodel.cn/models/zjyang8510/AniPortrait
基础依赖模型：Stable Diffusion v1.5（https://huggingface.co/runwayml/stable-diffusion-v1-5）、sd-vae-ft-mse（https://huggingface.co/stabilityai/sd-vae-ft-mse）、image_encoder（https://huggingface.co/lambdalabs/sd-image-variations-diffusers）、wav2vec2-base-960h（https://huggingface.co/facebook/wav2vec2-base-960h）

四、环境要求

按官方 README「Build environment」一节：

Python 版本：官方推荐 >= 3.10
CUDA 版本：官方推荐 = 11.7（即 PyTorch + CUDA 11.7 组合）
操作系统：官方未明确限制，但推理脚本基于 Python 与 Linux 生态（建议 Linux）；Windows 用户需自行解决 CUDA 与 ffmpeg 依赖
硬件：项目依赖 Stable Diffusion 1.5 + 运动模块 + wav2vec2，显存需求约 10GB 量级（官方未给出最低显存数字，社区实测需单张 24GB 级显卡较为从容）
磁盘：预训练权重约 10GB+，需预留 20GB 磁盘空间
软件依赖：通过 pip install -r requirements.txt 安装；ffmpeg（音频/视频处理，系统级依赖）、git-lfs（下载权重）

五、部署步骤

步骤 1：克隆仓库

git clone https://github.com/Zejun-Yang/AniPortrait.git
cd AniPortrait

逐段解释：git clone 把官方仓库拉到本地；cd AniPortrait 进入项目根目录，后续所有命令均在此目录下执行。

预期输出参考： 出现 Cloning into 'AniPortrait'... 与远程对象计数、接收进度，最终回到命令行。

步骤 2：安装 Python 依赖

官方原文命令：

pip install -r requirements.txt

逐段解释：pip install -r 按 requirements.txt 中列出的版本安装所有依赖（PyTorch、diffusers、transformers、mediapipe、decord、opencv 等）。官方建议先建好 Python >=3.10、CUDA 11.7 的 conda 环境再执行此命令。

预期输出参考： pip 安装进度条，结束时输出 Successfully installed ... 列表；若已有相同版本依赖则输出 Requirement already satisfied。

步骤 3：下载预训练权重到 ./pretrained_weights

官方要求所有权重放在 ./pretrained_weights 目录下。首先从 Hugging Face 下载 AniPortrait 自带权重：

下载官方训练权重：denoising_unet.pth、reference_unet.pth、pose_guider.pth、motion_module.pth、audio2mesh.pt、audio2pose.pt、film_net_fp16.pt，来源 https://huggingface.co/ZJYang/AniPortrait/tree/main
下载基础模型权重：
- StableDiffusion V1.5：https://huggingface.co/runwayml/stable-diffusion-v1-5
- sd-vae-ft-mse：https://huggingface.co/stabilityai/sd-vae-ft-mse
- image_encoder：https://huggingface.co/lambdalabs/sd-image-variations-diffusers/tree/main/image_encoder
- wav2vec2-base-960h：https://huggingface.co/facebook/wav2vec2-base-960h

最终目录结构必须严格按官方 README 组织：

./pretrained_weights/
|-- image_encoder
|   |-- config.json
|   `-- pytorch_model.bin
|-- sd-vae-ft-mse
|   |-- config.json
|   |-- diffusion_pytorch_model.bin
|   `-- diffusion_pytorch_model.safetensors
|-- stable-diffusion-v1-5
|   |-- feature_extractor
|   |   `-- preprocessor_config.json
|   |-- model_index.json
|   |-- unet
|   |   |-- config.json
|   |   `-- diffusion_pytorch_model.bin
|   `-- v1-inference.yaml
|-- wav2vec2-base-960h
|   |-- config.json
|   |-- feature_extractor_config.json
|   |-- preprocessor_config.json
|   |-- pytorch_model.bin
|   |-- README.md
|   |-- special_tokens_map.json
|   |-- tokenizer_config.json
|   `-- vocab.json
|-- audio2mesh.pt
|-- audio2pose.pt
|-- denoising_unet.pth
|-- film_net_fp16.pt
|-- motion_module.pth
|-- pose_guider.pth
`-- reference_unet.pth

逐段解释：官方 README 要求按此目录结构摆放；若已安装部分基础模型（如已下载过 StableDiffusion V1.5），可在配置文件（如 ./config/prompts/animation.yaml）中指定其路径，不必重复下载。

预期输出参考： 权重文件下载完成；无报错。

步骤 4（可选）：启动 Gradio Web UI

官方原文命令：

python -m scripts.app

逐段解释：python -m scripts.app 以模块方式运行 Gradio 网页演示程序，浏览器打开后可上传图片与音频进行交互式生成。

预期输出参考： Gradio 启动日志，输出形如 Running on local URL: http://127.0.0.1:7860（具体端口以实际输出为准）。

六、配置参数详解

AniPortrait 没有传统意义上的环境变量配置文件，核心运行参数位于 YAML 配置文件中，路径为 ./configs/prompts/ 与 ./configs/inference/。

1. 推理配置文件（官方 README 列出）：

配置文件	用途
`./configs/prompts/animation.yaml`	姿态驱动视频（pose2vid）的参考图与姿态视频清单
`./configs/prompts/animation_facereenac.yaml`	人脸重演（vid2vid）的源视频与参考图清单
`./configs/prompts/animation_audio.yaml`	音频驱动（audio2vid）的音频与参考图清单
`./configs/inference/head_pose_temp/pose.npy`	头部姿态临时文件（由 generate_ref_pose 生成）

2. 推理命令行参数（官方 README）：

参数	说明
`--config`	指定 YAML 配置文件路径
`-W 512`	输出视频宽度（官方示例 512）
`-H 512`	输出视频高度（官方示例 512）
`-L 300`	生成帧数（官方原文："you can set -L to the desired number of generating frames"）
`-acc`	启用帧插值加速（需先下载 film_net_fp16.pt）
`--video_path`	vid2pose 转换时输入的姿态视频路径
`--ref_video` / `--save_path`	generate_ref_pose 命令的参考视频与输出 npy 路径

3. 训练配置（官方 README）：

文件	用途
`./configs/train/stage1.yaml`	阶段 1 训练配置
`./configs/train/stage2.yaml`	阶段 2 训练配置（需在其中指定 stage1_ckpt_dir 与 stage1_ckpt_step）

七、启动与运维

启动 Gradio UI： python -m scripts.app（官方命令）。前台运行，Ctrl+C 退出。
命令行推理（官方原文三类命令）：

# 姿态驱动
python -m scripts.pose2vid --config ./configs/prompts/animation.yaml -W 512 -H 512 -acc

# 人脸重演
python -m scripts.vid2vid --config ./configs/prompts/animation_facereenac.yaml -W 512 -H 512 -acc

# 音频驱动
python -m scripts.audio2vid --config ./configs/prompts/animation_audio.yaml -W 512 -H 512 -acc

后台常驻 / 开机自启： 官方未提供。AniPortrait 是命令行/Gradio 推理工具，不是常驻服务；如需后台运行，可使用系统通用的 nohup 或 tmux 等方式（非官方机制）。
修改端口： 官方 Gradio 启动未提供显式端口参数；如需指定端口，可参考 Gradio 库通用的 server_port 参数（非官方文档内容，按 Gradio 官方文档为准）。
日志： 推理过程直接输出到终端；无独立日志文件机制。
数据持久化： 生成结果默认输出到 YAML 配置中指定的输出路径；权重目录 ./pretrained_weights 即为持久化目录，删除将导致重新下载。

八、实操验证

1. 验证 Gradio UI：

执行 python -m scripts.app 后，浏览器打开终端输出的本地 URL（如 http://127.0.0.1:7860），应看到 AniPortrait 的 Gradio 交互页面，包含上传参考图、上传音频、生成按钮等控件。

2. 运行音频驱动推理（官方示例）：

编辑 ./configs/prompts/animation_audio.yaml，加入自己的参考图与音频路径，然后执行：

python -m scripts.audio2vid --config ./configs/prompts/animation_audio.yaml -W 512 -H 512 -acc

逐段解释：-W 512 -H 512 指定 512×512 输出；-acc 启用帧插值加速。官方原文特别提示："Delete pose_temp in ./configs/prompts/animation_audio.yaml can enable the audio2pose model."——即删除 YAML 中的 pose_temp 字段后，会启用 audio2pose 模型直接从音频生成头部姿态。

预期输出参考： 终端输出扩散模型推理进度（如 denoising step 进度条），最终在 YAML 指定的输出路径生成 mp4 视频文件。无报错即视为部署成功。

3. 验证姿态序列转换（官方示例）：

python -m scripts.vid2pose --video_path pose_video_path.mp4

逐段解释：把原始视频转换为关键点（pose）序列，供 pose2vid 使用。

九、故障排查

案例 1：缺少 audio2pose.pt / audio2mesh.pt 权重，推理报 FileNotFoundError

报错原文（常见形式）：FileNotFoundError: pretrained_weights/audio2pose.pt
报错原因：官方 README 在 2024/04/21 更新中发布了 audio2pose 模型与预训练权重；未下载该权重即运行 audio2vid 会找不到文件。
分步解决：① 前往 https://huggingface.co/ZJYang/AniPortrait/tree/main 下载 audio2pose.pt 与 audio2mesh.pt；② 放到 ./pretrained_weights/ 根目录下（与 denoising_unet.pth 同级）；③ 重新执行推理命令。

案例 2：numpy 2.x 与 mediapipe / decord 冲突

报错原文（社区常见形式）：AttributeError: module 'numpy' has no attribute 'float' 或 decord 导入失败
报错原因：AniPortrait 依赖的 mediapipe、decord 等库在 numpy 2.x 下不兼容（社区部署反馈）。
分步解决：① 在 conda 环境中固定 numpy 1.x 版本：pip install "numpy<2"；② 重新执行 pip install -r requirements.txt；③ 确认 python -c "import mediapipe, decord" 无报错后再运行推理。

案例 3：Gradio 启动报 OOM（显存不足）

报错原文（常见形式）：CUDA out of memory. Tried to allocate ... GiB
报错原因：AniPortrait 同时加载 Stable Diffusion 1.5 UNet、运动模块、wav2vec2 与 audio2pose 模型，单卡显存不足。
分步解决：① 使用官方 -acc 参数启用帧插值（减少逐帧扩散步数）；② 减小输出分辨率（如 -W 384 -H 384）；③ 缩短 -L 帧数；④ 关闭其他占用显存的进程；⑤ 更换显存更大的 GPU（社区建议 24GB 级显卡较为从容）。

案例 4：权重目录结构错误导致加载失败

报错原文（常见形式）：KeyNotFoundError 或 OSError: Can't load config for ...
报错原因：未按官方 README 给出的目录结构摆放权重（例如把 sd-vae-ft-mse 的文件直接放到 pretrained_weights 根目录）。
分步解决：① 对照本文第六节给出的目录树逐项核对；② 确保 sd-vae-ft-mse/、stable-diffusion-v1-5/、image_encoder/、wav2vec2-base-960h/ 四个子目录齐全；③ 重新运行。

十、升级、回滚与卸载

升级：

git pull
pip install -r requirements.txt

逐段解释：git pull 拉取最新代码；重新执行 pip install -r requirements.txt 同步依赖。官方 README 在 Updates 章节多次要求"please update the code and download the weight file"——即升级代码后需同步检查 Hugging Face 权重页面是否有新权重发布。

回滚： 官方未提供专门回滚命令。可基于 git 标签/历史 commit：git checkout <旧 commit> 回到旧版本代码；权重需重新下载对应版本（Hugging Face 仓库的历史版本）。

卸载： ① 删除项目目录 rm -rf AniPortrait；② 删除 conda 环境 conda remove -n 环境名 --all；③ 权重目录随项目目录一并删除。注意：权重约 10GB，删除前如还需复用请先备份到其他目录。

十一、商用许可合规说明

许可证：Apache License 2.0（仓库 LICENSE 文件明确为 Apache 2.0）。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更。
注意事项：AniPortrait 所依赖的基础模型（Stable Diffusion v1.5、wav2vec2、image_encoder、sd-vae-ft-mse 等）各自有独立许可证，商用前需另行核查（如 Stable Diffusion 1.5 的 OpenRAIL-M 许可对生成内容、使用场景有附加约束）。