RVC（Retrieval-based-Voice-Conversion-WebUI）完整上手指南：环境搭建、预训练模型准备与 WebUI 使用详解

RVC（Retrieval-based-Voice-Conversion-WebUI）完整上手指南：环境搭建、预训练模型准备与 WebUI 使用详解

【免费下载链接】Retrieval-based-Voice-Conversion-WebUIEasily train a good VC model with voice data <= 10 mins!项目地址: https://gitcode.com/GitHub_Trending/re/Retrieval-based-Voice-Conversion-WebUI

本指南以仓库内 docs/en/README.en.md 为主线，结合 infer-web.py、configs/config.py、tools/download_models.py 等源码，系统讲解 RVC 的安装依赖、硬件适配、预训练资源下载、服务启动与 WebUI 各功能页，帮助读者在当前仓库环境中从零跑通“数据集预处理 → 特征/音高提取 → 训练 → 推理 → 索引检索增强 → 模型融合”的完整语音转换工作流。读完本文，你将具备独立部署 RVC WebUI、选择正确加速后端（CUDA / ROCm / DirectML / IPEX / MPS）并定位常见报错的能力。

一、RVC 是什么

Retrieval-based-Voice-Conversion-WebUI（下称 RVC）是一个基于 VITS 的易用语音转换（Voice Conversion, VC）框架，项目定位为“用不超过 10 分钟的低噪声语音数据，即可轻松训练出一个不错的 VC 模型”。文档中给出的核心功能定位包括：

• 减少音色泄漏：用 top1 检索（Retrieval）把源说话人特征替换为训练集特征，使转换结果音色更贴近目标说话人（详见 infer/modules/vc/pipeline.py）；
• 训练友好：即使显卡性能较差也能快速完成训练，推荐使用 ≥10 分钟的低噪声语音；
• 模型融合：通过 “ckpt 处理”页的 ckpt merge 功能改变音色（对应源码 infer/lib/train/process_ckpt.py 中的merge等函数）；
• 易用 WebUI：训练、推理、伴奏分离集成在同一图形界面（对应 infer-web.py）；
• UVR5 人声/伴奏分离：用于快速分离人声和乐器轨（对应 infer/modules/uvr5 与assets/uvr5_weights权重）；
• 高音准提取算法 RMVPE：源自 InterSpeech 2023，用于抑制“闷/哑”的声音问题，效果显著优于 Crepe_full 且资源占用更低、速度更快；
• 多硬件加速：支持 AMD/Intel 显卡（DirectML、ROCm）以及 Intel ARC 显卡（IPEX）。

补充背景（来自文档原句）：预训练模型使用的数据集来自约 50 小时的高质量 VCTK 开源语音；文档还预告了参数更大、训练数据更多、推理速度不变的 RVCv3 基座模型。训练页与推理页的分工可通过 infer-web.py 的 Tab 布局直接确认。

二、核心原理速览：为什么叫 “Retrieval-based”

RVC 的“检索”体现在推理阶段的特征替换上。整体链路可以概括为：

1. 使用 HuBERT 类模型对输入音频提取说话内容特征（content feature）；
2. 通过 FAISS 索引（index_faiss/.index文件）在训练集特征库（big_npy）中检索最接近的特征；
3. 用检索到的训练集特征替换（或按比例混合）源特征，从而把“音色”引导到目标说话人，同时保留内容与音高。

从 infer/modules/vc/pipeline.py 的实现可以看到，特征替换的实际逻辑是：

inputs = { "source": feats.to(self.device), "padding_mask": padding_mask, "output_layer": 9 if version == "v1" else 12, } logits = model.extract_features(**inputs) feats = model.final_proj(logits[0]) if version == "v1" else logits[0] ... score, ix = index.search(npy, k=8) weight = np.square(1 / score) weight /= weight.sum(axis=1, keepdims=True) npy = np.sum(big_npy[ix] * np.expand_dims(weight, axis=2), axis=1) feats = torch.from_numpy(npy).unsqueeze(0).to(self.device) * index_rate \ + (1 - index_rate) * feats

即：output_layer在 v1 版本取 HuBERT 第 9 层输出并经过final_proj（映射到 256 维），v2 版本直接取第 12 层 768 维输出；检索得到的近邻特征按“距离平方的倒数”加权融合，再乘以index_rate与原始特征按比例混合，最后scale_factor=2插值对齐帧数。这正是 README 中“减少音色泄漏、用训练集特征替换源特征”的源码级印证。

