Как изменить каталог кеша Hugging Face

Установите HF_HOME, если хотите переместить домашний каталог Hugging Face и его стандартные кеши вместе. Установите HF_HUB_CACHE, если требуется перенести лишь загруженные репозитории Hub. Скопируйте существующий кеш при остановленных загрузках, сделайте переменную постоянной для использующего её процесса и проверьте сохраняемую модель до удаления.

HF_HOME и HF_HUB_CACHE не взаимозаменяемы

Hugging Face предоставляет несколько переменных кеша, поскольку локальные данные неоднородны. Настройки по умолчанию производны от HF_HOME, обычно ~/.cache/huggingface, если их не меняет XDG_CACHE_HOME.

• HF_HOME перемещает домашний каталог Hugging Face, используемый для локально сохранённого состояния токенов и стандартных подкаталогов кеша.
• HF_HUB_CACHE перемещает кеш репозиториев Hub — модели, наборы данных и Spaces, — расположенный по умолчанию в $HF_HOME/hub.
• HF_XET_CACHE управляет кешем блоков Xet, по умолчанию $HF_HOME/xet.
• HF_ASSETS_CACHE управляет ресурсами нижестоящих библиотек, по умолчанию $HF_HOME/assets.

Если проблема связана с хранилищем загруженных моделей, HF_HUB_CACHE — самое узкое переопределение. Если требуется один автономный корень Hugging Face на другом диске, HF_HOME проще для понимания, но помните, что за ним могут последовать учётные данные и иное состояние.

Проверьте активный путь до выбора места назначения

Используйте руководство по расположению кеша Hugging Face, чтобы проверить существующие переменные среды и переопределения библиотек. Блокнот, служба, контейнер и интерактивная оболочка могут наследовать разную среду. Путь, выведенный внутри реальной рабочей нагрузки, полезнее значения в оболочке, которой она не видит.

hf cache ls

# Python: просмотрите кеш Hub, определённый этой средой
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Остановите активные загрузки и задания обучения до копирования. Кеш содержит снимки и общие блобы; лучше копировать стабильное дерево, чем догонять новые ссылки, пока другой процесс его меняет.

Сделайте новый путь постоянным в нужной среде

Для разовой проверки установите переменную в текущей оболочке. Для обычной работы поместите её в конфигурацию среды, запускающую рабочую нагрузку: профиль оболочки, модуль службы, определение контейнера, ядро блокнота или средство запуска приложения.

# macOS или Linux: переместите только кеш репозиториев Hub
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Или переместите весь домашний каталог Hugging Face
export HF_HOME="/mnt/ai-cache/huggingface"

# Пользовательская переменная среды PowerShell
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Перезапустите приложение после изменения постоянной переменной. Библиотеки Python часто определяют константы кеша при импорте; изменение среды в середине процесса может не перенаправить уже начатую работу.

Скопируйте, укажите путь, проверьте, затем очищайте

1. Создайте место назначения в файловой системе, поддерживающей нужные рабочим нагрузкам ссылки и разрешения.
2. Скопируйте старый кеш без перестановки refs, snapshots или blobs.
3. Установите выбранную переменную среды и перезапустите рабочую нагрузку.
4. Запустите hf cache ls --revisions и подтвердите наличие ожидаемого репозитория и ревизии.
5. Загрузите одну известную модель автономно или используйте hf cache verify <repo> для сохраняемого репозитория.
6. Выполните небольшую новую загрузку и подтвердите изменение места назначения, а не источника.

Сохраняйте исходный кеш как минимум до одного успешного перезапуска. Если проверка не пройдена, восстановите прежнюю переменную и изучите копирование или разрешения. Не пытайтесь «исправить» неудачную миграцию ручным объединением двух частичных кешей.

Только после этого решайте, удалять ли старый кеш

После подтверждения места назначения старая копия может стать лишней. Если также требуется удалить устаревшие репозитории или ревизии в новом кеше, воспользуйтесь документированным процессом безопасной очистки кеша Hugging Face. Перемещение и обрезка — разные операции; их объединение затрудняет определение причины исчезновения модели.

Для незаменимых семейств моделей храните намеренно созданный архив вне активного кеша. Tensor Archive может сохранить связанные локальные артефакты, проверить и точно восстановить их. Он не изменяет кеш Hub и не выбирает ревизию, которую должен загрузить ваш код.

Связанные ответы о хранении

Если место занято несколькими средами, а не одним кешем, прочитайте, как организовать одну базовую модель с несколькими адаптерами. Для более общего решения о хранении или удалении используйте контрольный список локальной библиотеки моделей.