SoulX-Singer 环境搭建完整指南

SoulX-Singer 环境搭建完整指南：从 Conda 到 WebUI 全流程（2026 实测版）

适用版本：SoulX-Singer (Apache-2.0, 2026-02 release)
作者：stlong309
创建时间：2026-07-09
最后更新：2026-07-10
验证环境：Linux (WSL2 Ubuntu) + NVIDIA RTX 2000 Ada (8GB) + CUDA 12.8
预计耗时：30-60 分钟（不含模型下载）

目录

• SoulX-Singer 环境搭建完整指南：从 Conda 到 WebUI 全流程（2026 实测版）
  • 0. 概述
  • 1. 环境要求
    • 版本兼容矩阵
    • 操作系统验证
  • 2. 实践心得
  • 3. 网络准备（核心坑点）
    • 3.1 国内 pip / conda 源
    • 3.2 HuggingFace 模型下载（最坑）
    • 3.3 pip 镜像
  • 4. 第 1 步：克隆仓库
  • 5. 第 2 步：创建 Conda 环境
  • 6. 第 3 步：安装 PyTorch（关键）
    • ❌ 别用 conda 装 PyTorch 2.2.0
    • ✅ 用 pip 装（自带完整 libomp）
  • 7. 第 4 步：装 requirements.txt 全部依赖
    • 装完后立刻降级 huggingface_hub
  • 8. 第 5 步：下载模型（手动）
    • 8.1 必需模型（约 5.2 GB）
    • 8.2 预处理模型（约 6.5 GB，仅 WebUI 需要）
    • 8.3 验证模型完整性
  • 9. 第 6 步：验证 CLI 推理
  • 10. 第 7 步：启动 SVS WebUI
  • 11. 第 8 步：启动 SVC WebUI（歌声转换）
  • 12. 常见问题排查（FAQ）
    • Q1: undefined symbol: iJIT_NotifyEvent
    • Q2: huggingface-hub>=0.23.0,<1.0 is required ... but found huggingface-hub==1.22.0
    • Q3: HF 模型下载到一半卡死
    • Q4: WebUI 启动时 FileNotFoundError: ... config_karaoke_becruily.yaml
    • Q5: WebUI 启动时显存 OOM
    • Q6: numpy 2.x 警告
    • Q7: pip 装包时 timeout
    • Q8: 跑示例时 pip install 整个卡住
    • Q9: 启动 SVC WebUI 时端口冲突
    • Q10: 8GB 显卡同时跑 SVS + SVC WebUI 报 OOM
    • Q11: webui_svc.py 报 RuntimeError: Found no valid file ...
  • 13. 完整命令速查
  • 14. 项目结构速记
  • 15. 模型架构速记
  • 16. 跑完之后能做什么
    • 1. 自定义歌声合成
    • 2. 音色转换（SVC）
    • 3. 读源码理解原理
    • 4. 魔改实验
    • 5. 集成到下游应用
  • 17. 参考资料
    • 关键技术参考
    • 工具/资源
  • 18. 致谢

---

0. 概述

SoulX-Singer 是 Soul-AILab 开源的零样本歌声合成推理项目（Apache 2.0 协议）。

这份指南记录的是在受限网络环境下（中国大陆，无稳定国际网络直连）从零搭建的全过程。我自己跑了一轮，把踩过的坑和验证过的命令都整理在里面。具体包括：

• HuggingFace 限流 / pip / conda 源问题的解法
• Intel MKL 与 PyTorch 2.2 符号冲突的绕过
• 模型手动下载（HF Xet 协议在国内限流）
• CLI 推理 + WebUI 启动全流程

我已经验证过 CLI SVS 推理、英文/中文/粤语示例、Gradio WebUI 都能跑通。

---

1. 环境要求

版本兼容矩阵

组件	推荐版本	最低版本	备注
Python	3.10.x	3.10.0	项目要求，3.11+ 兼容性没测
PyTorch	2.2.0+cu118	2.2.0	cu118 wheels 自带完整 libomp
CUDA Driver	525.60+	520.61	需支持 CUDA 11.8 runtime
磁盘	50 GB	30 GB	含模型 12 GB + 依赖 5 GB + 输出
内存	32 GB	16 GB	WebUI 多模型同驻 ~20 GB RSS
显存	8 GB	6 GB（可能 OOM）	SVS 5.4GB + SVC 4.3GB

