RVC 音色模型下载工具 — 实现规范

给 AI 看的实现文档。目标：用纯 Python 标准库，单文件脚本，从 HuggingFace 下载 RVC 音色模型。

1. 目标

写一个 download_voice_models.py 脚本，放在 tools/ 目录下。功能：

1. 扫描 HuggingFace 上公开的 RVC 音色模型仓库

2. 交互式选择模型，下载 .pth + .index 到 assets/weights/

3. 零依赖 — 只用 Python 3 标准库（urllib, json, zipfile 等）

4. 无需登录 — HuggingFace 公开仓库直接走 REST API

2. HuggingFace REST API（无需 token）

基地址：https://huggingface.co/api/

2.1 列出仓库文件

GET https://huggingface.co/api/models/{repo_id}?tree=true

返回 JSON，siblings 数组里每个元素有 rfilename 字段，就是文件路径。

示例：https://huggingface.co/api/models/Plana-Archive/Anime-RCV?tree=true

2.2 搜索仓库

GET https://huggingface.co/api/models?search={keyword}&limit=30

返回 JSON 数组，每个元素含 id（仓库ID）、downloads、pipeline_tag 等。

2.3 下载文件（原始内容）

GET https://huggingface.co/{repo_id}/resolve/main/{filepath}

返回文件的原始二进制内容，流式下载。

示例：https://huggingface.co/Plana-Archive/Anime-RCV/resolve/main/Arknights-RCV/weights/Arknights/Amiya/Amiya.pth

2.4 下载 LFS 大文件指针解析

如果文件是 LFS 存储（返回的是指针 JSON 而非实际内容），从 JSON 中取 oid（sha256），然后：

GET https://huggingface.co/{repo_id}/resolve/main/{filepath}?download=1

加 ?download=1 参数即可拿到 raw 内容。

3. 仓库文件结构的两种模式

模式 A：子目录嵌套（如 Plana-Archive/Anime-RCV）

Arknights-RCV/weights/Arknights/Amiya/Amiya.pth
Arknights-RCV/weights/Arknights/Amiya/Amiya.index
Kimetsu-no-Yaiba-RCV/weights/Kimetsu-no-Yaiba/Doma/Doma.pth
Kimetsu-no-Yaiba-RCV/weights/Kimetsu-no-Yaiba/Doma/Doma.index
VTUBER RCV MODELS/kitlemonfoot_rvc_models/AZKi (Hybrid).zip

规律：

• .pth 和 .index 成对放在同一个子目录下

• 模型名 = 最深层目录名（如 Amiya）

• 分类 = 父级路径

• 也有 .zip 包混在里面

模式 B：Zip 包（如 UnidentifiedPerson/VoiceModels）

ElonMusk(RVCV2)RVMPE-GPU250Epochs.zip
BenShapiro(RVCV2)RVMPE-GPU250Epochs.zip

规律：

• 每个模型是一个 .zip 文件

• 下载后解压，里面包含 .pth + .index

• 模型名 = zip 文件名（去掉 .zip）

4. 过滤规则：排除基座模型

只下载音色模型，跳过 RVC 基座/引擎模型。

基座模型文件名以这些前缀开头：D_, G_, f0D, f0G

示例要跳过的：

• D_6864.pth / G_6864.pth（判别器/生成器）

• f0D32k.pth / f0G40k.pth（F0 预训练）

这些是引擎依赖，不是音色，用户不需要看到它们。

5. 下载逻辑

模式 A（直接文件）：

1. 扫描仓库，按父目录分组

2. 同目录下有 .pth 的，找同名 .index 配对

3. 用户选择后，逐个下载 .pth 和 .index：

   • URL: https://huggingface.co/{repo_id}/resolve/main/{filepath}

   • 写入 assets/weights/{basename}

4. 用 urllib.request.urlopen 流式读取，shutil.copyfileobj 写入

模式 B（zip 包）：

1. 下载整个 zip 到临时目录

2. 用 zipfile.ZipFile 解压

3. 找到里面的 .pth 和 .index，复制到 assets/weights/

4. 清理临时文件

6. CLI 交互流程

╔══════════════════════════════════════════════════════╗
║       RVC 音色模型下载工具                           ║
║       下载到 assets/weights/                         ║
╚══════════════════════════════════════════════════════╝
  现有内置音色: 8 个
  源: HuggingFace Hub (无需登录)

------------------------------------------------------------
  [1] 浏览已知音色仓库
  [2] 搜索 HuggingFace
  [3] 直接输入仓库 ID
  [0] 退出
------------------------------------------------------------

[1] 已知仓库列表

预置以下仓库（存为一个常量列表）：

选仓库 → 扫描 → 显示模型列表（按分类分组，带编号）→ 选编号下载。

[2] 搜索

输入关键词 → 调用搜索 API → 显示匹配的仓库列表 → 选仓库 → 同 [1]。

[3] 直接输入

用户粘贴 HuggingFace 仓库 ID → 扫描 → 同 [1]。

7. 注意事项

1. 网络超时：urllib.request.urlopen 设置超时 30 秒，加上 User-Agent header

2. 文件已存在跳过：下载前检查 assets/weights/ 是否已有同名文件，已有则提示跳过

3. 进度显示：流式下载时打印简单的进度（如文件名 + 大小）

4. LFS 处理：先用不加 ?download=1 的 URL 试试，如果返回的内容以 version https://git-lfs 开头，说明是 LFS 指针，换用加 ?download=1 的 URL

5. 搜索过滤：搜索 API 返回的仓库可能混有非 RVC 内容，展示时优先选 pipeline_tag 与 audio/voice 相关的

6. 脚本路径：用 Path(__file__).resolve().parent.parent 定位项目根目录，确保从任意位置运行都能正确找到 assets/weights/