Переменные окружения

huggingface_hub можно настроить с помощью переменных окружения.

Если вы не знакомы с переменными окружения, вот общие статьи о них для macOS и Linux и для Windows.

На этой странице описаны все переменные окружения, специфичные для huggingface_hub, и их назначение.

Все переменные окружения считываются при импорте huggingface_hub. Любые изменения, внесённые после этого, не будут учтены. Убедитесь, что вы задали переменные окружения до импорта huggingface_hub.

Универсальный

HF_INFERENCE_ENDPOINT

Для настройки базового URL inference api. Возможно, вам потребуется установить эту переменную, если ваша организация обращается к API Gateway, а не напрямую к inference api.

По умолчанию "/static-proxy?url=https%3A%2F%2Fapi-inference.huggingface.co".

HF_HOME

Для настройки того, где huggingface_hub будет локально хранить данные. В частности, в этой папке будут храниться ваш токен и кэш.

По умолчанию "~/.cache/huggingface", если не задан XDG_CACHE_HOME.

HF_HUB_CACHE

Чтобы настроить место локального кэширования репозиториев из Hub (моделей, наборов данных и spaces).

По умолчанию "$HF_HOME/hub" (например, "~/.cache/huggingface/hub" по умолчанию).

HF_XET_CACHE

Настройка расположения локального кэша шардов и данных для загрузки в Xet. Дополнительные сведения см. в разделе Кэширование Xet.

По умолчанию "$HF_HOME/xet" (например, "~/.cache/huggingface/xet" по умолчанию).

HF_ASSETS_CACHE

Для настройки того, где локально будут кэшироваться assets, создаваемые библиотеками нижнего уровня. К таким ресурсам могут относиться предобработанные данные, файлы, загруженные с GitHub, журналы и т. д.

По умолчанию "$HF_HOME/assets" (например, "~/.cache/huggingface/assets" по умолчанию).

HF_TOKEN

Для настройки токена доступа пользователя для аутентификации в Hub. Если задано, это значение перезапишет токен, сохранённый на машине (в $HF_TOKEN_PATH или "$HF_HOME/token", если первое не задано).

Для получения подробной информации об аутентификации обратитесь к этому разделу.

HF_TOKEN_PATH

Для настройки места, где huggingface_hub должен хранить User Access Token. По умолчанию — "$HF_HOME/token" (например, ~/.cache/huggingface/token по умолчанию).

HF_HUB_VERBOSITY

Установите уровень детализации логгера huggingface_hub. Должно быть одним из {"debug", "info", "warning", "error", "critical"}.

По умолчанию "warning".

Подробнее см. в справочнике по ведению журнала.

HF_HUB_ETAG_TIMEOUT

Целочисленное значение, определяющее количество секунд ожидания ответа сервера при получении последних метаданных из репозитория перед загрузкой файла. Если запрос завершается по таймауту, huggingface_hub по умолчанию использует файлы из локального кэша. Установка меньшего значения ускоряет рабочий процесс на машинах с медленным соединением, у которых файлы уже закэшированы. Более высокое значение гарантирует успешное выполнение вызова метаданных в большем числе случаев. По умолчанию — 10 с.

HF_HUB_DOWNLOAD_TIMEOUT

Целочисленное значение, определяющее количество секунд ожидания ответа сервера при загрузке файла. Если запрос завершается по таймауту, возникает TimeoutError. Увеличение этого значения полезно на машинах с медленным соединением. Меньшее значение позволяет процессу быстрее завершиться с ошибкой в случае полного отсутствия сети. По умолчанию — 10 секунд.

Xet

Другие переменные окружения Xet

• HF_HUB_DISABLE_XET
• HF_XET_CACHE
• HF_XET_HIGH_PERFORMANCE
• HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

HF_XET_CHUNK_CACHE_SIZE_BYTES

Эта переменная больше не оказывает никакого влияния. hf_xet больше не использует локальный кэш чанков для загрузок, и установка этой переменной не включает его. Подробности см. в xet-core#715.

HF_XET_SHARD_CACHE_SIZE_LIMIT

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

По умолчанию 16000000000 (16 ГБ).

HF_XET_NUM_CONCURRENT_RANGE_GETS

Эта переменная больше не используется. Начиная с hf_xet 1.3.0, параллельность загрузок контролируется адаптивно.

Логические значения

Следующие переменные окружения ожидают булево значение. Переменная будет считаться True, если её значение равно одному из {"1", "ON", "YES", "TRUE"} (без учёта регистра). Любое другое значение (или отсутствие значения) будет считаться False.

HF_DEBUG

Если задано, уровень журнала для логгера huggingface_hub устанавливается в DEBUG. Кроме того, все запросы, выполняемые библиотеками HF, будут записываться в журнал в виде эквивалентных команд cURL для упрощения отладки и воспроизведения.

HF_HUB_OFFLINE

