LOCAL_TEST_GUIDE.md

# 本地测试和部署指南

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

## 重要说明

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

## 一、本地环境准备

### 1. 检查 Python 版本

```bash
python --version
```

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

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

**为什么需要虚拟环境？**
- 避免多个项目依赖冲突
- 保持系统 Python 环境干净
- 便于管理和删除项目

**快速设置（使用自动化脚本）**：
```bash
# 在 FaceSwap 目录下运行
python ../setup_project_env.py
```

**手动设置**：
```bash
# 进入项目目录
cd FaceSwap

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

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

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

### 3. 安装依赖

```bash
# 确保虚拟环境已激活（命令行前有 (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:**
```bash
sudo apt-get update
sudo apt-get install ffmpeg
```

**Mac:**
```bash
brew install ffmpeg
```

验证安装：
```bash
ffmpeg -version
```

## 二、本地测试

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

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

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

# 运行测试脚本
python test_local.py
```

### 方法二：直接运行 Gradio 应用

```bash
# 确保虚拟环境已激活
# 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` 中的设备配置：

```python
# 如果是 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. 提交修改

```bash
# 查看修改
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 文档](https://huggingface.co/docs/hub/spaces)
- [Gradio 文档](https://www.gradio.app/docs/)
- [InsightFace 文档](https://github.com/deepinsight/insightface)