# Amazon EC2 の推論ワークロードに対して EFA と NIXL の使用を開始する
<a name="efa-start-nixl"></a>

NVIDIA Inference Xfer Library (NIXL) は、分散推論ワークロード専用に設計された、高スループットで低レイテンシーの通信ライブラリです。NIXL は、EFA および Libfabric とともに使用すれば、プリフィルノードとデコードノード間の KV キャッシュ転送をサポートでき、さまざまなストレージレイヤー間での KV キャッシュ移動を効率化できます。詳細については、[NIXL](https://github.com/ai-dynamo/nixl) のウェブサイトを参照してください。

**要件**
+ Ubuntu 24.04 と Ubuntu 22.04 ベースの AMI のみがサポートされています。
+ EFA は NIXL 1.0.0 以降のみをサポートしています。

**Topics**

## ステップ 1: EFA 対応のセキュリティグループを準備する
<a name="nixl-start-base-setup"></a>

EFA にはセキュリティグループ自体とのインバウンドおよびアウトバウンドのトラフィックをすべて許可するセキュリティグループが必要です。以下の手順ではセキュリティグループを作成します。このセキュリティグループではセキュリティグループ自体とのすべてのインバウンドおよびアウトバウンドのトラフィックと、SSH 接続用の任意の IPv4 アドレスからのインバウンド SSH トラフィックを許可します。

**重要**  
このセキュリティグループはテストのみを目的としています。本番環境ではコンピュータの IP アドレスやローカルネットワークの IP アドレスの範囲など、接続元の IP アドレスからのトラフィックのみを許可するインバウンド SSH ルールを作成することをお勧めします。

その他のシナリオについては[さまざまなユースケースのセキュリティグループのルール](security-group-rules-reference.md)を参照してください。

**EFA 対応のセキュリティグループを作成するには**

1. Amazon EC2 コンソールの [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) を開いてください。

1. ナビゲーションペインで [**Security Groups**] (セキュリティグループ) を選択して、[**Create security group**] (セキュリティグループの作成) を選択してください。

1. [**Create security group**] (セキュリティグループの作成) ウィンドウで、以下を行います。

   1. [**セキュリティグループ名**] に、`EFA-enabled security group` のような、分かりやすいセキュリティグループ名を入力してください。

   1. (オプション) [**説明**] に、セキュリティグループの簡単な説明を入力してください。

   1. [**VPC**] で、EFA 対応のインスタンスを起動する VPC を選択してください。

   1. **[セキュリティグループの作成]** を選択してください。

1. 作成したセキュリティグループを選択し、**[Details]** (詳細) タブで **[Security group ID]** (セキュリティグループ ID) をコピーします。

1. セキュリティグループが選択された状態で、**[Actions]** (アクション)、**[Edit inbound rules]** (インバウンドルールの編集) の順に選択し、次の手順を実行します。

   1. [**Add rule**] を選択してください。

   1. [**Type**] で、[**All traffic**] を選択してください。

   1. **[Source type]** (送信元タイプ) で、**[Custom]** (カスタム) を選択し、コピーしたセキュリティグループ ID をフィールドに貼り付けます。

   1. [**ルールを追加**] を選択してください。

   1. **[タイプ]** で **SSH]** を選択してください。

   1. **[Source type]** (ソースタイプ) で、**[Anywhere-IPv4]** を選択してください。

   1. **[Save Rules]** (ルールの保存) を選択してください。

1. セキュリティグループが選択された状態で、**[Actions]** (アクション)、**[Edit outbound rules]** (アウトバウンドルールの編集) の順に選択し、次の手順を実行します。

   1. [**Add rule**] を選択してください。

   1. [**Type**] で、[**All traffic**] を選択してください。

   1. **[Destination type]** (送信先タイプ) で、**[Custom]** (カスタム) を選択し、コピーしたセキュリティグループ ID をフィールドに貼り付けます。

   1. **[Save Rules]** (ルールの保存) を選択してください。

## ステップ 2: 一時インスタンスを作成する
<a name="nixl-start-base-temp"></a>

EFA ソフトウェアコンポーネントのインストールおよび設定に使用する一時インスタンスを起動します。このインスタンスを使用して、EFA 対応のインスタンスを起動する EFA 対応の AMI を作成します。

**一時インスタンスを起動するには**

1. Amazon EC2 コンソールの [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) を開いてください。

1. ナビゲーションペインで、**[Instances]** (インスタンス) を選択し、**[Launch Instances]** (インスタンスの起動) を選択して、新しいインスタンス起動ウィザードを開きます。

1. (*オプション*) **[Name and tags]** (名前とタグ) セクションで、`EFA-instance` などのインスタンス名を指定します。指定した名前はリソースタグとしてインスタンスに割り当てられます (`Name={{EFA-instance}}`)。

