modelscope-multi-proxy-download 0.1.3

Multi-proxy downloader for ModelScope model repos

modelscope-multi-proxy-download

多代理并发下载 ModelScope 模型的命令行工具。

安装

推荐直接从 PyPI 安装：

python3 -m pip install -U modelscope-multi-proxy-download

安装后可直接使用：

modelscope_multi_proxy_download --help

如果你在本地开发本项目，再使用源码安装：

python3 -m venv .venv
.venv/bin/python -m pip install -e .

快速使用指南

由于不同机器通常都可能遇到网络限速，推荐配合代理使用多路下载。

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --local_dir ./Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:8888

如果单个文件达到 5GB 及以上，且有多个可用 route，工具会自动把这个文件拆段后同时走多个 route 下载。 如果你想在较小文件上验证这条逻辑，可以临时把阈值调低：

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090 \
  --proxy http://127.0.0.1:10091 \
  --multi-route-min-size-gb 0

仅检查代理链路可用性：

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:8888 \
  --check-only

Windows 场景快速指南

场景 A：Linux 服务器要下载模型，Windows 主动连接 Linux 并共享本地代理

目标：让 Linux 上的 modelscope_multi_proxy_download 通过 Windows 代理出网。

1. Windows 安装并启动 proxy.py（监听 8888）

py -m pip install proxy.py
py -m proxy --hostname 0.0.0.0 --port 8888

2. Windows 主动连接 Linux，建立反向端口转发（把 Linux 上的 127.0.0.1:8888 映射到 Windows 的 127.0.0.1:8888）

ssh -N -R 8888:127.0.0.1:8888 linux_user@linux_ip

3. Linux 下载模型（访问 Linux 本地 127.0.0.1:8888，实际走 Windows 代理）

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:8888

场景 B：Windows 是要下载模型的机器，Linux 提供代理

目标：让 Windows 上的下载进程通过 Linux 代理出网。

1. Linux 启动 proxy.py（监听 8888）

python3 -m pip install proxy.py
python3 -m proxy --hostname 0.0.0.0 --port 8888

2. Windows 建立本地端口转发（把 Windows 的 127.0.0.1:8888 映射到 Linux 127.0.0.1:8888）

ssh -N -L 8888:127.0.0.1:8888 linux_user@linux_ip

3. 在 Windows 上运行下载命令（PowerShell 或 WSL），代理填本地 8888

modelscope_multi_proxy_download Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 --proxy http://127.0.0.1:8888

详细使用步骤

兼容 modelscope download MODEL_ID --local_dir ... 的核心用法，并新增：

• --proxy（可重复传入，值可为代理地址或代理列表文件）
• 默认自动包含 DIRECT 直连
• --local_dir 不传时默认取 model_id 最后一段
• --no-direct 一般不需要；仅在你明确希望“禁止直连、只允许代理”时再启用

示例 1：多个代理并发下载

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --local_dir Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090 \
  --proxy http://127.0.0.1:10091

示例 2：省略 --local_dir

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090

示例 3：只检测路由可达性

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090 \
  --check-only

示例 4：禁用直连（只走代理）

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090 \
  --proxy http://127.0.0.1:10091 \
  --no-direct

示例 5：使用代理列表文件

modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy ./proxies.txt

proxies.txt 示例：

http://127.0.0.1:10090
http://127.0.0.1:10091
DIRECT

参数说明

• model_id: 模型 ID，例如 Qwen/Qwen3-VL-30B-A3B-Instruct-FP8
• --local_dir <dir>: 下载目录，默认是 model_id 最后一段
• --revision <rev>: 分支、标签或提交
• --cache_dir <dir>: ModelScope 缓存目录
• --token <token>: 私有模型 token
• --allow-pattern <glob>: 仅下载匹配文件（可重复）
• --ignore-pattern <glob>: 忽略匹配文件（可重复）
• --proxy <proxy_or_file>: 代理地址或代理列表文件（可重复）
• --max-workers <n>: 并发 worker 数，默认等于可用路由数
• --no-direct: 排除直连路由
• --dry-run: 仅列出将下载文件
• --no-worker-progress: 关闭主进程实时任务进度区
• --no-route-fallback: 失败后不主动切换其他路由
• --no-multi-route-large-files: 关闭单大文件的多 route 分段加速
• --multi-route-min-size-gb <n>: 单文件达到该大小时启用多 route 分段下载，默认 5
• --multi-route-part-size-mb <n>: 单大文件分段大小，默认 160
• --check-proxies: 下载前检测每条路由
• --check-only: 仅检测并退出
• --check-url <url>: 路由检测目标 URL（默认 https://www.modelscope.cn）
• --check-timeout <sec>: 路由检测超时时间，默认 8

行为说明

• 每个 worker 进程固定绑定一个路由，按文件粒度并发下载。
• 当单个文件达到阈值且存在多个 route 时，会优先启用“单文件分段、多 route 并发”下载。
• DIRECT/NONE/NO_PROXY/LOCAL 会被识别为直连。
• 若某任务速度连续 60 秒低于 500KB/s，优先切换空闲代理，否则最多尝试 1 次断开重连。
• 失败文件最多自动重试 3 次。
• 有失败文件时最终返回非 0 退出码。