aiqtech/SoulX-Singer

1# 🚀 部署到 Hugging Face Space 指南2 3本指南将帮助您将 SoulX-Singer 部署到 Hugging Face Space。4 5## 📋 前置要求6 71. **Hugging Face 账号**：如果没有，请先注册 [huggingface.co](https://huggingface.co/join)82. **Git**：确保已安装 Git93. **Hugging Face CLI**（可选但推荐）：`pip install huggingface_hub`10 11## 🎯 部署步骤12 13### 方法一：通过 Web 界面创建（推荐）14 15#### 步骤 1：准备代码仓库16 17确保您的代码已准备好：18- ✅ `app.py` - Space 入口文件19- ✅ `webui.py` - Gradio 界面代码20- ✅ `requirements.txt` - Python 依赖21- ✅ `README.md` - 包含 Space 配置的 YAML 头部22 23#### 步骤 2：创建 Space24 251. 访问 [huggingface.co/spaces](https://huggingface.co/spaces)262. 点击 **"Create new Space"** 按钮273. 填写 Space 信息：28   - **Space name**: 例如 `SoulX-Singer` 或 `soulx-singer-demo`29   - **SDK**: 选择 **Gradio**30   - **Hardware**: 推荐选择 **GPU T4 small**（推理更快，首次下载模型后缓存）31   - **Visibility**: 选择 Public（公开）或 Private（私有）324. 点击 **"Create Space"**33 34#### 步骤 3：上传代码35 36**选项 A：使用 Git 推送（推荐）**37 38```bash39# 1. 在本地代码目录初始化 Git（如果还没有）40git init41git add .42git commit -m "Initial commit for HF Space"43 44# 2. 添加 Hugging Face 远程仓库45# 替换 YOUR_USERNAME 和 YOUR_SPACE_NAME46git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME47 48# 3. 推送代码49git push -u origin main50```51 52**选项 B：使用 Web 界面上传**53 541. 在 Space 页面点击 **"Files and versions"** 标签552. 点击 **"Add file"** → **"Upload files"**563. 拖拽或选择以下必需文件：57   - `app.py`58   - `webui.py`59   - `requirements.txt`60   - `README.md`61   - `soulxsinger/` 目录（整个文件夹）62   - `preprocess/` 目录（整个文件夹）63   - `cli/` 目录（整个文件夹）64   - `example/` 目录（整个文件夹）65   - `assets/` 目录（整个文件夹）66   - 其他配置文件（如 `LICENSE`, `.gitignore` 等）67 68#### 步骤 4：等待构建和首次运行69 701. Space 会自动检测到代码并开始构建712. 查看 **"Logs"** 标签页监控构建进度723. 首次运行会：73   - 安装 `requirements.txt` 中的依赖74   - 执行 `app.py`75   - **自动下载** `Soul-AILab/SoulX-Singer` 和 `Soul-AILab/SoulX-Singer-Preprocess` 模型（可能需要 5-15 分钟，取决于网络速度）764. 构建完成后，Space 会自动启动，您可以在 **"App"** 标签页看到界面77 78### 方法二：使用 Hugging Face CLI79 80```bash81# 1. 安装 Hugging Face Hub CLI82pip install huggingface_hub83 84# 2. 登录（会打开浏览器）85huggingface-cli login86 87# 3. 创建 Space（替换 YOUR_USERNAME 和 YOUR_SPACE_NAME）88huggingface-cli repo create YOUR_SPACE_NAME --type space --sdk gradio89 90# 4. 克隆 Space 仓库91git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME92cd YOUR_SPACE_NAME93 94# 5. 复制代码文件到 Space 目录95# （将当前代码目录的所有文件复制过来）96 97# 6. 提交并推送98git add .99git commit -m "Deploy SoulX-Singer to HF Space"100git push101```102 103## ⚙️ Space 配置说明104 105Space 配置在 `README.md` 的 YAML 头部：106 107```yaml108---109title: SoulX-Singer110emoji: 🎤111sdk: gradio112sdk_version: "6.3.0"113app_file: app.py114python_version: "3.10"115suggested_hardware: t4-small  # 取消注释以启用 GPU116---117```118 119### 硬件选择建议120 121- **CPU Basic**: 免费，但推理速度较慢，适合测试122- **GPU T4 Small**: 推荐，推理速度快，首次下载模型后缓存123- **GPU T4 Medium/Large**: 适合高并发或更复杂的推理124 125### 修改硬件配置126 1271. 进入 Space 页面1282. 点击 **"Settings"** 标签1293. 在 **"Hardware"** 部分选择所需硬件1304. 保存后 Space 会重启131 132## 🔍 故障排查133 134### 问题 1：构建失败135 136**检查点：**137- ✅ `requirements.txt` 中所有依赖版本是否兼容138- ✅ `app.py` 文件是否存在且可执行139- ✅ `README.md` 的 YAML 配置是否正确140 141**查看日志：**142- 在 Space 页面的 **"Logs"** 标签查看详细错误信息143 144### 问题 2：模型下载失败145 146**可能原因：**147- 网络连接问题148- Hugging Face Hub 认证问题149 150**解决方案：**151- 确保 Space 有网络访问权限（默认有）152- 如果使用私有模型，需要在 Space Settings 中添加 HF Token153 154### 问题 3：应用启动后无法访问155 156**检查点：**157- ✅ `app.py` 中 `server_name="0.0.0.0"` 已设置158- ✅ 端口使用环境变量 `PORT`（Space 会自动注入）159- ✅ 查看 **"Logs"** 确认应用是否成功启动160 161### 问题 4：内存不足162 163**解决方案：**164- 升级到更大的硬件（T4 Medium/Large）165- 或优化代码，减少内存占用166 167## 📝 重要提示168 1691. **首次运行时间**：首次部署时，模型下载可能需要 5-15 分钟，请耐心等待1702. **模型缓存**：下载的模型会缓存在 Space 的存储中，重启后无需重新下载1713. **存储限制**：免费 Space 有存储限制，确保模型文件不会超过限制1724. **自动重启**：Space 会在代码更新后自动重启1735. **日志查看**：遇到问题时，首先查看 **"Logs"** 标签页的详细日志174 175## 🔗 相关链接176 177- [Hugging Face Spaces 文档](https://huggingface.co/docs/hub/spaces)178- [Gradio 文档](https://gradio.app/docs/)179- [SoulX-Singer 模型页面](https://huggingface.co/Soul-AILab/SoulX-Singer)180- [SoulX-Singer-Preprocess 模型页面](https://huggingface.co/Soul-AILab/SoulX-Singer-Preprocess)181 182## ✅ 部署检查清单183 184部署前确认：185- [ ] `app.py` 文件存在且正确186- [ ] `requirements.txt` 包含所有依赖（包括 `huggingface_hub`）187- [ ] `README.md` 包含正确的 YAML 配置188- [ ] 所有必需的代码文件都已上传189- [ ] `.gitignore` 正确配置（排除 `pretrained_models/` 和 `outputs/`）190- [ ] Space 硬件配置合适（推荐 GPU T4 Small）191 192部署后验证：193- [ ] Space 构建成功（无错误日志）194- [ ] 模型自动下载完成195- [ ] Web 界面可以正常访问196- [ ] 可以上传音频文件进行测试197- [ ] 推理功能正常工作198 199---200 201**祝部署顺利！** 🎉202