| # 部署前检查清单 |
|
|
| ## 文件信息 |
| - **文件路径**: DEPLOY_CHECKLIST.md |
| - **创建时间**: 2025-12-16 |
| - **开发者**: aidaox |
| |
| ## 在推送到 Hugging Face 之前，请逐项检查： |
| |
| ### ✅ 1. 依赖配置检查 |
| |
| - [ ] **requirements.txt** 使用 `onnxruntime`（不是 `onnxruntime-gpu`） |
| - [ ] 所有依赖包都有明确的版本号或兼容版本范围 |
| - [ ] `gradio` 版本 >= 5.29.0（与 README.md 中的 sdk_version 一致） |
| - [ ] `packages.txt` 只包含系统包（如 `ffmpeg`），不包含 Python 包 |
|
|
| ### ✅ 2. 代码兼容性检查 |
|
|
| - [ ] **SinglePhoto.py** 中的 `ctx_id` 配置： |
| - 当前使用 `ctx_id=0`（会自动回退到 CPU，通常可用） |
| - 如果 Hugging Face 上出现问题，考虑改为 `ctx_id=-1`（明确使用 CPU） |
| - [ ] 没有硬编码的本地路径（如 `C:\Users\...`、`/home/user/...`） |
| - [ ] 所有文件路径使用相对路径 |
| - [ ] 没有引用本地不存在的文件或目录 |
|
|
| ### ✅ 3. 文件完整性检查 |
|
|
| - [ ] `app.py` 存在且可以正常导入 |
| - [ ] `README.md` 中的 `app_file: app.py` 配置正确 |
| - [ ] `inswapper_128.onnx` 模型文件存在（或会在运行时自动下载） |
| - [ ] 所有必要的 Python 模块文件都存在： |
| - [ ] `SinglePhoto.py` |
| - [ ] `VideoSwapping.py` |
| - [ ] `app.py` |
|
|
| ### ✅ 4. 功能测试检查 |
|
|
| - [ ] 本地运行 `python test_local.py` 所有检查通过 |
| - [ ] 本地运行 `python app.py` 可以正常启动 |
| - [ ] 测试单张图片换脸功能正常 |
| - [ ] 检查日志输出，没有错误或警告 |
|
|
| ### ✅ 5. 性能优化检查（针对免费 CPU 服务器） |
|
|
| - [ ] 图片处理大小限制合理（建议不超过 1024x1024） |
| - [ ] 视频处理有合理的时长限制提示 |
| - [ ] 长时间运行的操作有超时处理 |
| - [ ] 临时文件及时清理（代码中已有清理逻辑） |
|
|
| ### ✅ 6. Git 提交检查 |
|
|
| - [ ] 所有修改已添加到暂存区：`git add .` |
| - [ ] 提交信息清晰描述修改内容 |
| - [ ] 没有提交敏感信息（如 API keys、tokens） |
| - [ ] 没有提交不必要的文件（如 `__pycache__`、`.pyc` 文件） |
|
|
| ### ✅ 7. 文档检查 |
|
|
| - [ ] `README.md` 中的配置信息正确 |
| - [ ] 项目描述清晰 |
| - [ ] 必要的使用说明已添加 |
|
|
| ## 快速检查命令 |
|
|
| 在推送前，运行以下命令进行快速检查： |
|
|
| ```bash |
| # 1. 检查 requirements.txt 是否包含 GPU 依赖 |
| grep -i "gpu" requirements.txt |
| # 应该没有输出，如果有 onnxruntime-gpu，需要改为 onnxruntime |
| |
| # 2. 检查是否有硬编码路径 |
| grep -r "C:\\\\Users" . --include="*.py" |
| grep -r "/home/" . --include="*.py" |
| # 应该没有输出 |
| |
| # 3. 运行本地测试 |
| python test_local.py |
| |
| # 4. 检查 Git 状态 |
| git status |
| ``` |
|
|
| ## 推送步骤 |
|
|
| 1. **提交所有修改**： |
| ```bash |
| git add . |
| git commit -m "修复 CPU 兼容性并添加测试脚本" |
| ``` |
|
|
| 2. **推送到 Hugging Face**： |
| ```bash |
| git push origin main |
| ``` |
|
|
| 3. **在 Hugging Face 上验证**： |
| - 访问 https://huggingface.co/spaces/aidao/FaceSwap |
| - 等待构建完成（查看 "Logs" 标签页） |
| - 测试应用功能 |
| - 检查是否有错误 |
|
|
| ## 如果部署失败 |
|
|
| ### 检查构建日志 |
|
|
| 1. 在 Hugging Face Space 页面点击 "Logs" 标签 |
| 2. 查看错误信息 |
| 3. 常见问题： |
| - 依赖安装失败 → 检查 `requirements.txt` |
| - 系统包缺失 → 检查 `packages.txt` |
| - 代码错误 → 检查本地测试是否通过 |
| - 内存不足 → 优化代码，减少内存使用 |
|
|
| ### 常见错误及解决方法 |
|
|
| | 错误 | 可能原因 | 解决方法 | |
| |------|---------|---------| |
| | `ModuleNotFoundError` | 依赖未安装 | 检查 `requirements.txt` | |
| | `onnxruntime` 相关错误 | 使用了 GPU 版本 | 确保使用 `onnxruntime`（CPU 版本） | |
| | `ffmpeg` 相关错误 | 系统包缺失 | 确保 `packages.txt` 包含 `ffmpeg` | |
| | 内存不足 | 处理大文件 | 限制输入文件大小 | |
| | 超时 | 处理时间过长 | 优化代码或添加超时处理 | |
|
|
| ## 部署后验证 |
|
|
| - [ ] Space 构建成功（无错误日志） |
| - [ ] 应用界面正常加载 |
| - [ ] 可以上传图片 |
| - [ ] 单张图片换脸功能正常 |
| - [ ] 日志输出正常（无错误） |
|
|
| ## 性能监控 |
|
|
| 部署后注意观察： |
| - 应用启动时间 |
| - 单次处理时间 |
| - 内存使用情况 |
| - 是否有超时错误 |
|
|
| 如果性能问题严重，考虑： |
| - 优化图片处理大小 |
| - 添加缓存机制 |
| - 限制并发请求 |
|
|
|
|