三、准备运行环境（依赖安装）

3.1 前提条件

文档明确要求Python 3.8 或更高版本。建议在干净的虚拟环境（venv/conda）中进行安装，避免与系统 Python 冲突。仓库提供的 run.sh 在 macOS/Linux 下会自动创建.venv并逐条校验安装依赖，可作为参考模板。

3.2 安装 PyTorch 核心依赖

先通过 pip 安装 PyTorch 全家桶（已安装可跳过）：

pip install torch torchvision torchaudio

不同的显卡平台需要选择对应的 PyTorch 版本（原文给出的三条经验性命令）：

# Windows + Nvidia Ampere 架构(RTX30xx 等)，需要按 CUDA 版本显式指定： # pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117 # Linux + AMD 显卡（ROCm 版 PyTorch）： # pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.4.2

注意：以上带注释的命令是历史经验写法，实际安装前请前往 PyTorch 官网（get-started/locally）按当前驱动/CUDA 环境选择最新匹配版本；本文仅转述文档原意，不作为当前版本强制要求。

3.3 安装其余项目依赖（二选一）

方式 A：Poetry（推荐用于开发）

# 安装 Poetry 依赖管理工具（已安装可跳过） curl -sSL https://install.python-poetry.org | python3 - # 在仓库根目录安装项目依赖 poetry install

仓库根目录提供 pyproject.toml 与 poetry.lock 支撑 Poetry 流程。

方式 B：pip + requirements 文件（按硬件选）

# Nvidia 显卡 pip install -r requirements.txt # Windows 下 AMD/Intel 显卡（DirectML） pip install -r requirements-dml.txt # Linux / WSL 下 Intel ARC 显卡（Python 3.10，IPEX） pip install -r requirements-ipex.txt # Linux 下 AMD 显卡（ROCm） pip install -r requirements-amd.txt

从 requirements.txt 可以看出核心依赖的大致构成，例如：torch/torchaudio、fairseq==0.12.2（HuBERT 特征抽取）、faiss-cpu==1.7.3（检索索引）、gradio==3.34.0（WebUI 框架）、praat-parselmouth/pyworld（音高提取）、torchcrepe/torchfcpe、librosa==0.9.1、numba、onnxruntime等。若你运行pip install -r requirements-dml.txt等变体文件，同样需要注意其与主文件在 onnxruntime/torch 版本上的差异。

macOS 用户可借助仓库脚本一键完成“建 venv → 装依赖 → 下载模型 → 启动”：

sh ./run.sh

run.sh 中会针对 macOS 设置PYTORCH_ENABLE_MPS_FALLBACK=1与PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0，并最终执行python3.8 infer-web.py --pycmd python3.8。

3.4 安装 FFmpeg

如果系统中已存在ffmpeg与ffprobe可跳过此步：

# Ubuntu/Debian sudo apt install ffmpeg # macOS brew install ffmpeg

Windows 用户则需要下载ffmpeg.exe与ffprobe.exe两个可执行文件并放入仓库根目录（RVC 通过 ffmpeg/ffprobe 处理音频切片与重采样，见 infer/lib/slicer2.py 等对音频文件的调用链）。

四、下载预训练模型与必需资源

RVC 的训练和推理都依赖若干预训练模型，文档给出两种获取方式：

方式一：使用仓库自带脚本一键下载

python tools/download_models.py

查看 tools/download_models.py 可知其下载清单与落盘路径完全对应下述目录结构：hubert_base.pt、rmvpe.pt、uvr5_weights（含 HP2/HP3/HP5 及去混响/去回声 VR 权重）、assets/pretrained与assets/pretrained_v2下各采样率（32k/40k/48k）的D*.pth、G*.pth、f0D*.pth、f0G*.pth生成器/判别器权重。

方式二：自行从 HuggingFace 空间下载后手动摆放。文档列出的必需文件/目录为：

./assets/hubert/hubert_base.pt # HuBERT 基座模型 ./assets/pretrained # v1 预训练权重目录 ./assets/uvr5_weights # UVR5 人声/伴奏分离权重目录

