Hugging Face 仓库下载指南

核心要点

1. 区分仓库类型

• 模型 (model): 默认类型，用于下载预训练模型
• 数据集 (dataset): 必须指定 repo_type="dataset"，用于下载数据集

关键经验: 如果作为 model 下载失败（401错误），立即尝试作为 dataset 下载。

2. 使用镜像源

在中国大陆，使用镜像源可大幅提升下载速度：

python
展开代码
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

3. 下载方法优先级

1. 首选: huggingface_hub.snapshot_download() - 自动处理大文件和断点续传
2. 备选: git clone - 当 huggingface_hub 失败时使用

标准下载代码

python
展开代码
import os
from huggingface_hub import snapshot_download

# 设置镜像源（推荐）
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

# 下载仓库
repo_id = "username/repo_name"
local_dir = "/path/to/save"

try:
    # 先尝试作为 model 下载
    snapshot_download(
        repo_id=repo_id,
        local_dir=local_dir,
    )
except Exception:
    # 如果失败，尝试作为 dataset 下载
    snapshot_download(
        repo_id=repo_id,
        repo_type="dataset",
        local_dir=local_dir,
    )

常见问题解决

问题1: 401 错误 - Repository Not Found

原因: 仓库类型不匹配（model vs dataset）或需要认证 解决:

• 尝试添加 repo_type="dataset"
• 如果是私有仓库，设置 HF_TOKEN 环境变量

问题2: 网络连接失败

原因: 无法访问 huggingface.co 解决:

• 使用镜像源: os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
• 检查网络连接和防火墙设置

问题3: 认证失败

原因: 私有仓库需要 token 解决:

bash
展开代码
export HF_TOKEN=your_token_here
# 或
export HUGGINGFACE_HUB_TOKEN=your_token_here

完整示例脚本

python
展开代码
#!/usr/bin/env python3
import os
import sys
from huggingface_hub import snapshot_download

def download_hf_repo(repo_id: str, local_dir: str, use_mirror: bool = True):
    """下载 Hugging Face 仓库"""
    if use_mirror:
        os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
    
    os.makedirs(local_dir, exist_ok=True)
    
    # 先尝试作为 model
    try:
        snapshot_download(repo_id=repo_id, local_dir=local_dir)
        print(f"✅ 下载完成: {local_dir}")
        return
    except Exception as e:
        print(f"作为 model 下载失败，尝试作为 dataset...")
    
    # 再尝试作为 dataset
    try:
        snapshot_download(
            repo_id=repo_id,
            repo_type="dataset",
            local_dir=local_dir
        )
        print(f"✅ 下载完成: {local_dir}")
    except Exception as e:
        print(f"❌ 下载失败: {e}")
        sys.exit(1)

# 使用示例
if __name__ == "__main__":
    download_hf_repo(
        repo_id="hugxd/mmdu_val",
        local_dir="/mnt/data/datasets/mmdu_val"
    )

最佳实践

1. 总是先尝试 model，再尝试 dataset - 大多数仓库是 model 类型
2. 使用镜像源 - 在中国大陆环境下必须使用
3. 检查 token - 私有仓库需要提前设置
4. 使用 snapshot_download - 自动处理大文件和 Git LFS
5. 设置断点续传 - 大文件下载中断后可继续

快速命令

bash
展开代码
# 设置镜像源
export HF_ENDPOINT=https://hf-mirror.com

# 设置 token（如需要）
export HF_TOKEN=your_token

# 使用 Python 下载
python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='username/repo', local_dir='./repo')"

注意事项

• 数据集通常很大，确保有足够的磁盘空间
• 下载过程中会显示进度条，请耐心等待
• 如果下载中断，重新运行会自动续传
• 私有仓库必须提供有效的 token