操作系统验证

• Ubuntu 22.04 / 20.04 直接装就行
• WSL2 Ubuntu 22.04 我用的就是这个
• Windows 原生没试过，建议用 WSL2
• macOS 只能 CPU 模式跑，CUDA 不支持

---

2. 实践心得

写文档 4 小时，踩坑 4 小时。三个最让我印象深刻的坑：

网络问题占了大头

我从 10:30 折腾到 19:00，差不多 8 小时里有一半在下载模型。HF 直连被 S3 限流，hf-mirror.com 主页能开但下大文件就卡死，hf CLI 里的 Xet 协议反复死锁。最后的解法是手动用浏览器下，绕开 Xet 那套机制。

"装好 pip 包" ≠ "装完"

有两个版本冲突差点让我崩溃。一是 conda 装的 PyTorch 2.2 链到了不兼容的 MKL 2025，缺 iJIT_NotifyEvent 那个符号；二是 pip install -U "huggingface_hub[cli]" 会把 huggingface_hub 升到 1.x，跟 transformers 4.41.2 要求的 <1.0 直接撞了。这俩错误都在 import 阶段就崩，但栈跟踪绕来绕去，看不到根因——只能从报错信息里猜。

WebUI 不是"启起来就没事"

webui.py 在 import 时就把 5 个预处理模型加载到显存了，缺一个 config 文件就直接报错。SVS 和 SVC 共享 4GB+ 显存，8GB 显卡只能二选一。看着是"启两个端口"的小事，实际要算清楚显存账。

给后人的建议：先按这个文档跑通一遍（30 分钟），再根据自己的卡和需求微调。别像我一样在 iJIT_NotifyEvent 那里死磕 1 小时。

---

项目	最低要求	推荐
OS	Linux (Ubuntu 20.04+)	Ubuntu 22.04 / WSL2
GPU	NVIDIA 8GB+ VRAM	RTX 30/40 系列 / Ada
CUDA	11.8+	12.x
磁盘	30 GB	50 GB+（含模型）
内存	16 GB	32 GB（WebUI 同时加载多模型时 ~20GB RSS）
Python	3.10	必须 3.10（requirements.txt 锁版本）

注意：项目要 Python 3.10，3.11+ 用不了（部分依赖的兼容性问题）。

---

3. 网络准备（核心坑点）

3.1 国内 pip / conda 源

清华 conda + 阿里云 pip 是国内最稳的组合。

# 配置 conda 用清华源
cat > ~/.condarc << 'EOF'
channels:
  - defaults
show_channel_urls: True
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
EOF

# conda ToS 接受（首次使用）
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

3.2 HuggingFace 模型下载（最坑）

在国内直连 HF 经常超时，HF Xet 协议会被 S3 出站限流。我的方案是手动从 HF 下载（浏览器或 hf CLI），绕开 Xet 自动限流。

# 装 hf CLI
pip install -U "huggingface_hub[cli]"

# 下载主模型（约 5.2 GB）
hf download Soul-AILab/SoulX-Singer --local-dir pretrained_models/SoulX-Singer

# 下载预处理模型（约 6.5 GB）
hf download Soul-AILab/SoulX-Singer-Preprocess --local-dir pretrained_models/SoulX-Singer-Preprocess

避坑提示：hf CLI 内部用 HF Xet 协议，经常卡住。建议用浏览器从 HF 仓库页面下载，或下网盘/镜像源（智源、启智社区、ModelScope 偶尔有镜像）。

3.3 pip 镜像

# 阿里云 PyPI 镜像（推荐，国内最快）
pip install -r requirements.txt \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host=mirrors.aliyun.com

如果阿里云慢，备用：

• 清华：https://pypi.tuna.tsinghua.edu.cn/simple/
• 豆瓣：https://pypi.doubanio.com/simple/

---

4. 第 1 步：克隆仓库

git clone https://github.com/Soul-AILab/SoulX-Singer.git
cd SoulX-Singer

---

5. 第 2 步：创建 Conda 环境

项目要 Python 3.10，且必须用 venv/conda 等独立环境隔离。

# 创建环境
conda create -n soulxsinger -y python=3.10

# 验证
conda run -n soulxsinger python --version   # 应输出 Python 3.10.x

---

6. 第 3 步：安装 PyTorch（关键）

❌ 别用 conda 装 PyTorch 2.2.0

