LOCAL_TEST_GUIDE.md

本地测试和部署指南

文件信息

• 文件路径: LOCAL_TEST_GUIDE.md
• 创建时间: 2024-12-19
• 开发者: aidaox

重要说明

⚠️ 关键修改：requirements.txt 中的 onnxruntime-gpu 已改为 onnxruntime，以确保在 Hugging Face 免费 CPU 服务器上正常运行。

一、本地环境准备

1. 检查 Python 版本

python --version

要求：Python 3.8 或更高版本（推荐 3.9+）

2. 创建虚拟环境（必须，推荐）

为什么需要虚拟环境？

• 避免多个项目依赖冲突
• 保持系统 Python 环境干净
• 便于管理和删除项目

快速设置（使用自动化脚本）：

# 在 FaceSwap 目录下运行
python ../setup_project_env.py

手动设置：

# 进入项目目录
cd FaceSwap

# 创建虚拟环境
# Windows:
python -m venv venv
venv\Scripts\activate

# Linux/Mac:
python3 -m venv venv
source venv/bin/activate

# 激活后，命令行前面会显示 (venv)

3. 安装依赖

# 确保虚拟环境已激活（命令行前有 (venv)）

# 安装 Python 依赖
pip install -r requirements.txt

# 如果安装失败，可以逐个安装
pip install numpy opencv-python onnxruntime-gpu scikit-learn scikit-image tqdm mxnet insightface gradio

注意：每次使用项目前，都需要先激活虚拟环境！

4. 安装系统依赖（FFmpeg）

Windows:

1. 下载 FFmpeg: https://ffmpeg.org/download.html
2. 解压并添加到系统 PATH
3. 或在项目目录中放置 ffmpeg.exe

Linux:

sudo apt-get update
sudo apt-get install ffmpeg

Mac:

brew install ffmpeg

验证安装：

ffmpeg -version

二、本地测试

方法一：使用测试脚本（推荐）

重要：确保虚拟环境已激活！

# 确保虚拟环境已激活
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate

# 运行测试脚本
python test_local.py

方法二：直接运行 Gradio 应用

# 确保虚拟环境已激活
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate

# 基本运行
python app.py

# 如果需要公网访问（使用 Gradio 的分享链接）
python app.py --share

应用启动后，浏览器会自动打开，或访问显示的本地地址（通常是 http://127.0.0.1:7860）

测试要点

1. 测试单张图片换脸：

   • 准备两张包含人脸的图片
   • 在 "Single Photo Swapping" 标签页测试
   • 检查输出图片是否正确

2. 测试视频换脸（可选，较慢）：

   • 准备一张源图片和一个短视频（建议 5-10 秒）
   • 在 "Video Swapping" 标签页测试
   • 检查输出视频是否正确

3. 检查日志输出：

   • 查看是否有错误信息
   • 确认所有依赖都正常加载

三、部署前检查清单

在推送到 Hugging Face 之前，请确保：

✅ 依赖检查

• requirements.txt 中使用 onnxruntime（不是 onnxruntime-gpu）
• 所有依赖版本兼容 CPU 环境
• packages.txt 中只包含系统包（如 ffmpeg）

✅ 代码检查

• 没有硬编码的本地路径（如 C:\Users\...）
• 没有使用 GPU 特定代码（如 ctx_id=0 在 CPU 上应该改为 -1）
• 所有文件路径使用相对路径
• 没有引用本地不存在的文件

✅ 文件检查

• app.py 存在且可运行
• README.md 配置正确（app_file: app.py）
• inswapper_128.onnx 模型文件存在
• 没有 .gitignore 忽略必要文件

✅ 性能优化（针对免费 CPU 服务器）

• 图片处理限制在合理大小（建议不超过 1024x1024）
• 视频处理限制帧数或时长
• 添加超时处理，避免长时间运行

四、修复 CPU/GPU 兼容性问题

检查 SinglePhoto.py

查看 SinglePhoto.py 中的设备配置：

# 如果是 GPU 配置
self.app.prepare(ctx_id=0, det_size=(640, 640))

# 应该改为 CPU 配置（如果 ctx_id=0 表示 GPU）
# ctx_id=-1 表示 CPU
self.app.prepare(ctx_id=-1, det_size=(640, 640))

注意：ctx_id=0 在某些情况下可能也支持 CPU，但 -1 明确表示 CPU。

五、推送到 Hugging Face

1. 提交修改

# 查看修改
git status

# 添加修改的文件
git add requirements.txt
git add LOCAL_TEST_GUIDE.md
# ... 其他修改的文件

# 提交
git commit -m "修复 CPU 兼容性：将 onnxruntime-gpu 改为 onnxruntime"

# 推送到 Hugging Face
git push origin main

2. 在 Hugging Face 上验证

1. 访问你的 Space: https://huggingface.co/spaces/aidao/FaceSwap
2. 等待构建完成（通常 5-10 分钟）
3. 测试应用是否正常运行
4. 检查日志是否有错误

六、常见问题

Q: 本地运行正常，但 Hugging Face 上失败？

可能原因：

1. 使用了 GPU 特定依赖（如 onnxruntime-gpu）
2. 代码中硬编码了 GPU 设备（ctx_id=0）
3. 缺少系统依赖（如 FFmpeg）

解决方法：

• 检查 requirements.txt 确保使用 CPU 版本
• 检查代码中的设备配置
• 确保 packages.txt 包含所有系统依赖

Q: 模型文件太大，无法上传？

解决方法：

• 使用 Git LFS 管理大文件
• 或使用 Hugging Face 的文件上传功能

Q: 本地测试很慢？

原因：CPU 处理比 GPU 慢很多，这是正常的。

优化建议：

• 使用较小的测试图片
• 视频处理时使用短视频（5-10 秒）
• 考虑在本地使用 GPU 版本进行开发，部署时使用 CPU 版本

七、性能对比

环境	单张图片处理	视频处理（10秒，30fps）
本地 GPU	~1-2 秒	~2-3 分钟
本地 CPU	~3-5 秒	~10-15 分钟
Hugging Face CPU	~5-10 秒	~15-30 分钟

注意：Hugging Face 免费 CPU 服务器性能有限，处理时间可能更长。

参考资源

• Hugging Face Spaces 文档
• Gradio 文档
• InsightFace 文档