Model-Down: AI Voice Platform 模型同步工具

本工具基于现代 Python 包管理工具 uv 与 ModelScope (魔搭社区) SDK 构建，专为 AI Voice Platform 的 ONNX 语音模型资产提供高效、可靠的生产部署一键拉取与云端上传备份能力。

---

特性

• ⚡ 超快依赖解析：全链路采用 uv 管理，秒级完成虚拟环境准备与依赖安装。
• 📦 整包同步：自动递归管理 onnx-platform/models/ 目录下的 16 个子模型及根级 silero_vad.onnx（总体积约 4.37 GB）。
• 🔄 断点续传：底层基于 ModelScope 分块并发上传与哈希增量下载，网络中断无需重新开始。
• 🛡️ 纯净模型库：自动严格排除 model-down/ 脚本工具自身、.venv 虚拟环境、缓存与临时文件，确保云端仓库只存放纯粹的 ONNX 权重与运行时资产。
• 🖥️ 跨平台支持：全面兼容 Windows 11、Linux (Ubuntu/Debian) 与 WSL 环境。

---

1. 准备环境 (安装 uv)

如果在当前机器或目标服务器尚未安装 uv，可一键安装：

• Linux / macOS / WSL：

  curl -LsSf https://astral.sh/uv/install.sh | sh
  source $HOME/.local/bin/env

• Windows (PowerShell)：

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

---

2. 依赖初始化

进入工具目录，使用 uv sync 一键初始化虚拟环境与依赖：

cd onnx-platform/models/model-down
uv sync

---

3. 从 ModelScope 下载模型 (核心高频操作)

在全新开发机、部署测试机、Debian 12 生产主机或 WSL Docker 环境中，一键高速拉取全套语音模型。

常用下载命令

# 1. 默认下载到上一级目录（还原为 onnx-platform/models）
uv run download.py --model-id wlf213/ai-voice-platform-models

# 2. 部署到指定服务器路径（例如 WSL / Linux 生产挂载目录 /data/ai-voice/models）
uv run download.py --model-id wlf213/ai-voice-platform-models --target-dir /data/ai-voice/models

# 3. 私有仓库下载（传入 Token 或通过环境变量注入）
export MODELSCOPE_API_TOKEN="your-token"
uv run download.py --model-id wlf213/ai-voice-platform-models --target-dir /data/ai-voice/models

# 4. 通过统一 CLI 入口运行
uv run main.py download --model-id wlf213/ai-voice-platform-models --target-dir ../

按需过滤下载（模式匹配）

如果测试或部署仅需特定模型族（例如仅需 FunASR 或 Sherpa 系列），无需全量拉取 4.3GB：

# 仅下载 FunASR 系列模型
uv run download.py --model-id wlf213/ai-voice-platform-models --allow-patterns "funasr-*"

# 仅下载 Sherpa ASR 与 Silero VAD
uv run download.py --model-id wlf213/ai-voice-platform-models --allow-patterns "sherpa-onnx-*" "silero-vad/*"

下载参数说明

参数	默认值	说明
--model-id	MODELSCOPE_MODEL_ID 环境变量	必填，ModelScope 模型仓库 ID（如 username/repo_name）
--target-dir	../（当前上级目录）	模型落地存储目录（自动递归建立父目录）
--token	MODELSCOPE_API_TOKEN 环境变量	私有模型库需要提供具有读权限的 Token
--revision	master	分支名或 Tag 版本号
--allow-patterns	None	可选通配符，仅下载匹配的文件/子目录
--ignore-patterns	["model-down/**"]	忽略匹配的文件（默认自动忽略工具脚本自身）
--max-workers	8	并发下载线程数（充分利用服务器多核与大带宽）

---

4. 在部署流程与自动化脚本中的应用

部署 Debian 12 或 WSL Docker 集群时，无需通过 SCP 缓慢拷贝几 GB 的静态模型，在部署机上执行即可完成初始化：

# 安装 uv（若无）
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# 一键拉取模型到部署挂载目录
cd onnx-platform/models/model-down
uv run download.py --model-id wlf213/ai-voice-platform-models --target-dir /data/ai-voice/models

---

5. 上传与同步模型到 ModelScope (模型维护者)

将本地 onnx-platform/models 下的全量模型同步至 ModelScope 模型仓库作为备份或新版本发布。

步骤 A：获取 ModelScope Access Token

1. 登录 ModelScope 官网；
2. 进入 个人中心 -> 访问令牌 (Access Token)，获取一个具有写权限的令牌。

步骤 B：执行上传命令

# 方式 1：直接通过命令行参数执行
uv run upload.py --model-id wlf213/ai-voice-platform-models --token <your-token>

# 方式 2：通过环境变量提供 Token（推荐）
export MODELSCOPE_API_TOKEN="your-token"
uv run upload.py --model-id wlf213/ai-voice-platform-models

# 方式 3：通过统一 CLI 入口
uv run main.py upload --model-id wlf213/ai-voice-platform-models

# 方式 4：上传成功后自动清理本地 .ms_upload_cache 断点续传记录文件
uv run upload.py --model-id wlf213/ai-voice-platform-models --clean-cache

上传参数说明

参数	默认值	说明
--model-id	MODELSCOPE_MODEL_ID 环境变量	必填，ModelScope 模型仓库 ID，如 username/repo_name
--token	MODELSCOPE_API_TOKEN 环境变量	ModelScope Access Token（有写权限）
--models-dir	../（当前上级目录）	待上传的本地模型根目录（默认上传 onnx-platform/models）
--visibility	public	仓库不存在且自动创建时的可见性（public 或 private）
--commit-msg	feat: upload and sync ...	Git 提交信息
--max-workers	4	并发上传工作线程数
--clean-cache	False	上传成功后是否自动清理本地 .ms_upload_cache 缓存文件

提示：若远端仓库尚未创建，工具将自动根据 --visibility 设置为您新建公开或私有模型仓库。

注意：model-down/ 脚本工具已被内置忽略规则自动排除。如果您此前已误上传了 model-down，可通过以下任一方式从 ModelScope 远端清理：

1. 网页端删除：在 ModelScope 模型页面的【文件】列表中，找到 model-down 目录并点击删除图标；
2. Git 仓库删除：

   git clone https://oauth2:<YOUR_TOKEN>@www.modelscope.cn/wlf213/ai-voice-platform-models.git temp-repo
   cd temp-repo && git rm -rf model-down && git commit -m "chore: remove model-down" && git push
   cd .. && rm -rf temp-repo