程序员行莫

菜单

行莫
行莫
发布于 2025-12-03 / 39 阅读
0
0

通过 HF-Mirror 镜像访问 Hugging Face

#人工智能

通过 HF-Mirror 镜像访问 Hugging Face

引言

对于国内 AI 开发者来说，访问 Hugging Face 下载模型和数据集时经常会遇到网络不稳定、下载速度慢甚至无法访问的问题。HF-Mirror 是一个公益项目，专门为国内开发者提供稳定、快速的 Hugging Face 镜像服务，让模型和数据集下载变得简单高效。

本文将详细介绍如何使用 HF-Mirror 镜像站访问 Hugging Face，涵盖多种使用方式，从最简单的网页下载到命令行工具，帮助你在不同场景下都能顺利下载所需的模型和数据集。

什么是 HF-Mirror？

项目简介

HF-Mirror（https://hf-mirror.com/）是一个专门镜像 Hugging Face 的公益项目，致力于帮助国内 AI 开发者快速、稳定地下载模型和数据集。

核心优势

  1. 稳定可靠：提供稳定的镜像服务，避免直接访问 Hugging Face 时的网络问题
  2. 高速下载：针对国内网络环境优化，下载速度更快
  3. 完全免费：作为公益项目，免费为开发者提供服务
  4. 易于使用：支持多种使用方式，从网页到命令行，满足不同需求

适用场景

  • 下载 Hugging Face 上的预训练模型
  • 下载公开数据集
  • 在 Python 代码中使用 from_pretrained 加载模型
  • 使用 huggingface-cli 命令行工具下载资源

方法一：网页直接下载

使用步骤

这是最简单直接的方法，适合偶尔下载少量文件的情况。

  1. 访问镜像站

  2. 搜索模型或数据集

    • 在搜索框中输入模型名称（如 gpt2、bert-base-chinese 等）
    • 或搜索数据集名称（如 wikitext、squad 等）

  3. 进入模型/数据集主页

    • 点击搜索结果，进入详情页面

  4. 下载文件

    • 在 Files and Version 标签页中
    • 找到需要下载的文件
    • 点击文件名即可直接下载

适用场景

  • 下载单个或少量文件
  • 不熟悉命令行的用户
  • 临时性下载需求

注意事项

  • 对于大型模型（几 GB 到几十 GB），建议使用命令行工具，支持断点续传
  • 下载多个文件时，命令行工具更高效

方法二：使用 huggingface-cli

huggingface-cli 是 Hugging Face 官方提供的命令行工具，功能完善，支持断点续传。

安装依赖

首先需要安装 huggingface_hub 库：

pip install -U huggingface_hub

设置环境变量

设置环境变量后，huggingface-cli 会自动使用镜像站。

Linux / macOS

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

永久设置（推荐）：将上述命令添加到 ~/.bashrc 或 ~/.zshrc 文件中：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell

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

永久设置（推荐）：在 PowerShell 中执行：

[System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.com', 'User')

然后重启 PowerShell 或重新打开终端。

Windows CMD

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

下载模型

huggingface-cli download --resume-download gpt2 --local-dir gpt2

参数说明：

  • --resume-download：支持断点续传，如果下载中断可以继续
  • gpt2：要下载的模型名称
  • --local-dir gpt2：本地保存目录

禁用软链接（可选）：
如果希望下载路径下所见即所得，可以添加 --local-dir-use-symlinks False：

huggingface-cli download --resume-download gpt2 --local-dir gpt2 --local-dir-use-symlinks False

下载数据集

huggingface-cli download --repo-type dataset --resume-download wikitext --local-dir wikitext

参数说明：

  • --repo-type dataset：指定下载的是数据集而不是模型
  • wikitext：数据集名称
  • --local-dir wikitext：本地保存目录

适用场景

  • 需要下载大型模型或数据集
  • 需要断点续传功能
  • 经常使用命令行工具
  • 需要批量下载

方法三：使用 hfd 工具

hfd 是 HF-Mirror 站点开发的专用下载工具，基于成熟的 aria2 工具，可以做到稳定高速下载且不断线。

下载 hfd

Linux / macOS

wget https://hf-mirror.com/hfd/hfd.sh
chmod a+x hfd.sh

Windows

在 PowerShell 中执行：

Invoke-WebRequest -Uri https://hf-mirror.com/hfd/hfd.sh -OutFile hfd.sh

设置环境变量

与 huggingface-cli 相同，需要设置 HF_ENDPOINT 环境变量：

Linux / macOS

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

Windows PowerShell

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

下载模型

./hfd.sh gpt2

下载数据集

./hfd.sh wikitext --dataset

适用场景

  • 需要最稳定的下载体验
  • 下载超大型模型（几十 GB 以上）
  • 网络环境不稳定，需要自动重试

方法四：在 Python 代码中使用（非侵入式）

如果你在 Python 代码中使用 from_pretrained 等方法加载模型，可以通过设置环境变量来使用镜像站，无需修改代码。

设置环境变量

Linux / macOS

export HF_ENDPOINT=https://hf-mirror.com
python your_script.py

Windows PowerShell

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

Windows CMD

set HF_ENDPOINT=https://hf-mirror.com
python your_script.py

代码示例

from transformers import AutoModel, AutoTokenizer

# 设置环境变量后，from_pretrained 会自动使用镜像站
model = AutoModel.from_pretrained("bert-base-chinese")
tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")

在代码中设置（可选）

如果不想设置环境变量，也可以在代码中直接指定：

import os
# 在代码中设置镜像站
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

import torch
from transformers import CLIPModel, CLIPProcessor
from PIL import Image
from hpsv2.src.open_clip import get_tokenizer

# load model
if torch.cuda.is_available():
    device = "cuda"
else:
    device = "cpu"
print(f"Using device: {device}")

processor_name_or_path = "laion/CLIP-ViT-H-14-laion2B-s32B-b79K"
model_pretrained_name_or_path = './models/8y/ICT'

processor = CLIPProcessor.from_pretrained(processor_name_or_path, cache_dir="./models/")
preprocess_val = lambda img: processor(images=img, return_tensors="pt")["pixel_values"]

适用场景

  • 在 Python 脚本中加载模型
  • 使用 transformers、datasets 等库
  • 不想修改代码逻辑，只需切换下载源

注意事项

  • 有些数据集有内置的下载脚本，可能需要手动修改脚本内的地址
  • 建议优先使用环境变量方式，这样更灵活

常见问题解答

Q1: 有些项目需要登录，如何下载？

A：部分 Gated Repo（需要许可的仓库）需要登录并申请许可。为了保障账号安全，HF-Mirror 镜像站不支持登录功能。

解决方案：

  1. 前往 Hugging Face 官网：

  2. 获取 Access Token：

    • 在 Hugging Face 官网的个人设置中生成 Access Token
    • Token 格式类似：hf_xxxxxxxxxxxxxxxxxxxx

  3. 使用 Token 下载：

    huggingface-cli：

    huggingface-cli download --token hf_*** --resume-download meta-llama/Llama-2-7b-hf --local-dir Llama-2-7b-hf

    hfd：

    ./hfd.sh meta-llama/Llama-2-7b --hf_username YOUR_HF_USERNAME --hf_token hf_***

    Python 代码：

    from transformers import AutoModel

model = AutoModel.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    token="hf_***"  # 使用你的 token
)