Если установлено, HTTP-запросы к Hugging Face Hub не будут выполняться. При попытке загрузить файлы будут доступны только файлы из кэша. Если файл в кэше не обнаружен, будет выброшено исключение. Это полезно, если ваша сеть медленная и вам не важна последняя версия файла.

Если переменная окружения HF_HUB_OFFLINE=1 установлена и вы вызываете любой метод HfApi, будет выброшено исключение OfflineModeIsEnabled.

Примечание: даже если последняя версия файла уже кэширована, вызов hf_hub_download всё равно инициирует HTTP-запрос для проверки наличия новой версии. Установка переменной HF_HUB_OFFLINE=1 позволяет пропустить этот запрос, что ускоряет загрузку.

Если вы хотите проверить, включён ли офлайн-режим, вы можете использовать вспомогательную функцию is_offline_mode().

HF_HUB_DISABLE_IMPLICIT_TOKEN

Аутентификация не является обязательной для каждого запроса к Hub. Например, для получения сведений о модели "gpt2" аутентификация не требуется. Однако, если пользователь вошёл в систему, по умолчанию токен всегда отправляется, чтобы упростить взаимодействие с пользователем (избежать ошибки HTTP 401 Unauthorized) при доступе к частным или закрытым репозиториям. В целях конфиденциальности вы можете отключить это поведение, установив HF_HUB_DISABLE_IMPLICIT_TOKEN=1. В этом случае токен будет отправляться только для вызовов с «доступом на запись» (например, создание коммита).

Примечание: отключение неявной передачи токена может привести к неожиданным побочным эффектам. Например, если вы хотите получить список всех моделей на Hub, ваши приватные модели не будут отображены. Вам потребуется явно передать аргумент token=True в вашем скрипте.

HF_HUB_DISABLE_PROGRESS_BARS

Для длительных задач huggingface_hub по умолчанию отображает индикатор прогресса (с использованием tqdm). Вы можете отключить все индикаторы прогресса сразу, установив HF_HUB_DISABLE_PROGRESS_BARS=1.

HF_HUB_DISABLE_SYMLINKS

Если установлено, huggingface_hub никогда не будет создавать символьные ссылки в кэше. Вместо этого файлы будут дублироваться или перемещаться непосредственно в каталоги снимков. Это функция для опытных пользователей, переводящая каталог кэша в деградированный режим, при котором огромные файлы в итоге дублируются на вашем диске.

Примером использования является ситуация, когда общая сетевая папка (например, NAS) используется в качестве HF_HUB_CACHE на машинах с различными операционными системами. Символические ссылки, созданные в Linux, не всегда доступны в Windows, что приводит к ошибкам. Установка переменной HF_HUB_DISABLE_SYMLINKS=1 позволяет избежать этой проблемы ценой отказа от дедупликации данных на диске.

HF_HUB_DISABLE_SYMLINKS_WARNING

Если вы работаете в Windows, рекомендуется включить режим разработчика или запускать huggingface_hub с правами администратора. В противном случае huggingface_hub не сможет создавать символические ссылки в вашей кэш-системе. Вы сможете выполнять любые скрипты, но качество работы будет снижено, поскольку некоторые крупные файлы могут оказаться продублированными на вашем диске. Для предупреждения о таком поведении выводится соответствующее сообщение. Чтобы отключить это предупреждение, установите переменную HF_HUB_DISABLE_SYMLINKS_WARNING=1.

Для получения дополнительных сведений см. ограничения кэша.

HF_HUB_DISABLE_EXPERIMENTAL_WARNING

Некоторые функции huggingface_hub являются экспериментальными. Это означает, что вы можете их использовать, но мы не гарантируем их поддержку в будущем. В частности, мы можем обновить API или поведение таких функций без этапа устаревания. При использовании экспериментальной функции выводится предупреждение. Если вы готовы самостоятельно отлаживать возможные проблемы, связанные с экспериментальными функциями, вы можете установить HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1, чтобы отключить предупреждение.

Если вы используете экспериментальную функцию, пожалуйста, сообщите нам! Ваши отзывы помогут нам спроектировать и улучшить её.

HF_HUB_DISABLE_TELEMETRY

По умолчанию некоторые данные собираются библиотеками HF (transformers, datasets, gradio,..) для мониторинга использования, отладки проблем и помощи в приоритизации функций. Каждая библиотека определяет собственную политику (т.е. какой тип использования отслеживать), но базовая реализация происходит в huggingface_hub (см. send_telemetry).

Вы можете установить переменную окружения HF_HUB_DISABLE_TELEMETRY=1, чтобы глобально отключить телеметрию.

HF_HUB_DISABLE_UPDATE_CHECK

По умолчанию CLI hf при запуске проверяет наличие новой версии на PyPI (не чаще одного раза в 24 часа) и выводит в stderr однострочное жёлтое предупреждение, если новая версия доступна, рекомендуя выполнить hf update. Для dev- и pre-release-версий эта проверка уже не выполняется.