conda install pytorch==2.2.0 -c pytorch 走清华源会拉到 MKL 2025.0.0（113 MB），但 PyTorch 2.2 链接的 libtorch_cpu.so 依赖 iJIT_NotifyEvent 符号。新版 MKL 把这个符号移除了，直接报 undefined symbol: iJIT_NotifyEvent。

✅ 用 pip 装（自带完整 libomp）

conda run -n soulxsinger pip install \
  torch==2.2.0 torchaudio==2.2.0 \
  --index-url https://download.pytorch.org/whl/cu118

避坑提示：--index-url 指向 PyTorch 自己的源（含 CUDA 11.8 wheels）。别用阿里云 PyPI 装 torch，那边只有 CPU 版。
验证：

conda run -n soulxsinger python -c "import torch; print(torch.cuda.is_available())"
# 应输出 True

---

7. 第 4 步：装 requirements.txt 全部依赖

# 用阿里云 PyPI 镜像
conda run -n soulxsinger pip install -r requirements.txt \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host=mirrors.aliyun.com

避坑提示：如果遇到 numpy 2.x 警告，安装时显式指定 numpy<2.0.0（项目要求）。

会装大约 380 个包，包括：

• 核心：transformers 4.41.2, accelerate, einops
• 音频：librosa 0.11.0, soundfile, praat-parselmouth, pyworld
• ASR：funasr 1.3.0, nemo_toolkit 2.6.1
• Web：gradio 6.3.0
• 预处理：pretty_midi, mido, webrtcvad
• 数据科学：scipy, scikit-learn, scikit-image, numpy<2.0.0, pandas

装完后立刻降级 huggingface_hub

pip install -U "huggingface_hub[cli]" 会把 huggingface_hub 升到 1.22.0，但 transformers 4.41.2 锁版本要求 huggingface_hub>=0.23.0,<1.0。需要在所有其他包都装完后主动降级：

conda run -n soulxsinger pip install "huggingface_hub>=0.23.0,<1.0"
# 验证
conda run -n soulxsinger pip show huggingface_hub | grep Version
# 应输出 0.x.x

---

8. 第 5 步：下载模型（手动）

国内网络条件下 hf CLI 经常卡死。建议用浏览器或第三方下载工具。

8.1 必需模型（约 5.2 GB）

来源：https://huggingface.co/Soul-AILab/SoulX-Singer

pretrained_models/SoulX-Singer/
├── model.pt         2.62 GB   (主 SVS 模型，必需)
└── model-svc.pt     2.60 GB   (SVC 歌声转换模型，跑 SVS 不需要)

8.2 预处理模型（约 6.5 GB，仅 WebUI 需要）

来源：https://huggingface.co/Soul-AILab/SoulX-Singer-Preprocess

pretrained_models/SoulX-Singer-Preprocess/
├── mel-band-roformer-karaoke/        1.72 GB  (人声分离)
│   ├── mel_band_roformer_karaoke_becruily.ckpt
│   └── config_karaoke_becruily.yaml
├── dereverb_mel_band_roformer/      0.91 GB  (去混响)
│   ├── dereverb_mel_band_roformer_anvuew_sdr_19.1729.ckpt
│   └── dereverb_mel_band_roformer_anvuew.yaml
├── rmvpe/                           0.18 GB  (F0 提取)
│   └── rmvpe.pt
├── parakeet-tdt-0.6b-v2/            2.47 GB  (英文 ASR)
│   └── parakeet-tdt-0.6b-v2.nemo
├── speech_seaco_paraformer_.../      0.99 GB  (中文 ASR)
│   ├── model.pt
│   ├── config.yaml
│   └── tokens.json
└── rosvot/                          0.63 GB  (音符转录)
    ├── rosvot/model.pt
    ├── rosvot/config.yaml
    ├── rmvpe/model.pt
    └── rwbd/model.pt

8.3 验证模型完整性

# 期望大小（部分）
expected_model_pt_size=2818092278
expected_model_svc_pt_size=2793965154
for f in pretrained_models/SoulX-Singer/model.pt \
         pretrained_models/SoulX-Singer/model-svc.pt; do
  size=$(stat -c %s "$f")
  echo "$f: $size bytes"
done
# 应分别输出 2818092278 和 2793965154

---

9. 第 6 步：验证 CLI 推理

# 直接跑官方示例脚本
bash example/infer.sh

