# Jupyter Notebookから分散学習を起動する

このチュートリアルでは、分散システム上の Jupyter Notebook から 🤗 Accelerate を使用してコンピュータビジョンモデルをファインチューニングする方法を学びます。また、環境が正しく設定されていること、データが適切に準備されていることを確認するために必要ないくつかの要件を設定する方法、そして最後にトレーニングを開始する方法についても学習します。

    このチュートリアルは、[こちら](https://github.com/huggingface/notebooks/blob/main/examples/accelerate_examples/simple_cv_example.ipynb)からJupyter Notebookとしてもご利用いただけます。

## 環境の構成

トレーニングを開始する前に、システムにAccelerateの設定ファイルが存在する必要があります。通常、ターミナルで以下を実行し、プロンプトに従って回答することで作成できます。

```bash
accelerate config
```

ただし、一般的なデフォルト設定で問題なく、*TPU上で*実行していない場合は、Accelerateには[utils.write_basic_config()](/docs/accelerate/v1.16.0/ja/package_reference/utilities#accelerate.commands.config.default.write_basic_config)を通じてデバイス設定を素早く設定ファイルに書き込むためのユーティリティが用意されています。

…

    マルチデバイスシステムでは、CUDAおよびXPUを2回以上初期化することはできません。ノートブック内でデバッグし、CUDA/XPUを呼び出すことは問題ありませんが、最終的にトレーニングを実行するには、完全なクリーンアップと再起動を行う必要があります。
    

```python
import os
from accelerate.utils import write_basic_config

write_basic_config()  # Write a config file
os._exit(00)  # Restart the notebook
```

## データセットとモデルの準備

次に、データセットの準備を行います。前述したように、`DataLoaders`とモデルの準備時には、**いかなるものも**GPUに配置しないよう、*あらゆる*点に細心の注意を払う必要があります。

そうする場合は、その特定のコードを関数にまとめ、後述するノートブックのランチャーインターフェースからその関数を呼び出すことをお勧めします。

指示に従ってデータセットがダウンロードされていることを確認してください。[こちら](https://github.com/huggingface/accelerate/tree/main/examples#simple-vision-example)

```python
import os, re, torch, PIL
import numpy as np

from torch.optim.lr_scheduler import OneCycleLR
from torch.utils.data import DataLoader, Dataset
from torchvision.transforms import Compose, RandomResizedCrop, Resize, ToTensor

from accelerate import Accelerator
from accelerate.utils import set_seed
from timm import create_model
```

まず、ファイル名に基づいてクラス名を抽出する関数を作成する必要があります:

```python
import os

data_dir = "../../images"
fnames = os.listdir(data_dir)
fname = fnames[0]
print(fname)
```

```python out
beagle_32.jpg
```

この場合、ラベルは`beagle`です。正規表現を使用して、ファイル名からラベルを抽出できます。

```python
import re

def extract_label(fname):
    stem = fname.split(os.path.sep)[-1]
    return re.search(r"^(.*)_\d+\.jpg$", stem).groups()[0]
```

```python
extract_label(fname)
```

ファイルの正しい名前が適切に返されたことが確認できます:

```python out
"beagle"
```

次に、画像とラベルの取得を処理するための`Dataset`クラスを作成します。

```python
class PetsDataset(Dataset):
    def __init__(self, file_names, image_transform=None, label_to_id=None):
        self.file_names = file_names
        self.image_transform = image_transform
        self.label_to_id = label_to_id

    def __len__(self):
        return len(self.file_names)

    def __getitem__(self, idx):
        fname = self.file_names[idx]
        raw_image = PIL.Image.open(fname)
        image = raw_image.convert("RGB")
        if self.image_transform is not None:
            image = self.image_transform(image)
        label = extract_label(fname)
        if self.label_to_id is not None:
            label = self.label_to_id[label]
        return {"image": image, "label": label}
```

次に、データセットを構築します。学習関数の外側で、すべてのファイル名とラベルを特定して宣言し、起動された関数の内部で参照として使用できます。

```python
fnames = [os.path.join("../../images", fname) for fname in fnames if fname.endswith(".jpg")]
```

次に、すべてのラベルを集めます:

```python
all_labels = [extract_label(fname) for fname in fnames]
id_to_label = list(set(all_labels))
id_to_label.sort()
label_to_id = {lbl: i for i, lbl in enumerate(id_to_label)}
```

次に、構築したデータローダーを返す`get_dataloaders`関数を作成する必要があります。前述したように、`DataLoaders`の構築時にデータが自動的にGPUやTPUデバイスに送信される場合、このメソッドを使用して構築する必要があります。

```python
def get_dataloaders(batch_size: int = 64):
    "Builds a set of dataloaders with a batch_size"
    random_perm = np.random.permutation(len(fnames))
    cut = int(0.8 * len(fnames))
    train_split = random_perm[:cut]
    eval_split = random_perm[cut:]

    # For training a simple RandomResizedCrop will be used
    train_tfm = Compose([RandomResizedCrop((224, 224), scale=(0.5, 1.0)), ToTensor()])
    train_dataset = PetsDataset([fnames[i] for i in train_split], image_transform=train_tfm, label_to_id=label_to_id)

    # For evaluation a deterministic Resize will be used
    eval_tfm = Compose([Resize((224, 224)), ToTensor()])
    eval_dataset = PetsDataset([fnames[i] for i in eval_split], image_transform=eval_tfm, label_to_id=label_to_id)

    # Instantiate dataloaders
    train_dataloader = DataLoader(train_dataset, shuffle=True, batch_size=batch_size, num_workers=4)
    eval_dataloader = DataLoader(eval_dataset, shuffle=False, batch_size=batch_size * 2, num_workers=4)
    return train_dataloader, eval_dataloader
```

最後に、後で使用するためのスケジューラーをインポートする必要があります。

```python
from torch.optim.lr_scheduler import CosineAnnealingLR
```

## 学習関数の作成

これでトレーニングループを構築できます。[notebook_launcher()](/docs/accelerate/v1.16.0/ja/package_reference/launchers#accelerate.notebook_launcher) は、分散システム全体で実行される呼び出し対象の関数を渡すことで動作します。

動物分類問題の基本的なトレーニングループは以下の通りです：

    各セクションの説明を容易にするため、コードは分割されています。コピー＆ペーストでそのまま使用できる完全なバージョンは、末尾で提供されます。

```python
def training_loop(mixed_precision="fp16", seed: int = 42, batch_size: int = 64):
    set_seed(seed)
    accelerator = Accelerator(mixed_precision=mixed_precision)
```

まず、シードを設定し、[Accelerator](/docs/accelerate/v1.16.0/ja/package_reference/accelerator#accelerate.Accelerator)オブジェクトを、トレーニングループの可能な限り早い段階で作成する必要があります。

    TPUでトレーニングを行う場合、トレーニングループはモデルをパラメータとして受け取り、モデルのインスタンス化はトレーニングループ関数の外で行う必要があります。その理由については、[TPUのベストプラクティス](../concept_guides/training_tpu)を参照してください。

次に、dataloaderを構築し、モデルを作成する必要があります。

```python
    train_dataloader, eval_dataloader = get_dataloaders(batch_size)
    model = create_model("resnet50d", pretrained=True, num_classes=len(label_to_id))
```

    ここでモデルを構築することで、シードが新しい重みの初期化も制御するようにします

この例では転移学習を実行しているため、モデルのエンコーダーは最初から凍結されており、モデルのヘッドのみが最初に学習されるようになっています：

```python
    for param in model.parameters():
        param.requires_grad = False
    for param in model.get_classifier().parameters():
        param.requires_grad = True
```

バッチ内の画像を正規化すると、トレーニングがわずかに高速化されます:

```python
    mean = torch.tensor(model.default_cfg["mean"])[None, :, None, None]
    std = torch.tensor(model.default_cfg["std"])[None, :, None, None]
```

これらの定数をアクティブなデバイスで利用可能にするには、Acceleratorのデバイスに設定する必要があります:

```python
    mean = mean.to(accelerator.device)
    std = std.to(accelerator.device)
```

次に、学習で使用される残りのPyTorchクラスをインスタンス化します：

```python
    optimizer = torch.optim.Adam(params=model.parameters(), lr=3e-2 / 25)
    lr_scheduler = OneCycleLR(optimizer=optimizer, max_lr=3e-2, epochs=5, steps_per_epoch=len(train_dataloader))
```

すべてを[prepare()](/docs/accelerate/v1.16.0/ja/package_reference/accelerator#accelerate.Accelerator.prepare)に渡す前に。

    特定の順序を覚える必要はありません。prepare メソッドに渡したのと同じ順序でオブジェクトを展開するだけです。

```python
    model, optimizer, train_dataloader, eval_dataloader, lr_scheduler = accelerator.prepare(
        model, optimizer, train_dataloader, eval_dataloader, lr_scheduler
    )
```

次にモデルを学習します:

```python
    for epoch in range(5):
        model.train()
        for batch in train_dataloader:
            inputs = (batch["image"] - mean) / std
            outputs = model(inputs)
            loss = torch.nn.functional.cross_entropy(outputs, batch["label"])
            accelerator.backward(loss)
            optimizer.step()
            lr_scheduler.step()
            optimizer.zero_grad()
```

評価ループは、トレーニングループとは少し異なる形になります。各バッチに渡される要素数と、全体の精度は、2つの定数に追加されます。

```python
        model.eval()
        accurate = 0
        num_elems = 0
```

次に、標準的なPyTorchループの残りの部分があります:

```python
        for batch in eval_dataloader:
            inputs = (batch["image"] - mean) / std
            with torch.no_grad():
                outputs = model(inputs)
            predictions = outputs.argmax(dim=-1)
```

最後に、最後の大きな違いについてです。

分散評価を実行する際、予測値とラベルは現在のデバイス上ですべてのデータが利用可能になり、適切に計算されたメトリクスが得られるように、[gather()](/docs/accelerate/v1.16.0/ja/package_reference/accelerator#accelerate.Accelerator.gather) を通して渡す必要があります。

```python
            accurate_preds = accelerator.gather(predictions) == accelerator.gather(batch["label"])
            num_elems += accurate_preds.shape[0]
            accurate += accurate_preds.long().sum()
```

次に、この問題の実際のメトリックを計算するだけです。メインプロセスで[print()](/docs/accelerate/v1.16.0/ja/package_reference/accelerator#accelerate.Accelerator.print)を使用して出力できます:

```python
        eval_metric = accurate.item() / num_elems
        accelerator.print(f"epoch {epoch}: {100 * eval_metric:.2f}")
```

このトレーニングループの完全なバージョンは以下で利用できます:

```python
def training_loop(mixed_precision="fp16", seed: int = 42, batch_size: int = 64):
    set_seed(seed)
    # Initialize accelerator
    accelerator = Accelerator(mixed_precision=mixed_precision)
    # Build dataloaders
    train_dataloader, eval_dataloader = get_dataloaders(batch_size)

    # Instantiate the model (you build the model here so that the seed also controls new weight initializations)
    model = create_model("resnet50d", pretrained=True, num_classes=len(label_to_id))

    # Freeze the base model
    for param in model.parameters():
        param.requires_grad = False
    for param in model.get_classifier().parameters():
        param.requires_grad = True

    # You can normalize the batches of images to be a bit faster
    mean = torch.tensor(model.default_cfg["mean"])[None, :, None, None]
    std = torch.tensor(model.default_cfg["std"])[None, :, None, None]

    # To make these constants available on the active device, set it to the accelerator device
    mean = mean.to(accelerator.device)
    std = std.to(accelerator.device)

    # Instantiate the optimizer
    optimizer = torch.optim.Adam(params=model.parameters(), lr=3e-2 / 25)

    # Instantiate the learning rate scheduler
    lr_scheduler = OneCycleLR(optimizer=optimizer, max_lr=3e-2, epochs=5, steps_per_epoch=len(train_dataloader))

    # Prepare everything
    # There is no specific order to remember, you just need to unpack the objects in the same order you gave them to the
    # prepare method.
    model, optimizer, train_dataloader, eval_dataloader, lr_scheduler = accelerator.prepare(
        model, optimizer, train_dataloader, eval_dataloader, lr_scheduler
    )

    # Now you train the model
    for epoch in range(5):
        model.train()
        for batch in train_dataloader:
            inputs = (batch["image"] - mean) / std
            outputs = model(inputs)
            loss = torch.nn.functional.cross_entropy(outputs, batch["label"])
            accelerator.backward(loss)
            optimizer.step()
            lr_scheduler.step()
            optimizer.zero_grad()

        model.eval()
        accurate = 0
        num_elems = 0
        for batch in eval_dataloader:
            inputs = (batch["image"] - mean) / std
            with torch.no_grad():
                outputs = model(inputs)
            predictions = outputs.argmax(dim=-1)
            accurate_preds = accelerator.gather(predictions) == accelerator.gather(batch["label"])
            num_elems += accurate_preds.shape[0]
            accurate += accurate_preds.long().sum()

        eval_metric = accurate.item() / num_elems
        # Use accelerator.print to print only on the main process.
        accelerator.print(f"epoch {epoch}: {100 * eval_metric:.2f}")
```

## notebook_launcherの使用

あとは[notebook_launcher()](/docs/accelerate/v1.16.0/ja/package_reference/launchers#accelerate.notebook_launcher)を使うだけです。

関数、引数（タプルとして）、および学習に使用するプロセス数を渡します。（詳細は[ドキュメント](../package_reference/launchers)を参照してください）

```python
from accelerate import notebook_launcher
```

```python
args = ("fp16", 42, 64)
notebook_launcher(training_loop, args, num_processes=2)
```

複数ノードで実行する場合、各ノードでJupyterセッションを設定し、起動セルを同時に実行する必要があります。

2ノード（コンピュータ）で各ノードに8つのGPUがあり、メインコンピュータのIPアドレスが"172.31.43.8"である環境では、次のようになります。

```python
notebook_launcher(training_loop, args, master_addr="172.31.43.8", node_rank=0, num_nodes=2, num_processes=8)
```

そして、別のマシンの2番目のJupyterセッションでは:

    `node_rank` が変更されている点に注目してください

```python
notebook_launcher(training_loop, args, master_addr="172.31.43.8", node_rank=1, num_nodes=2, num_processes=8)
```

TPU上で実行する場合、以下のようになります。

```python
model = create_model("resnet50d", pretrained=True, num_classes=len(label_to_id))

args = (model, "fp16", 42, 64)
notebook_launcher(training_loop, args, num_processes=8)
```

弾力性（Elasticity）を有効にしてフォールトトレランスを備えたトレーニングプロセスを開始するには、PyTorch が提供する `elastic_launch` 機能を使用できます。これには、`rdzv_backend` や `max_restarts` などの追加パラメータを設定する必要があります。以下は、弾力性機能を備えた `notebook_launcher` の使用例です。

```python
notebook_launcher(
    training_loop,
    args,
    num_processes=2,
    max_restarts=3
)
```

実行中は、進捗状況と使用したデバイスの数が表示されます。このチュートリアルは2つのGPUで実行されました:

```python out
Launching training on 2 GPUs.
epoch 0: 88.12
epoch 1: 91.73
epoch 2: 92.58
epoch 3: 93.90
epoch 4: 94.71
```

これで完了です！

[notebook_launcher()](/docs/accelerate/v1.16.0/ja/package_reference/launchers#accelerate.notebook_launcher)はAccelerateの設定ファイルを無視することに注意してください。設定に基づいて起動するには、以下を使用します:

```bash
accelerate launch
```

## デバッグ 

`notebook_launcher`の実行時に、CUDA/XPU has already been initialized という問題が発生することがあります。これは通常、ノートブック内のインポートや先行コードが、PyTorchの`torch.cuda`または`torch.xpu`サブライブラリを呼び出していることが原因です。問題の原因を絞り込むために、環境変数に`ACCELERATE_DEBUG_MODE=yes`を設定して`notebook_launcher`を起動すると、スポン時に通常のプロセスが問題なく作成され、CUDA/XPUを利用できるかという追加のチェックが行われます。（その後のCUDA/XPUコードの実行には影響しません）。

## 結論

このノートブックでは、Jupyter Notebook の内部から分散学習を実行する方法を示しました。覚えておくべき重要なポイントはいくつかあります。

- CUDA/XPU（または CUDA/XPU のインポート）を使用するコードは、[notebook_launcher()](/docs/accelerate/v1.16.0/ja/package_reference/launchers#accelerate.notebook_launcher) に渡す関数内に保存してください。
- `num_processes`を、学習に使用するデバイスの数（GPU、XPU、CPU、TPUなどの数）に設定します。
- TPUを使用する場合は、モデルをトレーニングループ関数の外で宣言してください

