Windows下载HuggingFace数据集

0 初始化

初始化 Conda (仅首次需要)

如果在 PowerShell 中输入 conda activate 报错，请执行以下步骤：

1. 以管理员身份

   打开 PowerShell，执行：

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   

   (输入 Y 确认)

2. 初始化 Conda

   conda init powershell
   

3. 重启 PowerShell 使配置生效。

4. 随后新建一个 conda 虚拟环境，我这里已经有虚拟环境就不额外新建了。

   下面直接激活环境

   conda activate inpainting
   

5. 安装依赖

   在激活的 inpainting 环境中安装 Hugging Face 相关库：

   pip install huggingface_hub hf_transfer
   

   注意: hf_transfer 是一个用 Rust 编写的高速上传/下载插件，但在网络不稳定时建议禁用（见下文）。

1 下载数据集

以 ROSE-Dataset 数据集为例

由于数据集较大 (~19.2 GB) 且包含大量小文件，直接下载容易超时。以下提供两种方案，强烈推荐方案一。

1.1 方案一：使用 huggingface-cli (推荐，最稳定)

此方案通过单线程下载和镜像加速，最大程度避免连接超时。

步骤 1: 设置环境变量

在 PowerShell 中执行以下命令，设置镜像源并禁用不稳定的加速插件：

# 设置 Hugging Face 镜像站 (国内加速)
$env:HF_ENDPOINT = "https://hf-mirror.com"

# 禁用 hf-transfer (防止在网络波动时崩溃)
$env:HF_HUB_ENABLE_HF_TRANSFER = "0"

步骤 2: 执行下载命令

进入目标目录并执行下载：

# 进入数据集存放目录
cd D:/learn_DeepLearning/Dataset

# 执行下载命令
huggingface-cli download Kunbyte/ROSE-Dataset `
    --repo-type dataset `
    --local-dir ./ROSE-Dataset `
    --resume-download `
    --max-workers 4

参数详解：

• --repo-type dataset: 明确指定仓库类型为数据集（避免 401/404 错误）。
• --local-dir ./ROSE-Dataset: 指定本地保存路径。
• --resume-download: 关键参数，支持断点续传。如果中途断开，重新运行即可继续。
• --max-workers 1: 关键参数。限制为单线程下载。虽然速度看似较慢，但能极大提高在国内网络环境下的成功率，避免因并发过高导致的连接重置

同理，下载模型去掉指定数据集的参数即可，例如：

huggingface-cli download TencentARC/VideoPainter `
    --local-dir ./VideoPainter `
    --resume-download `
    --max-workers 4

步骤3：使用 PowerShell 循环自动重试

命令本身支持 --resume-download（断点续传），我们可以写一个简单的 PowerShell 脚本，让它在报错后自动等待几秒并重新运行，直到所有文件下载完成。

# 设置环境变量
$env:HF_ENDPOINT = "https://hf-mirror.com"
$env:HF_HUB_ENABLE_HF_TRANSFER = "0"

# 定义最大重试次数（防止无限死循环，设大一点即可）
$maxRetries = 200
$retryCount = 0

Write-Host "开始自动重试下载循环..." -ForegroundColor Green

while ($retryCount -lt $maxRetries) {
    Write-Host "----------------------------------------" -ForegroundColor Cyan
    Write-Host "正在执行第 $($retryCount + 1) 次下载尝试..." -ForegroundColor Yellow
    
    # 执行下载命令
    huggingface-cli download Kunbyte/ROSE-Dataset `
        --repo-type dataset `
        --local-dir ./ROSE-Dataset `
        --resume-download `
        --max-workers 4
    
    # 检查上一条命令的退出代码
    if ($LASTEXITCODE -eq 0) {
        Write-Host "下载成功完成！" -ForegroundColor Green
        break
    } else {
        $retryCount++
        Write-Host "下载中断或出错。等待 10 秒后自动重试... (剩余重试次数: $($maxRetries - $retryCount))" -ForegroundColor Red
        Start-Sleep -Seconds 10
    }
}

if ($retryCount -ge $maxRetries) {
    Write-Host "达到最大重试次数，请检查网络连接。" -ForegroundColor DarkRed
}

另外可以新开一个 PowerShell 窗口，每隔一段时间运行以下命令查看已下载文件的数量：

# 统计 ROSE-Dataset 目录下的文件总数
(Get-ChildItem -Recurse D:/learn_DeepLearning/Dataset/ROSE-Dataset -File).Count

1.2 方案二：使用 Git LFS (备选)

如果 huggingface-cli 无法使用，可尝试 Git LFS。

步骤 1: 安装与配置 Git LFS

git lfs install

步骤 2: 克隆数据集 (使用镜像)

cd D:\learn_DeepLearning\Dataset
git clone https://hf-mirror.com/datasets/Kunbyte/ROSE-Dataset.git

步骤 3: 拉取大文件

克隆完成后，文件仅为指针，需执行拉取：

cd ROSE-Dataset
# 如果拉取失败，尝试关闭 SSL 验证 (仅用于解决镜像站证书问题)
git config http.sslVerify false
git lfs pull