预期输出（约 30-60 秒）：

Inferring segments: 100%|██████████| 1/1 [00:33<00:00, 33.26s/it]
Model initialized.
Model parameters: 704.344578 M
Model converted to FP16 (mel kept in FP32).
Model checkpoint loaded.
prompt_metadata_path: example/audio/zh_prompt.json
target_metadata_path: example/audio/music.json
Generated audio saved to example/generated/music/generated.wav

生成结果：

• 路径：example/generated/music/generated.wav
• 采样率：24 kHz
• 时长：约 50 秒（对应 music.mp3 的长度）
• 文件大小：约 2.4 MB

---

10. 第 7 步：启动 SVS WebUI

cd /home/stl/workspace/SoulX-Singer
setsid nohup bash -c 'conda run -n soulxsinger python webui.py --port 7860 --fp16' \
  > logs/webui.log 2>&1 < /dev/null &
disown

等约 60-90 秒（5 个模型 + SVS 模型加载到显存需要时间）。

验证：

# 1. 端口监听
ss -tlnp | grep 7860
# 期望: LISTEN 0 2048 0.0.0.0:7860

# 2. HTTP 200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:7860
# 期望: 200

# 3. GPU 占用
nvidia-smi --query-gpu=memory.used --format=csv
# 期望: ~5500 MiB

访问地址：

• WSL 内部：http://localhost:7860
• Windows 浏览器：http://localhost:7860（WSL 自动转发）或 http://<wsl-ip>:7860

---

11. 第 8 步：启动 SVC WebUI（歌声转换）

SVC 模式与 SVS 共用预处理模型，但用 model-svc.pt（Whisper encoder + CFM）。只做歌声转换（音频→音频），不需 MIDI/歌词输入。

# 先停 SVS WebUI（如果已在跑），避免显存冲突
pkill -9 -f "webui.py"

cd /home/stl/workspace/SoulX-Singer
setsid nohup conda run -n soulxsinger python webui_svc.py --port 7861 --fp16 \
  > logs/webui_svc.log 2>&1 < /dev/null &
disown

实测启动参数（RTX 2000 Ada 8GB, FP16）：

指标	值
端口	0.0.0.0:7861
进程内存	~18.9 GB RSS
显存占用	~4.3 GB（比 SVS 少 ~1GB，因 SVC 用 Whisper 而非 DiffLlama）
HTTP 响应	200 OK，6ms
启动时间	60-90 秒

SVC WebUI vs SVS WebUI 实测对比：

维度	SVS WebUI	SVC WebUI
入口脚本	webui.py	webui_svc.py
模型	model.pt (2.62 GB)	model-svc.pt (2.60 GB)
骨干	DiffLlama + CFM	Whisper encoder + CFM
输入	音素 + 音符 + F0/MIDI	源音频（mel 谱）
用途	文→歌（生成歌声）	歌→歌（音色转换）
显存（FP16）	~5.4 GB	~4.3 GB
端口	7860	7861
进程 RSS	~20 GB	~19 GB

SVC WebUI 操作流程：

1. 上传 Prompt 音频（参考音色，建议干净清晰）
2. 上传 Target 音频（要转换的源歌声，可带伴奏）
3. 勾选人声分离（如果 target 含伴奏）
4. 设置 n_step（越大越精细，推荐 32）和 cfg（1~3 之间）
5. 点 🎤 歌声转换

同时跑两个 WebUI（需 ≥12 GB 显存）：

# 8GB 显卡需先停一个再启另一个；12GB+ 可同时跑
cd /home/stl/workspace/SoulX-Singer

# 启 SVS (port 7860)
setsid nohup conda run -n soulxsinger python webui.py --port 7860 --fp16 \
  > logs/webui.log 2>&1 < /dev/null &
disown
sleep 90  # 等 SVS 加载完

# 启 SVC (port 7861)
setsid nohup conda run -n soulxsinger python webui_svc.py --port 7861 --fp16 \
  > logs/webui_svc.log 2>&1 < /dev/null &
disown

---

12. 常见问题排查（FAQ）

Q1: undefined symbol: iJIT_NotifyEvent

原因：conda 装的 PyTorch 2.2 链接了不兼容的 MKL 2025。
解法：卸载 conda 装的 torch，改用 pip 装（见第 5 步）。

Q2: huggingface-hub>=0.23.0,<1.0 is required ... but found huggingface-hub==1.22.0

