Metadata-Version: 2.4
Name: modelscope-multi-proxy-download
Version: 0.1.1
Summary: Multi-proxy downloader for ModelScope model repos
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: modelscope
Requires-Dist: requests

# modelscope-multi-proxy-download

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

## 安装

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

安装后命令为：

```bash
.venv/bin/modelscope_multi_proxy_download --help
```

## 快速使用指南

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

```bash
.venv/bin/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
```

仅检查代理链路可用性：

```bash
.venv/bin/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-download` 通过 Windows 代理出网。

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

```powershell
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`）

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

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

```bash
.venv/bin/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）

```bash
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`）

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

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

```powershell
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：多个代理并发下载

```bash
.venv/bin/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`

```bash
.venv/bin/modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090
```

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

```bash
.venv/bin/modelscope_multi_proxy_download \
  Qwen/Qwen3-VL-30B-A3B-Instruct-FP8 \
  --proxy http://127.0.0.1:10090 \
  --check-only
```

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

```bash
.venv/bin/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：使用代理列表文件

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

`proxies.txt` 示例：

```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`: 失败后不主动切换其他路由
- `--check-proxies`: 下载前检测每条路由
- `--check-only`: 仅检测并退出
- `--check-url <url>`: 路由检测目标 URL（默认 `https://www.modelscope.cn`）
- `--check-timeout <sec>`: 路由检测超时时间，默认 `8`

### 行为说明

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