Q2: 下载速度还是很慢怎么办？

A：可以尝试以下方法：

  1. 使用 hfd 工具：基于 aria2，支持多线程下载，速度更快
  2. 检查网络环境：确保网络连接稳定
  3. 使用代理：如果镜像站速度不理想，可以尝试使用代理访问原始站点

Q3: 环境变量设置后不生效？

A：检查以下几点：

  1. 确认环境变量已设置：

    • Linux/macOS: echo $HF_ENDPOINT
    • Windows PowerShell: $env:HF_ENDPOINT
    • Windows CMD: echo %HF_ENDPOINT%

  2. 重启终端：设置环境变量后需要重启终端才能生效

  3. 检查拼写：确保 URL 正确：https://hf-mirror.com

Q4: 如何验证是否使用了镜像站？

A：可以通过以下方式验证：

  1. 查看下载 URL：使用 huggingface-cli 下载时，观察输出的 URL 是否包含 hf-mirror.com
  2. 网络监控：使用网络监控工具查看实际连接的域名
  3. 下载速度：如果下载速度明显提升，说明很可能在使用镜像站

Q5: 镜像站和官方站有什么区别？

A：主要区别：

  1. 访问速度：镜像站针对国内网络优化，速度更快
  2. 登录功能：镜像站不支持登录，需要登录的模型需要先到官网申请许可
  3. 内容同步：镜像站会定期同步官方站内容，可能存在短暂延迟
  4. 功能完整性：大部分功能相同，但某些高级功能可能需要在官网使用

最佳实践建议

1. 选择合适的下载方式

  • 偶尔下载：使用网页直接下载
  • 经常下载：使用 huggingface-cli 或 hfd
  • 代码中使用：设置环境变量，使用 from_pretrained

2. 永久设置环境变量

建议将 HF_ENDPOINT 环境变量永久设置，这样每次使用都会自动使用镜像站，无需重复设置。

3. 使用断点续传

下载大型模型时，务必使用 --resume-download 参数，避免网络中断导致重新下载。

4. 合理选择下载目录

  • 使用 SSD 可以提高下载和读取速度
  • 确保有足够的磁盘空间
  • 建议为模型和数据集创建专门的目录

5. 处理 Gated Repo

如果需要下载需要许可的模型：

  1. 先在官网申请许可
  2. 获取 Access Token
  3. 使用 Token 通过镜像站下载

总结

HF-Mirror 为国内 AI 开发者提供了便捷的 Hugging Face 访问方案。通过本文介绍的四种方法，你可以根据实际需求选择最适合的方式：

  • 方法一（网页下载）：最简单，适合偶尔使用
  • 方法二（huggingface-cli）：功能完善，适合经常使用
  • 方法三（hfd）：最稳定，适合下载大型模型
  • 方法四（环境变量）：非侵入式，适合代码中使用

无论选择哪种方式，都建议永久设置 HF_ENDPOINT 环境变量，这样可以一劳永逸地享受镜像站带来的便利。

参考资源

ICT&HP提升高质量图像生成的奖励模型
ImageReward 文本到图像...

评论