4.1 若需运行 v2 版本模型

需要额外下载：

./assets/pretrained_v2

文档明确指出v1 与 v2 的核心差异：

• v1：使用 9 层 HuBERT +final_proj输出的256 维特征；
• v2：改用 12 层 HuBERT 输出的768 维特征，并新增 3 个周期判别器（period discriminators）。

上述差异在代码中有两处直接印证：

1. infer/modules/vc/pipeline.py 中output_layer: 9 if version == "v1" else 12，以及 v1 才走model.final_proj；
2. 配置目录 configs/v1（32k/40k/48k）与 configs/v2（32k/48k）分开维护，configs/config.py 中的version_config_list也会把configs/下的 json 首次运行时拷贝到configs/inuse/供训练使用。

4.2 若需使用 RMVPE 音高提取算法

下载rmvpe.pt权重放入仓库根目录；AMD/Intel 显卡用户还需额外下载rmvpe.onnx（ONNX 运行时版本）。RMVPE 相关实现位于 infer/lib/rmvpe.py，其.pt推理由 tools/infer_cli.py 与训练侧的 f0 提取脚本 infer/modules/train/extract（含 rmvpe 专用脚本）共同使用。

4.3 仓库目录对照

仓库内 assets 目录当前包含hubert、indices、pretrained、pretrained_v2、rmvpe、uvr5_weights、weights等子目录以及若干.pth输入样例文件——也就是说，除超大权重外的目录骨架仓库已备好，实际模型文件需要你按上文步骤下载后放入。

五、AMD 显卡的 ROCm 支持（仅 Linux）

若要在 Linux 上以 ROCm 后端运行 RVC，文档给出的要点如下：

1. 先按官方部署文档安装全部必需驱动；
2. Arch 系发行版可通过 pacman 安装驱动：

   pacman -S rocm-hip-sdk rocm-opencl-sdk

3. 可能需要按具体显卡型号设置环境变量（文档示例针对 RX6700XT）：

   export ROCM_PATH=/opt/rocm export HSA_OVERRIDE_GFX_VERSION=10.3.0

4. 确认当前用户属于render与video组：

   sudo usermod -aG render $USERNAME sudo usermod -aG video $USERNAME

补充：ROCm 对应依赖文件为 requirements-amd.txt。从 configs/config.py 的设备探测逻辑看，非 Nvidia 环境下 RVC 会自动回退并强制使用 FP32（调用use_fp32_config()把各版本 json 中fp16_run改写为 false、并把preprocess_per调整为 3.0），以保证 ROCm/MPS/CPU 等后端的数值稳定性。

六、启动 WebUI 并开始使用

6.1 直接启动

在仓库根目录执行：

python infer-web.py

启动后访问默认地址http://127.0.0.1:7865（configs/config.py 中--port默认值为7865）。从 infer-web.py 可以看到，非 Colab 环境下会以server_name="0.0.0.0"、quiet=True方式启动，并默认自动打开浏览器（除非传入--noautoopen）。

6.2 命令行启动参数

configs/config.py 定义了 WebUI 支持的全部参数，整理如下：

例如 Windows 集成包中的 go-web.bat 实际执行：

runtime\python.exe infer-web.py --pycmd runtime\python.exe --port 7897

即集成包默认把 WebUI 跑在7897端口并复用自带 runtime 的解释器。可对照仓库中的 go-realtime-gui.bat（实时变声 GUI，对应 README 所述 170ms 端到端延迟；配合 ASIO 输入输出设备可降至约 90ms，但文档强调高度依赖硬件驱动支持）、go-web-dml.bat（DirectML 版 WebUI）。

6.3 使用集成包启动

• Windows：下载并解压RVC-beta.7z后，双击go-web.bat；
• macOS：sh ./run.sh（脚本同时负责建环境与下载模型）；
• Intel IPEX 用户（仅 Linux）：先加载 oneAPI 环境变量再启动：

  source /opt/intel/oneapi/setvars.sh

  之后配合requirements-ipex.txt安装的intel_extension_for_pytorch使用。configs/config.py 中通过has_xpu()检测 XPU 并将device设为xpu:0。

6.4 WebUI 页面总览（源码 Tab 布局）

结合 infer-web.py 的页面定义，WebUI 顶层包含以下页签，与 README 描述的三大应用场景一一对应：

