Mirror Download Skill

核心原则

一次失败，立即切换。不要重复 retry 原站，直接用镜像站完成任务。

第一步：快速连通性检测

在下载前，先用一条命令检测哪些源可用，最多等 4 秒：

python3 - \x3C\x3C 'EOF'
import subprocess, time, sys

def ping(host, timeout=4):
    try:
        r = subprocess.run(
            ['curl', '-s', '-o', '/dev/null', '-w', '%{http_code}',
             '--connect-timeout', '3', '--max-time', str(timeout), f'https://{host}'],
            capture_output=True, text=True, timeout=timeout+1
        )
        ok = r.stdout.strip() not in ['000', '']
        return ok
    except:
        return False

sources = {
    'HuggingFace 原站': 'huggingface.co',
    'hf-mirror':        'hf-mirror.com',
    '魔搭社区':          'modelscope.cn',
    'GitHub 原站':       'github.com',
    'GitCode':          'gitcode.com',
}

print("=== 连通性检测 ===")
available = []
for name, host in sources.items():
    ok = ping(host)
    status = "✓ 可用" if ok else "✗ 不可达"
    print(f"  {name:12s} ({host}): {status}")
    if ok:
        available.append(name)

print(f"\
可用源: {', '.join(available) if available else '全部不可达'}")
EOF

根据检测结果，选择第一个可用的镜像进入对应下载流程。

第二步：HuggingFace 模型/数据集下载

方案 A：hf-mirror（推荐首选）

通过 HF_ENDPOINT 环境变量一键切换，无需修改任何代码：

# 方式1: 命令行临时切换（推荐）
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download \
    \x3C模型ID> \
    --local-dir \x3C本地目录> \
    --local-dir-use-symlinks False

# 方式2: Python 代码中切换
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

from huggingface_hub import snapshot_download
snapshot_download(
    repo_id='\x3C模型ID>',          # 例如: "Qwen/Qwen2-7B-Instruct"
    local_dir='\x3C本地目录>',
    ignore_patterns=['*.bin'],    # 可选: 跳过旧格式权重，只下载 safetensors
)

安装 huggingface_hub（若未安装）：

pip install huggingface_hub -q

方案 B：魔搭社区（ModelScope）

适合 Qwen、ChatGLM、通义系列等国产模型，命名与 HF 基本一致：

pip install modelscope -q

from modelscope import snapshot_download

# 模型ID映射规则（见下方参考表）
model_dir = snapshot_download(
    model_id='\x3CModelScope模型ID>',  # 例如: "qwen/Qwen2-7B-Instruct"
    cache_dir='\x3C本地目录>',
)
print(f"下载完成: {model_dir}")

HuggingFace → ModelScope 常用映射：

⚠️ 若不确定 ModelScope ID，用 search_modelscope 脚本查找（见下方）

方案 C：手动 wget/aria2 直接下载（适合单文件）

# 使用 hf-mirror 直接下载单个文件
wget "https://hf-mirror.com/\x3Cowner>/\x3Cmodel>/resolve/main/\x3Cfilename>" \
     -O \x3C本地文件名>

# 使用 aria2c 多线程加速（推荐大文件）
aria2c -x 16 -s 16 \
    "https://hf-mirror.com/\x3Cowner>/\x3Cmodel>/resolve/main/model.safetensors" \
    -o model.safetensors

第三步：GitHub 仓库下载

方案 A：GitCode 镜像

# 将 github.com 替换为 gitcode.com
# 原始: git clone https://github.com/owner/repo.git
git clone https://gitcode.com/mirrors/owner/repo.git

# 或者设置代理（已有VPN/代理时）
git config --global http.proxy http://127.0.0.1:7890
git clone https://github.com/owner/repo.git

方案 B：加速下载（ghproxy）

# 使用 ghfast.top 代理（速度快）
git clone https://ghfast.top/https://github.com/owner/repo.git

# 下载 Release 文件
wget "https://ghfast.top/https://github.com/owner/repo/releases/download/v1.0/file.zip"

方案 C：仅下载 Release 压缩包（不 clone）

# 直接下载 tarball（避免 .git 历史，更快）
wget "https://ghfast.top/https://github.com/owner/repo/archive/refs/heads/main.tar.gz" \
     -O repo.tar.gz
tar xzf repo.tar.gz

快速诊断脚本

遇到下载报错时，运行此脚本自动诊断并给出推荐方案：

python3 /path/to/mirror-download/scripts/diagnose.py "\x3C模型或仓库ID>"

参考 scripts/diagnose.py 和 scripts/mirror_download.py。

下载后验证

# 验证模型文件完整性
import os, glob

def check_download(model_dir):
    files = glob.glob(f"{model_dir}/**", recursive=True)
    total_size = sum(os.path.getsize(f) for f in files if os.path.isfile(f))
    print(f"文件数量: {len([f for f in files if os.path.isfile(f)])}")
    print(f"总大小: {total_size / 1024**3:.2f} GB")
    
    # 检查关键文件
    for name in ['config.json', 'tokenizer_config.json']:
        path = os.path.join(model_dir, name)
        print(f"{'✓' if os.path.exists(path) else '✗'} {name}")

check_download("\x3C模型目录>")

决策流程

用户要下载模型/仓库
       │
       ▼
  运行连通性检测
       │
  ┌────┴────┐
  │         │
HF可达    HF不可达
  │         │
直接下载  ┌──┴──────────┐
       hf-mirror     魔搭社区
       可达?          可达?
         │              │
        用它           用它
                        │
                   两者都不可达
                        │
                  检查 GitHub/GitCode
                  或提示用户检查网络

常见报错 → 解决方案速查

参考文件

• scripts/diagnose.py — 自动连通性检测 + 推荐下载方案
• scripts/mirror_download.py — 一键镜像下载封装函数
• references/modelscope_id_map.md — 详细的 HF→MS 模型ID映射表