Использование Xet Storage

Python

Чтобы получить версию huggingface_hub с поддержкой Xet, просто установите последнюю версию:

pip install -U huggingface_hub

Начиная с версии huggingface_hub 0.32.0, это также установит hf_xet. Пакет hf_xet интегрирует huggingface_hub с xet-core, клиентом на Rust для бэкенда Xet.

Если вы используете библиотеки transformers или datasets, они уже используют huggingface_hub. При условии, что версия huggingface_hub >= 0.32.0, никаких дополнительных действий не требуется.

Если установлены версии huggingface_hub >= 0.30.0 и < 0.32.0, hf_xet необходимо установить явно:

pip install -U hf-xet

И всё! Теперь вы получаете преимущества дедупликации Xet как при загрузке, так и при скачивании. Члены команды, использующие версию huggingface_hub < 0.30.0, по-прежнему смогут загружать и скачивать репозитории благодаря обратной совместимости, обеспечиваемой LFS-мостом.

Чтобы ознакомиться с более подробной документацией по использованию, обратитесь к документации huggingface_hub по:

• Загрузка
• Скачать
• Управление кэшем hf_xet

Git

Пользователи Git могут воспользоваться преимуществами Xet, скачав и установив расширение Git Xet. После установки достаточно использовать стандартные рабочие процессы для управления репозиториями Hub с помощью Git — никаких дополнительных изменений не требуется.

Предварительные требования

Установите Git и Git LFS.

Установка на macOS или Linux (amd64 или aarch64)

Установите с помощью скрипта установки, выполнив следующую команду в терминале (требуется curl и unzip):

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh

Или установите с помощью Homebrew:

brew install git-xet
git xet install

Для проверки установки выполните:

git xet --version

Windows (amd64)

С помощью winget:

winget install git-xet

С использованием установщика:

• Скачайте git-xet-windows-installer-x86_64.zip (доступен здесь) и распакуйте архив.
• Запустите файл установщика msi и следуйте инструкциям на экране.

Ручная установка:

• Скачайте git-xet-windows-x86_64.zip (доступен здесь) и распакуйте архив.
• Разместите извлечённый git-xet.exe в каталоге, указанном в переменной PATH.
• Выполните git xet install в терминале.

Для проверки установки выполните:

git xet --version

Использование Git Xet

После установки на вашу платформу использование Git Xet сводится к стандартным Git-процессам Hub.

Убедитесь, что все предварительные требования установлены и настроены, следуйте инструкциям по настройке для работы с репозиториями на Hub, затем зафиксируйте изменения и push на Hub:

# Create any files you like! Then...
git add .
git commit -m "Uploading new models"  # You can choose any descriptive message
git push

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

Удаление на macOS или Linux

С помощью Homebrew:

git xet uninstall
brew uninstall git-xet

Если вы использовали скрипт установки (для MacOS или Linux), выполните следующую команду в терминале:

git xet uninstall
sudo rm $(which git-xet)

Удаление в Windows

Если вы использовали winget:

winget uninstall git-xet

Если вы использовали установщик:

• Перейдите в раздел Параметры -> Приложения -> Установленные приложения
• Найдите «Git-Xet».
• Выберите пункт «Uninstall» в контекстном меню.

Если вы установили вручную:

• Выполните git xet uninstall в терминале.
• Удалите файл git-xet.exe из того места, где он был изначально размещён.

Рекомендации

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

При загрузке или скачивании с помощью Python:

• Убедитесь, что hf_xet установлен: хотя Xet сохраняет обратную совместимость с устаревшими клиентами, оптимизированными для Git LFS, интеграция hf_xet с huggingface_hub обеспечивает оптимальную производительность на основе чанков и более быструю работу с большими файлами.
• Адаптивная конкурентность включена по умолчанию: hf_xet автоматически регулирует количество параллельных потоков передачи в зависимости от текущих условий сети — настройка не требуется. Параметры по умолчанию обеспечивают полную загрузку большинства сетевых каналов без какой-либо оптимизации.
• Размер буферов загрузки масштабируется в зависимости от системной памяти: начиная с версии hf_xet 1.7.0, размер буферов загрузки определяется исходя из доступной памяти для hf_xet, включая ограничения памяти контейнера. Небольшие контейнеры используют меньше памяти для загрузки, а крупные машины — больше, при этом настраивать ничего не требуется. См. Буферы загрузки.
• Расширенная настройка: для тонкого управления переменные HF_XET_FIXED_DOWNLOAD_CONCURRENCY и HF_XET_FIXED_UPLOAD_CONCURRENCY позволяют зафиксировать уровень параллелизма, минуя адаптивный контроллер. Полный список параметров см. в разделе переменные окружения библиотеки hf_xet.

При загрузке или скачивании в Git или Python:

• Используйте частые инкрементальные коммиты: дедупликация на уровне чанков в Xet позволяет безопасно выполнять инкрементальные обновления моделей или наборов данных. Загружаются только изменённые чанки, поэтому частые коммиты быстры и экономны по месту хранения.
• Будьте конкретны в .gitattributes: при определении шаблонов для Xet или LFS используйте точные расширения файлов (например, *.safetensors, *.bin), чтобы избежать ненужного маршрутизации небольших файлов через хранилище больших файлов.
• Приоритизируйте доступ сообщества: Xet значительно повышает эффективность и масштабируемость передачи больших файлов. Вместо того чтобы структурировать репозиторий для уменьшения его общего размера (или размера отдельных файлов), организуйте его так, чтобы соавторы и пользователи сообщества могли легко ориентироваться в нём и получать нужный им контент.

