Hugging Face国内访问配置：镜像站使用与网络限制说明

要解决国内直接访问 Hugging Face 官网不稳定、下载模型和数据集速度慢的问题，最实用的方案是配置镜像站。推荐首选 HF-Mirror（hf-mirror.com），通过设置环境变量即可让所有命令行工具自动切换镜像，实现快速下载。这一方案属于合法接入官方资源的途径，无需额外的网络调节步骤。

HF-Mirror 镜像站配置方法

HF-Mirror 提供两种主要使用方式。方法一：直接在网页端搜索模型或数据集，在文件列表中点击下载。方法二：通过 Hugging Face 官方命令行工具 huggingface-cli 配合环境变量。先安装依赖：pip install -U huggingface_hub。然后设置环境变量指向镜像：在 Linux 下执行 export HF_ENDPOINT=https://hf-mirror.com；在 Windows PowerShell 下执行 $env:HF_ENDPOINT = "https://hf-mirror.com"。设置后，所有 huggingface-cli 及 Python 库的下载请求都会自动转发至镜像站。

其他可选镜像平台

除 HF-Mirror 外，国内还有多个镜像平台可供选择。阿里魔搭社区（ModelScope）提供大量模型和数据集，部分可直接通过其 SDK 下载；Gitee AI、始智 AI（WiseModel）、GitCode AI 社区也提供了 Hugging Face 资源的同步。这些平台适合在 HF-Mirror 出现临时故障时作为备用，或者根据项目需要选择特定生态。

网络限制说明与合法访问

国内直接访问 huggingface.co 域名受网络环境影响，可能出现连接超时或速度极慢。使用镜像站是最直接的解决方案，因为镜像服务器部署在国内，无需改变原有代码或额外配置。Hugging Face 核心库（Transformers、Datasets、Tokenizers）的安装同样推荐在虚拟环境中进行：python -m venv huggingface_env 创建环境，然后 pip install transformers 等命令会自动根据环境变量选择镜像源。

环境变量永久配置建议

临时配置只在当前会话有效，若希望每次打开终端都自动使用镜像，可将 export HF_ENDPOINT 写入 Linux 的 ~/.bashrc 或 Windows 的系统环境变量。这样后续所有与 Hugging Face 相关的操作都会走镜像，减少手动设置步骤。

总之，对于有模型下载需求的国内开发者，配置 HF-Mirror 环境变量是投入产出比最高的优化方式。结合其他镜像平台，基本可以覆盖日常使用场景，无需依赖其他网络通道。