Sync latest code and fix Space startup

README.md

@@ -1,151 +1,719 @@
----
-title: AI-RVC 一键 AI 翻唱
-emoji: 🎤
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: 3.50.2
-app_file: app.py
-pinned: false
-license: mit
----
+# AI-RVC 一键 AI 翻唱 / RVC Voice Conversion WebUI
+
+AI-RVC 是一个面向普通用户和创作者的 **RVC v2 AI 翻唱与声音转换工具**。上传一首歌，它会自动分离人声和伴奏，用角色 RVC 模型转换主唱音色，再把转换后的人声、伴奏和混响重新混成完整作品。
+
+不用先手动拆音轨，也不用在一堆脚本里来回切。打开 Gradio WebUI，选歌、选角色、点开始，一首 AI cover 就能从原曲一路跑到成品。
+
+> 在线体验：[https://telknet.cc/](https://telknet.cc/)
+
+**平台支持：Windows / Linux / WSL2 / Google Colab / Hugging Face Spaces**
+
+![Windows 界面](docs/Windows界面.png)
+
+## 项目定位与搜索关键词
+
+如果你在找 **AI 翻唱、RVC 翻唱、AI cover generator、RVC voice conversion、角色声线转换、人声分离、伴奏分离、HuBERT、RMVPE、FAISS、Gradio WebUI、Colab AI 翻唱** 这类工具，AI-RVC 的目标就是把这些零散步骤串成一条更省心的工作流。
 
-# 🎤 AI-RVC 一键 AI 翻唱
+适合放在 GitHub About 的仓库简介：
 
-基于 RVC v2 的一键 AI 翻唱系统，自动完成人声分离、音色转换、混音合成全流程。
+> 一键 AI 翻唱与 RVC v2 声音转换 WebUI：自动人声分离、HuBERT + RMVPE + FAISS 音色转换、角色模型下载、混音预设，并支持 Windows、Linux、WSL2、Google Colab 和 Hugging Face Spaces。
+
+推荐 GitHub Topics：
+
+`rvc`, `rvc-v2`, `voice-conversion`, `ai-cover`, `song-cover`, `singing-voice-conversion`, `voice-changer`, `voice-cloning`, `vocal-separation`, `audio-separation`, `rmvpe`, `hubert`, `faiss`, `gradio`, `pytorch`, `colab`, `uvr`, `demucs`, `roformer`, `ai-music`
 
 ## 功能特点
 
-- **AI 歌曲翻唱**：上传歌曲自动分离人声、转换音色、混合伴奏，一键生成翻唱
-- **人声分离**：默认 Mel-Band Roformer (KimberleyJensen)，在 MVSEP 公开 Multisong 指标中为 Vocals SDR 11.01 / Instrum SDR 17.32
-- **音色转换**：RVC v2 架构 + FAISS 检索增强流程
-- **RMVPE 音高提取**：高精度 F0 提取，噪声鲁棒性强
-- **角色模型**：内置 117 个可下载角色模型
-- **混音效果**：支持人声混响、音量调节、4 种混音预设
-- **卡拉OK模式**：分离主唱和伴唱轨道
-- **VC预处理**：4 种模式（自动、直通、学习型DeEcho、旧版手工链）
-- **双VC管道**：支持当前实现和官方实现
+- **AI 歌曲翻唱**：上传 MP3/WAV/FLAC，自动完成人声分离、RVC 音色转换、伴奏混合和结果导出，一首歌从原曲跑到 AI cover 成品。
+- **人声分离**：默认使用 `audio-separator` 0.44.1 ensemble 预设（`ensemble:vocal_rvc`）；可选卡拉OK预设、UVR5、Demucs，适配不同歌曲素材。
+- **音色转换**：RVC v2 架构 + 官方 VC 管道，结合 HuBERT 特征、角色模型和 FAISS 检索增强流程，让声线更贴近目标音色。
+- **RMVPE 音高提取**：按 RMVPE 论文报告，在公开基准上优于 CREPE / pYIN / SWIPE 等基线，并具备更好的噪声鲁棒性。
+- **角色模型**：内置可下载角色清单 117 项（以 `tools/character_models.py` 为准），支持系列筛选和关键词搜索。
+- **混音效果**：支持人声混响、音量调节、原声混合，生成结果不用再额外开一套音频工程。
+- **混音预设**：4 种预设（通用、人声突出、伴奏突出、现场感），想快一点就一键应用，想细一点也能继续手调。
+- **卡拉OK模式**：分离主唱和伴唱轨道，支持独立处理和混合，适合和声多、伴唱明显的歌曲。
+- **VC预处理**：4 种模式（自动、直通、学习型 DeEcho、旧版手工链），灵活控制人声预处理。
+- **双VC管道**：支持当前实现和官方实现，可按歌曲素材、模型效果做 A/B 对比。
+- **GPU 加速**：自动检测并使用 CUDA / ROCm / XPU / DirectML / MPS / CPU。
+- **简洁界面**：基于 Gradio 的中文图形界面，支持本地 Web、Google Colab 和 Hugging Face Spaces。
+
+## 平台支持
+
+| 平台 | 状态 | 安装方式 | 说明 |
+|------|------|---------|------|
+| Windows 10/11 (x64) | ✅ 已支持 | 可执行文件 / 本地安装 | 推荐使用可执行文件，无需安装 Python |
+| Linux (Ubuntu/Debian) | ✅ 按设计支持 | 可执行文件 / 本地安装 | 推荐 Ubuntu 22.04+，需在目标机器验证依赖与 GPU wheel |
+| WSL2 (Windows 11) | ✅ 已支持 | 本地安装 | 可直接通过浏览器访问 `http://127.0.0.1:7860` |
+| Google Colab | ⚠️ Notebook 已更新，需登录后实跑验证 | 在线使用 | 使用独立 Python 3.10 环境规避 Colab 默认 Python 版本变化；需在真实 Colab GPU 运行完整流程 |
+| Hugging Face Spaces | ✅ 已支持 | 在线使用 | 免费 CPU / 付费 GPU |
+| macOS | ⚠️ 未充分验证 | 本地安装 | 可尝试 CPU 模式；MPS 路径尚未适配 |
+
+## 快速开始
+
+> **💡 推荐方式**：
+> - **新手用户**：使用方式 1（可执行文件），无需安装 Python，开箱即用
+> - **开发者/频繁使用**：使用方式 4（本地安装），运行 `python install.py` 一键完成环境配置
+> - **临时体验**：使用方式 2（Google Colab）或方式 3（Hugging Face Spaces）
+
+### 方式 1：可执行文件（推荐新手，无需安装 Python）
+
+#### Windows
+
+1. 从 [Releases](https://github.com/mason369/AI-RVC/releases/latest) 下载 `AI-RVC-Windows-Portable.zip`
+2. 解压到任意目录
+3. 双击 `AI-RVC-Windows.exe` 启动
+4. 浏览器自动打开 http://127.0.0.1:7860
+
+#### Linux
+
+1. 从 [Releases](https://github.com/mason369/AI-RVC/releases/latest) 下载 `AI-RVC-Linux-Portable.tar.gz`
+2. 解压：`tar -xzf AI-RVC-Linux-Portable.tar.gz`
+3. 添加执行权限：`chmod +x AI-RVC-Linux-Portable/AI-RVC-Linux`
+4. 运行：`./AI-RVC-Linux-Portable/AI-RVC-Linux`
+5. 浏览器访问 http://127.0.0.1:7860
+
+**优势**：
+- ✅ 无需安装 Python 和依赖
+- ✅ 开箱即用，双击启动
+- ✅ 包含所有必需模型
+- ⚠️ 仅支持 CPU 推理（构建时使用 CPU 版 PyTorch 以控制包体积）
+- 💡 如需 GPU 加速，请使用方式 4 本地安装（`python install.py`）
+- ⚠️ 首次启动需要 5-10 分钟下载模型
+
+### 方式 2：Google Colab（推荐临时使用）
+
+![Colab 演示](docs/Colab演示.png)
+
+1. 打开 Colab notebook：[AI_RVC_Colab.ipynb](https://colab.research.google.com/github/mason369/AI-RVC/blob/master/AI_RVC_Colab.ipynb)
+2. 确保运行时类型设置为 **GPU**（菜单栏 → 代码执行程序 → 更改运行时类型 → T4 GPU）
+3. 按顺序执行每个单元格
+4. 启动 Gradio 界面后，点击生成的公共链接访问
+
+**当前状态**：
+- `AI_RVC_Colab.ipynb` 已改为在 Colab 内创建独立 Python 3.10 环境
+- 安装流程会调用 `install.py --no-run`，并严格检查 `fairseq==0.12.2`、`audio-separator>=0.44.1`、CUDA、HuBERT、RMVPE 等关键依赖和模型
+- Gradio 启动不再使用 `--skip-check`，启动前会再次检查环境和必需模型
+- 仍需在真实 Colab 登录态 + GPU 运行时中完整跑一遍，才能标记为“已实测完全可用”
+
+### 方式 3：Hugging Face Spaces（在线体验）
+
+访问：https://huggingface.co/spaces/mason369/AI-RVC
+
+**优势**：
+- 无需安装，直接使用
+- 随时随地访问
+- 易于分享
+
+**限制**：
+- 免费版使用 CPU（处理较慢）
+- 可升级到 GPU（付费）
+
+### 方式 4：本地安装（推荐开发者和频繁使用）
+
+#### 一键安装（推荐）
+
+**Windows**
+
+```powershell
+# 1. 克隆仓库
+git clone https://github.com/mason369/AI-RVC.git
+cd AI-RVC
+
+# 2. 运行一键安装脚本（自动创建虚拟环境、安装依赖）
+python install.py
+
+# 脚本会自动：
+# - 检测并创建 Python 3.10 虚拟环境
+# - 安装 PyTorch（自动检测 CUDA/CPU）
+# - 安装所有项目依赖
+# - 启动 Web 界面（首次运行时会自动下载基础模型）
+```
+
+**Linux / WSL2**
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/mason369/AI-RVC.git
+cd AI-RVC
+
+# 2. 运行一键安装脚本
+python3.10 install.py
+
+# 或仅检查环境（不安装）
+python3.10 install.py --check
+
+# 或安装 CPU 版本
+python3.10 install.py --cpu
+```
+
+**脚本选项**：
+- 无参数：完整安装 + 自动启动
+- `--check`：仅检查环境和依赖，不安装
+- `--cpu`：安装 CPU 版本 PyTorch（无 GPU 加速）
+- `--no-run`：安装完成后不自动启动
+
+> 脚本会自动创建 `venv310` 虚拟环境并在其中安装所有依赖。安装后手动启动请使用虚拟环境中的 Python：
+> - Windows：`venv310\Scripts\python run.py`
+> - Linux：`venv310/bin/python run.py`
+
+访问 http://127.0.0.1:7860 打开界面。
+
+首次运行翻唱时，audio-separator 会自动下载分离模型并缓存在 `assets/separator_models/`（体积随上游模型版本变化，通常为数百 MB）。
+
+---
+
+#### 手动安装（高级用户）
+
+如果需要自定义安装流程，可以手动执行以下步骤：
+
+**Windows**
+
+```powershell
+# 1. 克隆仓库
+git clone https://github.com/mason369/AI-RVC.git
+cd AI-RVC
+
+# 2. 创建虚拟环境
+python -m venv venv310
+.\venv310\Scripts\Activate.ps1
+
+# 3. 安装 PyTorch（先在官方页面生成与你环境匹配的命令）
+# https://pytorch.org/get-started/locally/
+# 示例（CUDA 12.6，2026-03-06）
+pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu126
+# CPU 示例
+# pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+
+# 4. 安装项目依赖
+pip install -r requirements.txt
+
+# 5. 下载基础模型（HuBERT、RMVPE）
+python tools/download_models.py
+
+# 6. ���动
+python run.py
+```
+
+**Linux / WSL2**
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/mason369/AI-RVC.git
+cd AI-RVC
+
+# 2. 创建虚拟环境
+python3.10 -m venv venv310
+source venv310/bin/activate
+
+# 3. 安装 PyTorch + 依赖
+# 先在 https://pytorch.org/get-started/locally/ 生成命令
+pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu126
+pip install -r requirements.txt
+
+# 4. 下载基础模型 + 启动
+python tools/download_models.py
+python run.py
+```
+
+---
+
+**Linux 兼容性说明**：
+- ✅ 核心代码路径使用 `pathlib.Path` 和跨平台设备检测，按设计支持 Linux / WSL2
+- ✅ 虚拟环境路径自动适配（`bin/python` vs `Scripts/python.exe`）
+- ✅ 音频处理库（librosa, soundfile, ffmpeg）在 Linux 上通常表现稳定
+- ✅ CUDA GPU 路径按 PyTorch Linux wheel 支持；ROCm 取决于本机 AMD 驱动、PyTorch ROCm wheel 与系统版本
+- ⚠️ `fairseq==0.12.2`、`pyworld`、`audio-separator[gpu]` 等依赖在不同 Linux 发行版上可能需要编译工具链和系统音频/FFmpeg 依赖
+- ⚠️ 本仓库的 Windows 环境已做自动化检查；Linux / WSL2 建议在目标机器运行 `python3.10 install.py --check` 和一次实际翻唱流程确认
+
+**安装脚本说明**：
+- `install.py` 会自动检测系统环境（Windows/Linux）并完成以下步骤：
+  1. **检测 Python 3.10**：Windows 检查常见安装路径 + `py -3.10` 启动器；Linux 使用 `python3.10` 命令
+  2. **创建虚拟环境**：在 `venv310/` 目录创建隔离的 Python 环境
+  3. **安装 PyTorch**：自动检测 CUDA 可用性，安装对应版本（GPU/CPU）
+  4. **安装项目依赖**：从 `requirements.txt` 安装所有必需包（包括 fairseq、audio-separator 等）
+  5. **启动应用**：自动运行 `run.py` 启动 Web 界面（除非使用 `--no-run`）
+- 基础模型（HuBERT、RMVPE）会在首次运行时由 `run.py` 自动下载
+- 支持参数：`--check`（仅检查）、`--cpu`（CPU 版本）、`--no-run`（不自动启动）
+- 如果虚拟环境已存在，会跳过创建步骤，直接检查依赖
+
+## 依赖版本说明
+
+| 依赖 | 版本要求 | 说明 |
+|------|----------|------|
+| Python | 3.10+ | 推荐 3.10 |
+| PyTorch | >= 2.0.0 | 语音转换 + 人声分离 |
+| torchaudio | >= 2.0.0 | 与 PyTorch 版本对应 |
+| CUDA | 与 torch wheel 匹配 | 常见 11.8 / 12.1 / 12.4 / 12.6（可选） |
+| fairseq | 0.12.2 | HuBERT 特征提取 |
+| audio-separator | >= 0.44.1 | Mel-Band Roformer / RoFormer 公开 scored SOTA 分离 |
+| demucs | >= 4.0.0 | Demucs 人声分离（可选） |
+
+> 建议使用 `python install.py` 安装依赖。`audio-separator` 0.44.1 的上游包元数据会请求 NumPy 2.x，但当前 Gradio 3.x/RVC 栈仍以 NumPy 1.x 最稳；安装脚本会在安装分离器后恢复 `numpy<2`。
 
 ## 使用方法
 
-### 1. 下载角色模型
+### 歌曲翻唱（推荐）
 
-首次使用需要下载角色模型：
 1. 进入「歌曲翻唱」标签页
-2. 展开「下载角色模型」折叠面板
-3. 选择并下载一个角色（推荐：星空凛、芙宁娜、纳西妲等）
+2. **下载角色模型**（首次使用）：
+   - 展开「下载角色模型」折叠面板
+   - 可按系列筛选或关键词搜索
+   - 点击「下载选中角色」下载单个角色
+   - 或点击「下载该分类全部」批量下载
+3. **上传歌曲**：支持 MP3/WAV/FLAC 格式
+4. **选择角色**：从已下载的角色列表中选择
+5. **调整参数**：
+   - 基础参数：音调偏移、索引率、说话人ID
+   - 卡拉OK设置：启用主唱/伴唱分离
+   - VC预处理模式：自动/直通/学习型DeEcho/旧版手工链
+   - 源约束策略：自动/关闭/启用
+   - VC管道模式：当前实现/官方实现
+   - 混音预设：通用/人声突出/伴奏突出/现场感
+   - 混音参数：人声音量、伴奏音量、混响、RMS混合率
+6. **开始翻唱**：点击「🚀 开始翻唱」按钮
+7. **下载结果**：
+   - 最终翻唱（混合后的完整作品）
+   - 转换后的人声
+   - 原始人声
+   - 主唱轨道（如启用卡拉OK）
+   - 伴唱轨道（如启用卡拉OK）
+   - 伴奏
 
-### 2. 开始翻唱
+### 角色模型管理
 
-1. 上传歌曲文件（支持 MP3/WAV/FLAC）
-2. 选择已下载的角色
-3. 调整参数：
-   - 音调偏移：男转女 +12，女转男 -12
-   - 混音预设：通用/人声突出/伴奏突出/现场感
-   - 卡拉OK模式：启用主唱/伴唱分离
-4. 点击「🚀 开始翻唱」
-5. 下载生成的翻唱作品
+**查看可用角色**：
+- 117 个角色，涵盖 Love Live!、原神、Hololive、偶像大师等系列
+- 支持按系列筛选和关键词搜索
+- 显示格式：【语言】角色名（出处）[内部名]
+
+**下载方式**：
+- 单个下载：选择角色后点击「下载选中角色」
+- 批量下载：选择系列后点击「下载该分类全部」
+- 全��下载：点击「下载全部角色模型」（需要较长时间）
+
+**已下载角色**：
+- 自动刷新列表
+- 支持按系列筛选和关键词搜索
+- 点击「刷新」按钮手动更新
+
+## 支持的格式
+
+**输入**：MP3, WAV, FLAC（UI 明确支持；其他格式取决于后端解码器）
+
+**输出**：WAV（翻唱成品 + 分离人声 + 伴奏）
+
+## 技术架构
+
+```
+音频输入 → CoverPipeline
+              ↓
+          ┌─ 步骤 1：人声分离 ─────────────────────────────┐
+          │  Mel-Band Roformer (默认) / UVR5 / Demucs      │
+          │      ↓                                         │
+          │  人声 (vocals.wav) + 伴奏 (accompaniment.wav)  │
+          └────────────────────────────────────────────────┘
+              ↓
+          ┌─ 步骤 2：RVC 语音转换 ─────────────────────────┐
+          │  HuBERT 特征提取 → RMVPE F0 提取               │
+          │      ↓                                         │
+          │  RVC v2 推理（角色模型 + FAISS 索引检索）       │
+          │      ↓                                         │
+          │  转换后人声 (converted_vocals.wav)              │
+          └────────────────────────────────────────────────┘
+              ↓
+          ┌─ 步骤 3：混音 ─────────────────────────────────┐
+          │  转换人声 + 伴奏 → 音量调节 + 混响             │
+          │      ↓                                         │
+          │  AI 翻唱成品 (cover.wav)                       │
+          └────────────────────────────────────────────────┘
+```
+
+### 使用的 AI 模型
+
+本项目翻唱流水线由处理链路模型组成，下面先给出当前默认值，再给出可选与对比项。
+
+| 环节 | 当前默认 | 作用 |
+|------|----------|------|
+| 人声分离 | `ensemble:vocal_rvc` | 分离主唱与伴奏 |
+| 卡拉OK分离 | `ensemble:karaoke` | 分离主唱与伴唱 |
+| 去混响/去回声 | `dereverb_mel_band_roformer_anvuew_sdr_19.1729.ckpt` | VC 预处理与严格 DeEcho 路径 |
+| 特征提取 | `hubert_base.pt` | 提取语音内容特征 |
+| 音高提取 | `rmvpe.pt` | 提取 F0 基频曲线 |
+| 语音转换 | RVC v2 | 执行 VC 推理 |
+
+---
+
+### 当前项目在用的模型
+
+| 模型 | 位置 | 用途 | 状态 |
+|------|------|------|------|
+| `ensemble:vocal_rvc` | `infer/separator.py` / `audio-separator` | 默认人声分离预设，包含 `melband_roformer_big_beta6x.ckpt` + `mel_band_roformer_vocals_fv4_gabox.ckpt`，算法 `avg_wave` | 使用中 |
+| `ensemble:karaoke` | `infer/separator.py` / `audio-separator` | 默认卡拉OK分离预设，包含 `mel_band_roformer_karaoke_aufr33_viperx_sdr_10.1956.ckpt` + `mel_band_roformer_karaoke_gabox_v2.ckpt` + `mel_band_roformer_karaoke_becruily.ckpt`，算法 `avg_wave` | 使用中 |
+| `dereverb_mel_band_roformer_anvuew_sdr_19.1729.ckpt` | `infer/separator.py` | 严格 DeEcho / 去混响 | 使用中 |
+| `htdemucs` / `htdemucs_ft` | `infer/separator.py` | Demucs 分离后端 | 可选 |
+| `HP2_all_vocals.pth` | `configs/config.json` | 当前 UVR5 预设 | 可选 |
+| `htdemucs_ft` | `configs/config.json` | 当前 Demucs 默认值 | 可选 |
+| `HP2_all_vocals.pth` | `tools/download_models.py` | UVR5 主人声模型；同时在 `REQUIRED_MODELS` 下载清单中 | 需要下载 |
+| `HP3_all_vocals.pth` | `tools/download_models.py` | UVR5 主人声模型 | 可选下载 |
+| `HP5_only_main_vocal.pth` | `tools/download_models.py` | UVR5 主人声模型 | 可选下载 |
+| `VR-DeEchoNormal.pth` | `tools/download_models.py` | 旧版 DeEcho | 可选下载 |
+| `VR-DeEchoAggressive.pth` | `tools/download_models.py` | 旧版强去回声 | 可选下载 |
+| `VR-DeEchoDeReverb.pth` | `tools/download_models.py` | 旧版去混响 | 可选下载 |
+| `onnx_dereverb_By_FoxJoy/vocals.onnx` | `tools/download_models.py` | 旧版 ONNX 去混响 | 可选下载 |
+| `hubert_base.pt` | `tools/download_models.py` | HuBERT 内容特征 | 需要下载 |
+| `rmvpe.pt` | `tools/download_models.py` | RMVPE 音高提取 | 需要下载 |
+| `f0G48k.pth` / `f0D48k.pth` | `tools/download_models.py` | 48k 预训练权重 | 可选下载 |
+| `f0G40k.pth` / `f0D40k.pth` | `tools/download_models.py` | 40k 预训练权重 | 可选下载 |
+
+---
+
+### 人声分离模型对比
+
+本项目当前默认使用 `audio-separator` 的 ensemble 预设，而不是旧版单一 ckpt。以下模型名以当前代码和本地 `audio-separator==0.44.1` 包内 `ensemble_presets.json` / `models.json` 为准。
+
+| 模型/预设 | 类型 | 用途 | 状态 | 说明 |
+|-----------|------|------|------|------|
+| `ensemble:vocal_rvc` | RoFormer ensemble | 默认人声分离 | 使用中 | `melband_roformer_big_beta6x.ckpt` + `mel_band_roformer_vocals_fv4_gabox.ckpt`，`avg_wave` |
+| `vocals_mel_band_roformer.ckpt` | 单模型 ckpt | 旧版单模人声分离 | 历史参考 | 旧 README 常写的单模型，不再作为当前默认 |
+| `melband_roformer_big_beta6x.ckpt` | 单模型 ckpt | 人声分离候选 | 可选 | 公开可下载的高质量候选模型 |
+| `mel_band_roformer_vocals_fv4_gabox.ckpt` | 单模型 ckpt | 人声分离候选 | 可选 | 公开可下载的高质量候选模型 |
+| `htdemucs` | Demucs | 人声/伴奏分离 | 可选 | 轻量稳定，适合对比 |
+| `htdemucs_ft` | Demucs | 人声/伴奏分离 | 可选 | 微调版，通常比基线更稳 |
+| `bs_roformer_viperx_1053` | BS-RoFormer | 人声/伴奏分离 | 公开参考 | 不在当前本地 `models.json` 可下载名中，不能直接当作本项目可选模型 |
+| `ensemble:karaoke` | RoFormer ensemble | 卡拉OK 主唱/伴唱分离 | 使用中 | 三模型 ensemble，`avg_wave` |
+| `mel_band_roformer_karaoke_aufr33_viperx_sdr_10.1956.ckpt` | 单模型 ckpt | 卡拉OK 分离 | 可选 | 公开带分数的卡拉OK候选 |
+| `dereverb_mel_band_roformer_anvuew_sdr_19.1729.ckpt` | 单模型 ckpt | 去混响/去回声 | 使用中 | 当前严格 DeEcho 路线使用的模型 |
+
+> 说明：不同数据集、榜单和评测协议不能直接横比。这里按“当前默认 / 可选 / 历史参考”来写，不把不同口径的分数硬拼成一张总榜。
+
+---
+
+### 语音转换模型：RVC v2
+
+使用 **RVC v2**（Retrieval-based Voice Conversion v2）进行人声音色转换。
+
+| 项目 | 详情 |
+|------|------|
+| 模型全称 | Retrieval-based Voice Conversion v2 |
+| 来源 | [RVC-Project](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI) |
+| 架构 | HuBERT 特征提取 → F0 条件 → 生成器 + FAISS 索引检索 |
+| 特征提取器 | HuBERT Base（`hubert_base.pt`） |
+| 推理权重 | 用户选择的 RVC `.pth` 声线模型 |
+| 索引文件 | 可选 `.index`，通过 FAISS 做检索增强 |
+| 许可证 | MIT |
+
+#### 同领域语音转换框架对比
+
+| 框架 | 来源 | 架构 | 说明 |
+|------|------|------|------|
+| [RVC v2](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI)（当前） | RVC-Project | HuBERT + 检索增强生成 | 本项目当前采用 |
+| [so-vits-svc](https://github.com/PlayVoice/whisper-vits-svc) | PlayVoice | VITS 系列 | 常见开源 SVC 路线 |
+| [GPT-SoVITS](https://github.com/RVC-Boss/GPT-SoVITS) | RVC-Boss | GPT + VITS few-shot | 更偏 TTS/语音克隆 |
+| [DDSP-SVC](https://github.com/yxlllc/DDSP-SVC) | yxlllc | DDSP | 轻量实时方向 |
+| [Seed-VC](https://arxiv.org/html/2407.07728v3) | 研究论文 | 零样本 VC | 研究方向 |
+
+> **结论**：在“角色模型翻唱”工作流里，RVC v2 目前仍是工程上最易落地的选项之一。
+
+---
+
+### F0 提取模型：RMVPE
+
+使用 **RMVPE** 从人声中提取基频（F0）曲线，用于保持转换后的音高/旋律。
+
+| 项目 | 详情 |
+|------|------|
+| 模型全称 | Robust Model for Vocal Pitch Estimation in Polyphonic Music |
+| 论文 | [arXiv:2306.15412](https://arxiv.org/abs/2306.15412) |
+| 检查点 | `rmvpe.pt` |
+| 核心优势 | 直接从多声道混音中提取人声音高，噪声鲁棒性强 |
+| 指标 | 论文报告在 RPA/RCA 等指标上优于 CREPE、pYIN、SWIPE、Harvest 等基线 |
+
+#### 同领域 F0 提取模型对比
+
+| 模型 | 来源 | 说明 |
+|------|------|------|
+| [RMVPE](https://arxiv.org/abs/2306.15412)（当前） | Dream-High | 当前项目默认方案，兼顾精度与鲁棒性 |
+| [CREPE](https://github.com/marl/crepe) | NYU MARL | 经典 CNN 方案，生态成熟 |
+| [Harvest](https://github.com/mmorise/World) | WORLD | 传统信号处理方案，部署简单 |
+
+> **结论**：默认推荐 RMVPE。
+
+---
+
+### 特征提取模型：HuBERT Base
+
+| 项目 | 详情 |
+|------|------|
+| 模型全称 | Hidden-Unit BERT |
+| 来源 | [Meta AI / fairseq](https://github.com/facebookresearch/fairseq/tree/main/examples/hubert) |
+| 检查点 | `hubert_base.pt` |
+| 用途 | 提取语音内容特征（去除说话人信息），供 RVC 生成器使用 |
+| 说明 | RVC v2 架构绑定 HuBERT Base；WavLM/ContentVec 在其他框架中可能更优，但本项目现有模型以 HuBERT 为准 |
 
 ## 参数说明
 
-### 基础参数
+### 转换参数
+
+| 参数 | 说明 | 建议值 |
+|------|------|--------|
+| 音调偏移 | 半音数，正数升调，负数降调 | 男转女: +12, 女转男: -12 |
+| F0 提取方法 | 音高提取算法 | rmvpe（默认） |
+| 索引比率 | 越高越像训练音色 | 0.1-0.5 (10-50%) |
+| 滤波半径 | 中值滤波，减少气音抖动 | 3 |
+| 保护系数 | 防止撕裂伪影，越小保护越强 | 0.33 |
+| RMS 混合率 | 音量包络匹配程度 | 0.15 (15%) |
+
+### 混音参数（翻唱）
 
-- **音调偏移**：半音数，正数升调，负数降调（男转女: +12, 女转男: -12）
-- **索引率**：越高越像训练音色（建议 10-50%）
-- **说话人ID**：多说话人模型的说话人选择（通常为 0）
+| 参数 | 说明 | 建议值 |
+|------|------|--------|
+| 人声音量 | 转换后人声的音量 | 100% |
+| 伴奏音量 | 背景伴奏的音量 | 100% |
+| 人声混响 | 为人声添加空间感 | 10-20% |
+| 伴唱混合率 | 伴唱在最终输出中的比例 | 0-100% |
 
 ### 混音预设
 
-- **通用**：默认均衡设置
-- **人声突出**：人声 +15%，伴奏 -10%，混响 -5%
-- **伴奏突出**：人声 -10%，伴奏 +15%，混响 -5%
-- **现场感**：默认音量，混响 +10%
+| 预设 | 人声音量 | 伴奏音量 | 混响 | 说明 |
+|------|---------|---------|------|------|
+| 通用 | 100% | 100% | 10% | 默认均衡设置 |
+| 人声突出 | 115% | 90% | 5% | 突出人声，适合清唱风格 |
+| 伴奏突出 | 90% | 115% | 5% | 突出伴奏，适合背景音乐丰富的歌曲 |
+| 现场感 | 100% | 100% | 20% | 增加混响，模拟现场演出效果 |
 
 ### VC 预处理模式
 
-- **自动**：根据模型可用性自动选择（推荐）
-- **直通**：主唱直接进入 RVC
-- **学习型 DeEcho**：使用 UVR DeEcho/DeReverb
-- **旧版手工链**：仅用于对比测试
+| 模式 | 说明 | 适用场景 |
+|------|------|---------|
+| 自动 | 根据模型可用性自动选择 | 推荐，智能选择最佳路径 |
+| 直通 | 主唱直接进入 RVC | 干净人声，无需去混响 |
+| 学习型 DeEcho | 使用 UVR DeEcho/DeReverb | 需要去除混响和回声 |
+| 旧版手工链 | 旧版手工去回声链 | 仅用于对比测试 |
 
-## 可用角色模型（117 个）
+### 源约束策略
+
+| 模式 | 说明 |
+|------|------|
+| 自动 | 根据场景自动决定 |
+| 关闭 | 不使用源约束 |
+| 启用 | 强制启用源约束 |
+
+### VC 管道模式
+
+| 模式 | 说明 | 特点 |
+|------|------|------|
+| 当前实现 | 使用项目自定义 VC 流程 | 支持完整的预处理和后处理 |
+| 官方实现 | 使用内置官方 RVC | 跳过自定义预处理，支持唱歌修复 |
+
+### 人声分离参数 (config.json)
+
+| 参数 | 说明 | 建议值 |
+|------|------|--------|
+| separator | 分离器类型 | roformer（推荐）、uvr5 或 demucs |
+| uvr5_model | UVR5 模型 | HP2_all_vocals |
+| uvr5_agg | UVR5 激进度 (1-10) | 6-8（高音问题可降低） |
+| demucs_model | Demucs 模型 | htdemucs |
+| karaoke_model | 卡拉OK分离模型 | mel_band_roformer_karaoke_gabox.ckpt |
+
+### 分离质量评估
+
+真实量化指标需要参考 stem。项目提供 `tools/evaluate_karaoke_models.py` 用于对比本地 Karaoke 模型：
+
+```powershell
+python tools/evaluate_karaoke_models.py --vocals-path vocals.wav --output-dir outputs/karaoke_eval
+```
+
+无参考 stem 时，报告里的 `score` 只是诊断代理分数，用于检查重建误差、主唱/伴唱相关性、能量比例和长度覆盖率，不能代表最终听感。若有人工标注或数据集参考 stem，可加入参考主唱/伴唱，此时报告会输出论文中常用的 SI-SDR / SDR：
+
+```powershell
+python tools/evaluate_karaoke_models.py `
+  --vocals-path vocals.wav `
+  --reference-lead refs/lead.wav `
+  --reference-backing refs/backing.wav `
+  --output-dir outputs/karaoke_eval
+```
+
+实践建议：当前默认使用最新 audio-separator 公开 scored SOTA 分离模型；若某首歌出现主唱变薄或和声泄漏，可以在评估工具中加入参考 stem 使用 SI-SDR/SDR 排名，或手动把 `karaoke_model` 临时改为 `mel_band_roformer_karaoke_aufr33_viperx_sdr_10.1956.ckpt` 做 A/B。
+
+## 配置文件
+
+主要配置在 `configs/config.json`：
+
+```json
+{
+  "device": "cuda",
+  "f0_method": "rmvpe",
+  "index_rate": 0.1,
+  "filter_radius": 3,
+  "protect": 0.33,
+  "cover": {
+    "separator": "roformer",
+    "karaoke_model": "mel_band_roformer_karaoke_gabox.ckpt",
+    "uvr5_model": "HP2_all_vocals",
+    "uvr5_agg": 8,
+    "rms_mix_rate": 0.0,
+    "backing_mix": 0.0
+  }
+}
+```
+
+## 可用角色模型（100+，当前清单 117）
 
 | 系列 | 角色示例 |
 |------|----------|
 | Love Live! | 星空凛、园田海未、东条希、小泉花阳、南小鸟 |
-| Love Live! Sunshine!! | 高海千歌、樱内梨子、黑泽黛雅、黑泽露比、国木田花丸 |
-| Love Live! 虹咲学园 | 上原步梦、中须霞、天王寺璃奈、近江彼方、优木雪菜 |
+| Love Live! Sunshine!! | 高海千歌、樱内梨子、黑泽黛雅、黑泽露比、国木田花丸、津岛善子、小原鞠莉、渡边曜、松浦果南 |
+| Love Live! 虹咲学园 | 上原步梦、中须霞、天王寺璃奈、近江彼方、优木雪菜、三船栞子���米雅·泰勒 |
+| Love Live! Superstar!! | 唐可可、平安名堇 |
+| 偶像大师 | 神崎兰子、梦见莉亚梦、双叶杏、本田未央、岛村卯月 |
 | 原神 | 芙宁娜、枫原万叶、纳西妲、八重神子、雷电将军 |
+| 碧蓝航线 | 埃塞克斯 |
 | Hololive | Fuwawa、Mococo |
-| 偶像大师 | 神崎兰子、梦见莉亚梦、双叶杏、本田未央、岛村卯月 |
+| 原创 | 爱美 (Aimi) |
 
 > 完整列表请在 UI 中查看「下载角色模型」面板
 
-## 技术架构
+## 项目结构
 
 ```
-音频输入 → CoverPipeline
-              ↓
-          人声分离 (Mel-Band Roformer)
-              ↓
-          RVC 音色转换 (HuBERT + RMVPE + FAISS)
-              ↓
-          混音 (音量调节 + 混响)
-              ↓
-          AI 翻唱成品
+AI-RVC/
+├── venv310/                 # 虚拟环境 (Python 3.10)
+├── assets/                  # 模型文件
+│   ├── hubert/              # HuBERT 模型 (~190 MB)
+│   ├── rmvpe/               # RMVPE 模型
+│   ├── uvr5_weights/        # UVR5 人声分离模型
+│   ├── separator_models/    # Roformer 人声分离模型 (自动下载)
+│   └── weights/             # 用户语音模型
+│       └── characters/      # 角色模型 (100+，自动下载)
+├── configs/                 # 配置文件
+│   └── config.json          # 主配置
+├── infer/                   # 推理模块
+│   ├── pipeline.py          # 自定义 RVC 推理管道
+│   ├── cover_pipeline.py    # 翻唱流水线
+│   ├── separator.py         # 人声分离 (Roformer/Demucs)
+│   └── modules/             # 官方 VC 模块
+│       ├── vc/              # 官方 VC 管道
+│       └── uvr5/            # UVR5 人声分离
+├── lib/                     # 核心库
+│   ├── audio.py             # 音频处理
+│   ├── mixer.py             # 混音模块
+│   └── logger.py            # 日志系统
+├── models/                  # 模型定义
+├── tools/                   # 工具脚本
+│   ├── download_models.py   # 基础模型下载
+│   └── character_models.py  # 角色模型管理
+├── ui/                      # Gradio 界面
+├── outputs/                 # 输出文件
+├── temp/                    # 临时文件
+└── run.py                   # 主入口
 ```
 
 ## 常见问题
 
-**Q: 首次运行很慢？**
+**Q: CUDA out of memory**
 
-A: 首次运行会自动下载模型文件（HuBERT、RMVPE、Roformer 等），请耐心等待。
+人声分离通常需要约 4GB 以上显存（取决于音频时长和模型），尝试：
+- 关闭其他占用显存的程序
+- 使用较短的音频（建议 < 5 分钟）
+- 在 config.json 中切换 separator 为 demucs 或 uvr5
 
-**Q: 高音断音/撕裂？**
+**Q: 首次运行很慢**
 
-A: 尝试降低保护系数（0.33 → 0.2），增大滤波半径（3 → 5）。
+首次运行会自动下载模型文件（大小随模型版本变化），请耐心等待。
 
-**Q: 转换后声音失真？**
+**Q: 高音断音/撕裂**
 
-A: 降低索引率，调整音调偏移，使用更高质量的输入音频。
+这通常是 F0 提取不稳定导致的，尝试：
+- 降低 UVR5 激进度（`uvr5_agg`: 8 → 6-7）
+- 降低保护系数（`protect`: 0.33 → 0.2）
+- 增大滤波半径（`filter_radius`: 3 → 5）
+- 使用更干净的输入音频
 
-**Q: 如何选择合适的角色？**
+**Q: 转换后声音失真**
 
-A: 建议选择与原唱性别、音色相近的角色，效果更自然。
+尝试：降低索引比率、调整音调偏移、使用更高质量的输入音频。
 
-## 性能说明
+**Q: 角色模型下载失败**
 
-- **GPU 加速**：自动检测并使用 GPU（CUDA/ROCm）
-- **处理时间**：一首 3-5 分钟的歌曲约需 2-5 分钟处理
-- **显存需求**：建议 4GB 以上显存
+检查网络连接，或手动下载：
+```bash
+python -c "from tools.character_models import download_character_model; download_character_model('rin')"
+```
 
-## 限制说明
+**Q: faiss AVX512 警告**
 
-- **音频长度**：建议单次处理不超过 10 分钟
-- **文件大小**：建议上传文件不超过 50MB
-- **并发处理**：同时只能处理一个任务
+正常的回退机制，faiss 会自动使用 AVX2，不影响功能。
 
-## 更多信息
+**Q: CUDA 不可用**
+```bash
+nvidia-smi
+python -c "import torch; print(torch.cuda.is_available())"
+```
 
-- **GitHub 仓库**：https://github.com/mason369/AI-RVC
-- **完整文档**：查看仓库中的 README.md
-- **Colab 版本**：AI_RVC_Colab.ipynb
-- **问题反馈**：GitHub Issues
+**Q: torchaudio DLL 加载失败 / 路径相关报错**
 
-## 免责声明
+项目路径中不能包含中文或特殊字符（如 `C:\新建文件夹\AI-RVC`），否则 PyTorch/torchaudio 的 C++ 库无法正确加��。请将项目放在纯英文路径下，例如 `C:\AI-RVC` 或 `D:\AI-RVC`。
+
+## 数据核验说明（2026-05-02）
+
+以下外部数据已在 2026-05-02 复核，README 中涉及的关键数字以这些来源为准：
+
+- MVSEP 算法页（Multisong 指标与模型分数）：https://mvsep.com/algorithms
+- audio-separator 公开模型表：https://pypi.org/project/audio-separator/
+- MVSEP 算法详情（KimberleyJensen 模型）：https://mvsep.com/algorithms/49
+- SI-SDR 指标讨论（Le Roux et al., 2019）：https://arxiv.org/abs/1811.02508
+- BSS Eval / museval 源分离评估工具链：https://github.com/sigsep/sigsep-mus-eval
+- RVC 官方仓库与许可证：https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI
+- 第三方模型聚合计数（voice-models 列表页）：https://voice-models.com/models
+- RMVPE 论文：https://arxiv.org/abs/2306.15412
+- FCPE 论文：https://arxiv.org/html/2509.15140
+- PyTorch 安装页面（当前 CUDA wheel 选择）：https://pytorch.org/get-started/locally/
+
+## 贡献
+
+欢迎提交 Pull Request。
+
+1. Fork 本仓库
+2. 创建功能分支：`git checkout -b feature/amazing-feature`
+3. 提交更改：`git commit -m 'feat: add amazing feature'`
+4. 推送分支：`git push origin feature/amazing-feature`
+5. 创建 Pull Request
+
+## 许可证
 
-本项目仅供学习研究和个人娱乐用途，不得用于任何商业目的。严禁使用本软件进行欺诈、传播虚假信息或侵犯他人权益。用户对使用本软件产生的所有内容和后果承担全部责任。
+MIT License
 
 ## 致谢
 
 - [RVC-Project](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI) - 原始 RVC 项目
-- [Mel-Band RoFormer](https://arxiv.org/abs/2310.01809) - 人声分离模型
-- [audio-separator](https://github.com/nomadkaraoke/python-audio-separator) - 音源分离框架
-- [RMVPE](https://arxiv.org/abs/2306.15412) - F0 提取
+- [Mel-Band RoFormer](https://arxiv.org/abs/2310.01809) - 人声分离模型架构论文
+- [audio-separator](https://github.com/nomadkaraoke/python-audio-separator) - 音源分离推理框架
+- [Music-Source-Separation-Training](https://github.com/ZFTurbo/Music-Source-Separation-Training) - Roformer 预训练权重
+- [UVR5](https://github.com/Anjok07/ultimatevocalremovergui) - Ultimate Vocal Remover
+- [Demucs](https://github.com/facebookresearch/demucs) - Meta 人声分离
+- [RMVPE](https://arxiv.org/abs/2306.15412) - 高质量 F0 提取
+- [HuBERT](https://github.com/facebookresearch/fairseq/tree/main/examples/hubert) - 语音特征提取
 - [Gradio](https://gradio.app/) - Web 界面框架
 
----
+## 免责声明
+
+**重要提示：使用本软件前请仔细阅读以下声明**
+
+1. **仅供学习研究**：本项目仅供学习、研究和个人娱乐用途，不得用于任何商业目的。
+
+2. **禁止非法使用**：严禁使用本软件进行以下行为：
+   - 未经授权模仿他人声音进行欺诈、诈骗
+   - 制作虚假音频用于传播谣言或误导公众
+   - 侵犯他人肖像权、名誉权或其他合法权益
+   - 任何违反当地法律法规的行为
+
+3. **版权声明**：
+   - 使用本软件转换的音频版权归原作者所有
+   - 用户需自行获取原始音频和模型的使用授权
+   - 本项目内置的角色模型仅供技术演示，请勿用于商业用途
+
+4. **用户责任**：用户对使用本软件产生的所有内容和后果承担全部责任。开发者不对任何滥用行为负责。
+
+5. **无担保声明**：本软件按"原样"提供，不提供任何明示或暗示的担保。
 
-**License**: MIT
-**Version**: 2.0
-**Last Updated**: 2026-03-15
+**使用本软件即表示您已阅读、理解并同意以上声明。**

README_HF.md

@@ -12,19 +12,21 @@ license: mit
 
 # 🎤 AI-RVC 一键 AI 翻唱
 
-基于 RVC v2 的一键 AI 翻唱系统，自动完成人声分离、音色转换、混音合成全流程。
+AI-RVC 是一个基于 **RVC v2** 的一键 AI 翻唱与声音转换 WebUI。上传歌曲后，它会自动分离人声与伴奏，使用角色 RVC 模型转换主唱音色，再把转换后的人声和伴奏混成完整作品。
+
+如果你想搜索或分享本项目，可以用这些关键词：AI 翻唱、RVC 翻唱、AI cover generator、RVC voice conversion、角色声线转换、人声分离、伴奏分离、HuBERT、RMVPE、FAISS、Gradio WebUI、Colab AI 翻唱。
 
 ## 功能特点
 
-- **AI 歌曲翻唱**：上传歌曲自动分离人声、转换音色、混合伴奏，一键生成翻唱
-- **人声分离**：默认 Mel-Band Roformer (KimberleyJensen)，在 MVSEP 公开 Multisong 指标中为 Vocals SDR 11.01 / Instrum SDR 17.32
-- **音色转换**：RVC v2 架构 + FAISS 检索增强流程
-- **RMVPE 音高提取**：高精度 F0 提取，噪声鲁棒性强
-- **角色模型**：内置 117 个可下载角色模型
-- **混音效果**：支持人声混响、音量调节、4 种混音预设
-- **卡拉OK模式**：分离主唱和伴唱轨道
-- **VC预处理**：4 种模式（自动、直通、学习型DeEcho、旧版手工链）
-- **双VC管道**：支持当前实现和官方实现
+- **AI 歌曲翻唱**：上传 MP3/WAV/FLAC，自动分离人声、转换音色、混合伴奏，一键生成 AI cover。
+- **人声分离**：默认 `audio-separator` 0.44.1 ensemble 预设（`ensemble:vocal_rvc`），可处理常见歌曲里的主唱与伴奏分离。
+- **音色转换**：RVC v2 架构 + FAISS 检索增强流程，搭配角色模型完成声线转换。
+- **RMVPE 音高提取**：用于提取 F0 基频曲线，让旋律和音高更稳。
+- **角色模型**：内置 117 个可下载角色模型，支持系列筛选和关键词搜索。
+- **混音效果**：支持人声混响、音量调节和 4 种混音预设。
+- **卡拉OK模式**：分离主唱和伴唱轨道，方便对和声较多的歌曲做进一步处理。
+- **VC预处理**：4 种模式（自动、直通、学习型 DeEcho、旧版手工链），根据素材干净程度灵活选择。
+- **双VC管道**：支持当前实现和官方实现，可对比不同歌曲、不同模型下的效果。
 
 ## 使用方法
 
@@ -148,4 +150,4 @@ A: 建议选择与原唱性别、音色相近的角色，效果更自然。
 
 **License**: MIT
 **Version**: 2.0
-**Last Updated**: 2026-03-15
+**Last Updated**: 2026-06-18

docs/repository-introduction.md

@@ -0,0 +1,46 @@
+# AI-RVC 仓库介绍与搜索可见性文案
+
+这份文档用于配置 GitHub About、仓库 topics、Hugging Face Space 简介或第三方项目介绍页。目标是让搜索引擎和 GitHub 主题页更容易理解：AI-RVC 是一个围绕 **AI 翻唱、RVC v2 声音转换、人声分离、角色声线模型和混音合成** 的项目。
+
+## GitHub About 简介
+
+中文推荐版：
+
+> 一键 AI 翻唱与 RVC v2 声音转换 WebUI：自动人声分离、HuBERT + RMVPE + FAISS 音色转换、角色模型下载、混音预设，并支持 Windows、Linux、WSL2、Google Colab 和 Hugging Face Spaces。
+
+English version:
+
+> One-click AI cover and RVC v2 voice conversion WebUI with vocal separation, HuBERT + RMVPE + FAISS inference, character model downloads, mixing presets, and support for Windows, Linux, WSL2, Google Colab, and Hugging Face Spaces.
+
+## GitHub Topics
+
+GitHub topics 建议使用小写字母、数字和连字符。下面这组控制在 20 个以内，便于直接粘贴到仓库 About 面板：
+
+`rvc`, `rvc-v2`, `voice-conversion`, `ai-cover`, `song-cover`, `singing-voice-conversion`, `voice-changer`, `voice-cloning`, `vocal-separation`, `audio-separation`, `rmvpe`, `hubert`, `faiss`, `gradio`, `pytorch`, `colab`, `uvr`, `demucs`, `roformer`, `ai-music`
+
+## 搜索摘要
+
+短版：
+
+> AI-RVC 是一个基于 RVC v2 的一键 AI 翻唱工具，自动完成人声分离、角色声线转换、音高提取和混音合成，支持本地 WebUI、Google Colab 与 Hugging Face Spaces。
+
+长版：
+
+> AI-RVC 面向想做 AI cover、RVC 翻唱和角色声线转换的用户。项目把歌曲处理流程串成一条完整流水线：先用 `audio-separator` / RoFormer 分离人声与伴奏，再通过 HuBERT、RMVPE、FAISS 和 RVC v2 模型转换主唱音色，最后用混音预设生成完整翻唱作品。它提供中文 Gradio WebUI、117 个可下载角色模型、卡拉OK分离、VC 预处理、双 VC 管道，并支持 Windows、Linux、WSL2、Google Colab 和 Hugging Face Spaces。
+
+## 关键词组合
+
+中文关键词：
+
+AI 翻唱、RVC 翻唱、RVC v2 声音转换、AI 声音转换、AI cover、角色声线转换、人声分离、伴奏分离、卡拉OK分离、AI 歌曲翻唱、Gradio WebUI、Colab AI 翻唱、HuBERT、RMVPE、FAISS
+
+English keywords:
+
+AI cover generator, RVC voice conversion, Retrieval-based Voice Conversion, RVC v2, singing voice conversion, voice changer, voice cloning, vocal separation, audio separation, karaoke separation, Gradio WebUI, Google Colab AI cover, HuBERT, RMVPE, FAISS
+
+## 写法原则
+
+- 用真实功能词做关键词，不堆无关热词。
+- 仓库简介先说清楚“做什么”，再说“用什么技术”，最后说“在哪些平台可用”。
+- README 首页保留原有技术结构，搜索关键词只放在简介、功能点和仓库介绍中自然出现。
+- 不建议加入与项目无关的关键词，例如“风扇自动控制”。这类页面可以参考它们的一句话简介和 topics 写法，但不能把无关词塞进 AI-RVC 仓库，否则搜索命中会变脏，读者也容易误会项目用途。

infer/separator.py

@@ -2,6 +2,8 @@
 """
 人声分离模块 - 支持 Demucs 和 Mel-Band Roformer (audio-separator)
 """
+from __future__ import annotations
+
 import os
 import gc
 import shutil

tests/test_model_defaults.py

@@ -1,3 +1,4 @@
+import subprocess
 import sys
 import tempfile
 import unittest
@@ -71,6 +72,42 @@ class ModelDefaultTests(unittest.TestCase):
         self.assertFalse(hasattr(separator, "KARAOKE_FALLBACK_MODELS"))
         self.assertFalse(hasattr(separator, "ROFORMER_DEREVERB_FALLBACK_MODELS"))
 
+    def test_separator_import_survives_missing_audio_separator(self):
+        script = """
+import importlib.abc
+import sys
+
+class BlockAudioSeparator(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname == "audio_separator" or fullname.startswith("audio_separator."):
+            raise ImportError("blocked audio_separator")
+        return None
+
+sys.meta_path.insert(0, BlockAudioSeparator())
+from infer import separator
+
+assert separator.AUDIO_SEPARATOR_AVAILABLE is False
+try:
+    separator.RoformerSeparator()
+except ImportError as exc:
+    assert "audio-separator" in str(exc)
+else:
+    raise AssertionError("RoformerSeparator should fail when audio_separator is missing")
+"""
+        result = subprocess.run(
+            [sys.executable, "-c", script],
+            cwd=REPO_ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(
+            result.returncode,
+            0,
+            msg=f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}",
+        )
+
 
 class KaraokeCandidateScoringTests(unittest.TestCase):
     def test_karaoke_candidate_score_rewards_reconstruction_and_low_correlation(self):