DEPLOY.md

🚀 部署到 Hugging Face Space 指南

本指南将帮助您将 SoulX-Singer 部署到 Hugging Face Space。

📋 前置要求

1. Hugging Face 账号：如果没有，请先注册 huggingface.co
2. Git：确保已安装 Git
3. Hugging Face CLI（可选但推荐）：pip install huggingface_hub

🎯 部署步骤

方法一：通过 Web 界面创建（推荐）

步骤 1：准备代码仓库

确保您的代码已准备好：

• ✅ app.py - Space 入口文件
• ✅ webui.py - Gradio 界面代码
• ✅ requirements.txt - Python 依赖
• ✅ README.md - 包含 Space 配置的 YAML 头部

步骤 2：创建 Space

1. 访问 huggingface.co/spaces
2. 点击 "Create new Space" 按钮
3. 填写 Space 信息：
   • Space name: 例如 SoulX-Singer 或 soulx-singer-demo
   • SDK: 选择 Gradio
   • Hardware: 推荐选择 GPU T4 small（推理更快，首次下载模型后缓存）
   • Visibility: 选择 Public（公开）或 Private（私有）
4. 点击 "Create Space"

步骤 3：上传代码

选项 A：使用 Git 推送（推荐）

# 1. 在本地代码目录初始化 Git（如果还没有）
git init
git add .
git commit -m "Initial commit for HF Space"

# 2. 添加 Hugging Face 远程仓库
# 替换 YOUR_USERNAME 和 YOUR_SPACE_NAME
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# 3. 推送代码
git push -u origin main

选项 B：使用 Web 界面上传

1. 在 Space 页面点击 "Files and versions" 标签
2. 点击 "Add file" → "Upload files"
3. 拖拽或选择以下必需文件：
   • app.py
   • webui.py
   • requirements.txt
   • README.md
   • soulxsinger/ 目录（整个文件夹）
   • preprocess/ 目录（整个文件夹）
   • cli/ 目录（整个文件夹）
   • example/ 目录（整个文件夹）
   • assets/ 目录（整个文件夹）
   • 其他配置文件（如 LICENSE, .gitignore 等）

步骤 4：等待构建和首次运行

1. Space 会自动检测到代码并开始构建
2. 查看 "Logs" 标签页监控构建进度
3. 首次运行会：
   • 安装 requirements.txt 中的依赖
   • 执行 app.py
   • 自动下载 Soul-AILab/SoulX-Singer 和 Soul-AILab/SoulX-Singer-Preprocess 模型（可能需要 5-15 分钟，取决于网络速度）
4. 构建完成后，Space 会自动启动，您可以在 "App" 标签页看到界面

方法二：使用 Hugging Face CLI

# 1. 安装 Hugging Face Hub CLI
pip install huggingface_hub

# 2. 登录（会打开浏览器）
huggingface-cli login

# 3. 创建 Space（替换 YOUR_USERNAME 和 YOUR_SPACE_NAME）
huggingface-cli repo create YOUR_SPACE_NAME --type space --sdk gradio

# 4. 克隆 Space 仓库
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# 5. 复制代码文件到 Space 目录
# （将当前代码目录的所有文件复制过来）

# 6. 提交并推送
git add .
git commit -m "Deploy SoulX-Singer to HF Space"
git push

⚙️ Space 配置说明

Space 配置在 README.md 的 YAML 头部：

---
title: SoulX-Singer
emoji: 🎤
sdk: gradio
sdk_version: "6.3.0"
app_file: app.py
python_version: "3.10"
suggested_hardware: t4-small  # 取消注释以启用 GPU
---

硬件选择建议

• CPU Basic: 免费，但推理速度较慢，适合测试
• GPU T4 Small: 推荐，推理速度快，首次下载模型后缓存
• GPU T4 Medium/Large: 适合高并发或更复杂的推理

修改硬件配置

1. 进入 Space 页面
2. 点击 "Settings" 标签
3. 在 "Hardware" 部分选择所需硬件
4. 保存后 Space 会重启

🔍 故障排查

问题 1：构建失败

检查点：

• ✅ requirements.txt 中所有依赖版本是否兼容
• ✅ app.py 文件是否存在且可执行
• ✅ README.md 的 YAML 配置是否正确

查看日志：

• 在 Space 页面的 "Logs" 标签查看详细错误信息

问题 2：模型下载失败

可能原因：

• 网络连接问题
• Hugging Face Hub 认证问题

解决方案：

• 确保 Space 有网络访问权限（默认有）
• 如果使用私有模型，需要在 Space Settings 中添加 HF Token

问题 3：应用启动后无法访问

检查点：

• ✅ app.py 中 server_name="0.0.0.0" 已设置
• ✅ 端口使用环境变量 PORT（Space 会自动注入）
• ✅ 查看 "Logs" 确认应用是否成功启动

问题 4：内存不足

解决方案：

• 升级到更大的硬件（T4 Medium/Large）
• 或优化代码，减少内存占用

📝 重要提示

1. 首次运行时间：首次部署时，模型下载可能需要 5-15 分钟，请耐心等待
2. 模型缓存：下载的模型会缓存在 Space 的存储中，重启后无需重新下载
3. 存储限制：免费 Space 有存储限制，确保模型文件不会超过限制
4. 自动重启：Space 会在代码更新后自动重启
5. 日志查看：遇到问题时，首先查看 "Logs" 标签页的详细日志

🔗 相关链接

• Hugging Face Spaces 文档
• Gradio 文档
• SoulX-Singer 模型页面
• SoulX-Singer-Preprocess 模型页面

✅ 部署检查清单

部署前确认：

• app.py 文件存在且正确
• requirements.txt 包含所有依赖（包括 huggingface_hub）
• README.md 包含正确的 YAML 配置
• 所有必需的代码文件都已上传
• .gitignore 正确配置（排除 pretrained_models/ 和 outputs/）
• Space 硬件配置合适（推荐 GPU T4 Small）

部署后验证：

• Space 构建成功（无错误日志）
• 模型自动下载完成
• Web 界面可以正常访问
• 可以上传音频文件进行测试
• 推理功能正常工作

---

祝部署顺利！ 🎉