HuggingFace国内访问不了怎么解决？镜像站使用指南

HuggingFace 国内访问受限的现状与痛点

HuggingFace 作为全球开发者最信赖的 AI 模型托管平台，汇聚了海量的预训练模型与数据集。然而，受限于网络环境，国内用户在直接访问 huggingface.co 时，经常遭遇网页加载缓慢、图片无法显示甚至连接超时的问题。更为严重的是，大体积模型的下载往往中断，严重影响了研发进度。因此，掌握国内访问的解决方案至关重要。

对于依赖 AI 模型的开发者而言，无法快速获取模型意味着无法进行实验和部署。HF-Mirror 是 huggingface.co 的镜像站，其核心宗旨是致力于帮助国内 AI 开发者快速、稳定地下载模型和数据集。为了进一步提升下载体验，HF-Mirror 开发了专用下载工具 hfd。该工具基于 aria2 开发，具备强大的多线程下载能力，能够支持稳定高速下载不断线，有效解决了因网络波动导致的下载中断和速度慢的问题。

方法一：网页端直接下载模型文件

网页下载是门槛最低的方式，适合临时或少量文件的获取。用户只需访问 HF-Mirror 官网（hf-mirror.com），在站内搜索框输入模型名称进行查找。进入模型主页后，点击顶部的 "Files and Version" 标签页，这里列出了该模型的所有文件版本。用户可以直接点击文件链接进行下载，整个过程无需安装任何软件。

方法二：命令行工具 huggingface-cli 使用指南

对于需要批量下载或集成到自动化流程中的开发者，命令行工具 huggingface-cli 是最佳选择。首先，确保已安装依赖：执行 pip install -U huggingface_hub。随后，必须设置环境变量以指向镜像站：export HF_ENDPOINT=https://hf-mirror.com。最后，使用 huggingface-cli download --resume-download [repo_id] --local-dir [path] 命令开始下载。

在使用 huggingface-cli 下载受限仓库（Gated Repo）时，需添加 --token 参数。该参数的值必须在 HuggingFace 官网先登录账号并获取 Access Token，否则无法通过镜像站下载这些受保护的内容。

方法三：专用下载工具 hfd 的高效用法

HF-Mirror 还提供了更强大的专用工具 hfd，其基于 aria2，支持稳定高速下载不断线。具体操作步骤为：第一步，使用 wget https://hf-mirror.com/hfd/hfd.sh 下载脚本；第二步，设置环境变量 export HF_ENDPOINT=https://hf-mirror.com；第三步，执行下载命令 ./hfd.sh [repo_id]。

使用 hfd 工具时，如果下载受限仓库，记得添加 --hf_username 和 --hf_token 参数。这些参数用于在镜像站环境下进行身份认证，确保能够访问私有或受限的数据集资源。

遇到 Gated Repo（受限仓库）如何处理

在使用上述工具下载 Gated Repo（受限仓库）时，必须进行额外的认证配置。如果使用 huggingface-cli，需在命令中添加 --token 参数。如果使用 hfd 工具，则需要添加 --hf_username 和 --hf_token 参数。这些参数的值必须在 HuggingFace 官网先登录账号并获取 Access Token，否则无法通过镜像站下载这些受保护的内容。

常见风险与注意事项

使用镜像站虽然解决了访问问题，但也存在一些需要注意的风险和限制。首先，镜像站目前不支持登录操作，这意味着无法直接在镜像站管理账号或下载私有仓库。其次，对于部分数据集，其自带的下载脚本可能需要手动修改脚本内的地址才能生效。最后，Gated Repo 必须先在官网获取 Access Token，否则即使使用了镜像站也无法下载。

下一步怎么做

点下方按钮拿镜像站配置与下载命令。