Dev Solve

中文

English
日本語

中文

English
日本語

Appearance

相关文章

从 Hugging Face 下载模型的方法

Hugging Face 缓存目录配置 ​

当使用 Hugging Face Transformers 库时，默认情况下模型文件会存储在 ~/.cache/huggingface/hub 目录中。如果该目录所在的磁盘空间不足，你需要更改默认缓存目录的位置。本文将详细介绍多种配置方法，包括环境变量设置、代码内配置和符号链接等解决方案。

问题背景 ​

Hugging Face 生态系统（包括 Transformers、Datasets 等库）都会使用缓存来存储下载的模型和数据集。当默认缓存目录所在磁盘空间不足时，会导致以下问题：

  • 无法下载新的预训练模型
  • 训练过程因磁盘空间不足而中断
  • 多个 Hugging Face 组件可能分散存储，管理困难

解决方案 ​

方法一：使用 HF_HOME 环境变量（推荐） ​

设置 HF_HOME 环境变量是最全面和推荐的解决方案，因为它统一管理所有 Hugging Face 组件的缓存。

bash
# 临时设置（当前终端会话有效）
export HF_HOME=/path/to/your/cache/directory

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export HF_HOME="/path/to/your/cache/directory"' >> ~/.bashrc
source ~/.bashrc
powershell
# 临时设置（当前会话有效）
set HF_HOME=E:\huggingface_cache

# 永久设置（系统属性 > 环境变量）
# 或使用PowerShell：
[Environment]::SetEnvironmentVariable("HF_HOME", "E:\huggingface_cache", "User")
python
import os
os.environ['HF_HOME'] = '/path/to/your/cache/directory'
# 注意：必须在导入任何 Hugging Face 库之前设置

为什么推荐 HF_HOME？

HF_HOME 环境变量被所有 Hugging Face 库（Transformers、Datasets、Hub 等）识别，可以统一管理整个生态系统的缓存，而不仅仅是 Transformers 的模型缓存。

方法二：使用特定库的环境变量 ​

如果需要更细粒度的控制，可以为不同的 Hugging Face 组件设置单独的缓存目录：

bash
export HF_HOME=/my_drive/hf/misc          # 通用 Hub 缓存
export HF_DATASETS_CACHE=/my_drive/hf/datasets   # 数据集缓存
export TRANSFORMERS_CACHE=/my_drive/hf/models    # 模型缓存

版本兼容性说明

  • Transformers < v4.0.0：使用 TRANSFORMERS_CACHE
  • Transformers v4.0.0 - v4.36.0：TRANSFORMERS_CACHE 仍可用但会显示弃用警告
  • Transformers >= v4.36.0：推荐使用 HF_HOME，TRANSFORMERS_CACHE 将在 v5 中移除

方法三：代码内指定缓存目录 ​

对于特定模型加载操作，可以直接在代码中指定缓存位置：

python
from transformers import AutoModel, AutoTokenizer

cache_dir = "/path/to/your/cache/directory"

# 加载分词器
tokenizer = AutoTokenizer.from_pretrained(
    "bert-base-uncased", 
    cache_dir=cache_dir
)

# 加载模型
model = AutoModel.from_pretrained(
    "bert-base-uncased", 
    cache_dir=cache_dir
)

方法四：使用符号链接 ​

如果某些情况下环境变量设置不生效，可以使用符号链接：

bash
# 移动现有缓存（如果存在）
mv ~/.cache/huggingface /path/to/new/cache/directory

# 创建符号链接
ln -s /path/to/new/cache/directory ~/.cache/huggingface

或者仅为特定子目录创建符号链接：

bash
# 进入默认缓存目录
cd ~/.cache/huggingface

# 为 hub 和 modules 目录创建符号链接
ln -s /path/to/new/cache/hub hub
ln -s /path/to/new/cache/modules modules

方法五：Docker 环境配置 ​

在 Docker 容器中使用时，可以通过卷挂载和环境变量结合的方式：

bash
# 创建主机缓存目录
mkdir ~/my_hf_cache

# 运行容器并设置缓存
docker run -v ~/my_hf_cache:/app/cache \
           -e HF_HOME="/app/cache" \
           <image_name>

缓存目录优先级 ​

Hugging Face 库按照以下优先级确定缓存目录（从高到低）：

  1. HUGGINGFACE_HUB_CACHE 或 TRANSFORMERS_CACHE 环境变量
  2. HF_HOME 环境变量
  3. XDG_CACHE_HOME/huggingface（通常为 ~/.cache/huggingface）

最佳实践建议 ​

  1. 统一管理：使用 HF_HOME 统一管理所有 Hugging Face 组件的缓存

  2. 定期清理：定期清理不再需要的模型和数据集缓存

  3. 令牌安全：如果需要清除整个 HF_HOME 但想保留访问令牌，可以设置：

    bash
    export HF_TOKEN_PATH=$HOME/.huggingface_token

  4. 磁盘选择：将缓存目录设置在拥有足够空间的高速磁盘上

  5. 版本兼容：注意不同 Transformers 版本的环境变量变化

常见问题解答 ​

Q: 设置了环境变量但为什么不生效？ A: 确保在导入任何 Hugging Face 库之前设置环境变量，或者重启终端/IDE使永久设置生效。

Q: 如何检查当前使用的缓存目录？ A: 在 Python 中可以使用以下代码检查：

python
from transformers import TRANSFORMERS_CACHE
print(TRANSFORMERS_CACHE)

Q: 不同的 Hugging Face 库会共用缓存吗？ A: 是的，当使用 HF_HOME 时，Transformers、Datasets 等库会共享同一缓存体系结构，但不同类型的文件会存储在不同子目录中。

通过合理配置缓存目录，你可以有效管理磁盘空间，同时确保 Hugging Face 生态系统各组件正常工作。