Docker容器中Huggingface Transformers无法加载自定义缓存模型的原因

问题原因 #

你遇到的权限错误，核心原因是**huggingface_hub库（transformers依赖的底层库）并未完全遵守TRANSFORMERS_CACHE变量**，它会优先读取HF_HOME环境变量，默认值是~/.cache/huggingface。如果容器内运行Python的用户没有对/home目录的写入权限（比如以非root用户运行但/home未挂载），它会尝试在根目录/下创建/.cache，而普通用户没有这个权限，就会触发PermissionError。

另外，你在Python代码中设置环境变量的时机太晚——import transformers之后再设置TRANSFORMERS_OFFLINE和TRANSFORMERS_CACHE，部分底层模块已经完成初始化，无法读取到新的环境变量值。

解决方案 #

1. 容器启动时全局设置环境变量 #

直接在启动容器时设置HF_HOME（覆盖huggingface_hub的默认缓存路径），同时设置TRANSFORMERS_OFFLINE，确保整个容器环境都生效：

docker run -it --rm \
  -v /tmp:/tmp:rw \
  -e HF_HOME="/tmp/models/huggingface_cache" \
  -e TRANSFORMERS_OFFLINE="1" \
  generic-container /bin/bash

2. 代码中提前设置环境变量 #

如果必须在代码中设置，一定要在import任何transformers模块之前设置环境变量：

from os import environ

# 先设置环境变量，再导入transformers
environ["TRANSFORMERS_OFFLINE"] = "1"
environ["HF_HOME"] = "/tmp/models/huggingface_cache"
environ["TRANSFORMERS_CACHE"] = "/tmp/models/huggingface_cache"

from transformers import pipeline

classifier = pipeline("zero-shot-classification", model="facebook/bart-large-mnli", cache_dir="/tmp/models/huggingface_cache")

3. 直接指定本地模型路径 #

如果自定义缓存目录下已经有完整的模型文件，可以直接传入模型的本地路径，完全绕过缓存机制：

from transformers import pipeline

# 假设模型文件存放在/tmp/models/huggingface_cache/models--facebook--bart-large-mnli目录下
classifier = pipeline(
    "zero-shot-classification",
    model="/tmp/models/huggingface_cache/models--facebook--bart-large-mnli",
    cache_dir="/tmp/models/huggingface_cache"
)

4. 确保缓存目录结构正确 #

自定义缓存目录下的模型需要符合huggingface的缓存结构：

/tmp/models/huggingface_cache/
└── models--facebook--bart-large-mnli
    ├── config.json
    ├── pytorch_model.bin
    ├── tokenizer_config.json
    └── vocab.json

如果结构不对，库会认为模型不存在，尝试重新下载（即使离线模式），进而触发缓存目录创建逻辑。

内容的提问来源于stack exchange，提问作者data-hungry