在国内服务器或实验室环境中直接访问 Hugging Face 经常会遇到如下错误Connection reset by peer或者ReadTimeoutError又或者Returning existing local_dir ... as remote repo cannot be accessed这是由于网络原因导致服务器无法直接访问 Hugging Face 官方站点而不是代码本身存在问题。本文介绍如何通过Hugging Face 镜像HF Mirror来快速下载模型和数据集。一、为什么需要使用镜像很多国内高校、实验室服务器无法正常连接https://huggingface.co例如使用snapshot_download()下载数据集时fromhuggingface_hubimportsnapshot_download snapshot_download(repo_idzhuhu00/hm3d,repo_typedataset,local_dir/data/datasets/hm3d)可能出现Connection reset by peer或者remote repo cannot be accessed这说明程序无法连接到 Hugging Face 官方服务器。二、HF Mirror 简介HF Mirror 是 Hugging Face 的国内镜像站可以加速模型和数据集下载。使用镜像后huggingface.co ↓ hf-mirror.com下载速度通常会明显提升同时解决无法访问的问题。三、方法一临时使用镜像推荐只对当前终端生效。Linux/macOSexportHF_ENDPOINThttps://hf-mirror.comWindows PowerShell$env:HF_ENDPOINThttps://hf-mirror.com然后正常运行下载程序即可python download.py或者HF_ENDPOINThttps://hf-mirror.com python download.py这种方式不会修改系统配置非常适合临时下载。四、方法二在 Python 中设置镜像如果希望代码本身就使用镜像可以在程序开始加入importos os.environ[HF_ENDPOINT]https://hf-mirror.com例如importosfromhuggingface_hubimportsnapshot_download os.environ[HF_ENDPOINT]https://hf-mirror.comsnapshot_download(repo_idzhuhu00/hm3d,repo_typedataset,local_dir/data/XXX/datasets/hm3d)这样无论在哪里运行都默认使用镜像。五、方法三永久配置镜像如果以后经常使用 Hugging Face可以永久设置环境变量。编辑vim~/.bashrc或者nano~/.bashrc在最后添加exportHF_ENDPOINThttps://hf-mirror.com保存后执行source~/.bashrc检查是否生效echo$HF_ENDPOINT如果输出https://hf-mirror.com说明配置成功。以后所有使用huggingface_hub的程序都会自动走镜像。六、下载模型示例例如下载 Qwen 模型fromhuggingface_hubimportsnapshot_download snapshot_download(repo_idQwen/Qwen2.5-7B-Instruct,local_dir./Qwen2.5-7B-Instruct)由于已经配置了镜像无需修改代码。七、下载数据集示例例如下载 HM3D 数据集fromhuggingface_hubimportsnapshot_download snapshot_download(repo_idzhuhu00/hm3d,repo_typedataset,local_dir/data/XXX/datasets/hm3d)下载完成后目录类似hm3d/ ├── hm3d-train-glb-v0.2.tar ├── hm3d-train-habitat-v0.2.tar ├── hm3d-val-glb-v0.2.tar ├── hm3d-minival-glb-v0.2.tar └── ...八、下载单个文件如果数据集较大可以只下载需要的文件。例如fromhuggingface_hubimporthf_hub_download hf_hub_download(repo_idzhuhu00/hm3d,repo_typedataset,filenamehm3d-minival-glb-v0.2.tar,local_dir/data/XXX/datasets/hm3d)相比下载整个仓库这种方式更加节省时间和磁盘空间。九、验证镜像是否生效可以执行echo$HF_ENDPOINT输出https://hf-mirror.com或者在 Python 中importosprint(os.getenv(HF_ENDPOINT))输出https://hf-mirror.com说明程序已经使用 HF Mirror。十、常见问题1. 仍然提示Connection reset by peer首先确认环境变量是否生效echo$HF_ENDPOINT如果为空请重新设置exportHF_ENDPOINThttps://hf-mirror.com2. Python 中没有使用镜像确保设置环境变量的代码位于导入和调用下载函数之前importos os.environ[HF_ENDPOINT]https://hf-mirror.comfromhuggingface_hubimportsnapshot_download3. 服务器无法联网如果服务器无法访问外网即使配置镜像也无法下载。可以先测试curlhttps://hf-mirror.com如果能够正常返回网页内容则说明镜像可访问。4. 镜像速度仍然较慢对于几十 GB 的模型或数据集建议使用有线网络使用校园网或稳定的公网环境下载完成后做好备份避免重复下载。总结对于国内开发者而言使用HF Mirror是下载 Hugging Face 模型和数据集最简单、最稳定的方法。推荐的使用方式如下临时使用推荐exportHF_ENDPOINThttps://hf-mirror.comPython 中设置importos os.environ[HF_ENDPOINT]https://hf-mirror.com永久配置在~/.bashrc中加入exportHF_ENDPOINThttps://hf-mirror.com配置完成后无需修改snapshot_download()、hf_hub_download()等下载代码即可自动通过镜像访问 Hugging Face大幅提升国内环境下模型和数据集的下载成功率。