Загрузка через прокси или межсетевой экран

Начиная с версии hf_xet 1.8.0, при загрузке данных можно отправлять их напрямую в Amazon S3, а не только через сервис хранения Xet. Hub самостоятельно решает для каждой загрузки, использовать ли прямую загрузку, и постепенно включает эту функцию. Загрузка данных (downloads) остаётся без изменений.

Если ваша сеть ограничивает исходящий трафик, разрешите эти имена хостов (HTTPS, порт 443) в дополнение к тем, что перечислены в разделе Загрузка за прокси или файрволом:

Эти имена хостов не находятся в доменах hf.co или huggingface.co, поэтому добавление этих суффиксов в белый список их не покрывает.

Если hf_xet не может установить соединение с S3, он повторяет попытку прямой загрузки, а затем отправляет эти данные через сервис хранения Xet. Загрузка всё равно завершается, но может занимать значительно больше времени, так как каждый блок сначала проходит через цикл повторных попыток. В журнале hf_xet при этом выводится сообщение Upload grant URL unreachable, falling back to legacy xorb upload path (may be slower). Если вы не можете разрешить хосты S3, установите HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD=1, чтобы отключить прямые загрузки.

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

Обе библиотеки hf_xet и Git Xet работают на базе xet-core, который настраивается через переменные окружения. В таблицах ниже перечислены отдельные переменные для тонкой настройки. Большинству пользователей не потребуется изменять ни одну из них — значения по умолчанию настроены так, чтобы автоматически обеспечивать максимальную пропускную способность большинства сетевых каналов.

HF_XET_HIGH_PERFORMANCE=1 — это удобный флаг, который одновременно настраивает несколько параметров (ограничения параллелизма, размеры буферов и лимиты параллельных файлов). Он предназначен для машин с высокой пропускной способностью и быстрым диском. Начиная с версии hf_xet 1.7.0, размеры буферов, которые он устанавливает, основаны на памяти, доступной для hf_xet (см. Download Buffers), поэтому ему больше не требуется 64 ГБ ОЗУ, и любая переменная, установленная вами вручную, имеет приоритет над этим флагом. В более ранних версиях используйте его только на машинах с ОЗУ не менее 64 ГБ.

Общие

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

Адаптивная конкурентность

По умолчанию xet-core использует адаптивную конкурентность — динамически настраивает параллелизм в зависимости от текущих сетевых условий. Это продвинутые настройки, которые в большинстве случаев не потребуются. Переменные ниже управляют поведением адаптивного контроллера:

Чтобы зафиксировать уровень параллелизма (обойдя адаптивный контроллер), используйте удобные псевдонимы HF_XET_FIXED_UPLOAD_CONCURRENCY и HF_XET_FIXED_DOWNLOAD_CONCURRENCY. Они устанавливают начальное, минимальное и максимальное значения параллелизма в одно и то же число.

Сеть и повторные попытки

Передача данных

Загрузка буферов

Эти параметры управляют использованием памяти во время загрузок.

Начиная с версии hf_xet 1.7.0, значения по умолчанию для трех переменных DOWNLOAD_BUFFER определяются на основе доступной памяти hf_xet. Это объем оперативной памяти машины или лимит памяти контейнера, если он меньше. Каждое значение по умолчанию представляет собой долю этой памяти, ограниченную минимальным и максимальным значениями, указанными в таблице. В режиме HP используется удвоенная доля при тех же минимальных и максимальных значениях. Например, контейнер с лимитом 4 ГБ получит буфер примерно 256 МБ с лимитом 1 ГБ, а машина с 32 ГБ получит примерно тот же буфер 2 ГБ и лимит 8 ГБ, что и в предыдущих версиях.

Ранее выпущенные версии, а также любые версии, не способные определить доступный объём памяти, используют фиксированные значения по умолчанию: 2gb, 512mb и 8gb (в режиме HP — 16gb, 2gb и 64gb). Используемые значения записываются в файл журнала hf_xet при его запуске (см. Журналирование).

Кэш шардов

Кэш shard cache хранит на диске в каталоге кэша Xet индекс дедупликации (так называемые «shards», описывающие уже загруженные фрагменты). Чем больше кэш, тем больше ранее просмотренных данных может использовать клиент для дедупликации, что приводит к повторной загрузке меньшего количества байт.

Кэш чанков

hf_xet больше не использует локальный кэш чанков для загрузок. Скачанные файлы по-прежнему хранятся в файловом кэше huggingface_hub.

Логирование

Телеметрия

hf_xet отправляет краткий отчёт после каждой загрузки и скачивания. См. Телеметрия, чтобы узнать, что он содержит. Чтобы отключить телеметрию, установите HF_HUB_DISABLE_TELEMETRY=1.

Текущие ограничения

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

• Только 64-битные системы: и hf_xet, и Git Xet в настоящее время требуют 64-битной архитектуры; 32-битные системы не поддерживаются.