# Облачное хранилище

## Hugging Face Datasets

Hugging Face Dataset Hub — это хранилище постоянно растущей коллекции наборов данных, охватывающих различные области и задачи.

Это не просто облачное хранилище: Dataset Hub — это платформа, которая обеспечивает версионирование данных с помощью git, а также предоставляет Dataset Viewer для исследования данных, что делает её отличным местом для хранения датасетов, готовых к использованию в ИИ.

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

## Хранилища Hugging Face

Storage Buckets — это тип репозитория на Hugging Face Hub, обеспечивающий объектное хранилище, аналогичное S3, на базе системы хранения Xet. В отличие от репозиториев датасетов на базе Git, бакеты не имеют версионирования и допускают изменения. Они предназначены для сценариев, где требуется простое и быстрое хранилище, например для логов, промежуточных артефактов или любых больших коллекций файлов, не требующих контроля версий.

## Импорт данных из облачного хранилища

Большинство провайдеров облачного хранилища предоставляют реализацию FileSystem для `fsspec`, что позволяет импортировать данные из любого облачного провайдера с помощью одного и того же кода. Это особенно полезно для публикации датасетов на Hugging Face.

Ознакомьтесь с таблицей ниже, в которой приведены примеры поддерживаемых провайдеров облачного хранилища:

| Провайдер хранилища     | Реализация файловой системы                                     |
|----------------------|---------------------------------------------------------------|
| Amazon S3            | [s3fs](https://s3fs.readthedocs.io/en/latest/)                |
| Google Cloud Storage | [gcsfs](https://gcsfs.readthedocs.io/en/latest/)              |
| Azure Blob/DataLake  | [adlfs](https://github.com/fsspec/adlfs)                      |
| Oracle Cloud Storage | [ocifs](https://ocifs.readthedocs.io/en/latest/)              |

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

Допустим, мы хотим опубликовать датасет на Hugging Face из файлов Parquet, находящихся в облачном хранилище.

Сначала создайте экземпляр файловой системы облачного хранилища и перечислите файлы, которые вы хотите импортировать:

```python
>>> import fsspec
>>> fs = fsspec.filesystem("...")  # s3 / gcs / abfs / adl / oci / ...
>>> data_dir = "path/to/my/data/"
>>> pattern = "*.parquet"
>>> data_files = fs.glob(data_dir + pattern)
["path/to/my/data/0001.parquet", "path/to/my/data/0001.parquet", ...]
```

### Опубликовать набор данных

Затем вы можете создать набор данных на Hugging Face и импортировать файлы данных, например, с помощью

```python
>>> from huggingface_hub import create_repo, upload_folder
>>> from tqdm.auto import tqdm
>>> destination_dataset = "username/my-dataset"
>>> create_repo(destination_dataset, repo_type="dataset")
>>> batch_size = 100
>>> for data_files in batched(tqdm(fs.glob(data_dir + pattern)), batch_size):
...     with TemporaryDirectory() as tmp_dir:
...         tmp_files = [os.path.join(tmp_dir, x[len(data_dir):]) for x in data_files]
...         fs.download(data_files, tmp_files)
...         upload_folder(
...             repo_id=destination_dataset,
...             folder_path=tmp_dir,
...             repo_type="dataset",
...         )
```

См. документацию [huggingface_hub](https://huggingface.co/docs/huggingface_hub) по загрузке файлов [здесь](https://huggingface.co/docs/huggingface_hub/en/guides/upload), если вам нужны дополнительные варианты загрузки.

В итоге теперь вы можете загрузить набор данных с помощью 🤗 Datasets:

```python
>>> from datasets import load_dataset
>>> ds = load_dataset("username/my-dataset")
```

### Импорт необработанных данных в Storage Buckets

В качестве альтернативы, если вы не хотите публиковать датасет, а просто импортировать файлы с сырыми данными в [Storage Bucket](https://huggingface.co/docs/hub/storage-buckets) Hugging Face, вы можете использовать:

```python
>>> from huggingface_hub import create_bucket, sync_bucket
>>> from tqdm.auto import tqdm
>>> from itertools import batched
>>> from tempfile import TemporaryDirectory
>>> import os
>>> create_bucket("username/my-bucket")
>>> bucket_files_location = "hf://buckets/username/my-bucket/path/to/raw/files"
>>> batch_size = 100
>>> for data_files in batched(tqdm(fs.glob(data_dir + pattern)), batch_size):
...     with TemporaryDirectory() as tmp_dir:
...         tmp_files = [os.path.join(tmp_dir, x[len(data_dir):]) for x in data_files]
...         fs.download(data_files, tmp_files)
...         sync_bucket(tmp_dir, bucket_files_location)
```

См. документацию [huggingface_hub](https://huggingface.co/docs/huggingface_hub) по Storage Buckets [здесь](https://huggingface.co/docs/hub/storage-buckets), если вам нужны дополнительные варианты загрузки.

Затем вы можете загрузить исходные файлы с помощью 🤗 Datasets, преобразовать их и загрузить готовые к использованию в ИИ наборы данных, например, в режиме потоковой обработки:

Если файлы находятся в формате, поддерживаемом 🤗 Datasets:

```python
>>> from datasets import load_dataset
>>> ds = load_dataset(bucket_files_location, streaming=True)
>>> ds = ds.map(...).filter(...)
>>> ds.push_to_hub("username/my-dataset", num_proc=4)
>>> # and later
>>> ds = load_dataset("username/my-dataset")
```

В противном случае вы можете использовать собственную функцию разбора файлов:

```python
>>> from datasets import IterableDataset
>>> from huggingface_hub import hffs
>>> data_files = hffs.find(bucket_files_location)
>>> num_shards = 1024  # For parallelism. PS: every shard should fit in RAM
>>> ds = IterableDataset.from_dict({"data_file": data_files}, num_shards=num_shards)
>>> def parse_data_files(data_files):
...     ...
...     return {"col_1": [...], "col_2": [...]}
>>> ds = ds.map(parse_data_files, batched=True, input_column=["data_file"])
>>> ds.push_to_hub("username/my-dataset", num_proc=4)
>>> # and later
>>> ds = load_dataset("username/my-dataset")
```