Hugging Face 国内镜像地址使用

前言

在 AI 开发过程中，Hugging Face 作为全球顶尖的开源模型与数据集社区，几乎是每个算法工程师的必备工具。然而国内用户在访问官方仓库时，常常遭遇网络超时、下载中断、速度缓慢等问题，尤其是动辄数 GB 的大模型文件，往往耗费数小时仍无法完成下载，严重影响开发效率。本文将详细介绍主流镜像平台的特性、使用方法。

一、国内主流 Hugging Face 镜像平台

1、 HF-Mirror（推荐首选）

官方地址：https://hf-mirror.com
核心特性：目前国内最主流的 Hugging Face 公益镜像站，由开源社区维护，具备高速下载、稳定性强、支持断点续传等优势，完美兼容 Hugging Face 官方工具链，涵盖绝大多数公开模型与数据集。
适用场景：日常开发、大模型下载、自动化部署等绝大多数场景。

2、阿里魔搭社区（ModelScope）

官方地址：https://modelscope.cn
核心特性：阿里云推出的一站式 AI 开发平台，不仅提供 Hugging Face 热门模型的镜像，还拥有丰富的国产特色模型，支持从模型训练、推理到部署的全流程服务，提供在线开发环境。
适用场景：需要国产模型资源、追求全流程开发支持的场景。

3、Gitee AI

官方地址：https://ai.gitee.com
核心特性：依托国内知名代码托管平台 Gitee 构建，模型资源丰富，与代码管理工作流兼容性好，适合国内开发者协作开发。
适用场景：团队协作开发、需要结合代码托管的场景。

4、始智 AI（WiseModel）

官方地址：https://wisemodel.cn
核心特性：模型资源覆盖广泛，访问速度稳定，界面简洁易用，提供模型预览、在线推理等功能。
适用场景：快速体验模型效果、中小型模型下载。

5、GitCode AI 社区

官方地址：https://ai.gitcode.com/models
核心特性：支持 Git 原生操作（如 git clone、git-lfs），与 Git 工作流兼容度高。
注意事项：模型更新频率略低于官方源，镜像资源相对较少，适合小规模模型研究场景。

二、HF-Mirror 镜像详细使用教程（首选方案）

HF-Mirror 因兼容性强、速度快成为首选方案，以下介绍多种使用方式，满足不同开发场景需求。

1. 环境变量配置（全局生效）

通过设置HF_ENDPOINT环境变量，让所有基于huggingface-hub的工具自动使用镜像源，是最便捷的全局配置方式。

（1）临时配置（当前会话有效）

Windows PowerShell：

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

Linux/macOS 终端：

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

（2）永久配置（长期生效）

Windows 系统：控制面板 → 系统和安全 → 系统 → 高级系统设置 → 环境变量；在 "用户变量" 或 "系统变量" 中点击 "新建"；变量名输入HF_ENDPOINT，变量值输入https://hf-mirror.com，点击确定；重启命令行工具或 IDE 生效。

Linux 系统（bash）：

# 编辑配置文件
vim ~/.bashrc
# 在文件末尾添加
export HF_ENDPOINT=https://hf-mirror.com
# 生效配置
source ~/.bashrc

macOS 系统（zsh）：

# 编辑配置文件
open -e ~/.zshrc
# 在文件末尾添加
export HF_ENDPOINT=https://hf-mirror.com
# 生效配置
source ~/.zshrc

2. 命令行工具下载（huggingface-cli）

（1）安装依赖工具

# 安装并更新工具库
pip install -U huggingface_hub

（2）下载模型 / 数据集示例

# 下载模型到指定目录，支持断点续传
huggingface-cli download --resume-download openai-community/gpt2-medium --local-dir ./models/gpt2-medium

# 下载数据集
huggingface-cli download datasets/insomnia7/SIU3R --local-dir ./datasets/SIU3R

3. Python 代码中使用（已设置环境变量可不再配置镜像参数）

（1）通过环境变量设置

import os
from transformers import AutoModel

# 设置镜像源（需在加载模型前执行）
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

# 正常加载模型，自动通过镜像下载
model = AutoModel.from_pretrained("bert-base-uncased")

（2）通过 huggingface-hub 库设置

from huggingface_hub import set_endpoint
from sentence_transformers import SentenceTransformer

# 直接设置镜像端点
set_endpoint("https://hf-mirror.com")

# 加载模型
model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')

（3）手动指定镜像 URL 下载

from huggingface_hub import snapshot_download

# 直接指定镜像地址下载
snapshot_download(
    repo_id="sentence-transformers/all-MiniLM-L6-v2",
    local_dir="./models/all-MiniLM-L6-v2",
    endpoint="https://hf-mirror.com"
)

4. 浏览器手动下载

对于少量文件需求，可直接通过浏览器访问HF-Mirror 官网，搜索目标模型或数据集，导航到对应文件后点击 "Download" 按钮下载，适合快速获取单个文件。

三、常见问题排查与解决方案

1. 镜像配置后仍访问官方源

检查环境变量是否生效：在命令行输入echo $HF_ENDPOINT（Linux/macOS）或$env:HF_ENDPOINT（Windows），确认输出https://hf-mirror.com。
重启命令行工具或 IDE，确保配置生效。
检查是否存在多个环境变量配置冲突，会话级配置优先级高于用户级和系统级。

2. 下载中断或速度缓慢

启用断点续传：添加--resume-download参数（huggingface-cli）。
更换网络环境：尝试使用手机热点避开企业 / 校园网限制。
升级工具版本：pip install -U huggingface_hub。

3. 模型加载失败（如 sentence-transformers）

方案 1：先下载到本地再加载，参考以下代码：

from sentence_transformers import SentenceTransformer
from huggingface_hub import snapshot_download

# 先下载模型到本地
snapshot_download(
    repo_id="sentence-transformers/all-MiniLM-L6-v2",
    local_dir="./models/all-MiniLM-L6-v2",
    endpoint="https://hf-mirror.com"
)

# 从本地加载
model = SentenceTransformer("./models/all-MiniLM-L6-v2")

方案 2：直接替换镜像 URL 尝试：

model = SentenceTransformer("https://hf-mirror.com/sentence-transformers/all-MiniLM-L6-v2")

4. 权限不足（403 Forbidden）

对于需要登录的私有模型，先执行登录命令：
```
huggingface-cli login
```
按照提示输入 Hugging Face 个人令牌（在官网个人设置中获取）。

五、总结

国内 Hugging Face 镜像服务为开发者提供了高效的资源获取渠道，其中 HF-Mirror 以其兼容性强、速度快的优势成为大多数场景的首选。通过环境变量配置、命令行工具或 Python 代码集成等方式，可轻松实现模型与数据集的高速下载。

在实际使用中，建议根据网络环境、资源类型和项目需求选择合适的方案：日常开发优先使用 HF-Mirror 全局配置；大模型下载结合多线程工具和断点续传；特殊资源则通过代理或云服务器中转解决。

文章版权归作者所有，未经允许请勿转载。

THE END