# PyTorch ile kullanma

Bu belge, `datasets` kütüphanesinin PyTorch ile kullanımına hızlı bir giriş niteliğindedir; odak noktası, veri setlerimizden `torch.Tensor` nesnelerini nasıl elde edeceğimiz ve bir PyTorch `DataLoader` ile bir Hugging Face `Dataset`'ini en iyi performansla nasıl kullanacağımızdır.

## Veri seti biçimi

Varsayılan olarak veri kümeleri, tamsayılar, ondalık sayılar, dizeler, listeler gibi standart Python nesneleri döndürür.

Bunun yerine PyTorch tensörleri almak için, veri setinin biçimini [Dataset.with_format()](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Dataset.with_format) kullanarak `pytorch` olarak ayarlayabilirsiniz:

```py
>>> from datasets import Dataset
>>> data = [[1, 2],[3, 4]]
>>> ds = Dataset.from_dict({"data": data})
>>> ds = ds.with_format("torch")
>>> ds[0]
{'data': tensor([1, 2])}
>>> ds[:2]
{'data': tensor([[1, 2],
         [3, 4]])}
```

> [!TIP]
> Bir [Dataset](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Dataset) nesnesi, bir Arrow tablosunun sarmalayıcısıdır ve veri setindeki dizilerden PyTorch tensörlerine hızlı, kopyasız (zero-copy) okumalara olanak tanır.

Verileri GPU üzerinde tensörler olarak yüklemek için `device` argümanını belirtin:
```py
>>> import torch
>>> device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
>>> ds = ds.with_format("torch", device=device)
>>> ds[0]
{'data': tensor([1, 2], device='cuda:0')}
```

### N boyutlu diziler

Veri setiniz N boyutlu dizilerden oluşuyorsa, şekil sabit olduğunda varsayılan olarak bunların aynı tensör olarak ele alındığını göreceksiniz:

```py
>>> from datasets import Dataset
>>> data = [[[1, 2],[3, 4]],[[5, 6],[7, 8]]]  # fixed shape
>>> ds = Dataset.from_dict({"data": data})
>>> ds = ds.with_format("torch")
>>> ds[0]
{'data': tensor([[1, 2],
         [3, 4]])}
```

```py
>>> from datasets import Dataset
>>> data = [[[1, 2],[3]],[[4, 5, 6],[7, 8]]]  # varying shape
>>> ds = Dataset.from_dict({"data": data})
>>> ds = ds.with_format("torch")
>>> ds[0]
{'data': [tensor([1, 2]), tensor([3])]}
```

Ancak bu mantık genellikle yavaş şekil karşılaştırmaları ve veri kopyalamaları gerektirir. Bunu önlemek için `Array` özellik türünü açıkça kullanmalı ve tensörlerinizin şeklini belirtmelisiniz:

```py
>>> from datasets import Dataset, Features, Array2D
>>> data = [[[1, 2],[3, 4]],[[5, 6],[7, 8]]]
>>> features = Features({"data": Array2D(shape=(2, 2), dtype='int32')})
>>> ds = Dataset.from_dict({"data": data}, features=features)
>>> ds = ds.with_format("torch")
>>> ds[0]
{'data': tensor([[1, 2],
         [3, 4]])}
>>> ds[:2]
{'data': tensor([[[1, 2],
          [3, 4]],
 
         [[5, 6],
          [7, 8]]])}
```

### Diğer özellik türleri

[ClassLabel](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.ClassLabel) verileri doğru şekilde tensörlere dönüştürülür:

```py
>>> from datasets import Dataset, Features, ClassLabel
>>> labels = [0, 0, 1]
>>> features = Features({"label": ClassLabel(names=["negative", "positive"])})
>>> ds = Dataset.from_dict({"label": labels}, features=features) 
>>> ds = ds.with_format("torch")  
>>> ds[:3]
{'label': tensor([0, 0, 1])}
```

String ve ikili nesneler, PyTorch yalnızca sayıları desteklediği için değiştirilmez.

[Image](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Image) ve [Audio](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Audio) özellik türleri de desteklenir.