原因：pip install -U "huggingface_hub[cli]" 升到了 1.x。
解法：执行 pip install "huggingface_hub>=0.23.0,<1.0"（见第 6 步结尾）。

Q3: HF 模型下载到一半卡死

原因：HF Xet 协议被 S3 出站限流（30 秒超时反复出现）。
解法：换用浏览器下载，或换网盘/镜像。详见第 7 步。

Q4: WebUI 启动时 FileNotFoundError: ... config_karaoke_becruily.yaml

原因：缺 SoulX-Singer-Preprocess 预处理模型。
解法：下载并放到 pretrained_models/SoulX-Singer-Preprocess/（见第 7.2 节）。

Q5: WebUI 启动时显存 OOM

原因：5 个模型 + SVS 模型同时驻留显存，共需约 5.4GB（8GB 显卡够用，6GB 显卡会 OOM）。
解法：去掉 --fp16 启动会失败（fp32 显存更大），改为：

setsid nohup bash -c 'conda run -n soulxsinger python webui.py --port 7860' \
  > logs/webui.log 2>&1 < /dev/null &
disown
# 注意：项目不推荐 fp32，webui.py 启动会快但推理可能 OOM

Q6: numpy 2.x 警告

原因：pip 装 huggingface_hub 时可能拉新版 numpy。
解法：pip install "numpy<2.0.0" 重装（项目锁版本）。

Q7: pip 装包时 timeout

原因：阿里云 PyPI 偶尔抽风。
解法：换清华源 https://pypi.tuna.tsinghua.edu.cn/simple/，或重试。

Q8: 跑示例时 pip install 整个卡住

原因：默认 hf CLI 在等 xet 重连，输出被 buffer。
解法：用 setsid nohup 启动，且主动降级 huggingface_hub，别用 pip install -U "huggingface_hub[cli]" 升到 1.x。

Q9: 启动 SVC WebUI 时端口冲突

原因：SVS WebUI 已占 7860，但 SVC 启动命令错用了 7860。
解法：SVC 必须用不同端口（推荐 7861），且先停 SVS：

pkill -9 -f "webui.py"        # 停 SVS
setsid nohup conda run -n soulxsinger python webui_svc.py --port 7861 --fp16 \
  > logs/webui_svc.log 2>&1 < /dev/null &
disown

Q10: 8GB 显卡同时跑 SVS + SVC WebUI 报 OOM

原因：SVS ~5.4GB + SVC ~4.3GB = 9.7GB > 8GB。
解法：

• 8GB 显卡：二选一，不能同时跑
• 12GB+ 显卡：见 9.1 节"同时跑两个 WebUI"命令
• 临时降显存：先停 SVS 跑 SVC 任务；或反之

Q11: webui_svc.py 报 RuntimeError: Found no valid file ...

原因：SVC 需要 pretrained_models/SoulX-Singer/model-svc.pt，但只下过 model.pt。
解法：补下 model-svc.pt（2.60 GB），见第 7.1 节。

---

13. 完整命令速查

# ============================================
# 一、环境准备（一次性）
# ============================================
# conda 源
cat > ~/.condarc << 'EOF'
channels: [defaults]
show_channel_urls: True
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
EOF
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

# ============================================
# 二、克隆 + 创建环境
# ============================================
git clone https://github.com/Soul-AILab/SoulX-Singer.git
cd SoulX-Singer
conda create -n soulxsinger -y python=3.10

# ============================================
# 三、装 PyTorch（关键：用 pip 装，避开 MKL 问题）
# ============================================
conda run -n soulxsinger pip install \
  torch==2.2.0 torchaudio==2.2.0 \
  --index-url https://download.pytorch.org/whl/cu118

# ============================================
# 四、装其他依赖（用阿里云 PyPI）
# ============================================
conda run -n soulxsinger pip install -r requirements.txt \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host=mirrors.aliyun.com

# ============================================
# 五、降级 huggingface_hub（关键：避开 1.x 冲突）
# ============================================
conda run -n soulxsinger pip install "huggingface_hub>=0.23.0,<1.0"

# ============================================
# 六、下载模型（手动，避开 HF Xet 限流）
# ============================================
# 用浏览器从 https://huggingface.co/Soul-AILab/SoulX-Singer 下载
# 把 model.pt 放到 pretrained_models/SoulX-Singer/
# 把整个 SoulX-Singer-Preprocess 放到 pretrained_models/ 下