1. **[アプリケーションと OS のイメージ]** セクションで、サポートされるオペレーティングシステムのいずれかに対応する AMI を選択してください。[DLAMI リリースノートページ](https://docs.aws.amazon.com/dlami/latest/devguide/appendix-ami-release-notes)で、サポートされている DLAMI を選択することもできます。

1. **[インスタンスタイプ]** セクションで、サポートされているインスタンスタイプを選択してください。

1. **[Key pair]** (キーペア) セクションで、インスタンスに使用するキーペアを選択してください。

1. **[Network settings]** (ネットワーク設定) セクションで、**[Edit]** (編集) を選択し、次の操作を行います。

   1. [**サブネット**] で、インスタンスを起動するサブネットを選択してください。サブネットを選択しない場合、EFA のインスタンスを有効にすることはできません。

   1. **[Firewall (security groups)]** (ファイアウォール (セキュリティグループ)) の場合、**[Select existing security group]** (既存のセキュリティグループの選択) を選択し、前のステップで作成したセキュリティグループを選択してください。

   1. **[高度な設定]** セクションを展開します。

      **ネットワークインターフェイス 1** では**[ネットワークカードインデックス = 0]**、**[デバイスインデックス = 0]**、**[インターフェイスタイプ = EFA と ENA の組み合わせ]** を選択してください。

      (*オプション*) `p4d.24xlarge` または `p5.48xlarge` などのマルチカードインスタンスタイプを、必要な追加のネットワークインターフェイスごとに使用する場合は**[ネットワークインターフェイスの追加]** を選択し、**ネットワークカードインデックス**の場合は次の未使用インデックスを選択してから、**[デバイスインデックス = 1]**、**[インターフェイスタイプ = EFA と ENA の組み合わせ]** または **[EFA のみ]** を選択してください。

1. **[Storage]** (ストレージ) セクションで、必要に応じてボリュームを設定します。
**注記**  
Nvidia CUDA ツールキットには追加の 10 ～ 20 GiB のストレージをプロビジョニングする必要があります。十分な量のストレージをプロビジョニングしないと、Nvidia ドライバーと CUDA ツールキットをインストールしようとしたときに、`insufficient disk space` エラーが発生します。

1. 右側の **[合計mary]** (サマリー) パネルで、**[Launch instance]** (インスタンスの起動) を選択してください。

**重要**  
AMI に Nvidia GPU ドライバー、CUDA ツールキット、cuDNN がすでに含まれている場合、または非 GPU インスタンスを使用している場合は、ステップ 3 をスキップします。

## ステップ 3: Nvidia GPU ドライバー、Nvidia CUDA ツールキットおよび cuDNN をインストールする
<a name="nixl-start-base-drivers"></a>

**NVIDIA GPU ドライバー、NVIDIA CUDA ツールキットおよび cuDNN をインストールするには**

1. すべてのソフトウェアパッケージが最新の状態であることを確認するため、インスタンスでソフトウェアの更新を実行します。

   ```
   $ sudo apt-get update && sudo apt-get upgrade -y
   ```

1. Nvidia GPU ドライバと Nvidia CUDA ツールキットをインストールするために必要なユーティリティをインストールします。

   ```
   $ sudo apt-get install build-essential -y
   ```

1. Nvidia GPU ドライバを使用するにはまず、`nouveau` オープンソースドライバを無効にする必要があります。

   1. 必要なユーティリティ、および現在実行しているカーネルのバージョン用のカーネルヘッダーパッケージをインストールします。

      ```
      $ sudo apt-get install -y gcc make linux-headers-$(uname -r)
      ```

   1. `nouveau` 拒否リストファイルに `/etc/modprobe.d/blacklist.conf ` を追加します。

      ```
      $ cat << EOF | sudo tee --append /etc/modprobe.d/blacklist.conf
      blacklist vga16fb
      blacklist nouveau
      blacklist rivafb
      blacklist nvidiafb
      blacklist rivatv
      EOF
      ```

   1. 任意のテキストエディタを使用して `/etc/default/grub` ファイルを開き、以下を追加します。

      ```
      GRUB_CMDLINE_LINUX="rdblacklist=nouveau"
      ```

   1. Grub 設定を再構築します。

      ```
      $ sudo update-grub
      ```

1. インスタンスを再起動して、そのインスタンスに再接続します。

1. CUDA リポジトリを追加し、Nvidia GPU ドライバー、NVIDIA CUDA ツールキット、および cuDNN をインストールします。

   ```
   $ sudo apt-key adv --fetch-keys http://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu2004/x86_64/7fa2af80.pub \
   && wget -O /tmp/deeplearning.deb http://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu2004/x86_64/nvidia-machine-learning-repo-ubuntu2004_1.0.0-1_amd64.deb \
   && sudo dpkg -i /tmp/deeplearning.deb \
   && wget -O /tmp/cuda.pin https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-ubuntu2004.pin \
   && sudo mv /tmp/cuda.pin /etc/apt/preferences.d/cuda-repository-pin-600 \
   && sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/3bf863cc.pub \
   && sudo add-apt-repository 'deb http://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/ /' \
   && sudo apt update \
   && sudo apt install nvidia-dkms-535 \
   && sudo apt install -o Dpkg::Options::='--force-overwrite' cuda-drivers-535 cuda-toolkit-12-3 libcudnn8 libcudnn8-dev -y
   ```

1. インスタンスを再起動して、そのインスタンスに再接続します。

1. (`p4d.24xlarge` および `p5.48xlarge` のみ) NVIDIA Fabric Manager をインストールします。

   1. 前の手順でインストールした Nvidia カーネルモジュールのバージョンと一致する Nvidia Fabric Manager のバージョンをインストールする必要があります。

      Nvidia カーネルモジュールのバージョンを確認するには次のコマンドを実行します。

      ```
      $ cat /proc/driver/nvidia/version | grep "Kernel Module"
      ```

      以下は出力の例です。

      ```
      NVRM version: NVIDIA UNIX x86_64 Kernel Module  450.42.01  Tue Jun 15 21:26:37 UTC 2021
      ```

      上記の例ではメジャーバージョン `450` のカーネルモジュールがインストールされました。これはNvidia Fabric Manager のバージョン `450` をインストールする必要があることを意味します。

   1. Nvidia Fabric Manager をインストールする 次のコマンドを、前の手順で識別されたメジャーバージョンを指定して実行します。

      ```
      $ sudo apt install -o Dpkg::Options::='--force-overwrite' nvidia-fabricmanager-{{major_version_number}}
      ```

      例えば、メジャーバージョン `450` のカーネルモジュールがインストールされた場合、以下のコマンドを使用して、一致するバージョンの Nvidia Fabric Manager をインストールします。

      ```
      $ sudo apt install -o Dpkg::Options::='--force-overwrite' nvidia-fabricmanager-450
      ```

   1. サービスを開始し、インスタンスの起動時に自動的に起動することを確認します。NVIDIA Fabric Manager はNV Switch Management に必要です。

      ```
      $ sudo systemctl start nvidia-fabricmanager && sudo systemctl enable nvidia-fabricmanager
      ```

1. インスタンスが起動するたびに CUDA パスが設定されていることを確認します。
   + *bash* シェルの場合、次のステートメントを `/home/{{username}}/.bashrc` と `/home/{{username}}/.bash_profile` に追加します。

     ```
     export PATH=/usr/local/cuda/bin:$PATH
     export LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64:$LD_LIBRARY_PATH
     ```
   + *tcsh* シェルの場合、次の文を `/home/{{username}}/.cshrc` に追加します。

     ```
     setenv PATH=/usr/local/cuda/bin:$PATH
     setenv LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64:$LD_LIBRARY_PATH
     ```

1. 以下のコマンドを実行して、Nvidia GPU ドライバが機能することを確認します。

   ```
   $ nvidia-smi -q | head
   ```

   このコマンドはNvidia GPU、Nvidia GPU ドライバ、Nvidia CUDA ツールキットの情報を返します。

**重要**  
AMI にすでに GDRCopy が含まれている場合、または非 GPU インスタンスを使用している場合は、ステップ 4 をスキップします。

## ステップ 4: GDRCopy をインストールする
<a name="nixl-start-base-gdrcopy"></a>

GDRCopy をインストールして GPU ベースのプラットフォーム上で Libfabric のパフォーマンスを向上させます。GDRCopy の詳細については「[GDRCopy レポジトリ](https://github.com/NVIDIA/gdrcopy)」を参照してください。

**GDRCopy をインストールするには**

1. 必要な依存ファイルをインストールします。

   ```
   $ sudo apt -y install build-essential devscripts debhelper check libsubunit-dev fakeroot pkg-config dkms
   ```

1. GDRCopy パッケージをダウンロードして解凍します。

   ```
   $ wget https://github.com/NVIDIA/gdrcopy/archive/refs/tags/v2.4.tar.gz \
   && tar xf v2.4.tar.gz \
   && cd gdrcopy-2.4/packages
   ```

1. GDRCopy DEB パッケージをビルドします。

   ```
   $ CUDA=/usr/local/cuda ./build-deb-packages.sh
   ```

1. GDRCopy DEB パッケージをインストールします。

   ```
   $ sudo dpkg -i gdrdrv-dkms_2.4-1_amd64.*.deb \
   && sudo dpkg -i libgdrapi_2.4-1_amd64.*.deb \
   && sudo dpkg -i gdrcopy-tests_2.4-1_amd64.*.deb \
   && sudo dpkg -i gdrcopy_2.4-1_amd64.*.deb
   ```

**重要**  
AMI に最新の EFA インストーラがすでに含まれている場合は、ステップ 5 をスキップします。

## ステップ 5: EFA ソフトウェアをインストールする
<a name="nixl-start-base-enable"></a>

インスタンスで EFA をサポートするために必要な EFA 対応のカーネル、EFA ドライバー、Libfabric スタックをインストールします。

**EFA ソフトウェアをインストールするには**

1. 起動したインスタンスに接続します。詳細については「[SSH を使用した Linux インスタンスへの接続](connect-to-linux-instance.md)」を参照してください。

1. EFA ソフトウェアのインストールファイルをダウンロードします。ソフトウェアのインストールファイルは圧縮された tar (`.tar.gz`) ファイルにパッケージ化されています。次のコマンドを使用して、*安定している*最新バージョンをダウンロードします。

   ```
   $ curl -O https://efa-installer.amazonaws.com/aws-efa-installer-1.48.0.tar.gz
   ```

1. 圧縮された `.tar.gz` ファイルからファイルを展開してターボールを削除し、展開されたディレクトリに移動します。

   ```
   $ tar -xf aws-efa-installer-1.48.0.tar.gz && rm -rf aws-efa-installer-1.48.0.tar.gz && cd aws-efa-installer
   ```

1. (*オプション*) インストール中に個々のパッケージ署名を検証します。

   EFA インストーラ 1.48.0 以降では、インストーラには GPG 署名の個々の RPM および DEB パッケージが含まれています。インストール中に個々のパッケージの信頼性と整合性を検証するには、`--check-signatures` フラグを使用します。このフラグを有効にすると、まず、インストーラはすべてのパッケージ署名を検証し、すべてのパッケージが検証に合格した場合にのみインストールを続行します。パッケージが検証に失敗すると、インストーラは何もインストールせずにすぐに終了します。

   1. GPG 公開鍵をダウンロードします。

      ```
      $ wget https://efa-installer.amazonaws.com/aws-efa-installer.key
      ```

   1. キーパスをエクスポートします。次に、次のステップで、インストールコマンドに `--check-signatures` を追加し、`sudo` の代わりに `sudo -E` を使用して環境変数を保持します。

      ```
      $ export EFA_INSTALLER_KEY=$(pwd)/aws-efa-installer.key
      ```

   RPM ベースのシステム (Amazon Linux、RHEL、Rocky Linux、SUSE) では、インストーラは `rpm --checksig` を使用して各 RPM を検証します。DEB ベースのシステム (Ubuntu、Debian) では、インストーラは GPG 署名検証を使用して各 DEB を検証します。

   パッケージの検証に失敗すると、インストールは直ちに中止され、壊れたパッケージや悪意のあるパッケージからシステムを保護します。
**注記**  
`--check-signatures` フラグはオプションです。これがないと、インストーラは個々の署名検証を実行しません。

1. EFA ソフトウェアのインストールスクリプトを実行します。
**注記**  
前のオプションステップを完了してパッケージ署名の検証をセットアップした場合は、インストールコマンドに `--check-signatures` を追加して、`sudo` の代わりに `sudo -E` を使用します。例: `sudo -E ./efa_installer.sh -y --check-signatures`。

   ```
   $ sudo ./efa_installer.sh -y
   ```

   **Libfabric** は `/opt/amazon/efa` ディレクトリにインストールされます。

1. EFA インストーラーでインスタンスの再起動を求めるメッセージが表示された場合は再起動してからインスタンスに再接続します。それ以外の場合はインスタンスからログアウトし、再度ログインしてインストールを完了します。

1. EFA ソフトウェアコンポーネントが正常にインストールされたことを確認します。

   ```
   $ fi_info -p efa -t FI_EP_RDM
   ```

   コマンドによって、Libfabric の EFA インターフェイスに関する情報が返ります。以下の例はコマンド出力を示しています。
   + 単一のネットワークインターフェイスを持つ `p3dn.24xlarge`

     ```
     provider: efa
     fabric: EFA-fe80::94:3dff:fe89:1b70
     domain: efa_0-rdm
     version: 2.0
     type: FI_EP_RDM
     protocol: FI_PROTO_EFA
     ```
   + 複数のネットワークインターフェイスを持つ `p4d.24xlarge` および `p5.48xlarge`

     ```
     provider: efa
     fabric: EFA-fe80::c6e:8fff:fef6:e7ff
     domain: efa_0-rdm
     version: 111.0
     type: FI_EP_RDM
     protocol: FI_PROTO_EFA
     provider: efa
     fabric: EFA-fe80::c34:3eff:feb2:3c35
     domain: efa_1-rdm
     version: 111.0
     type: FI_EP_RDM
     protocol: FI_PROTO_EFA
     provider: efa
     fabric: EFA-fe80::c0f:7bff:fe68:a775
     domain: efa_2-rdm
     version: 111.0
     type: FI_EP_RDM
     protocol: FI_PROTO_EFA
     provider: efa
     fabric: EFA-fe80::ca7:b0ff:fea6:5e99
     domain: efa_3-rdm
     version: 111.0
     type: FI_EP_RDM
     protocol: FI_PROTO_EFA
     ```

## ステップ 6: NIXL をインストールする
<a name="nixl-start-base-nixl"></a>

NIXL をインストールします。NIXL の詳細については、[NIXL リポジトリ](https://github.com/ai-dynamo/nixl)を参照してください。

------
#### [ Pre-built distributions ]

**PyPI を使用して NIXL をインストールする方法**

1. 必要な依存ファイルをインストールします。

   ```
   $ sudo apt install pip
   ```

1. NIXL をインストールします。

   ```
   $ pip install nixl
   ```

------
#### [ Build from source ]

**ソースから NIXL をビルドしてインストールする方法**

1. 必要な依存ファイルをインストールします。

   ```
   $ sudo apt install cmake pkg-config meson pybind11-dev libaio-dev nvidia-cuda-toolkit pip libhwloc-dev \
   && pip install meson ninja pybind11
   ```

1. ホームディレクトリに移動します。

   ```
   $ cd $HOME
   ```

1. 公式の NIXL リポジトリをインスタンスにクローンし、ローカルのクローンされたリポジトリに移動します。

   ```
   $ sudo git clone https://github.com/ai-dynamo/nixl.git && cd nixl
   ```

1. NIXL を構築してインストールし、Libfabric インストールディレクトリへのパスを指定します。

   ```
   $ sudo meson setup . nixl --prefix=/usr/local/nixl -Dlibfabric_path=/opt/amazon/efa
   $ cd nixl && sudo ninja && sudo ninja install
   ```

------

## ステップ 7: NIXL Benchmark をインストールして EFA と NIXL 設定をテストする
<a name="nixl-start-base-tests"></a>

NIXL Benchmark をインストールし、テストを実行して EFA と NIXL に一時インスタンスが適切に設定されていることを確認します。NIXL Benchmark により、NIXL が適切にインストールされていることと、想定どおりに機能していることを確認できます。詳細については、[nixlbench リポジトリ](https://github.com/ai-dynamo/nixl/tree/main/benchmark/nixlbench)を参照してください。

NIXL Benchmark (nixlbench) では、クライアントとサーバー間の調整に ETCD が必要です。ETCD と NIXL を併用するには、ETCD サーバーとクライアント、および ETCD CPP API が必要です。

------
#### [ Build from Docker ]

**Docker を使用して NIXL Benchmark をインストールしてテストする方法**

1. 公式の NIXL リポジトリのクローンを作成してインスタンスに投入し、nixlbench ビルドディレクトリに移動します。

   ```
   $ git clone https://github.com/ai-dynamo/nixl.git
   $ cd nixl/benchmark/nixlbench/contrib
   ```

1. コンテナを構築します。

   ```
   $ ./build.sh
   ```

   Docker ビルドオプションの詳細については、[nixlbench リポジトリ](https://github.com/ai-dynamo/nixl/tree/main/benchmark/nixlbench)を参照してください。

1. Docker をインストールします。

   ```
   $ sudo apt install docker.io -y
   ```

1. 調整のために ETCD サーバーを起動します。

   ```
   $ docker run -d --name etcd-server \
       -p 2379:2379 -p 2380:2380 \
       quay.io/coreos/etcd:v3.5.18 \
       /usr/local/bin/etcd \
       --data-dir=/etcd-data \
       --listen-client-urls=http://0.0.0.0:2379 \
       --advertise-client-urls=http://0.0.0.0:2379 \
       --listen-peer-urls=http://0.0.0.0:2380 \
       --initial-advertise-peer-urls=http://0.0.0.0:2380 \
       --initial-cluster=default=http://0.0.0.0:2380
   ```

1. ETCD サーバーが実行されていることを確認します。

   ```
   $ curl -L http://localhost:2379/health
   ```

   正常な出力:

   ```
   {"health":"true"}
   ```

1. インスタンスの 2 つのターミナルを開きます。両方のターミナルで、以下のコマンドを実行してインストールを確認します。コマンドは、同じインスタンス上の ETCD サーバーを使用し、バックエンドとして Libfabric を使用し、GPU メモリを使用して動作します。

   ```
   $ docker run -it --gpus all --network host nixlbench:latest \
       nixlbench --etcd_endpoints http://localhost:2379 \
       --backend LIBFABRIC \
       --initiator_seg_type VRAM \
       --target_seg_type VRAM
   ```
**注記**  
GPU 以外のインスタンスには `VRAM` の代わりに `DRAM` 値を使用します。

------
#### [ Build from source ]

**重要**  
ステップ 6 で **[ソースからビルドする]** を選択した場合のみ、このタブに従います。

**NIXL Benchmark をインストールする方法**

1. 必要なシステム依存関係をインストールします。

   ```
   $ sudo apt install libgflags-dev
   ```

1. ETCD サーバーとクライアントをインストールします。

   ```
   $ sudo apt install -y etcd-server etcd-client
   ```

1. ETCD CPP API をインストールします。

   1. ETCD CPP API に必要な依存関係をインストールします。

      ```
      $ sudo apt install libboost-all-dev libssl-dev libgrpc-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libcpprest-dev
      ```

   1. ETCD CPP API のクローンを作成してインストールします。

      ```
      $ cd $HOME
      $ git clone https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3.git
      $ cd etcd-cpp-apiv3
      $ mkdir build && cd build
      $ cmake ..
      $ sudo make -j$(nproc) && sudo make install
      ```

1. nixlbench をビルドしてインストールします。

   ```
   $ sudo meson setup . $HOME/nixl/benchmark/nixlbench -Dnixl_path=/usr/local/nixl/
   $ sudo ninja && sudo ninja install
   ```

**EFA と NIXL 設定をテストする方法**

1. インスタンスで ETCD サーバーを起動します。

   ```
   $ etcd --listen-client-urls "http://0.0.0.0:2379" \
       --advertise-client-urls "http://localhost:2379" &
   ```

1. ETCD サーバーが実行されていることを確認します。

   ```
   $ curl -L http://localhost:2379/health
   ```

   正常な出力:

   ```
   {"health":"true"}
   ```

1. インスタンスの 2 つのターミナルを開きます。両方のターミナルで、以下の手順に従って nixlbench を実行します。

   1. nixlbench がインストールされているディレクトリに移動します。

      ```
      $ cd /usr/local/nixlbench/bin/
      ```

   1. テストを実行し、バックエンド、ETCD サーバーのアドレス、イニシエータセグメントタイプを指定します。次のコマンドは、同じインスタンス上の ETCD サーバーを使用し、バックエンドとして Libfabric を使用し、GPU メモリを使用して動作します。環境変数により以下が設定されます。
      + `NIXL_LOG_LEVEL=INFO` — 詳細なデバッグ出力を有効にします。エラーメッセージのみを受信するように `WARN` を指定することもできます。
      + `LD_LIBRARY_PATH` — NIXL ライブラリのパスを設定します。

      NIXL Benchmark 引数の詳細については、公式の nixlbench リポジトリの [NIXLbench README](https://github.com/ai-dynamo/nixl/blob/main/benchmark/nixlbench/README.md) を参照してください。

      ```
      $ export NIXL_LOG_LEVEL=INFO
      $ export LD_LIBRARY_PATH=/usr/local/nixl/lib/$(gcc -dumpmachine):$LD_LIBRARY_PATH
      
      $ nixlbench --etcd-endpoints 'http://localhost:2379' \
          --backend 'LIBFABRIC' \
          --initiator_seg_type 'VRAM' \
          --target_seg_type 'VRAM'
      ```
**注記**  
GPU 以外のインスタンスには `VRAM` の代わりに `DRAM` 値を使用します。

------

## ステップ 8: 機械学習アプリケーションをインストールする
<a name="nixl-start-base-app"></a>

機械学習アプリケーションを一時インスタンスにインストールします。インストール手順はそれぞれの機械学習アプリケーションによって異なります。

**注記**  
インストール手順については機械学習アプリケーションのドキュメントを参照してください。

## ステップ 9: EFA および NIXL 対応 AMI を作成する
<a name="nixl-start-base-ami"></a>

必要なソフトウェアコンポーネントのインストール後、EFA 対応のインスタンスの起動に再利用できる AMI を作成します。

**一時インスタンスから AMI を作成するには**

1. Amazon EC2 コンソールの [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) を開いてください。

1. ナビゲーションペインで、[**インスタンス**] を選択してください。

1. 作成した一時インスタンスを選択し、[**アクション**]、[**イメージ**]、[**イメージの作成**] の順に選択してください。

1. [**イメージの作成**] で、次を行います。

   1. [**イメージ名**] に、の分かりやすい AMI 名を入力してください。

   1. (オプション) [**イメージの説明**] に、AMI の簡単な説明を入力してください。

   1. [**イメージを作成**] を選択してください。

1. ナビゲーションペインで [**AMI**] を選択してください。

1. リストで作成した AMI を探します。ステータスが `pending` から `available` に変わるまで待ってから、次のステップに進みます。

## ステップ 10: 一時インスタンスを終了する
<a name="nixl-start-base-terminate"></a>

この時点で、起動した一時インスタンスは不要になります。インスタンスを終了して、料金の発生を停止できます。

**一時インスタンスを終了するには**

1. Amazon EC2 コンソールの [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) を開いてください。

1. ナビゲーションペインで、[**インスタンス**] を選択してください。

1. 作成した一時インスタンスを選択し、[**アクション**]、[**インスタンスの状態**]、[**インスタンスの終了**] の順に選択してください。

1. 確認を求めるメッセージが表示されたら、[**終了**] を選択してください。

## ステップ 11: EFA および NIXL 対応インスタンスを起動する
<a name="nixl-start-base-cluster"></a>

**ステップ 9** で作成した EFA 対応の AMI と、**ステップ 1** で作成した EFA 対応のセキュリティグループを使用して、EFA および NIXL 対応インスタンスを起動します。

**EFA および NIXL 対応インスタンスを起動する方法**

1. Amazon EC2 コンソールの [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) を開いてください。

1. ナビゲーションペインで、**[Instances]** (インスタンス) を選択し、**[Launch Instances]** (インスタンスの起動) を選択して、新しいインスタンス起動ウィザードを開きます。

1. (*オプション*) **[Name and tags]** (名前とタグ) セクションで、`EFA-instance` などのインスタンス名を指定します。指定した名前はリソースタグとしてインスタンスに割り当てられます (`Name={{EFA-instance}}`)。

1. **[Application and OS Images]** (アプリケーションと OS イメージ) セクションで、**[My AMI]** (マイ AMI) をクリックし、前のステップで作成した AMI を選択してください。

1. **[インスタンスタイプ]** セクションで、サポートされているインスタンスタイプを選択してください。

1. **[Key pair]** (キーペア) セクションで、インスタンスに使用するキーペアを選択してください。

1. **[Network settings]** (ネットワーク設定) セクションで、**[Edit]** (編集) を選択し、次の操作を行います。

   1. [**サブネット**] で、インスタンスを起動するサブネットを選択してください。サブネットを選択しない場合、EFA のインスタンスを有効にすることはできません。

   1. **[ファイアウォール (セキュリティグループ)]** の場合、**[既存のセキュリティグループを選択]** を選択し、**ステップ 1**で作成したセキュリティグループを選択してください。

   1. **[高度な設定]** セクションを展開します。

      **ネットワークインターフェイス 1** では**[ネットワークカードインデックス = 0]**、**[デバイスインデックス = 0]**、**[インターフェイスタイプ = EFA と ENA の組み合わせ]** を選択してください。

      (*オプション*) `p4d.24xlarge` または `p5.48xlarge` などのマルチカードインスタンスタイプを、必要な追加のネットワークインターフェイスごとに使用する場合は**[ネットワークインターフェイスの追加]** を選択し、**ネットワークカードインデックス**の場合は次の未使用インデックスを選択してから、**[デバイスインデックス = 1]**、**[インターフェイスタイプ = EFA と ENA の組み合わせ]** または **[EFA のみ]** を選択してください。

1. (*オプション*) **[Storage]** (ストレージ) セクションで、必要に応じてボリュームを設定します。

1. 右側の **[合計mary]** (サマリー) パネルで、**[Number of instances]** (インスタンス数) に、起動する EFA 対応のインスタンスの数を入力し、**[Launch Instance]** (インスタンスの起動) を選択してください。

## ステップ 12: パスワードレス SSH を有効にする
<a name="nixl-start-base-passwordless"></a>

クラスター内のすべてのインスタンスでアプリケーションを実行できるようにするにはリーダーノードからメンバーノードへのパスワードなしの SSH アクセスを有効にする必要があります。リーダーノードはアプリケーションを実行するインスタンスです。クラスター内の残りのインスタンスはメンバーノードです。

**クラスター内のインスタンス間でパスワードなしの SSH を有効にするには**

1. クラスター内の 1 つのインスタンスをリーダーノードとして選択し、それに接続します。

1. リーダーノード上で `strictHostKeyChecking` を無効にし `ForwardAgent` を有効にします。任意のテキストエディタを使用して `~/.ssh/config` ファイルを開き、以下を追加します。

   ```
   Host *
       ForwardAgent yes
   Host *
       StrictHostKeyChecking no
   ```

1. RSA キーペアを生成します。

   ```
   $ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
   ```

   キーペアは`$HOME/.ssh/` ディレクトリで作成されます。

1. リーダーノードのプライベートキーの許可を変更します。

   ```
   $ chmod 600 ~/.ssh/id_rsa
   chmod 600 ~/.ssh/config
   ```

1. 任意のテキストエディタで `~/.ssh/id_rsa.pub` を開き、キーをコピーします。

1. クラスター内の各メンバーノードについて、次の操作を行います。

   1. インスタンスに接続します。

   1. 任意のテキストエディタで `~/.ssh/authorized_keys` を開き、前にコピーしたパブリックキーを追加します。

1. パスワードレス SSH が正常に機能していることをテストするにはリーダーノードに接続して、次のコマンドを実行します。

   ```
   $ ssh {{member_node_private_ip}}
   ```

   キーまたはパスワードの入力を求められずに、メンバーノードに接続できるはずです。

**重要**  
ステップ 7 に従った場合にのみ、ステップ 13 に従ってください。

## ステップ 13: インスタンス間で EFA と NIXL の設定をテストする
<a name="nixl-start-base-test-multi"></a>

テストを実行し、EFA と NIXL に対して一時インスタンスが適切に設定されていることを確認します。

------
#### [ Build from Docker ]

**Docker を使用してインスタンス間で EFA と NIXL の設定をテストする方法**

1. nixlbench ベンチマークを実行するためにホストを 2 つ選択します。最初のホストの IP アドレスをメタデータ交換用の ETCD サーバー IP として使用します。

1. ホスト 1 で ETCD サーバーを起動します。

   ```
   $ docker run -d --name etcd-server \
       -p 2379:2379 -p 2380:2380 \
       quay.io/coreos/etcd:v3.5.18 \
       /usr/local/bin/etcd \
       --data-dir=/etcd-data \
       --listen-client-urls=http://0.0.0.0:2379 \
       --advertise-client-urls=http://0.0.0.0:2379 \
       --listen-peer-urls=http://0.0.0.0:2380 \
       --initial-advertise-peer-urls=http://0.0.0.0:2380 \
       --initial-cluster=default=http://0.0.0.0:2380
   ```

1. ETCD サーバーが実行されていることを確認します。

   ```
   $ curl -L http://localhost:2379/health
   ```

   ```
   {"health":"true"}
   ```

1. ホスト 1 で nixlbench ベンチマークを実行します。

   ```
   $ docker run -it --gpus all --network host nixlbench:latest \
       nixlbench --etcd_endpoints http://localhost:2379 \
       --backend LIBFABRIC \
       --initiator_seg_type VRAM
   ```

1. ホスト 2 で nixlbench ベンチマークを実行します。

   ```
   $ docker run -it --gpus all --network host nixlbench:latest \
       nixlbench --etcd_endpoints http://{{ETCD_SERVER_IP}}:2379 \
       --backend LIBFABRIC \
       --initiator_seg_type VRAM
   ```

------
#### [ Build from source ]

**重要**  
ステップ 6 で **[ソースからビルドする]** を選択した場合のみ、このタブに従います。

**インスタンス間で EFA と NIXL の設定をテストする方法**

1. nixlbench ベンチマークを実行するためにホストを 2 つ選択します。最初のホストの IP アドレスをメタデータ交換用の ETCD サーバー IP として使用します。

1. ホスト 1 で ETCD サーバーを起動します。

   ```
   $ etcd --listen-client-urls "http://0.0.0.0:2379" \
       --advertise-client-urls "http://localhost:2379" &
   ```

1. ETCD サーバーが実行されていることを確認します。

   ```
   $ curl -L http://localhost:2379/health
   ```

   ```
   {"health":"true"}
   ```

1. ホスト 1 で nixlbench ベンチマークを実行します。

   ```
   $ export NIXL_LOG_LEVEL=INFO
   $ export LD_LIBRARY_PATH=$HOME/nixl/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
   
   $ nixlbench \
       --etcd-endpoints http://localhost:2379 \
       --backend LIBFABRIC \
       --initiator_seg_type VRAM
   ```

1. ホスト 2 で nixlbench ベンチマークを実行します。

   ```
   $ export NIXL_LOG_LEVEL=INFO
   $ export LD_LIBRARY_PATH=$HOME/nixl/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
   
   $ nixlbench \
       --etcd-endpoints http://{{ETCD_SERVER_IP}}:2379 \
       --backend LIBFABRIC \
       --initiator_seg_type VRAM
   ```

------

## ステップ 14: vLLM で提供される分散推論をテストする (*オプション*)
<a name="nixl-start-base-serve"></a>

NIXL をインストールしたら、LLM 推論を通じて NIXL を使用すると、vLLM、SGLang、TensorRT-LLM などのフレームワークを提供できます。

**vLLM を使用して推論ワークロードを提供する方法**

1. vLLM をインストールします。

   ```
   $ pip install vllm
   ```

1. NIXL を使用して vLLM サーバーを起動します。次のサンプルコマンドにより、NIXL ハンドシェイク接続、KV コネクタ、KV ロール、トランスポートバックエンド用として、プリフィル (プロデューサー) インスタンスが 1 つとデコード (コンシューマー) インスタンスが 1 つ作成されます。詳細な例とスクリプトについては、「[NIXLConnector 使用ガイド](https://github.com/vllm-project/vllm/blob/2d977a7a9ead3179fde9ed55d69393ef7b6cec47/docs/features/nixl_connector_usage.md)」を参照してください。

   NIXL を EFA とともに使用するには、セットアップとユースケースに基づいて環境変数を設定します。
   + プロデューサー (プリフィラー) の設定

     ```
     $ vllm serve {{your-application}} \
         --port 8200 \
         --enforce-eager \
         --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both","kv_buffer_device":"cuda","kv_connector_extra_config":{"backends":["LIBFABRIC"]}}'
     ```
   + コンシューマー (デコーダー) の設定

     ```
     $ vllm serve {{your-application}} \
         --port 8200 \
         --enforce-eager \
         --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both","kv_buffer_device":"cuda","kv_connector_extra_config":{"backends":["LIBFABRIC"]}}'
     ```

   前述のサンプル設定では、以下を設定します。
   + `kv_role` を `kv_both` に設定すると、コネクタがプロデューサーとコンシューマーの両方として機能する対称機能が有効になります。これにより、実験的なセットアップや、ロールの区別が事前に決定されていないシナリオに柔軟性が生まれます。
   + `kv_buffer_device` を `cuda` に設定すると、GPU メモリの使用が可能になります。
   + NIXL バックエンドを `LIBFABRIC` に設定すると、NIXL トラフィックが EFA を通過できるようになります。