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

## Python

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

```bash
pip install -U huggingface_hub
```

Начиная с версии `huggingface_hub` 0.32.0, это также установит `hf_xet`. Пакет `hf_xet` интегрирует `huggingface_hub` с [`xet-core`](https://github.com/huggingface/xet-core), клиентом на Rust для бэкенда Xet.

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

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

```bash
pip install -U hf-xet
```

И всё! Теперь вы получаете преимущества дедупликации Xet как при загрузке, так и при скачивании. Члены команды, использующие версию `huggingface_hub` < 0.30.0, по-прежнему смогут загружать и скачивать репозитории благодаря [обратной совместимости, обеспечиваемой LFS-мостом](legacy-git-lfs#backward-compatibility-with-lfs).

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

- [Загрузка](https://huggingface.co/docs/huggingface_hub/guides/upload#faster-uploads)
- [Скачать](https://huggingface.co/docs/huggingface_hub/guides/download#faster-downloads)
- [Управление кэшем `hf_xet`](https://huggingface.co/docs/huggingface_hub/guides/manage-cache#chunk-based-caching-xet)

## Git

Пользователи Git могут воспользоваться преимуществами Xet, скачав и установив расширение Git Xet. После установки достаточно использовать [стандартные рабочие процессы для управления репозиториями Hub с помощью Git](../repositories-getting-started) — никаких дополнительных изменений не требуется.

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

Установите [Git](https://git-scm.com/) и [Git LFS](https://git-lfs.com/).

### Установка на 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](https://brew.sh/):
```
brew install git-xet
git xet install
```

Для проверки установки выполните:
```
git xet --version
```

### Windows (amd64)

С помощью `winget`:
```
winget install git-xet
```

С использованием установщика:
 - Скачайте `git-xet-windows-installer-x86_64.zip` ([доступен здесь](https://github.com/huggingface/xet-core/releases/download/git-xet-v0.2.0/git-xet-windows-installer-x86_64.zip)) и распакуйте архив.
 - Запустите файл установщика `msi` и следуйте инструкциям на экране.

Ручная установка:
 - Скачайте `git-xet-windows-x86_64.zip` ([доступен здесь](https://github.com/huggingface/xet-core/releases/download/git-xet-v0.2.0/git-xet-windows-x86_64.zip)) и распакуйте архив.
 - Разместите извлечённый `git-xet.exe` в каталоге, указанном в переменной `PATH`.
 - Выполните `git xet install` в терминале.

Для проверки установки выполните:
  ```
  git xet --version
  ```

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

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

Убедитесь, что все [предварительные требования установлены и настроены](https://huggingface.co/docs/hub/repositories-getting-started#requirements), следуйте [инструкциям по настройке для работы с репозиториями на Hub](https://huggingface.co/docs/hub/repositories-getting-started#set-up), затем зафиксируйте изменения и `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](https://huggingface.co/docs/xet/index), что повышает скорость загрузки благодаря [дедупликации на уровне чанков](./deduplication).

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

С помощью Homebrew:
```bash
git xet uninstall
brew uninstall git-xet
```
Если вы использовали скрипт установки (для MacOS или Linux), выполните следующую команду в терминале:
```bash
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`, включая ограничения памяти контейнера. Небольшие контейнеры используют меньше памяти для загрузки, а крупные машины — больше, при этом настраивать ничего не требуется. См. [Буферы загрузки](#download-buffers).
- **Расширенная настройка**: для тонкого управления переменные `HF_XET_FIXED_DOWNLOAD_CONCURRENCY` и `HF_XET_FIXED_UPLOAD_CONCURRENCY` позволяют зафиксировать уровень параллелизма, минуя адаптивный контроллер. Полный список параметров см. в разделе [переменные окружения](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#xet) библиотеки `hf_xet`.

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

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

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

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

Если ваша сеть ограничивает исходящий трафик, разрешите эти имена хостов (HTTPS, порт 443) в дополнение к тем, что перечислены в разделе [Загрузка за прокси или файрволом](../models-downloading#downloading-behind-a-proxy-or-firewall):

| Имя хоста                     | Назначение                                          |
|------------------------------|--------------------------------------------------|
| `s3.us-east-1.amazonaws.com` | Прямые загрузки (США)                              |
| `s3.eu-west-3.amazonaws.com` | Прямые загрузки для репозиториев, хранящихся в ЕС |

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

Если `hf_xet` не может установить соединение с S3, он повторяет попытку прямой загрузки, а затем отправляет эти данные через сервис хранения Xet. Загрузка всё равно завершается, но может занимать значительно больше времени, так как каждый блок сначала проходит цикл повторных попыток. В [журнале](#logging) `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`, который настраивается через переменные окружения. В таблицах ниже перечислены отдельные переменные для тонкой настройки. Большинству пользователей не потребуется изменять ни одну из них — значения по умолчанию настроены так, чтобы автоматически обеспечивать максимальную пропускную способность большинства сетевых каналов.

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

### Общие

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

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_HIGH_PERFORMANCE` (псевдоним `HF_XET_HP`) | off | Флаг для удобства, который максимизирует использование сети и ЦП, одновременно увеличивая уровень параллелизма, размеры буферов и лимиты на количество параллельных файлов. См. примечание выше. |
| `HF_XET_CACHE` | `$HF_HOME/xet` | Каталог, в котором Xet хранит данные локально (скачанные фрагменты и шары дедупликации). Имеет приоритет над `HF_HOME`. |

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

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

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_CLIENT_AC_INITIAL_UPLOAD_CONCURRENCY` | `2` | Начальное количество параллельных потоков загрузки. Режим HP: `16`. |
| `HF_XET_CLIENT_AC_INITIAL_DOWNLOAD_CONCURRENCY` | `4` | Начальное количество параллельных потоков загрузки. Режим HP: `16`. |
| `HF_XET_CLIENT_AC_MIN_UPLOAD_CONCURRENCY` | `1` | Нижняя граница для параллельности загрузки. Режим HP: `4`. |
| `HF_XET_CLIENT_AC_MIN_DOWNLOAD_CONCURRENCY` | `1` | Нижняя граница для параллельности загрузки. Режим HP: `4`. |
| `HF_XET_CLIENT_AC_MAX_UPLOAD_CONCURRENCY` | `64` | Верхний предел для параллельности загрузки. Режим HP: `124`. |
| `HF_XET_CLIENT_AC_MAX_DOWNLOAD_CONCURRENCY` | `64` | Верхний предел для параллельности загрузки. Режим HP: `124`. |
| `HF_XET_CLIENT_AC_TARGET_RTT` | `60s` | Целевое время полного цикла. Уровень параллелизма увеличивается, пока прогнозируемое время полного цикла для полной передачи не превышает это значение. |
| `HF_XET_CLIENT_AC_MAX_HEALTHY_RTT` | `90s` | Максимально допустимое время полного цикла. Трансферы, длящиеся дольше этого значения, считаются адаптивным контроллером сбоями. |
| `HF_XET_CLIENT_AC_HEALTHY_SUCCESS_RATIO_THRESHOLD` | `0.8` | Коэффициент успешности, выше которого контроллер увеличивает параллелизм. |
| `HF_XET_CLIENT_AC_UNHEALTHY_SUCCESS_RATIO_THRESHOLD` | `0.5` | Коэффициент успешности, ниже которого контроллер снижает уровень параллелизма. |
| `HF_XET_CLIENT_AC_LOGGING_INTERVAL_MS` | `10000` | Интервал (в мс), с которым выводится статус конкурентности. |

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

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

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_CLIENT_RETRY_MAX_ATTEMPTS` | `5` | Максимальное количество попыток повторения для неудачных запросов. |
| `HF_XET_CLIENT_RETRY_BASE_DELAY` | `3000ms` | Базовая задержка между повторными попытками (с экспоненциальным откатом). |
| `HF_XET_CLIENT_RETRY_MAX_DURATION` | `360s` | Максимальное время ожидания перед каждой отдельной попыткой повторения. Повторные попытки прекращаются после `HF_XET_CLIENT_RETRY_MAX_ATTEMPTS`, поэтому общее время повторных попыток может превышать это значение. |
| `HF_XET_CLIENT_CONNECT_TIMEOUT` | `60s` | Тайм-аут TCP-соединения. |
| `HF_XET_CLIENT_READ_TIMEOUT` | `300s` | Время ожидания ответа HTTP. |
| `HF_XET_CLIENT_IDLE_CONNECTION_TIMEOUT` | `60s` | Время ожидания перед закрытием неактивных соединений. |
| `HF_XET_CLIENT_MAX_IDLE_CONNECTIONS` | `16` | Максимальное количество простаивающих соединений в пуле. |
| `HF_XET_CLIENT_RECONSTRUCTION_API_VERSION` | (не задано) | Принудительно установить версию API загрузки (реконструкции) на `1` или `2` без отката. Если значение не задано, `hf_xet` пытается использовать версию 2 и откатывается к версии 1, если сервер её не поддерживает. |
| `HF_XET_CLIENT_SHARD_API_VERSION` | (не задано) | Принудительно задайте версию API загрузки (шарда) `1` или `2` без отката. Если параметр не задан, `hf_xet` пытается использовать версию 2 и откатывается к версии 1, если сервер её не поддерживает. |

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

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_DATA_MAX_CONCURRENT_FILE_INGESTION` | `8` | Максимальное количество файлов, обрабатываемых одновременно во время загрузки. Режим HP: `100`. |
| `HF_XET_DATA_MAX_CONCURRENT_FILE_DOWNLOADS` | `8` | Максимальное количество файлов, загружаемых одновременно. |
| `HF_XET_DATA_INGESTION_BLOCK_SIZE` | `8mb` | Размер блоков, читаемых при загрузке файла. |
| `HF_XET_DATA_PROGRESS_UPDATE_INTERVAL` | `200ms` | Как часто обновляются индикаторы прогресса. |
| `HF_XET_DATA_PROGRESS_UPDATE_SPEED_SAMPLING_WINDOW` | `10s` | Временное окно, используемое для агрегирования измерений скорости передачи данных в отчётах о ходе выполнения. |
| `HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD` | `false` | Установите значение `1`, чтобы отправлять все данные загрузки через сервис хранения Xet, а не напрямую в S3 (`hf_xet` 1.8.0+). См. [Загрузка через прокси или межсетевой экран](#uploading-behind-a-proxy-or-firewall). |

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

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

Начиная с версии `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` при его запуске (см. [Журналирование](#logging)).

| Переменная окружения | По умолчанию | Режим HP | Описание |
|---|---|---|---|
| `HF_XET_RECONSTRUCTION_MIN_RECONSTRUCTION_FETCH_SIZE` | `256mb` | `1gb` | Минимальный размер выборки для запросов реконструкции. |
| `HF_XET_RECONSTRUCTION_MAX_RECONSTRUCTION_FETCH_SIZE` | `8gb` | `16gb` | Максимальный размер выборки для запросов реконструкции. |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE` | 1/16 памяти, от `64mb` до `16gb` | 1/8 памяти | Базовый бюджет разделяемого буфера. |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_PERFILE_SIZE` | 1/64 памяти, от `16mb` до `2gb` | 1/32 памяти | Дополнительный бюджет буфера на каждый активный файл. |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_LIMIT` | 1/4 памяти, `264mb` до `64gb` | 1/2 памяти | Жёсткий лимит на объём памяти буфера загрузки. Если `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE` задано с большим значением, лимит повышается до соответствующего уровня. |
| `HF_XET_DISABLE_MEMORY_DERIVED_DOWNLOAD_BUFFERS` | unset | — | Установите значение `1`, чтобы использовать фиксированные значения по умолчанию вместо определения размера буферов на основе доступной памяти. |
| `HF_XET_RECONSTRUCTION_TARGET_BLOCK_COMPLETION_TIME` | `15m` | — | Целевое время для завершения блока предварительной загрузки. Используется для определения количества данных, которые следует предварительно загрузить во время скачивания. |
| `HF_XET_RECONSTRUCTION_MIN_PREFETCH_BUFFER` | `1gb` | — | Минимальный объём данных, который следует удерживать в предзагрузке во время скачивания, независимо от предполагаемого времени завершения. |

### Кэш шардов

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

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_SHARD_CACHE_SIZE_LIMIT` | `16gb` | Мягкий лимит для кэша шардов на диске. Кэш обрезается до этого размера в **начале** запуска, но может превышать его в рамках одной длительной сессии. В качестве ориентира, кэш размера *X* дедуплицирует данные объёмом примерно 1000 × *X* (16 ГБ → ~16 ТБ). Увеличьте значение для лучшей дедупликации в очень больших репозиториях; уменьшите, если растущий кэш рискует заполнить диск. Принимает размер в человекочитаемом формате (например, `32gb`) или количество байтов. |
| `HF_XET_SHARD_CHUNK_INDEX_TABLE_MAX_SIZE` | `67108864` | Максимальное количество записей чанков в индексе дедупликации в оперативной памяти. Укажите целое число, а не размер, например `128mb`. Начиная с версии `hf_xet` 1.7.1, когда индекс заполняется, самые старые шарды удаляются из него, чтобы освободить место для новых; в более ранних версиях добавление чанков прекращается, как только индекс заполняется. |
| `HF_XET_SHARD_CACHE_SUBDIR` | `shard-cache` | Подкаталог для кэша шардов внутри каталога кэша Xet. |

### Кэш чанков

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

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_CHUNK_CACHE_SIZE_BYTES` | — | Более не используется в `hf_xet`. Установка этого параметра не включает кэш загрузок по частям. |

### Логирование

| Переменная окружения | По умолчанию | Описание |
|---|---|---|
| `HF_XET_LOG_DEST` | (none) | Место записи журнала. Принимает путь к файлу или путь к каталогу (заканчивающийся на `/`). Если задан каталог, файлы журнала создаются с именами, содержащими метку времени. Если задана пустая строка, журнал выводится в консоль. Если параметр не задан, журнал записывается в подкаталог `logs/` в каталоге кэша Hugging Face Xet. |
| `HF_XET_LOG_FORMAT` | (none) | Формат журнала. Установите `json` для журналов в формате JSON; в противном случае используется обычный текст. По умолчанию для записи в файл используется JSON, а для вывода в консоль — текст. |
| `HF_XET_LOG_PREFIX` | `xet` | Префикс для имён файлов журнала при записи в каталог. |
| `HF_XET_LOG_DIR_DISABLE_CLEANUP` | `false` | Отключить автоматическую очистку старых файлов журнала в каталоге журналов. |
| `HF_XET_LOG_DIR_MAX_SIZE` | `250mb` | Максимальный суммарный размер файлов журнала в каталоге журналов. Старые файлы удаляются, чтобы не превышать этот лимит. |
| `HF_XET_LOG_DIR_MIN_DELETION_AGE` | `1d` | Минимальный возраст файла журнала, после которого он может быть удалён при очистке. |
| `HF_XET_LOG_DIR_MAX_RETENTION_AGE` | `14d` | Максимальный возраст файлов журнала. Файлы старше этого значения всегда удаляются при очистке. |

### Телеметрия

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

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

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

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