# ============================================
# 七、验证 CLI
# ============================================
bash example/infer.sh
# 输出: example/generated/music/generated.wav

# ============================================
# 八、启动 WebUI（SVS 歌声合成，端口 7860）
# ============================================
setsid nohup bash -c 'conda run -n soulxsinger python webui.py --port 7860 --fp16' \
  > logs/webui.log 2>&1 < /dev/null &
disown

# 60-90 秒后，访问 http://localhost:7860

# ============================================
# 九、启动 SVC WebUI（歌声转换，端口 7861，需 model-svc.pt）
# ============================================
# 先停 SVS，避免显存冲突
pkill -9 -f "webui.py"
sleep 3

setsid nohup conda run -n soulxsinger python webui_svc.py --port 7861 --fp16 \
  > logs/webui_svc.log 2>&1 < /dev/null &
disown

# 60-90 秒后，访问 http://localhost:7861

# ============================================
# 常用管理命令
# ============================================
# 激活环境
conda activate soulxsinger

# 跑任意命令
conda run -n soulxsinger python xxx.py

# 停止所有 WebUI
pkill -f "webui.py"          # 停 SVS
pkill -f "webui_svc.py"      # 停 SVC

# 重新启动 SVS
cd /home/stl/workspace/SoulX-Singer
setsid nohup bash -c 'conda run -n soulxsinger python webui.py --port 7860 --fp16' \
  > logs/webui.log 2>&1 < /dev/null &
disown

# 重新启动 SVC
cd /home/stl/workspace/SoulX-Singer
setsid nohup conda run -n soulxsinger python webui_svc.py --port 7861 --fp16 \
  > logs/webui_svc.log 2>&1 < /dev/null &
disown

# 查看 SVS 日志
tail -f /home/stl/workspace/SoulX-Singer/logs/webui.log

# 查看 SVC 日志
tail -f /home/stl/workspace/SoulX-Singer/logs/webui_svc.log

# 查看进程
ps aux | grep -E "(webui|cli\.inference)"

# 查看 GPU
nvidia-smi

# 删除整个环境（重建用）
conda env remove -n soulxsinger

---

14. 项目结构速记

SoulX-Singer/
├── cli/                          # 命令行入口
│   ├── inference.py              # SVS CLI
│   └── inference_svc.py          # SVC CLI
├── example/                      # 演示样例
│   ├── infer.sh                  # SVS 推理
│   ├── infer_svc.sh              # SVC 推理
│   ├── audio/                    # 中/英/粤/音乐 prompt+target
│   └── generated/                # 推理输出
├── preprocess/                   # 预处理流水线
│   ├── pipeline.py               # 串联: 分离→F0→转录
│   └── tools/
│       ├── f0_extraction.py      # RMVPE
│       ├── lyric_transcription.py# Paraformer + Parakeet
│       ├── midi_parser.py        # MIDI ↔ metadata
│       ├── midi_editor/          # Vite + TS MIDI 编辑器
│       ├── note_transcription/   # ROSVOT
│       ├── vocal_detection/      # VAD
│       └── vocal_separation/     # Mel-Band Roformer
├── soulxsinger/                  # 主库
│   ├── config/soulxsinger.yaml
│   ├── models/
│   │   ├── soulxsinger.py        # SVS 主类
│   │   ├── soulxsinger_svc.py    # SVC 主类
│   │   └── modules/
│   │       ├── convnext.py       # preflow: ConvNeXtV2
│   │       ├── decoder.py        # CFM decoder
│   │       ├── flow_matching.py  # FlowMatchingTransformer (Amphion 派生)
│   │       ├── llama.py          # DiffLlama (Adaptive RMSNorm)
│   │       ├── mel_transform.py  # 24kHz mel 谱
│   │       ├── vocoder.py        # BigVGAN-style
│   │       └── whisper_encoder.py
│   └── utils/
│       ├── data_processor.py     # phoneme + note → tensor
│       ├── audio_utils.py
│       ├── pitch_utils.py
│       └── phoneme/phone_set.json
├── webui.py                      # SVS WebUI (Gradio)
├── webui_svc.py                  # SVC WebUI (Gradio)
├── requirements.txt
├── README.md
└── SETUP_GUIDE.md                # 本文档

---

15. 模型架构速记

