HuggingFace 使用指南

首先由于国内的墙的问题。我们不能直接从huggingface 下载模型。

所以只能手动下载，然后指定本地路径。或者直接配置镜像网站

（一）配置镜像网站

让当前终端会话中的 Hugging Face 使用 https://hf-mirror.com 作为资源下载地址。

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

为了永久使用镜像地址，可以将上述命令添加到用户的 ~/.bashrc或 ~/.zshrc文件中：

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

使配置生效

source ~/.bashrc

检测配置是否成功

import os

HF_ENDPOINT = os.getenv("HF_ENDPOINT", " https://huggingface.co")
print(HF_ENDPOINT)

其中，HF_ENDPOINT 是默认 Hugging Face 地址的配置项，默认值为 https://huggingface.co

如果设置了 HF_ENDPOINT 则会改为指定值 https://hf-mirror.com

找到 huggingface_hub/constants.py 文件的路径

python -c "import huggingface_hub; print(huggingface_hub.__file__)"

输出如下：

/home/heihe/.pyenv/versions/anaconda3-2024.10-1/envs/pytorch_env/lib/python3.12/site-packages/huggingface_hub/__init__.py

则来到该路径（huggingface_hub/）下，修改 constants.py 中的 HF_ENDPOINT为：HF_ENDPOINT = " https://hf-mirror.com"

（二）下载模型

以下是两种主要的下载方法：

transformers 库通过 Python 代码下载模型
通过 Hugging Face 的命令行工具 huggingface-cli 下载模型。

代码下载

使用 Python 代码下载模型，下载的模型会默认存储在本地缓存中。

pip install transformers

比如代码如下

from transformers import BertTokenizer, BertModel

# 下载并加载预训练的 BERT 模型和词汇表
tokenizer = BertTokenizer.from_pretrained('bert-base-uncased')
model = BertModel.from_pretrained('bert-base-uncased')

# 输出模型结构
print(model)

命令下载

安装 huggingface_hub ，用于与 Hugging Face 模型库进行交互的 Python 库和命令行工具，支持模型下载、上传、查询等操作

pip install -U huggingface_hub

秘钥为：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

huggingface-cli login

下载模型

huggingface-cli download --resume-download google-bert/bert-base-uncased --local-dir   ~/Machine_learning/models_chache/bert-base-uncased

google-bert/bert-base-uncased ：模型的标识符，它指向 Hugging Face 模型库中的具体模型。
--resume-download ：选项确保如果下载过程中断，可以继续下载。
--local-dir ：选项指定了模型存储的本地目录。

下载过程中断。解决方法：再次运行相同的命令即可

下载完成后，目录结构会类似以下内容：

local_models/
└── bert-base-uncased/
    ├── config.json                   分词器词汇表。
    ├── pytorch_model.bin       分词器词汇表。
    ├── tokenizer_config.json   分词器配置文件。
    ├── vocab.txt                      分词器词汇表。

tip

正常情况下所有下载的模型、分词器和其他资源都会存储在默认的缓存路径：~/.cache/huggingface

如果下载时使用命令：

huggingface-cli download bert-base-uncased --cache-dir ./huggingface_cache

则是指定 Hugging Face 的缓存路径，所有下载的模型、分词器和其他资源都会存储在这个缓存目录中

代码加载方式（无需显式指定路径）：

from transformers import BertModel
model = BertModel.from_pretrained("bert-base-uncased")  # 自动从缓存加载

总之：

--local-dir 不依赖缓存：使用 --local-dir 后，下载的模型不会自动复用缓存。需要显式指定路径并手动管理。
--cache-dir 替换默认缓存路径：设置后会影响所有 Hugging Face 模型的默认缓存位置。由系统自动管理，适合频繁使用。

如果要完全离线运行，可以设置环境变量 HF_DATASETS_OFFLINE 和 TRANSFORMERS_OFFLINE：

export HF_DATASETS_OFFLINE=1

export TRANSFORMERS_OFFLINE=1

这会让 Hugging Face 在加载模型时只查找本地缓存。

脚本下载

对于需要在自动化环境中（例如，CI/CD 管道）下载和管理模型的用户，

Hugging Face 提供了丰富的 API 接口。你可以通过 huggingface_hub 库进行更灵活的操作。

下载模型文件：

from huggingface_hub import hf_hub_download

# 下载模型文件并保存到本地
file_path = hf_hub_download(repo_id="bigscience/bloom-560m", filename="pytorch_model.bin", local_dir="bloom-560m")

print(f"Model file downloaded to: {file_path}")

repo_id 参数指定了模型库中的模型标识符。
filename 参数指定了要下载的具体文件（例如 pytorch_model.bin）。
local_dir 参数指定了保存文件的本地目录。

下载整个模型目录，而不仅仅是单个文件

from huggingface_hub import snapshot_download

# 下载整个模型的所有文件
local_dir = snapshot_download(repo_id="bigscience/bloom-560m", local_dir="bloom-560m")

print(f"Model directory downloaded to: {local_dir}")

snapshot_download 方法会下载模型的所有相关文件并存储在指定的本地目录中

（一）配置镜像网站​

（二）下载模型​

代码下载​

命令下载​

脚本下载​

（一）配置镜像网站

（二）下载模型

代码下载

命令下载

脚本下载