> [!TIP]
> [Image](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Image) özellik türünü kullanmak için `vision` ek paketini `pip install datasets[vision]` olarak yüklemeniz gerekir.

```py
>>> from datasets import Dataset, Features, Audio, Image
>>> images = ["path/to/image.png"] * 10
>>> features = Features({"image": Image()})
>>> ds = Dataset.from_dict({"image": images}, features=features) 
>>> ds = ds.with_format("torch")
>>> ds[0]["image"].shape
torch.Size([512, 512, 4])
>>> ds[0]
{'image': tensor([[[255, 215, 106, 255],
         [255, 215, 106, 255],
         ...,
         [255, 255, 255, 255],
         [255, 255, 255, 255]]], dtype=torch.uint8)}
>>> ds[:2]["image"].shape
torch.Size([2, 512, 512, 4])
>>> ds[:2]
{'image': tensor([[[[255, 215, 106, 255],
          [255, 215, 106, 255],
          ...,
          [255, 255, 255, 255],
          [255, 255, 255, 255]]]], dtype=torch.uint8)}
```

> [!TIP]
> [Audio](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Audio) özellik türünü kullanmak için `audio` ek paketini `pip install datasets[audio]` olarak yüklemeniz gerekir.

```py
>>> from datasets import Dataset, Features, Audio, Image
>>> audio = ["path/to/audio.wav"] * 10
>>> features = Features({"audio": Audio()})
>>> ds = Dataset.from_dict({"audio": audio}, features=features) 
>>> ds = ds.with_format("torch")  
>>> ds[0]["audio"]["array"]
tensor([ 6.1035e-05,  1.5259e-05,  1.6785e-04,  ..., -1.5259e-05,
        -1.5259e-05,  1.5259e-05])
>>> ds[0]["audio"]["sampling_rate"]
tensor(44100)
```

## Veri yükleme

`torch.utils.data.Dataset` nesneleri gibi, bir [Dataset](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.Dataset) doğrudan bir PyTorch `DataLoader`'a geçirilebilir:

```py
>>> import numpy as np
>>> from datasets import Dataset 
>>> from torch.utils.data import DataLoader
>>> data = np.random.rand(16)
>>> label = np.random.randint(0, 2, size=16)
>>> ds = Dataset.from_dict({"data": data, "label": label}).with_format("torch")
>>> dataloader = DataLoader(ds, batch_size=4)
>>> for batch in dataloader:
...     print(batch)                                                                                            
{'data': tensor([0.0047, 0.4979, 0.6726, 0.8105]), 'label': tensor([0, 1, 0, 1])}
{'data': tensor([0.4832, 0.2723, 0.4259, 0.2224]), 'label': tensor([0, 0, 0, 0])}
{'data': tensor([0.5837, 0.3444, 0.4658, 0.6417]), 'label': tensor([0, 1, 0, 0])}
{'data': tensor([0.7022, 0.1225, 0.7228, 0.8259]), 'label': tensor([1, 1, 1, 1])}
```

### Veri yükleme işlemini optimize edin

Veri yükleme hızını artırmanın, özellikle büyük veri setleriyle çalışırken zaman tasarrufu sağlayabilecek birkaç yolu vardır. PyTorch, indeksleri tek tek yerine partiler halinde alarak paralelleştirilmiş veri yükleme ve veri setini diske indirmeden üzerinde gezinmek için akış (streaming) sunar.

#### Birden çok Worker kullanın

Veri yükleme işlemini, PyTorch `DataLoader`'nin `num_workers` argümanı ile paralelleştirebilir ve daha yüksek bir işleme hızı elde edebilirsiniz.

Arka planda, `DataLoader` `num_workers` süreç başlatır. Her süreç, `DataLoader`'a geçirilen veri setini yeniden yükler ve örnek sorgulamak için kullanılır. İşçi içinde veri setinin yeniden yüklenmesi RAM'inizi doldurmaz, çünkü veri seti diskinizden basitçe yeniden bellek eşlemesi yapılır.