6.5 无独显/低显存环境下的自动降级

启动时 infer-web.py 会枚举可用的 Nvidia 显卡（按显存型号白名单判断），据此计算默认batch_size（min(mem) // 2）；完全没有可用 N 卡时给出中文/英文提示并把默认 batch 设为 1。另一方面 configs/config.py 会根据显卡名（如 16 系、P40/P10、1060/1070/1080）自动把半精度关闭并强制 FP32，同时依据显存（≤4GB）与精度档位自动选择x_pad / x_query / x_center / x_max等切分窗口参数——这是“差显卡也能跑”的底层保障。

七、进阶：训练与推理涉及的配置与资源

7.1 配置文件（以 v2/48k 为例）

模型超参与音频参数集中在 configs/v2/48k.json 等 json 中，关键字段节选如下，供你在训练前核对：

• train：learning_rate: 1e-4、batch_size: 4、fp16_run: true、epochs: 20000、lr_decay: 0.999875、segment_size: 17280、c_mel: 45、c_kl: 1.0；
• data：sampling_rate: 48000、filter_length: 2048、hop_length: 480、n_mel_channels: 128；
• model：inter_channels: 192、hidden_channels: 192、filter_channels: 768、resblock: "1"、upsample_rates: [12,10,2,2]、spk_embed_dim: 109等，整体承袭 VITS 风格生成器结构。

配置在首次运行时会被 configs/config.py 从configs/拷贝到configs/inuse/后读取，FP32 模式还会就地改写 json 中的fp16_run。

7.2 音高提取器家族

README 着重推荐的 RMVPE 之外，从仓库 infer/lib/infer_pack/modules/F0Predictor 可以看出框架支持多种 F0 算法：Dio、Harvest、PM（parselmouth）等，且 requirements.txt 还包含torchcrepe、torchfcpe。推理 GUI 中通常按模型训练时使用的 f0 类型（如 f0 与 rmvpe）配对选择，训练侧的 f0 提取见 infer/modules/train/extract/extract_f0_rmvpe.py。

7.3 实时变声与命令行/批处理入口

除 WebUI 外，仓库还提供：

• 实时变声 GUI（对应 README 的 go-realtime-gui 界面）与独立示例 tools/rvc_for_realtime.py；
• 命令行推理 tools/infer_cli.py 与批处理脚本 tools/infer_batch_rvc.py；
• HTTP API 服务（api_240604.py 等），便于将 RVC 集成进其他服务。

7.4 更多资料

• 版本更新说明：docs/en/Changelog_EN.md；
• 高频问题排查：docs/en/faq_en.md；
• 中文主 README（含简体中文使用引导）：README.md；
• Colab 在线演示笔记本：Retrieval_based_Voice_Conversion_WebUI.ipynb；
• 多语言界面资源：仓库内置 i18n/locale（含 zh_CN、en_US 等十余种语言），WebUI 语言由 i18n/i18n.py 自动选择，这也解释了为何英文界面会加载docs/en/faq_en.md而非中文版。

八、快速自查清单

完成部署后，可对照以下清单确认各环节是否就绪：

1. python --version≥ 3.8，python -c "import torch"无报错；
2. ffmpeg -version与ffprobe -version可用（Windows 下位于仓库根目录）；
3. assets/hubert/hubert_base.pt、assets/pretrained/、assets/uvr5_weights/已就位；使用 v2 或 RMVPE 时对应assets/pretrained_v2/、rmvpe.pt（AMD/Intel 用户为rmvpe.onnx）亦已下载；
4. 执行python infer-web.py后浏览器能打开对应端口（默认 7865，Windows 集成包为 7897）；
5. 训练页能成功预处理 ≥10 分钟的低噪声数据集，并按所选采样率（32k/40k/48k）加载对应版本配置。

按照上述步骤操作后，你就能在本地完成从环境搭建、模型资源准备到 WebUI 全流程使用的 RVC 部署，并可依据本文第七节的源码指引进一步深入训练参数与推理机制的调优。

【免费下载链接】Retrieval-based-Voice-Conversion-WebUIEasily train a good VC model with voice data <= 10 mins!项目地址: https://gitcode.com/GitHub_Trending/re/Retrieval-based-Voice-Conversion-WebUI