Hub Python Library documentation
Переменные окружения
Переменные окружения
huggingface_hub можно настроить с помощью переменных окружения.
Если вы не знакомы с переменными окружения, вот общие статьи о них для macOS и Linux и для Windows.
На этой странице описаны все переменные окружения, специфичные для huggingface_hub, и их назначение.
Все переменные окружения считываются при импорте
huggingface_hub. Любые изменения, внесённые после этого, не будут учтены. Убедитесь, что вы задали переменные окружения до импортаhuggingface_hub.
Универсальный
HF_INFERENCE_ENDPOINT
Для настройки базового URL inference api. Возможно, вам потребуется установить эту переменную, если ваша организация обращается к API Gateway, а не напрямую к inference api.
По умолчанию "https://huggingface.co/static-proxy/api-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_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".