```py
>>> import numpy as np
>>> from datasets import Dataset, load_from_disk
>>> from torch.utils.data import DataLoader
>>> data = np.random.rand(10_000)
>>> Dataset.from_dict({"data": data}).save_to_disk("my_dataset")
>>> ds = load_from_disk("my_dataset").with_format("torch")
>>> dataloader = DataLoader(ds, batch_size=32, num_workers=4)
```

### Verileri akıt

Bir veri setini [IterableDataset](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.IterableDataset) olarak yükleyerek akış (stream) olarak kullanın. Bu, bir uzak veri setini diske indirmeden veya yerel veri dosyaları üzerinde kademeli olarak yinelemenize (iterate) olanak tanır. Hangi tür veri setinin kullanım senaryonuz için en uygun olduğunu öğrenmek için [düzenli bir veri seti ile yinelebilir (iterable) bir veri seti arasında seçim yapma](./about_mapstyle_vs_iterable) kılavuzuna göz atın.

`datasets` kütüphanesinden gelen bir iterable veri seti, `torch.utils.data.IterableDataset` sınıfından türetildiği için bir `torch.utils.data.DataLoader` nesnesine aktarılabilir:

```py
>>> import numpy as np
>>> from datasets import Dataset, load_dataset
>>> from torch.utils.data import DataLoader
>>> data = np.random.rand(10_000)
>>> Dataset.from_dict({"data": data}).push_to_hub("<username>/my_dataset")  # Upload to the Hugging Face Hub
>>> my_iterable_dataset = load_dataset("<username>/my_dataset", streaming=True, split="train")
>>> dataloader = DataLoader(my_iterable_dataset, batch_size=32)
```

Veri seti birkaç parçaya bölünmüşse (yani veri seti birden fazla veri dosyasından oluşuyorsa), `num_workers` kullanarak paralel olarak akış yapabilirsiniz:

```py
>>> my_iterable_dataset = load_dataset("deepmind/code_contests", streaming=True, split="train")
>>> my_iterable_dataset.num_shards
39
>>> dataloader = DataLoader(my_iterable_dataset, batch_size=32, num_workers=4)
```

Bu durumda her işçiye, akışın yapılacağı shard listesinin bir alt kümesi verilir.

### Kontrol noktası ve devam

Eğitimin ortasında kontrol noktası alıp devam edebileceğiniz bir DataLoader'a ihtiyacınız varsa, [torchdata](https://github.com/pytorch/data)'daki `StatefulDataLoader`'ı kullanabilirsiniz:

```py
>>> from torchdata.stateful_dataloader import StatefulDataLoader
>>> my_iterable_dataset = load_dataset("deepmind/code_contests", streaming=True, split="train")
>>> dataloader = StatefulDataLoader(my_iterable_dataset, batch_size=32, num_workers=4)
>>> # save in the middle of training
>>> state_dict = dataloader.state_dict()
>>> # and resume later
>>> dataloader.load_state_dict(state_dict)
```

Bu, [IterableDataset.state_dict()](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.IterableDataset.state_dict) ve [IterableDataset.load_state_dict()](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.IterableDataset.load_state_dict) sayesinde mümkündür.

### Dağıtık

Veri setinizi eğitim düğümleri arasında bölmek için [datasets.distributed.split_dataset_by_node()](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.distributed.split_dataset_by_node) işlevini kullanabilirsiniz:

```python
import os
from datasets.distributed import split_dataset_by_node

ds = split_dataset_by_node(ds, rank=int(os.environ["RANK"]), world_size=int(os.environ["WORLD_SIZE"]))
```

Bu, hem harita tarzı veri kümeleri hem de yinelebilir veri kümeleri için geçerlidir. Veri kümesi, `world_size` boyutundaki bir düğüm havuzunda `rank` sırasındaki düğüm için bölünür.

Harita tarzı veri kümeleri için:

Her düğüme bir veri parçası atanır, örneğin rank 0'a veri setinin ilk parçası verilir.

Yinelenebilir veri kümeleri için:

Bölme `strategy` `"auto"`, `"shards"` veya `"examples"` olabilir:

