Hugging Face镜像——再也不用烦恼无法从Hugging Face下载模型和数据集了

在AI　开发的时候很多时候会从Hugging Face下载模型和数据集，但是直接访问会提升速度慢或者无法下载，解决方法就是使用Hugging Face 的中国镜像。

一、Hugging Face 中国镜像地址

镜像站地址为： https://hf-mirror.com。

这个镜像由国内开发者维护，支持模型、数据集、库文件的加速下载。其特点包括：

1. 域名替换：将 huggingface.co 替换为 hf-mirror.com 即可访问镜像资源。
2. 支持工具兼容：适配 huggingface-cli、transformers、datasets 等官方工具。

二、镜像设置方法

首先安装依赖，然后设置环境变量

pip install -U huggingface_hub

1. 全局环境变量设置

• Linux/macOS：

export HF_ENDPOINT=https://hf-mirror.com

• Windows（PowerShell）：

$env:HF_ENDPOINT = "https://hf-mirror.com"

设置后，所有通过 huggingface_hub 或 datasets 的下载请求将自动使用镜像。

2. 临时设置（Python脚本中）

在代码中动态设置环境变量：

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
from datasets import load_dataset
dataset = load_dataset("数据集名称")

三、datasets** 库使用镜像下载**

1. 直接加载数据集

通过 load_dataset 函数时，镜像会自动生效：

from datasets import load_dataset
dataset = load_dataset("neulab/conala", cache_dir="./本地路径")  # 指定缓存路径

2. 保存与加载本地缓存

• 保存数据集到本地：

dataset.save_to_disk("本地路径/数据集名称")  # 避免重复下载

• 从本地加载：

dataset = datasets.load_from_disk("本地路径/数据集名称")

3. 通过 huggingface-cli 下载数据集

安装工具并设置镜像后，可直接下载数据集：

huggingface-cli download --repo-type dataset --resume-download 数据集名称 --local-dir 本地路径

示例：

huggingface-cli download --repo-type dataset --resume-download glue --local-dir ./glue_data

四、其他注意事项

1. 代理冲突：使用镜像时需关闭科学上网工具，否则可能因网络代理冲突导致下载失败。
2. 登录模型下载：若需下载需授权的模型（如 gated 模型），需在命令中添加 --token hf_YourToken 参数。
3. 缓存管理：通过 --cache-dir 参数指定缓存路径，避免默认路径空间不足：

huggingface-cli download --cache-dir 自定义路径

五、手动下载替代方案

若需直接通过浏览器下载，访问镜像站并替换原链接中的域名：

• 原链接：https://huggingface.co/数据集名称
• 镜像链接：https://hf-mirror.com/数据集名称