Также он проверяет (не чаще одного раза в 24 часа, исключительно локально), установлен ли навык hf-cli и сгенерирован ли он текущей версией, и при необходимости предлагает выполнить hf skills add / hf skills update. Проверка лишь выводит подсказку и никогда не изменяет ваши каталоги навыков.

Перед запуском установленной расширения CLI система проверяет (не чаще одного раза в 24 часа для каждого расширения), доступна ли более новая версия на GitHub, и при наличии предлагает выполнить hf extensions update <name>. Команда hf extensions list использует ту же проверку для своей колонки LATEST.

Установите HF_HUB_DISABLE_UPDATE_CHECK=1, чтобы пропустить эти запросы и отключить все подобные подсказки. Это полезно в офлайн-средах CI или если вы предпочитаете менее «шумный» вывод в терминале.

HF_HUB_DISABLE_XET

Установите, чтобы отключить использование hf-xet, даже если он доступен в вашем окружении Python. Это необходимо, так как hf-xet используется автоматически при обнаружении, и данный параметр позволяет явно отключить его применение. Если вы отключаете Xet, пожалуйста, рассмотрите возможность создания заявки с включением диагностической информации, чтобы помочь нам понять, почему Xet не работает у вас.

HF_HUB_ENABLE_HF_TRANSFER

Это устаревшая переменная окружения. Теперь, когда Hugging Face Hub полностью работает на базе хранилища Xet, все передачи файлов выполняются через бинарный пакет hf-xet. Он обеспечивает эффективную передачу данных с использованием стратегии дедупликации на основе чанков и бесшовно интегрируется с huggingface_hub. Это означает, что hf_transfer больше не может использоваться. Если вас интересует более высокая производительность, ознакомьтесь с разделом HF_XET_HIGH_PERFORMANCE

HF_HUB_DISABLE_SHARED_BLOBS

Установите значение 1, чтобы отключить общий хранилище блобов для кэша. По умолчанию успешно загруженные файлы Xet сохраняются в <CACHE_DIR>/blobs/<prefix>/<xet_hash> и подключаются через символьные ссылки в кэши репозиториев, благодаря чему идентичные файлы хранятся на диске только один раз для всех репозиториев и могут переиспользоваться без повторной загрузки. Эта оптимизация включена по умолчанию, но отключается, если Xet недоступен (например, если задано HF_HUB_DISABLE_XET=1) или если локально не поддерживаются символьные ссылки. В таких случаях система без предупреждений переходит на обычное локальное хранение в репозитории. Подробности см. в руководстве по кэшированию.

HF_XET_HIGH_PERFORMANCE

Настройте hf-xet на работу с повышенными параметрами, чтобы максимально использовать сетевые и дисковые ресурсы машины. Включение режима высокой производительности попытается насытить сетевую пропускную способность этого компьютера и задействовать все ядра ЦП для параллельной загрузки и выгрузки данных.

Рассмотрите это как аналог переменной окружения HF_HUB_ENABLE_HF_TRANSFER=1 из предыдущих версий, но применённой к hf-xet.

Чтобы узнать больше о преимуществах хранилища Xet и hf_xet, обратитесь к этому разделу.

HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

Эта переменная больше не используется. Начиная с hf_xet 1.3.0, файлы всегда записываются на локальный диск последовательно (см. модуль записи файлов в v1.3.0).

Устаревшие переменные окружения

Чтобы стандартизовать все переменные окружения в экосистеме Hugging Face, некоторые переменные были помечены как устаревшие. Хотя они по-прежнему работают, они больше не имеют приоритета над своими заменами. В таблице ниже перечислены устаревшие переменные и соответствующие им альтернативы:

Устаревшая переменная	Замена
HUGGINGFACE_HUB_CACHE	HF_HUB_CACHE
HUGGINGFACE_ASSETS_CACHE	HF_ASSETS_CACHE
HUGGING_FACE_HUB_TOKEN	HF_TOKEN

Из внешних инструментов

Некоторые переменные окружения не являются специфичными для huggingface_hub, но всё равно учитываются, если они заданы.

DO_NOT_TRACK

Логическое значение. Эквивалентно HF_HUB_DISABLE_TELEMETRY. Если установлено в true, телеметрия глобально отключается в экосистеме Python Hugging Face (transformers, diffusers, gradio и т. д.). Подробнее см. https://donottrack.sh/.

NO_COLOR

Логическое значение. Если установлено, CLI hf не будет выводить цвета ANSI. См. no-color.org.

XDG_CACHE_HOME

Используется только в том случае, если HF_HOME не задан!

Это способ по умолчанию для настройки того, куда на машинах с Linux следует записывать некритичные пользовательские данные (кэш).

Если HF_HOME не задан, домашним каталогом по умолчанию будет "$XDG_CACHE_HOME/huggingface" вместо "~/.cache/huggingface".

Update on GitHub