* `"shards"`: shard'ler düğümler arasında eşit olarak dağıtılır
* `"examples"`: her düğüm, `world_size` içindeki örneklerden 1 tanesini saklar, diğer örnekleri atlar
* `"auto"` (varsayılan): veri setinin shard sayısı `world_size`'in bir çarpanıysa (yani `dataset.num_shards % world_size == 0` ise) `"shards"` kullanılır; bu en optimize seçenektir. Aksi halde `"examples"` kullanılır.

Bu, her düğümün verileri yüklemek için birden fazla işçi kullanmasını istiyorsanız, `torch.utils.data.DataLoader` ile de birleştirilebilir.

> [!WARNING]
> Dağıtık bir yapılandırma içinde iteratif veri setinizi karıştırıyorsanız, her düğümün hangi shard'ları atlaması gerektiğini bilmesi için her düğümde aynı karıştırılmış shard listesinin kullanılmasını sağlamak üzere [IterableDataset.shuffle()](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.IterableDataset.shuffle) içinde sabit bir `seed` değerini ayarladığınızdan emin olun.

#### Hibrit parçalı veri paralelliği (HSDP)

Bir [`torch.distributed.device_mesh.DeviceMesh`](https://pytorch.org/docs/stable/distributed.html#devicemesh), eğitim topolojinizi her paralellik stratejisi için bir boyut olacak şekilde rank ızgarası olarak tanımlar. Veri yükleme için yalnızca veri paralelliği boyutları önemlidir ve hibrit parçalama bunları gözden kaçırmayı kolaylaştırır:

* `"fsdp"` (genellikle düğüm içi): her rank'ın yalnızca model durumlarının (parametreler, gradyanlar ve optimizör durumları) bir dilimini tuttuğu ve bir modül üzerinde hesaplama yapmadan hemen önce o modülün tam parametrelerini geçici olarak all-gather ettiği [FSDP](https://pytorch.org/docs/stable/fsdp.html) grubu. Eğitim veri paralel kalmaya devam eder: her rank kendi batch'i üzerinde tam bir ileri ve geri geçiş çalıştırır, bu nedenle bu boyut, DDP'de olduğu gibi rank başına farklı veri gerektirir.
* `"dp_replicate"` (genellikle düğümler arası): o bölünmüş modelin, replikalar arasında ek bir all-reduce ile senkronize tutulan kopyaları. Replikalar ayrıca farklı verileri işler.
* `"tp"` (düğümler arası): her katmanın ağırlıklarını bölerek bir partiyi birlikte hesaplayan tensör paralel sıraları. Bunlar veri paraleli değildir ve aynı örnekleri okumalıdır.

Veri paralel derecesi, sharding (FSDP) ve replikasyon boyutlarının çarpımıdır ve mesh'te `"tp"` gibi bir boyut olduğu anda `WORLD_SIZE`'den küçük olur. [datasets.distributed.split_dataset_by_node()](/docs/datasets/v5.2.0/tr/package_reference/main_classes#datasets.distributed.split_dataset_by_node) fonksiyonuna bu çarpımı ve bu iki boyut üzerinde düzleştirilen rank değerini verin:

```python
from torch.distributed.device_mesh import init_device_mesh
from datasets.distributed import split_dataset_by_node

# Hybrid sharding spreads data parallelism over two mesh dimensions, but both
# need different data per rank, so `dp_size` is their product.
mesh = init_device_mesh("cuda", (2, 2, 2), mesh_dim_names=("dp_replicate", "fsdp", "tp"))
dp_replicate_mesh, fsdp_mesh = mesh["dp_replicate"], mesh["fsdp"]

dp_size = dp_replicate_mesh.size() * fsdp_mesh.size()
dp_rank = dp_replicate_mesh.get_local_rank() * shard.size() + fsdp_mesh.get_local_rank()

ds = split_dataset_by_node(ds, rank=dp_rank, world_size=dp_size)
```

Burada `dp_size` değeri `2 * 2 = 4`'tür: her veri paralel sıralaması veri setinin dörtte birini okur ve her `"tp"` çiftindeki iki sıralama aynı örnekleri okur.

