# Загрузка наборов данных

## Интегрированные библиотеки

Если набор данных на Hub привязан к [поддерживаемой библиотеке](./datasets-libraries), его загрузка выполняется всего в несколько строк. Чтобы узнать, как получить доступ к набору данных, нажмите кнопку «Use this dataset» на странице набора данных. Например, [`samsum`](https://huggingface.co/datasets/knkarthick/samsum?library=datasets) показывает, как это сделать с помощью `datasets`, ниже.

## Использование клиентской библиотеки Hugging Face

Вы можете использовать библиотеку [`huggingface_hub`](/docs/huggingface_hub) для создания, удаления, обновления и получения информации о репозиториях. Например, чтобы скачать датасет `HuggingFaceH4/ultrachat_200k` из командной строки, выполните

```bash
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
```

См. [документацию по загрузке в HF CLI](https://huggingface.co/docs/huggingface_hub/en/guides/cli#download-a-dataset-a-space-or-a-kernel) для получения дополнительной информации.

Вы также можете интегрировать это в собственную библиотеру! Например, с помощью Pandas можно быстро загрузить набор данных в формате CSV всего несколькими строками кода.
```py
from huggingface_hub import hf_hub_download
import pandas as pd

REPO_ID = "YOUR_REPO_ID"
FILENAME = "data.csv"

dataset = pd.read_csv(
    hf_hub_download(repo_id=REPO_ID, filename=FILENAME, repo_type="dataset")
)
```

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

Поскольку все наборы данных на Hub представляют собой Git-репозитории с поддержкой Xet, вы можете клонировать их локально, [установив git-xet](./xet/using-xet-storage#git-xet) и выполнив:

```bash
git xet install
git lfs install
git clone git@hf.co:datasets/<dataset ID> # example: git clone git@hf.co:datasets/allenai/c4
```

Если у вас есть права на запись в конкретном репозитории датасета, вы также сможете коммитить и пушить ревизии датасета.

Добавьте ваш публичный SSH-ключ в [настройки пользователя](https://huggingface.co/settings/keys), чтобы отправлять изменения и/или получать доступ к закрытым репозиториям.

## Более быстрая загрузка

Вы можете проверить скорость загрузки с CDN Hugging Face на [fast.hf.co](https://fast.hf.co). Это запускает быстрое тестирование пропускной способности по отношению к ближайшему edge-серверу HF, что помогает понять базовую пропускную способность вашего соединения. Также вы можете измерить скорость загрузки из терминала с помощью расширения CLI [`hf-speedtest`](https://github.com/julien-c/hf-speedtest):

```bash
hf extensions install julien-c/hf-speedtest
hf speedtest
```

Для более быстрого переноса данных Hub использует [бэкенд хранения Xet](https://huggingface.co/docs/hub/en/xet/index) с адаптивной конкурентностью, которая автоматически настраивает параллельные потоки в зависимости от условий сети. Подробности о параметрах настройки, таких как `HF_XET_HIGH_PERFORMANCE=1`, см. в разделе [Быстрая загрузка моделей](./models-downloading#faster-downloads).

## Использование hf-mount

Для больших наборов данных вместо загрузки всего репозитория вы можете смонтировать его как локальную файловую систему с помощью [hf-mount](https://github.com/huggingface/hf-mount). Файлы загружаются лениво — в сеть отправляются только те байты, которые читает ваш код. Это полезно, когда ваш рабочий процесс ожидает локальные пути к файлам (например, `tarfile`, `zipfile`, `imagefolder`), а не итераторы Python.

```bash
brew install hf-mount
hf-mount start repo datasets/stanfordnlp/imdb /tmp/imdb
```

Репозитории монтируются только для чтения. См. [Монтирование как локальную файловую систему](./storage-buckets-access#mount-as-a-local-filesystem) для подробностей настройки, вариантов бэкенда и кэширования.

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

Если ваша сеть ограничивает исходящий трафик с помощью файрвола или прокси, для загрузки наборов данных недостаточно доступа только к `huggingface.co`. Содержимое файлов предоставляется с отдельных хостов хранения и CDN, и `load_dataset` / `hf download` завершатся с ошибкой, если эти хосты недоступны, даже если сам `huggingface.co` добавлен в белый список.

Добавьте следующие имена хостов в список разрешённых (все по HTTPS / порт 443):

| Имя хоста                     | Назначение                                     |
|------------------------------|---------------------------------------------|
| `huggingface.co`             | Hub API, метаданные и перенаправления загрузок   |
| `cas-server.xethub.hf.co`    | API протокола Xet, загрузка и выгрузка (США) |
| `cas-server.xethub-eu.hf.co` | API протокола Xet, загрузка и выгрузка (ЕС) |
| `transfer.xethub.hf.co`      | API для загрузки данных из хранилища Xet (США)              |
| `transfer.xethub-eu.hf.co`   | API для загрузки из хранилища Xet (ЕС)              |
| `us.aws.cdn.hf.co`           | CDN-узел (США)                               |
| `us.gcp.cdn.hf.co`           | CDN-узел (США)                               |
| `cdn-lfs-us-1.hf.co`         | LFS CDN (США)                                |
| `cdn-lfs-eu-1.hf.co`         | LFS CDN (ЕС)                                |

> [!TIP]
> Загрузки следуют HTTP-редиректам с `huggingface.co` на указанные выше хосты, поэтому добавления только `huggingface.co` в белый список недостаточно. Ошибка `ReadTimeoutError` (вместо ошибки подключения) в процессе загрузки обычно означает, что начальное соединение было установлено, но хост хранилища или CDN заблокирован.

> [!TIP]
> Поведение подстановочных символов зависит от того, как ваш прокси сопоставляет домены. Многие корпоративные прокси трактуют запись в списке разрешённых доменов как совпадение по суффиксу, охватывающее поддомены на любой глубине. Если ваш прокси работает так, самый простой вариант — добавить в список разрешённых суффиксы `hf.co` и `huggingface.co` — они покрывают все текущие и будущие конечные точки хранения и CDN.
>
> Если ваш прокси поддерживает только одноуровневые маски (где `*.hf.co` совпадает с `cdn-lfs-us-1.hf.co`, но не с более глубокими `us.aws.cdn.hf.co` или `cas-server.xethub.hf.co`), добавьте в список разрешённых явные имена хостов из таблицы выше. Обратите внимание, что `*.xethub.hf.co` не покрывает хосты ЕС под `xethub-eu.hf.co`, а `*.cdn.hf.co` не покрывает двухуровневые `us.aws.cdn.hf.co` / `us.gcp.cdn.hf.co`.

> [!WARNING]
> Эти имена хостов могут меняться по мере развития нашей инфраструктуры хранения и CDN. Если ваша политика безопасности позволяет, добавьте в белый список суффиксы `hf.co` и `huggingface.co` (все поддомены), чтобы ваши правила не ломались при изменении конкретного конечного пункта.

> [!NOTE]
> Загрузки с `hf_xet` версии 1.8.0 и выше также могут выполняться напрямую на хосты Amazon S3, которые не находятся в доменах `hf.co` или `huggingface.co`. См. [Загрузка через прокси или межсетевой экран](./xet/using-xet-storage#uploading-behind-a-proxy-or-firewall).

### Список в машиночитаемом формате

Перечисленные выше имена хостов также публикуются в формате JSON по адресу [`https://huggingface.co/.well-known/meta.json`](https://huggingface.co/.well-known/meta.json), поэтому вы можете сгенерировать правила прокси или файрвола на основе этого файла, а не копировать таблицу вручную.

> [!WARNING]
> Файл изменяется по мере добавления и удаления конечных точек. Получайте его при построении правил, а не фиксируйте копию.