安裝與啟用
依照以下步驟建立安裝 Robotic Suite/Physical AI 。
安裝前準備
本系統的訓練可由 CPU 或 GPU 執行，因此可安裝於 NVIDIA 平台、NVIDIA Thor 平台或 Intel 平台。GPU 並非必要條件，僅在使用 NVIDIA 平台加速訓練時才需要；不同平台所需的前置元件如下：
| 前置元件 | Intel 平台 | NVIDIA 平台 | NVIDIA Thor 平台 |
|---|---|---|---|
| Docker | 需自行安裝 | 需自行安裝 | 已內建 |
| NVIDIA GPU 驅動程式 | 不需要 | 需自行安裝 | 已內建（隨 JetPack） |
| NVIDIA Container Toolkit | 不需要 | 需自行安裝 | 已內建 |
NVIDIA Thor 平台的三項元件皆隨系統映像檔提供，可直接跳至安裝前驗證確認狀態；如驗證未通過，再依對應章節補行安裝。
1. 安裝 Docker
Intel 平台與 NVIDIA 平台均須自行安裝 Docker。以下依 Docker 官方軟體庫進行安裝：
# 移除可能衝突的舊套件
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
sudo apt remove -y $pkg
done
# 加入 Docker 官方 GPG 金鑰與軟體庫
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安裝 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# 將目前使用者加入 docker 群組
sudo usermod -aG docker $USER
群組變更須重新登入
usermod 的效果須重新登入後方能生效。未重新登入即執行後續指令時，將出現 permission denied 錯誤，此為預期行為，登出後重新登入即可。
2. 安裝 NVIDIA GPU 驅動程式
此步驟僅適用於 NVIDIA 平台。驅動程式的安裝程序因平台而異，請依所使用的機型選擇對應方式：
| 平台 | 安裝方式 |
|---|---|
| NVIDIA 平台（x86_64） | 透過 Ubuntu 套件庫安裝，詳見 NVIDIA 驅動程式安裝指南 |
| NVIDIA Thor 平台（aarch64） | 驅動程式隨 JetPack 系統映像檔提供，無須另行安裝 |
x86_64 平台可先以下列指令查詢可用的驅動程式版本：
ubuntu-drivers devices
安裝完成後須重新開機，驅動程式方能載入。
3. 安裝 NVIDIA Container Toolkit
此步驟僅適用於 NVIDIA 平台。NVIDIA Container Toolkit 的作用是讓容器能夠存取主機的 GPU；未安裝此元件時，Docker 本身仍可正常運作，但容器內無法使用 GPU，訓練將退回以 CPU 執行。
安裝前可先確認是否已存在：
nvidia-ctk --version
如指令無法執行，則依下列步驟安裝：
# 加入 NVIDIA 軟體庫
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
# 安裝
sudo apt update
sudo apt install -y nvidia-container-toolkit
# 設定 Docker 使用 NVIDIA runtime 並重新啟動
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
完整說明詳見 NVIDIA Container Toolkit 官方安裝指南。
4. 安裝前驗證
執行安裝流程之前，應先確認前置元件的狀態。Intel 平台僅需執行第一項，NVIDIA 平台與 Thor 平台三項皆須通過：
# 一、Docker 可正常執行
docker run --rm hello-world
# 二、主機可辨識 GPU（僅 NVIDIA 平台）
nvidia-smi
# 三、容器內可存取 GPU（僅 NVIDIA 平台）
docker run --rm --gpus all ubuntu nvidia-smi
第三項是實際的判斷依據。第二項通過而第三項失敗，表示驅動程式本身正常，但 Container Toolkit 尚未正確設定——此狀態下系統仍可安裝並執行，惟訓練將以 CPU 進行，速度顯著較慢。如欲以 GPU 訓練，應先完成步驟三後再繼續。
三項驗證通過後，方可執行下列安裝流程。
安裝流程
./Robotic-Suite_v0.0.408_x64_setup.run
安裝目錄會在 ~/Advantech/Robotic-Suite
選配：模擬環境建置
模擬環境（模擬錄製與 SDG 合成資料生成）不隨安裝流程一併佈署，須另行取得原始碼並建置容器映像檔。僅採用實體錄製時無須執行本節。
模擬環境以 GPU 執行算繪，因此安裝前驗證的三項均須通過。目前僅 AIR-420 經實機驗證，詳見系統需求。
建置步驟
# 取得原始碼
git clone https://github.com/ADVANTECH-Corp/Robotic-Suite-Physai-Simulation.git
cd Robotic-Suite-Physai-Simulation/
# 建置模擬環境本體
docker build -t pait/simulation:latest .
# 建置畫面檢視服務
docker build -t pait/isaacsim-viewer:latest ./isaacsim-viewer
# 以常駐容器啟動檢視服務
docker run -d --restart always -p 5173:5173 \
--name pait_isaacsim-viewer \
pait/isaacsim-viewer:latest
兩個映像檔的用法不同：
pait/simulation— 模擬環境本體，僅需建置，無須docker run。平台會偵測本機是否存在此映像檔，存在即於進入模擬環境時自行以其啟動模擬器。pait/isaacsim-viewer— 畫面檢視服務，須如上以常駐容器執行，並佔用 5173 埠。--restart always使其於主機重新開機後自動啟動，因此該指令僅需執行一次。
建置為一次性且耗時的作業
pait/simulation 建置完成後約佔 35 GB，過程中另需下載體積龐大的基礎映像檔，所需時間視網路頻寬而定。開始前應確認磁碟空間充足。
驗證
# 兩個映像檔均已建立
docker images | grep pait
# 檢視服務為 Up 狀態
docker ps --filter name=pait_isaacsim-viewer
第一項即為平台判斷模擬環境是否可用的依據：清單中出現 pait/simulation 即表示可偵測到。
完成後重新整理瀏覽器頁面，模擬相關功能方會出現。後續操作詳見模擬環境與 SDG 生成。
下一步: 設備準備.