Prompt WAV + Target metadata
        ↓
[ConvNeXtV2 × 4]  音素/音高/类型 嵌入局部上下文
        ↓
[DiffLlama × 22]  1024 维 16 头
  - Adaptive RMSNorm (由 diffusion step 调节)
  - 非因果 attention
        ↓
[Flow Matching]  32 步 ODE + CFG=3 + Cosine scheduler
        ↓
128 维 mel 谱 (24 kHz, 50 Hz 帧率)
        ↓
[BigVGAN-style Vocoder]
        ↓
24 kHz 音频波形

源码在 soulxsinger.py 等文件里，每个模块不到 400 行。

---

16. 跑完之后能做什么

环境装完 + 模型下好 + WebUI 跑起来后，可以往这几个方向玩：

1. 自定义歌声合成

• 准备 prompt 音频（参考音色，< 30s）+ target 音频（带歌词/旋律的源，< 60s）
• 用 WebUI 自动转录 → 在 MIDI Editor 手动对齐 → 重新生成
• 调 auto_shift 和 n_steps 优化质量

2. 音色转换（SVC）

• 准备 prompt 音频 + 任意带歌声的 target
• 选 n_step=32, cfg=1~3
• 适合"翻唱"场景：把别人的歌换成自己音色

3. 读源码理解原理

• soulxsinger/models/soulxsinger.py (~200 行) - 主模型
• soulxsinger/models/modules/flow_matching.py (~440 行) - 流匹配核心
• soulxsinger/models/modules/llama.py (~390 行) - DiffLlama 骨干
• soulxsinger/utils/data_processor.py (~170 行) - 数据处理

4. 魔改实验

• 改 config 调 n_steps 看速度/质量权衡
• 加新控制模式（如歌词引导的 tokenizer）
• 把 DiffLlama 换成 GPT-2 / Mamba 试试

5. 集成到下游应用

• 包装成 REST API（FastAPI + Gradio api_name）
• 集成到 ComfyUI / Stable Audio 工作流
• 做实时歌声转换（需 Streaming CFM）

进阶路线：先把 WebUI 跑通 → 看懂 cli/inference.py 入口 → 读 flow_matching.py 数学 → 自己魔改

---

17. 参考资料

• 项目主页：https://github.com/Soul-AILab/SoulX-Singer
• HF 模型：https://huggingface.co/Soul-AILab/SoulX-Singer
• HF 预处理模型：https://huggingface.co/Soul-AILab/SoulX-Singer-Preprocess
• 论文：arXiv 2602.07803
• Demo：HF Space
• MIDI 编辑器：HF Space

关键技术参考

• Flow Matching for Generative Modeling（Lipman et al. 2023）— 流匹配理论
• Amphion 项目（ https://github.com/open-mmlab/Amphion ）— 本项目 FMT 实现来源
• F5-TTS（ https://github.com/SWivid/F5-TTS ）— ConvNeXtV2 Block 来源
• ROSVOT（ https://github.com/RickyL-2000/ROSVOT ）— 音符转录模块
• RMVPE（ https://github.com/Dream-High/RMVPE ）— F0 提取
• DiffLlama 论文：基于 Llama-2 改造的 diffusion transformer

工具/资源

• 魔搭社区（ https://www.modelscope.cn ）— 国内模型镜像
• 清华 PyPI 镜像（ https://pypi.tuna.tsinghua.edu.cn ）— conda/pip 国内源
• Gradio 文档（ https://gradio.app/docs ）— WebUI 框架

---

18. 致谢

这份指南是我自己跑了一遍后整理的，特别感谢以下开源项目：

• Amphion（ https://github.com/open-mmlab/Amphion ）— 提供了 FlowMatchingTransformer 的基础
• F5-TTS（ https://github.com/SWivid/F5-TTS ）— 提供了 ConvNeXtV2 Block 实现
• ROSVOT（ https://github.com/RickyL-2000/ROSVOT ）— 音符转录模块
• RMVPE（ https://github.com/Dream-High/RMVPE ）— F0 提取
• 魔搭社区 / HuggingFace — 提供了开源的预处理模型
• Soul-AILab — 提供了高质量的预训练模型

---

本文在 Linux 6.6.87 WSL2 Ubuntu + NVIDIA RTX 2000 Ada (8GB) + CUDA 12.8 环境下完整验证。
最后更新：2026-07-10