FantasyTalking Hugging Face Space 部署指南

本项目是FantasyTalking的Hugging Face Space演示版本，由于模型体积巨大（40GB+）和GPU内存需求，在线Space主要展示界面，完整功能需要本地部署。

🚀 在Hugging Face Space中部署

方法1: 直接复制项目

登录 Hugging Face
创建新的Space: https://huggingface.co/new-space
选择Gradio SDK
将本项目所有文件上传到Space

方法2: 从GitHub导入

Fork原始仓库: https://github.com/Fantasy-AMAP/fantasy-talking
在Hugging Face创建Space时选择"Import from GitHub"
输入你的GitHub仓库地址

Space配置

确保在Space的README.md中包含以下配置：

---
title: FantasyTalking Demo
emoji: 🎬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: apache-2.0
---

💻 本地完整部署

环境要求

操作系统: Linux/Windows/macOS
Python: 3.8+
GPU: NVIDIA GPU with CUDA
VRAM: 至少5GB（推荐20GB+）
存储: 50GB+可用空间
内存: 16GB+

快速部署

# 1. 克隆仓库
git clone https://github.com/Fantasy-AMAP/fantasy-talking.git
cd fantasy-talking

# 2. 自动部署（推荐）
python deploy.py

# 3. 手动部署
# 安装依赖
pip install -r requirements.txt
pip install flash_attn  # 可选，需要CUDA

# 下载模型
huggingface-cli download Wan-AI/Wan2.1-I2V-14B-720P --local-dir ./models/Wan2.1-I2V-14B-720P
huggingface-cli download facebook/wav2vec2-base-960h --local-dir ./models/wav2vec2-base-960h
huggingface-cli download acvlab/FantasyTalking fantasytalking_model.ckpt --local-dir ./models

# 运行应用
python app.py

Docker部署

FROM nvidia/cuda:11.8-devel-ubuntu20.04

RUN apt-get update && apt-get install -y \
    python3 python3-pip git ffmpeg \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip3 install -r requirements.txt

COPY . .
CMD ["python3", "app.py"]

🔧 配置选项

内存优化

根据GPU内存调整num_persistent_param_in_dit参数：

40GB+ VRAM: None (无限制，最快)
20GB VRAM: 7000000000 (7B参数)
5GB VRAM: 0 (最省内存，较慢)

模型精度

torch.bfloat16: 推荐，平衡速度和质量
torch.float16: 更快，可能影响质量
torch.float32: 最高质量，需要更多内存

📊 性能参考

配置	GPU	VRAM	生成时间 (81帧)
最高质量	A100	40GB	15.5s/it
平衡模式	RTX 4090	20GB	32.8s/it
节能模式	RTX 3060	5GB	42.6s/it

🛠 故障排除

常见问题

CUDA内存不足

# 设置环境变量
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

模型下载失败

# 使用镜像
export HF_ENDPOINT=https://hf-mirror.com

依赖冲突

# 使用虚拟环境
python -m venv fantasy_talking
source fantasy_talking/bin/activate  # Linux/Mac
# fantasy_talking\Scripts\activate  # Windows

日志和调试

# 启用详细日志
export PYTHONPATH=.
export CUDA_LAUNCH_BLOCKING=1
python app.py --debug

🌐 在线资源

原始仓库: https://github.com/Fantasy-AMAP/fantasy-talking
论文: https://arxiv.org/abs/2504.04842
模型: https://huggingface.co/acvlab/FantasyTalking
在线演示: https://huggingface.co/spaces/acvlab/FantasyTalking

📄 许可证

本项目遵循Apache-2.0许可证。详见原始仓库。

🤝 贡献

欢迎提交Issue和Pull Request到原始仓库： https://github.com/Fantasy-AMAP/fantasy-talking