# NVIDIA Taipei-1 DGX Cluster 使用者指南
## 📘 版本紀錄
| 📅 日期 | 🔖 版本 | ✍️ 作者 | 📝 變更摘要 |
| :----: | :----: | :----: | :---- |
| **2023/12/12** | `0.1` | Mason Wu | 初版 |
| **2024/02/26** | `0.2` | Mason Wu | 新增 TP-1 存取說明 |
| **2024/07/08** | `0.3` | Mason Wu | 新增使用條款 |
| **2024/07/26** | `1.0` | Mason Wu | 定稿版本 |
| **2025/01/01** | `1.1` | Mason Wu | 修改 Taipei-1 DGX 叢集使用條款 |
| **2025/03/23** | `1.2` | Mason Wu | 新增磁碟配額與硬體資源限制 |
| **2025/07/18** | `1.3` | Mason Wu | 新增SF登入說明 |
# Taipei-1 DGX 叢集使用條款
**僅限平日 09:00-17:00 營運（UTC+8）**
Taipei-1 DGX 叢集並未提供 24/7 全天候客戶支援服務。
**Taipei-1 DGX 叢集為「盡力提供」服務**
Taipei-1 DGX 叢集的服務可用性為「盡力提供」——無法保證或提供 SLA。每個租戶會獲得一定的資源配額，但若機器健康狀況不足，Taipei-1 DGX 叢集可能無法滿足分配的資源。
**Taipei-1 DGX 叢集計畫性維護**
Taipei-1 DGX 叢集偶爾會進行計畫性停機維護，以升級服務或硬體。我們將盡力提前通知（至少 72 小時），並與租戶協調，以降低影響。
**關於專有或敏感資訊的使用**
NVIDIA 的 Taipei-1 超級電腦旨在協助研究人員、教師與學生運用 AI 與數位分身技術，解決各行業中的複雜挑戰。本叢集的目的是協助使用者在最短時間內理解並學會使用 DGX 叢集。請注意，此叢集僅供測試、評估與開發使用；使用者 **不得** 在此叢集中存放或處理任何專有或敏感資訊。
此外，嚴禁使用者攜入或上傳任何非法取得的資料至 Taipei-1 DGX 叢集。本平台僅限用於合法與合乎倫理的行為。
**禁止在非運算節點執行運算密集任務**
禁止使用者在非運算節點（例如登入節點）上執行運算密集的任務，否則將影響其他使用者的使用體驗。
# 啟用帳號以登入 Taipei-1 DGX 叢集
## 啟用帳號
當你的 Taipei-1 DGX 叢集申請審核完成後，你將會收到來自 teams@nvidia.com，主旨為 **Invitation to join NVIDIA team** 的邀請郵件，如下圖所示。請點擊 **JOIN THE TEAM**：
:::warning
您需要註冊一個 NVIDIA Developer 帳號才能使用 Taipei-1，若尚未註冊，請至 https://developer.nvidia.com/login 註冊 NVIDIA Develpoer。
:::
## 產生 SSH 金鑰以存取 Taipei-1 DGX H100 叢集
前往 Frontier 網頁介面登入，並依指示產生 SSH 金鑰，以存取 Taipei-1
👉 https://frontier.nvidia.com/
**登入後，請先確認畫面右上角的帳號資訊，該帳號為你的 部分email 前綴和網域名稱，再加上 **-{chars}**，這就是你之後登入 Taipei-1 所使用的帳號。**
**Certificate Validaity Period : 請設定為 2d 避免頻繁的產生新的憑證**
接著，請依照畫面指示建立 SSH 公鑰，以便存取 Taipei-1 DGX H100 叢集。將 SSH 公鑰貼到圖中所示的位置，然後點選 **Generate SSH Certificate** 產生憑證。
:::warning
如果您已有公鑰，則不一定需要重新產生公鑰用於存取Taipei-1，可直接使用原本的公鑰。
:::
接著，複製新的 SSH 憑證內容並貼上到新的公鑰檔案中
:::warning
請注意，新憑證的檔名需以 `-cert.pub` 結尾。例如，若您的公鑰名稱為 `id_ed25519.pub`，則新的檔案應命名為 `id_ed25519-cert.pub`。
:::
完成後，請使用下列指令確認新憑證正確，應會看到類似以下的輸出結果：
```bash
$ ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub
(stdin):1:
Type: ssh-ed25519-cert-v01@openssh.com user certificate
Public key: ED25519-CERT SHA256:amNGhlqAUoruU96UkNLxbOFZWMnOVv6zK2VxbtFUqCY
Signing CA: ECDSA SHA256:5hMguQjiRi40bruppVJFpOcLFqm2wwGkVIm7SLqtiF8 (using ecdsa-sha2-nistp384)
Key ID: "group=ngc-ext user=yuanhuaiw-nvid-e2c967 roles=ThRA7KhKmhmaMZ_eTYrR6vAXu1XV60g6pvsmdJll5lc sub=ijXZjSpJOfI3so2hpwac_vjPRCFxyfv4oJY-ilJPOqQ"
Serial: 7722138430346938299
Valid: from 2025-07-23T23:26:53 to 2025-07-25T23:27:23
Principals:
yuanhuaiw-nvid-e2c967
Critical Options: (none)
Extensions:
permit-agent-forwarding
permit-port-forwarding
permit-pty
(stdin):2: invalid key: invalid format
```
同時也可以檢查`~/.ssh/`資料夾，是否有一組ssh key用於存取Taipei-1
```bash
$ ls -al ~/.
ls -al ~/.ssh
total 17
drwxr-xr-x 1 Mason UsersGrp 0 Jul 23 23:45 .
drwxr-xr-x 1 Mason UsersGrp 0 Jul 23 23:46 ..
-rw-r--r-- 1 Mason UsersGrp 297 Jul 23 23:45 config
-rw-r--r-- 1 Mason UsersGrp 419 Mar 4 2024 id_ed25519
-rw-r--r-- 1 Mason UsersGrp 935 Jul 21 12:58 id_ed25519-cert.pub
-rw-r--r-- 1 Mason UsersGrp 104 Mar 4 2024 id_ed25519.pub
-rw-r--r-- 1 Mason UsersGrp 994 Jul 23 23:38 known_hosts
```
現在，您已可存取 Taipei-1 DGX 叢集，以下是登入 DGX 叢集的方法：
```bash
# 使用 SSH Tunnel 透過 Jumpbox 登入 Taipei-1 DGX 節點，並使用id_ed25519 public key
# 注意：請將 <USER> 替換為你的帳號名稱，將<TARGET_IP>替換為叢集登入節點IP
ssh -i ~/.ssh/id_ed25519 \
-o IdentitiesOnly=yes -p 2222 \
-o "ProxyCommand=ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 -W %h:%p -p 2222 <USER>@jb1.frontier.nvidia.com" \
<USER>@<TARGET_IP>
```
> 📌 此指令的說明：
> - `-i ~/.ssh/id_ed25519`：使用你的私鑰（請依實際路徑調整）
> - `ProxyCommand`：透過 jumpbox（jb1.frontier.nvidia.com:2222）中轉
> - `<USER>`：請替換為你在 Taipei-1 上的使用者名稱
> - `<TARGET_IP>`：目標 DGX 節點（可依實際需要更換）
若每次連線都需要輸入一長串 `ssh -i ~/.ssh/xxx -o ProxyCommand=...` 的指令，不僅繁瑣又容易出錯。你也可以透過 `~/.ssh/config` 檔案事先定義連線規則，大幅簡化連線流程
```bash
# 開啟/編輯 SSH 設定檔：
$ vim ~/.ssh/config
#加入以下內容（請依實際情況替換括號中的值）：
Host jb1
HostName jb1.frontier.nvidia.com
User <YOUR_USER_NAME>
Port 2222
IdentityFile ~/.ssh/<YOUR_PRIVATE_KEY_NAME>
IdentitiesOnly yes
Host taipei-1
HostName <TARGET_IP>
User <YOUR_USER_NAME>
IdentityFile ~/.ssh/<YOUR_PRIVATE_KEY_NAME>
IdentitiesOnly yes
Port 2222
ProxyJump jb1
```
設定好之後，你只需要執行：
```bash
$ ssh taipei-1
```
SSH 會自動使用 jb1 當跳板連線到 <TARGET_IP>，而且會套用對應的私鑰與連線參數，無需每次重打。
### 清除 SSH 舊主機記錄
若你連線 Taipei-1 平台時出現下列警告訊息：
```
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
...
```
這表示你本機中 `~/.ssh/known_hosts` 檔案內的記錄已過時，請執行以下指令清除舊有紀錄：
```bash
$ sed -i '/jb1\.frontier\.nvidia\.com/d;/\.tun\.tp1-cluster\.nvidia\.com/d' ~/.ssh/known_hosts
```
此指令會移除以下相關主機的紀錄：
- `jb1.frontier.nvidia.com`（Jumpbox 節點）
- 所有 `*.tun.tp1-cluster.nvidia.com`（DGX 登入節點）
清除後再次連線時，系統會要求你確認新的指紋資訊，請依照提示接受即可。
:::warning
請注意：此 `-cert.pub` 憑證的有效期限為 **48 小時**。您需要**每隔 48 小時重新產生一次憑證**，以確保能順利登入系統。此外，若登入服務進行更新或重啟，也會導致憑證失效，屆時您也需要重新產生憑證。**系統不會另行通知，請自行留意**。
:::
# Taipei-1 登入節點使用限制
Taipei-1 的登入節點是一個共享資源，主要設計用於進行輕量作業，例如程式編輯、檔案管理與作業提交，**此節點不適合用於長時間或資源密集型的互動式操作。**
使用者在登入節點上工作時，請注意以下限制與建議使用方式：
## **資源使用限制**
* **處理程序限制：每個工作階段最多允許執行 1024 個處理程序**:
每位使用者在登入節點上可啟動的處理程序數量有限。**嚴禁**在登入節點上執行 **Visual Studio Code (VSCode)**，因為它會迅速耗盡允許的處理程序上限。這可能導致無法啟動新程序或開啟新的 shell 工作階段，並影響其他使用者在共享環境中的操作。同樣地，維持多個背景中的 **tmux** 工作階段，也可能導致觸及處理程序上限，應盡量減少此類情況。
- **同時登入限制：每位使用者最多允許 20 個同時 SSH 登入工作階段**
系統會限制每位使用者的同時 SSH 登入數量。若開啟多個 **tmux** 視窗或終端機分頁，也可能導致達到此上限。
* **記憶體使用限制：每個工作階段最多使用 8 GB 記憶體**
- 在登入節點上執行資源密集的工作可能會影響其他使用者，系統管理員有權監控並中止這類作業。
## **使用建議**
- **避免直接在登入節點執行 Visual Studio Code**：建議改為在透過互動式作業分配的運算節點上，啟用 [Visual Studio Code Remote Tunnels](https://code.visualstudio.com/docs/remote/tunnels) 功能。如此可將計算與程序執行轉移至專屬環境，降低對共享資源的影響。
- **減少背景 tmux 工作階段數量**：請避免在登入節點上留下多個閒置的 tmux 工作階段。
- **為 tmux 使用非登入 shell 工作階段**：若必須在登入節點上使用 tmux，建議參考 [tmux 非登入 shell 設定方式](https://wiki.archlinux.org/title/Tmux#Start_a_non-login_shell)，以降低不必要的 shell 與環境負擔。
遵循以上建議，有助於維持 Taipei-1 上穩定且公平的運算環境。
# Taipei-1 DGX 叢集簡介
Taipei-1 是由 NVIDIA 與台灣政府合作推動的計畫，目標是加速台灣的 AI 發展。其中一項重點是讓潛在使用者、客戶與合作夥伴能實際體驗 DGX 系統及其相關工作負載（如 Base Command Manager）。Taipei-1 叢集的組成包括以下幾個部分：
**Forge 平台**：提供 IaaS（基礎設施即服務）功能
**DPU BF3220**：用於將管理網路與其他網路隔離，並由 NVIDIA Forge 使用，以打造混合雲平台，協助服務供應商與企業部署與營運加速運算雲端，執行現代化工作負載
**DGX H100 GPU 節點**：用於執行各類計算密集型工作負載，例如大型語言模型（LLM）、推薦系統與電腦視覺（CV）任務
**DDN 儲存系統**：作為高效能儲存解決方案
**NVIDIA Base Command Manager 搭配 Slurm 調度器**：提供高效能的 AI 訓練作業管理
## 運算節點與網路架構
Taipei-1 共安裝了 16 台 DGX H100 系統。每台 DGX H100 配備 4 組雙埠的 InfiniBand NDR 400Gb/s OSFP 連接埠，並與 InfiniBand NDR Leaf Switch 相連。整體拓撲採用經軌道優化（rail-optimized）的全 fat-tree 結構，充分發揮 DGX H100 在 InfiniBand 網路上的高效能傳輸能力。
## 儲存節點與網路架構
高效能儲存對高效能運算至關重要。Taipei-1 DGX 叢集的平行檔案系統是建構於 DDN 儲存系統之上。DGX H100 系統透過 DPU 連接至乙太網路架構（Ethernet Fabric），以存取 DDN 儲存資源。
## 管理節點
Taipei-1 DGX 叢集中的管理節點是一台僅搭載 CPU 的伺服器。它同時扮演登入節點（Login Node）的角色，連接至叢集內部的管理網路與儲存網路，讓使用者能透過作業排程器提交作業並存取檔案系統。由於該節點為純 CPU 設備，因此不適合用來建構或驗證應用程式。
## 作業排程器
工作負載管理指的是系統上的作業提交與控制。在 Taipei-1 DGX 叢集中，我們使用 Slurm 作為工作負載管理系統（workload manager）。
當您透過 SSH 指令成功登入 Taipei-1 DGX 叢集後，系統會將您導入 DGX 叢集的登入節點（Login Node），您即可從此節點提交作業至 DGX H100 進行大規模多節點訓練。
# Taipei-1 DGX 叢集的資料上下載說明
使用者的主目錄掛載點為 **/mnt/home/<USERNAME>**，此處為 256 TB 的高速共享儲存空間，每位使用者僅能存取自己的目錄（具備讀寫與執行權限）。請將您的訓練資料與執行腳本儲存在 **/mnt/home/<USERNAME>** 目錄下。
若需團隊共用資料，請將共用檔案存放於 **/mnt/shared/<ORG_NAME>**。
預設情況下，每位使用者在 **/mnt/home/<USERNAME>** 擁有 5 TB 空間，而 **/mnt/shared/<ORG_NAME>** 的空間則可視需求進行設定。
您可以從外部系統將資料上傳至 Taipei-1 DGX H100 叢集所使用的 DDN 平行檔案系統。以下為幾種可用的上傳方式。
我們已驗證以下指令可成功上傳資料，請依實際目標 IP 進行替換。
```bash
$ sftp -i ~/.ssh/id_ed25519 -o \
"ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p <USER>@jb1.frontier.nvidia.com -p 2222" \
<USER>@<TARGET_IP>
$ scp -i ~/.ssh/id_ed25519 -o \
"ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p <USER>@jb1.frontier.nvidia.com -p 2222" \
<YOUR_FILE> <USER>@<TARGET_IP>:<DEST_PATH>
$ rsync -azv --progress --partial -e \
"ssh -i ~/.ssh/id_ed25519 -o 'ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p <USER>@jb1.frontier.nvidia.com -p 2222'" \
<YOUR_FILE> <USER>@<TARGET_IP>:<DEST_PATH>
ssh -i ~/.ssh/id_ed25519 \
-o "ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p -p 2222 <USER>@jb1.frontier.nvidia.com" \
<USER>@<TARGET_IP>
```
以下是一些將資料上傳至伺服器的範例。請注意，範例中的目標 IP、使用者名稱與路徑可能與您的實際情況不同，請務必替換為您自己的資訊。
## SFTP
### 從您的電腦執行 SFTP
```bash
#Example : Username is “user”
$ sftp -i ~/.ssh/id_ed25519 -o \
"ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p user@jb1.frontier.nvidia.com -p 2222" \
user@<Target_IP>
Connected to <Target_IP>.
sftp> put your_local_sample_file
```
### 從 Taipei-1 登入節點執行 SFTP
```bash
#Example : Username is “user”
$ sftp user@<YOUR_SFTP_SERVER>
Connected to <Target_IP>.
sftp> put your_sample_file_in_Taipei-1
```
## SCP
### 從您的電腦執行 SCP
```bash
#Example : Username is “user”
$ scp -i ~/.ssh/id_ed25519 -o \
"ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p user@jb1.frontier.nvidia.com -p 2222" \
your_local_sample_file \
user@<Target_IP>:/mnt/home/user/
```
### 從 Taipei-1 登入節點執行 SCP
```bash
$ scp your_sample_file_in_Taipei-1 \
<YOUR_NMAE>@<YOUR_SFTP_SERVER>:<YOUR_PATH>
```
## RSYNC
### 從您的電腦執行 RSYNC
```bash
#Example : Username is “user”
$ rsync -azv --progress --partial \
-e "ssh -i ~/.ssh/id_ed25519 -o 'ProxyCommand=ssh -i ~/.ssh/id_ed25519 -W %h:%p user@jb1.frontier.nvidia.com -p 2222'" \
your_local_sample_file \
user@<Target_IP>:/mnt/home/user
```
### 從 Taipei-1 登入節點執行 RSYNC
```bash
$ rsync -avz your_sample_file_in_Taipei-1 \
<YOUR_NMAE>@<YOUR_SFTP_SERVER>:<YOUR_PATH>
```
# 存取 Slurm 叢集
在 Taipei-1 DGX H100 叢集上，我們使用 Slurm 作為作業排程系統。使用者可以透過提交互動式作業（interactive job）的方式開始操作，該作業會請求一個偽終端機（pseudo-terminal），讓使用者不必撰寫腳本也能直接在叢集上進行互動操作。
互動式作業可透過 srun 指令搭配 --pty 參數提交。當您使用互動模式提交作業時，srun 指令會暫停，直到所需的節點資源可用，然後才會提供一個互動式終端機。
使用者啟動前的第一個步驟，是先載入 Slurm 模組（module）:
```bash
$ module load slurm
#or use another easy way
$ ml slurm
```
## Bare-metal 使用方式
以下是一個請求單一 DGX H100 節點並開啟互動式終端機的範例。使用者可以在該節點上建構自己的專案
:::warning
請注意，您無法取得 **root** 或 **sudo** 權限來安裝套件。
:::
您可以使用 sinfo 指令來查看叢集中所有節點的狀態。
sinfo 會列出叢集中的所有 partition，並根據每個節點的狀態將其分類。
```bash
$ sinfo
PARTITION AVAIL TIMELIMIT NODES STATE NODELIST
defq* up infinite 5 drain cnode[006,008,010,030,032]
defq* up infinite 2 idle cnode[002,004]
partition1 up infinite 6 idle cnode[014-019]
partition2 up infinite 8 idle cnode[021-028]
```
當您請求一個節點時，Slurm 排程器會自動從預設的 **defq** partition 中分配一個可用的閒置節點。完成分配後，您會從登入節點切換至指定的計算節點。
```bash
user1@dgx-cluster:~$ srun -N 1 -p defq --pty /bin/bash
user1@cnode002:~$ module available
user1@cnode002:~$ module load <Package>
user1@cnode002:~$ exit
```
:::warning
請注意，雖然系統允許在 bare-metal 環境中執行作業，但考量安裝權限與使用便利性，我們建議優先使用容器進行工作。
在 bare-metal 環境中，您需負責安裝所有相依套件，且因無 root 權限，需自行編譯與設定執行路徑，相對較為繁瑣。使用容器可大幅簡化這些流程，並提升穩定性與可重現性。
:::
如需查看 Slurm 節點的詳細資訊，可使用 scontrol 指令：
```bash
$ scontrol show node cnode002
NodeName=cnode002 Arch=x86_64 CoresPerSocket=56
CPUAlloc=0 CPUEfctv=224 CPUTot=224 CPULoad=1.12
AvailableFeatures=location=local
ActiveFeatures=location=local
Gres=gpu:8(S:0-1)
NodeAddr=cnode002 NodeHostName=cnode002 Version=23.02.6
OS=Linux 5.15.0-1029-nvidia #29-Ubuntu SMP Mon Jul 17 15:02:31 UTC 2023
RealMemory=2064005 AllocMem=0 FreeMem=2011541 Sockets=2 Boards=1
State=IDLE ThreadsPerCore=2 TmpDisk=0 Weight=1 Owner=N/A MCS_label=N/A
Partitions=defq
BootTime=2023-12-15T20:14:16 SlurmdStartTime=2023-12-19T18:40:47
LastBusyTime=2023-12-20T07:06:06 ResumeAfterTime=None
CfgTRES=cpu=224,mem=2064005M,billing=224
AllocTRES=
CapWatts=n/a
CurrentWatts=0 AveWatts=0
ExtSensorsJoules=n/s ExtSensorsWatts=0 ExtSensorsTemp=n/s
```
## 容器使用方式
若您希望在單台或多台 DGX H100 伺服器上執行作業，我們建議將 AI 開發工作負載運行在容器中。在本叢集中，我們使用 **[Pyxis]([https](https://github.com/NVIDIA/pyxis))** 與 **[Enroot](https://github.com/NVIDIA/enroot)**，提供一個簡潔且安全的執行環境，這與 NVIDIA 大型叢集如 Selene 與 EOS 採用的架構一致。
Taipei-1 環境中已預先整合 Pyxis 與 Enroot，使用者無需手動安裝，可直接使用。接下來的章節將說明這些工具的使用方式。
### Pyxis
Pyxis 是一個為 Slurm 工作負載管理器設計的 SPANK 外掛，允許無特權的叢集使用者透過 srun 指令執行容器化任務。Pyxis 一詞源自古希臘語，原意為小型容器。
**優點**
* 可在無特權容器中無縫執行使用者工作
* 提供簡潔直覺的命令列操作介面
* 支援快速下載 Docker 映像，具備映像層快取與跨使用者共用功能
* 支援透過 PMI2 或 PMIx 進行多節點 MPI 任務（需 Slurm 支援）
* 可在容器內部安裝額外套件
* 相容於共享檔案系統
* 不需於全叢集管理使用者／群組子帳號 ID
### Enroot
Enroot 是一個簡潔但功能強大的工具，可將傳統容器或作業系統映像轉換為 **無特權沙盒環境**。
它可以視為加強版的無特權 chroot(1)，採用與容器相同的核心技術，但移除了大部分預設的隔離機制，同時保留檔案系統的分離性。
這種作法特別適合於高效能運算（HPC）或虛擬化環境中使用，當「可攜性與可重現性」較「額外隔離性」更重要時會是最佳選擇。
Enroot 也與其他工具如 proot(1) 或 fakeroot(1) 類似，不過它更依賴 Linux 核心的新特性（如使用者命名空間與掛載命名空間），並提供將主流容器映像格式（如 Docker）匯入的功能。
## 容器化開發流程
### **從線上或私有regisrty下載image**
將 Ubuntu 的 Docker image 從 DockerHub 匯入至您的家目錄，並儲存為 ubuntu.sqsh 檔案。
```bash
$ srun --ntasks=1 -p defq \
--container-image ubuntu --container-save ./ubuntu.sqsh true
```
將 TensorFlow 的 Docker image 從 NGC（NVIDIA GPU Cloud）匯入至您的家目錄，並儲存為 tf2303.sqsh 檔案
```bash
srun --ntasks=1 -p defq \
--container-image nvcr.io#nvidia/tensorflow:23.03-tf1-py3 \
--container-save ./tf2303.sqsh true
```
:::warning
請注意，若image的註冊網址格式為 nvcr.io/nvidia/tensorflow ，則您需要將其改為 nvcr.io#nvidia/tensorflow。
:::
請確認您的家目錄中已成功產生 TensorFlow 的 .sqsh 映像檔。
```bash
$ ls ~/
tf2303.sqsh
```
如果從 NGC 或您的私有regisrty下載image時需要認證，請將相關認證檔案放置在您的家目錄下。
```bash
$ mkdir ~/.config/enroot -p
$ vim ~/.config/enroot/.credentials
machine nvcr.io login $oauthtoken password <NGC_API_KEY>
machine <your_registry> ……
```
### **建立並使用自訂映像檔**
若您的image沒有儲存在線上或私有regisrty，建議您在自己的開發環境先準備好 sqsh image，然後再上傳至 Taipei-1；這是最簡單的方式。或者，您也可以將自訂映像上傳至映像庫，然後透過前述方法從 Taipei-1 下載。
在自己的開發環境中建立image，您可以輕鬆安裝所有所需套件，且不受 Taipei-1 上安全限制所造成的不便。
若您選擇在本機建立 sqsh 映像檔，請參考以下連結以安裝 Enroot：
👉 https://github.com/NVIDIA/enroot
接著，請參考 Enroot GitHub 頁面上的匯入使用說明：
👉 https://github.com/NVIDIA/enroot/blob/master/doc/cmd/import.md
以便將您本地映像庫中的映像轉換成 SQSH 檔案。如果您仍希望直接在 Taipei-1 上建立映像，以下是操作步驟：
1. 登入一台運算節點以開始自訂您的映像檔。
```bash
$ srun -N 1 -p defq --mpi=pmix --gres=gpu:1 --ntasks-per-node 1 --pty /bin/bash
```
2. 在 Taipei-1 上無法使用 docker build，因此您需要先下載一個基礎映像檔。例如，您可以參考上述方法下載 TensorFlow 23.02 映像，並以此建立一個基礎容器。
```bash
$ enroot create --name my_custom_tf tf2302.sqsh
```
3. 啟動該容器，並開啟容器檔案系統的寫入權限（root 模式），以便安裝套件
```bash
$ enroot start --root -w my_custom_tf /bin/bash
```
4. 在容器中加入您需要的套件，並進行程式碼修改
```bash
<do your code changes >
$ apt install <SOMETHING>
$ pip install <SOMETHING>
$ exit
```
5. 將修改後的容器儲存為新的映像檔
```bash
$ enroot export --output my_custom_tf.sqsh my_custom_tf```
```
6. 最後，移除該容器
```bash
$ enroot remove my_custom_tf
$ exit
```
## **使用容器執行 Slurm 作業**
無論您是從Registry下載image，還是自行建立的image，都可以使用這些image來執行您的工作負載。
以下是一個範例指令格式：
```bash
$ srun -N 1 -p defq --mpi=pmix --gres=gpu:8 --ntasks-per-node 8 \
--container-image /mnt/home/user/tf2303.sqsh \
--container-writable \
--container-remap-root \
--pty /bin/bash
```
### **Slurm srun 參數說明**
**執行所需的節點數量**:
在 Taipei-1 環境中，最多可使用 16 個運算節點:
```bash
# apply for 2 nodes
-N 2
```
**作業分區**
Partition 可視為作業佇列，每個分區都有其限制條件，例如作業大小、執行時間、使用者權限等:
```bash
# apply for nodes in defq partition
-p defq
```
若要查詢可用的分區，請使用 sinfo 指令。實際可用分區可能因系統設定而異，並不一定只限於 defq。
**專屬節點分配**
讓作業在專屬模式下執行:
```bash
--exclusive
```
啟用 --exclusive 模式表示該節點在作業執行期間不會與其他作業共享資源，可確保您的作業擁有該節點的完整運算能力，避免其他工作負載的干擾。此模式適用於對效能一致性有高度要求的工作負載。
:::warning
請注意：單一節點最多可同時支援 8 個單 GPU 任務，請勿過度申請資源，建議斟酌使用以避免影響其他使用者。
:::
**指定使用的 MPI 類型**
透過下列參數指定使用的 MPI 類型，預設為 pmix:
```bash
--mpi=pmix
```
若要查看支援的 MPI 類型，可使用下列指令：
```bash
srun --mpi=list
```
**指定所需的通用資源（Generic Resources）**
例如，請求 8 張 GPU：
```bash
# apply for 8 GPUs per node
--gres=gpu:8
```
**每個節點啟動的任務數**
每個節點上啟動的任務數（--ntasks-per-node）會依不同情境而異：
* 在 MPI 類型的工作中，通常每張 GPU 對應一個 task，因此任務數會與 GPU 數量相同。
* 在使用 PyTorch 進行多 GPU 訓練 時，通常只需啟動一個 task per node，由程式內部透過 torch.nn.DataParallel 或 torchrun 等方式自行管理多張 GPU
```bash
# apply for 8 tasks per node
--ntasks-per-node 8
```
**容器映像檔**
指定要使用的容器檔案系統，可為 enroot URI 格式的 Docker 映像，或是遠端主機上的 .sqsh 映像路徑：
```bash
--container-image /mnt/home/user/tf2303.sqsh
```
**啟用容器檔案系統的寫入權限**
將容器檔案系統設為可寫入:
```bash
--container-writabe
```
**重新對映容器內的 root 權限**
將容器內的帳號對應為 root，方便安裝套件:
```bash
--container-remap-root
```
**掛載特定資料夾至容器內**
格式為 [來源路徑]:/[容器內路徑]：
```bash
--container-mounts /mnt/SCRATCH/:/mnt/SCRATCH_IN_CONTAINER
```
**掛載使用者的家目錄至容器內**
將主機端的家目錄與容器中的家目錄同步掛載:
```bash
--container-mount-home
```
**分配一個偽終端機（Pseudo-TTY）**
方便互動式執行 shell 或需要終端機介面的應用程式:
```bash
--pty /bin/bash
```
**在容器中執行的指令**
指定在容器中執行的實際指令:
```bash
python /workspace/nvidia-examples/cnn/resnet.py --layers 50 -b 512 -i 100
```
## **範例一：使用 8 張 GPU 的單節點作業指令**
```bash
srun \
-N 1 \ #Request 1 node
-p defq \ #Request node in defq partition
--mpi=pmix \ #Request use pmix for MPI
--gres=gpu:8 \ #Request 8 GPUs
--ntasks-per-node 8 \ #Request 8 tasks
--container-image ${HOME}/tf2303.sqsh \ #Use tf2303 image
--container-writable \ #Able to write file in tf2303 image
python /workspace/nvidia-examples/cnn/resnet.py --layers 50 -b 512 -i 100
```
或使用互動模式執行
```bash
srun \
-N 1 \
-p partition1 \ #Request node in partition1 partition
--mpi=pmix \
--gres=gpu:8 \
--ntasks-per-node 8 \
--container-image ${HOME}/tf2303.sqsh \
--container-writable \
--pty /bin/bash #Get access to container
$ python /workspace/nvidia-examples/cnn/resnet.py --layers 50 -b 512 -i 100
#Manually run any command by yourself until you leave container
```
## **範例二：多節點作業指令**
```bash
srun \
-N 2 \ #Request 2 node
-p partition4 \ #Request nodes in partition4 partition
--mpi=pmix \
--gres=gpu:8 \
--ntasks-per-node 8 \
--container-image ${HOME}/tf2303.sqsh \
--container-writable \
--container-mounts /mnt/SCRATCH/:/mnt/SCRATCH \
python /workspace/nvidia-examples/cnn/resnet.py --layers 50 -b 512 -i 100
```
:::warning
請注意，並非所有容器化作業都能輕易調整 Slurm 節點數並順利執行分散式運算。我們強烈建議使用來自 NGC 的映像，例如 TensorFlow、PyTorch 與 NeMo，這些映像針對多節點訓練進行過最佳化，可大幅簡化調校流程。
:::
## **範例三：使用 sbatch 提交批次作業**
您也可以透過 Slurm 的 sbatch 指令提交作業，只需撰寫一個 .sh 檔案即可。以下為一個使用 2 個節點進行 TensorFlow 分散式訓練的範例：
```bash
$ vim tf-training-2N.sh
```
```bash
#!/bin/bash
# Parameters
#SBATCH -N 2 #Request 2 nodes
#SBATCH -p defq #Request nodes in defq partition
#SBATCH --ntasks-per-node=8
#SBATCH --time=0-08:00:00 #wall time limit, hr:min:sec
#SBATCH --gres=gpu:8
# name of the stdout, using the job number (%j) and the first node (%N)
#SBATCH -o ./result/%j-%N-slurm.out
# name of the stderr, using job and first node values
#SBATCH -e ./result/%j-%N-slurm.err
CONT="${HOME}/tf2303.sqsh" # point out image location
echo -e "Container using ${CONT}"
echo -e "Running on hosts: $(echo $(scontrol show hostname))"
# command
srun --mpi=pmix \
--container-image $CONT \
--container-writable \
bash -c "python /workspace/nvidia-examples/cnn/resnet.py --layers 50 -b 512 -i 100"
```
執行批次任務並查看輸出結果：
```bash
user1@dgx-cluster:~$ sbatch tf-training-2N.sh #Submit batch job
Submitted batch job 442
user1@dgx-cluster:~$ cat result/442-cnode004-slurm.out #check output
user1@dgx-cluster:~$ cat result/442-cnode004-slurm.err #check err output
```
### **何時該使用 sbatch 與 srun？**
#### **sbatch**
當您希望提交一份作業腳本到排程佇列，並在資源可用時自動執行時，建議使用 sbatch。
這種方式適用於時間較長、不需互動的背景作業，尤其適合批次處理流程，不需要即時回應或介入。
#### **srun**
當您需要即時互動回饋，例如進行測試、除錯，或在作業執行期間與其互動時，請使用 srun。srun 也可在 sbatch 提交的作業腳本中使用，用來分配資源給腳本中的特定任務。
透過理解何時適合使用 sbatch 或 srun，您可以更有效地管理並執行 Slurm 上的作業。
# 監控 GPU 使用情況
在作業執行期間，您可以透過以下幾種方式來監控 GPU 使用指標：
## 在 sbatch 作業腳本中使用 nvidia-smi dmon 紀錄 GPU 使用狀況
```bash
#!/bin/bash
# Parameters
#SBATCH -N 2 #Request 2 nodes
#SBATCH -p defq #Request nodes in defq partition
#SBATCH --ntasks-per-node=8
#SBATCH --time=0-08:00:00 #wall time limit, hr:min:sec
#SBATCH --gres=gpu:8
# name of the stdout, using the job number (%j) and the first node (%N)
#SBATCH -o ./result/%j-%N-slurm.out
# name of the stderr, using job and first node values
#SBATCH -e ./result/%j-%N-slurm.err
# command
srun --mpi=pmix \
--container-image $CONT \
--container-writable \
--container-mount-home \
bash -c \
"nohup nvidia-smi dmon -s puc -o DT -f $HOME/gpu_usage-\$(hostname).log > /dev/null 2>&1 & \
exec python /workspace/nvidia-examples/cnn/resnet.py --layers 50 -b 512 -i 100"
```
## SSH 登入運算節點進行即時監控
當您的作業已開始執行並且節點已分配完成時，您可以透過 SSH 登入該節點以進行即時監控：
```bash
$ srun -N 1 … <you job>
…
…
ssh <node-name> # SSH into the node(by other terminal)
nvidia-smi # Basic GPU usage info
nvidia-smi dmon # Real-time monitoring
```
:::warning
只有在作業已分配至運算節點之後，SSH 存取才會啟用
**請勿透過 SSH 執行工作負載** SSH 僅限用於在作業執行期間進行監控或除錯用途
:::
# Taipei-1 DGX 叢集的範例工作流程
## LLM training and fine-tuning
此範例資源庫是為使用 Taipei-1 並透過 NeMo Framework 訓練大型語言模型（LLM）的使用者所設計。提供的腳本涵蓋前訓練（pre-training）、**微調（fine-tuning）與參數高效微調（PEFT）**的流程。
所有腳本皆基於 Slurm（Taipei-1 使用的排程系統 BCM）設計，目的是協助使用者順利啟動並監控 LLM 訓練作業。
更詳細內容請參見：
🔗 https://hackmd.io/@MasonWu/SkKYpjAUp
## PyTorch Training
TBD
# Slurm初學者 常見問題集
* Q: 什麼是 Slurm？
* A: Slurm 是一套用於高效能運算環境中進行作業排程與資源管理的工作負載管理系統。
* Q: 如何檢查我提交的作業狀態？
* A: 使用 `squeue` 指令來檢查您的作業在佇列中的狀態。
* Q: 如何取消作業？
* A: 使用 `scancel` 搭配作業 ID，例如：`scancel 12345`。
* Q: Slurm 中的 partition 是什麼？
* A: Partition 是一組被劃分出來的運算節點集合，可視為作業佇列。
* Q: 如何查詢有哪些 partition 可用？
* A: 使用 `sinfo` 指令來顯示可用的 partition 與節點資訊。
* Q: 如何請求指定數量的節點？
* A: 在 `sbatch` 或 `srun` 中使用 `-N` 參數，例如：`sbatch -N 2 my_job_script.sh`。
* Q: 如何指定作業所需的執行時間？
* A: 使用 `--time` 參數，格式為 `天-時:分:秒`，例如：`--time=1-00:00:00`。
* Q: `--gres` 參數是做什麼的？
* A: 用來請求通用資源（如 GPU），例如：`--gres=gpu:4` 表示請求 4 張 GPU。
* Q: `srun` 和 `sbatch` 有什麼不同？
* A: `srun` 用於互動式作業，`sbatch` 用於提交批次作業腳本。
* Q: 如何查看作業使用了哪些資源？
* A: 使用 `sacct` 指令顯示作業的資源使用記錄。
* Q: 如何取得作業的輸出結果？
* A: 在腳本中使用 `-o` 參數，例如：`#SBATCH -o my_output_file.out`。
* Q: 如何設定作業的相依性？
* A: 使用 `--dependency` 參數，例如：`--dependency=afterok:job_id`。
* Q: 如何執行指定 MPI 版本的作業？
* A: 使用 `--mpi` 參數，例如：`--mpi=pmix`，可使用 `srun --mpi=list` 查詢支援的 MPI 版本。
* Q: `srun --pty` 有什麼用途？
* A: 分配一個 pseudo-TTY，適用於互動式 shell 操作。
* Q: 如何執行容器化的作業？
* A: 使用 `--container-image` 參數並指定映像路徑，例如：`--container-image=my_image.sqsh`。
* Q: 如何讓容器檔案系統具有寫入權限？
* A: 使用 `--container-writable` 參數。
* Q: 如何掛載特定資料夾到容器中？
* A: 使用 `--container-mounts` 參數，例如：`--container-mounts /mnt/SCRATCH/:/mnt/SCRATCH`。
* Q: 如何同時指定輸出與錯誤檔案？
* A: 使用 `-o` 與 `-e` 參數，例如：`#SBATCH -o my_output.out -e my_error.err`。
* Q: 如何在作業腳本中使用環境變數？
* A: 使用 `--export` 參數，例如：`--export=ALL,MY_VAR=value`。
* Q: 如何除錯失敗的作業？
* A: 檢查 `-e` 指定的錯誤檔案，並使用 `scontrol show job` 查詢詳細資訊。
* Q: 如何知道可以分配多少 GPU 節點？
* A: 使用 `sinfo` 指令並查看 GPU 類型節點的可用數量。
* Q: 如何知道目前有多少空閒節點可使用？
* A: 使用 `sinfo` 指令，查詢 `idle` 或 `mix` 狀態的節點數。
* Q: 為什麼我一直等待節點分配並看到以下訊息？
```bash
srun: Requested partition configuration not available now
srun: job <ID> queued and waiting for resources
```
* A: 表示您所要求的資源目前尚未可用，作業正在佇列中等待。也可能是指定了錯誤的 partition 名稱。
* Q: 為什麼我看到以下訊息並無法建立作業步驟？(add Q here)
```bash
srun: job <ID> step creation temporarily disabled, retrying
srun: job <ID> step creation still disabled, retrying
```
* A: 表示 Slurm 因資源限制或排程政策暫時無法建立作業步驟，系統會持續重試。通常是因為在 GPU 節點內部再次執行 Slurm 指令所導致。
* Q: 有一個作業執行了很久，我要怎麼知道是誰的？
* A: 使用 `squeue` 查詢目前執行中作業與對應使用者，例如：`squeue -u <username>`。
* Q: 我該怎麼取消自己的作業？
* A: 使用 `scancel` 加上您的作業 ID，例如：`scancel 12345`。
* Q: 我可以取消別人的作業嗎？
* A: 不可以。
# 技術支援
技術支援可透過電子郵件取得。Taipei-1-SA-support 團隊會在台灣時間的上班時段回覆。
請注意：即使您有 NVIDIA 的個別聯絡窗口協助您的專案，若是任何與基礎設施或執行環境有關的問題，請務必直接聯繫：
📧 Taipei-1-SA-support（[Taipei-1-SA-support@nvidia.com](mailto:Taipei-1-SA-support@nvidia.com)）
Sign in with Wallet
Connect another wallet